diff options
Diffstat (limited to 'docs')
289 files changed, 27190 insertions, 0 deletions
diff --git a/docs/docs-documentation-redirect.html b/docs/docs-documentation-redirect.html new file mode 100644 index 0000000..98a265e --- /dev/null +++ b/docs/docs-documentation-redirect.html @@ -0,0 +1,9 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=documentation.html"> +</head> +<body> +<a href="documentation.html">click here if you are not redirected</a> +</body> +</html> + diff --git a/docs/docs-redirect-index.html b/docs/docs-redirect-index.html new file mode 100644 index 0000000..dc0bc72 --- /dev/null +++ b/docs/docs-redirect-index.html @@ -0,0 +1,8 @@ +<html>
+<head>
+<meta http-equiv="refresh" content="0;url=framework/index.html">
+</head>
+<body>
+<a href="framework/index.html">click here if you are not redirected</a>
+</body>
+</html>
diff --git a/docs/docs-redirect.html b/docs/docs-redirect.html new file mode 100644 index 0000000..3d2b8a0 --- /dev/null +++ b/docs/docs-redirect.html @@ -0,0 +1,8 @@ +<html>
+<head>
+<meta http-equiv="refresh" content="0;url=docs/index.html">
+</head>
+<body>
+<a href="docs/index.html">click here if you are not redirected</a>
+</body>
+</html>
diff --git a/docs/docs-samples-redirect.html b/docs/docs-samples-redirect.html new file mode 100644 index 0000000..4e549e6 --- /dev/null +++ b/docs/docs-samples-redirect.html @@ -0,0 +1,8 @@ +<html>
+<head>
+<meta http-equiv="refresh" content="0;url=../../samples/">
+</head>
+<body>
+<a href="../../samples/">click here if you are not redirected</a>
+</body>
+</html>
diff --git a/docs/html/_build_id.cs b/docs/html/_build_id.cs new file mode 100644 index 0000000..139c216 --- /dev/null +++ b/docs/html/_build_id.cs @@ -0,0 +1,2 @@ +<?cs # appears on the right side of the blue bar at the bottom of every page +?><div id="jd-build-id"> Build <?cs var:page.build ?> - <?cs var:page.now ?> </div> diff --git a/docs/html/about.jd b/docs/html/about.jd new file mode 100755 index 0000000..a129916 --- /dev/null +++ b/docs/html/about.jd @@ -0,0 +1,13 @@ +about=true
+page.title=About
+@jd:body
+
+ <div id="mainBodyFixed">
+ <h2 id="searchTitle">About</h2>
+ <img src="{@docRoot}assets/images/hr_gray_main.jpg" />
+ <div><br /></div>
+ <p>Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.</p>
+ <br /><br /><br /><br /><br /><br /><br /><br />
+ <br /><br /><br /><br /><br /><br /><br /><br />
+ <br /><br /><br /><br /><br /><br /><br /><br />
+ </div>
\ No newline at end of file diff --git a/docs/html/app.yaml b/docs/html/app.yaml new file mode 100644 index 0000000..c63791e --- /dev/null +++ b/docs/html/app.yaml @@ -0,0 +1,11 @@ +application: androidappdocs-staging +version: 1 +runtime: python +api_version: 1 + +handlers: + +- url: / + static_dir: / + + diff --git a/docs/html/blog/blog_toc.cs b/docs/html/blog/blog_toc.cs new file mode 100644 index 0000000..b2a73f5 --- /dev/null +++ b/docs/html/blog/blog_toc.cs @@ -0,0 +1 @@ +<ul>
<li>Android Developer Blog
<ul>
<li><a href="">Blog</a></li>
<li><a href="">Blog</a></li>
</ul>
</li>
</ul>
FIXME
diff --git a/docs/html/blog/index.jd b/docs/html/blog/index.jd new file mode 100644 index 0000000..835c55d --- /dev/null +++ b/docs/html/blog/index.jd @@ -0,0 +1,4 @@ +page.title=Android Developer Blog +@jd:body + +FIXME diff --git a/docs/html/community/groups.jd b/docs/html/community/groups.jd new file mode 100755 index 0000000..9d6a2d7 --- /dev/null +++ b/docs/html/community/groups.jd @@ -0,0 +1,98 @@ +community=true
+page.title=Groups
+@jd:body
+
+ <div id="mainBodyFixed">
+ <div id="mainBodyLeft">
+ <h3>Android Discussion Groups</h3>
+ <p>Welcome to the Android community! We're glad you're here and invite you to participate in these discussions. Before posting, please red the <a href="#">Groups Charter</a> that covers the community guidelines.</p>
+ <p>To get the most out of this group, please do the following before you post:</p>
+ <div class="indent">
+ <p><strong>1.</strong> <a href="community_2.html">Read the FAQs</a> The most common questions are addressed in this frequently updated list.</p>
+ <p><strong>2.</strong> <strong>Type in keywords of your questions in the main Android site's search bar</strong> (such as the one above). This search encompasses all previous discussions, across all groups, as well as the full contents of the site, documentation, and blogs. Chances are good that somebody has run into the same issue before.</li>
+ <p><strong>3.</strong> <strong>Be very clear</strong> about your question in the subject - it helps everyone, both those trying to answer your question as well as those who may be looking for information in the future. Also <strong>give plenty of details</strong> in your post to help others understand your problem. Code or log snippets, as well as pointers to screenshots, may also be helpful.
+ </p>
+ </div>
+ <p>For a great guide to phrasing your questions, please read: <a href="#">How to Ask Questions The Smart Way</a>.</p>
+ <br /><br />
+ </div>
+
+ <div id="mainBodyRight">
+ <table>
+ <tr>
+ <td class="blueBorderBox">
+ <h3 class="green">News</h3>
+ <a href="community_2.html" class="orangeLink">Developers get hands on unlocked phones</a>
+ <h4>mobile.google.com</h4>
+ <br />
+
+ <a href="community_2.html" class="orangeLink">Google announces availability of Google Mobile products on T-Mobile G1</a>
+ <h4>mobile.google.com</h4>
+ <br />
+
+ <a href="community_2.html" class="orangeLink">Android 1.0 SDK R1 now available</a>
+ <h4>android-developers.com</h4>
+ <br />
+
+ <a href="community_2.html" class="orangeLink">Android Market Announcement</a>
+ <h4>market.android.com</h4>
+ <br />
+ </td>
+ </tr>
+ </table>
+ </div>
+ </div>
+ <div id="mainBodyBottom">
+ <h3>Available Groups</h3>
+ <br />
+ <table class="groupTable">
+ <tr>
+ <th>Group - Web Access</th>
+ <th>Description</th>
+ <th>Subscribe by email</th>
+ </tr>
+ <tr class="oddRow">
+ <td><a href="#">android-beginners</a></td>
+ <td>Discuss developing Android applications using the Android framework. Get help with troubleshooting apps, advice on implementation, and strategies for improving your app's speed and user experience.</td>
+ <td><a href="#">android-beginners-subscribe@googlegroups.com</a></td>
+ </tr>
+ <tr class="evenRow">
+ <td><a href="#">android-developers</a></td>
+ <td>New to ANdroid development? Start here. Open to any discussion around beginner-type questions; this is a great way to get up and running with your new App on the Android platform.</td>
+ <td><a href="#">android-developers-subscribe@googlegroups.com</a></td>
+ </tr>
+ <tr class="oddRow">
+ <td><a href="#">android-internals</a></td>
+ <td>For "hackers" interested in discussing the innards of Android or exploring its use on various hardware.</td>
+ <td><a href="#">android-internals-subscribe@googlegroups.com</a></td>
+ </tr>
+ <tr class="evenRow">
+ <td><a href="#">android-discuss</a></td>
+ <td>The "water cooler" of Android discussion. Free-wheeling discussion from ideas about the Android platform to your announcements on other Android resources.</td>
+ <td><a href="#">android-discuss-subscribe@googlegroups.com</a></td>
+ </tr>
+ <tr class="oddRow">
+ <td><a href="#">android-security-discuss</a></td>
+ <td>A place for open discussion on secure development, emerging security concerns, and best practices for and by android developers.</td>
+ <td><a href="#">android-security-discuss@googlegroups.com</a></td>
+ </tr>
+ <tr class="evenRow">
+ <td><a href="#">android-security-announce</a></td>
+ <td>A low-volume group for security-related announcements by the Android Security Team.</td>
+ <td><a href="#">android-security-announce-subscribe@googlegroups.com</a></td>
+ </tr>
+ </table>
+ <br /><br />
+
+
+ <h3 class="green">Subscribing to Groups via Email</h3>
+ <img src="images/hr_gray_main.jpg" />
+ <p><br />You can also subscribe to these groups through email and handle your posts with your email client of choice.</p>
+ <p>To do so, either:</p>
+ <ol>
+ <li>Use the ink under "subscribe b email" in the table above to bypass the web interface altogether.</li>
+ <li>If you're already signed in to the groups via the web, simply click "edit my membership" on the right hand side and choose "email" under "How do you want to read this group?"</li>
+ </ol>
+ <p> </p>
+ <p> </p>
+ </div>
\ No newline at end of file diff --git a/docs/html/community/index.jd b/docs/html/community/index.jd new file mode 100644 index 0000000..eadd94d --- /dev/null +++ b/docs/html/community/index.jd @@ -0,0 +1,47 @@ +community=true +page.title=Community +@jd:body + +<div id="mainBodyFixed"> + <div id="mainBodyLeft"> + <div id="communityDiv"> + <h2>Latest News</h2> + <br /><br /> + + <a href="groups.html" class="orangeLink">Developers get hands on unlocked phones</a> + <p>mobile.google.com</p> + <br /> + + <a href="groups.html" class="orangeLink">Google announces availability of Google Mobile products on T-Mobile G1</a> + <p>mobile.google.com</p> + <br /> + + <a href="groups.html" class="orangeLink">Android 1.0 SDK R1 now available</a> + <p>android-developers.com</p> + <br /> + + <a href="groups.html" class="orangeLink">Android Market Announcement</a> + <p>market.android.com</p> + <br /> + </div> + </div> + + <div id="mainBodyRight"> + <table id="rightColumn"> + <tr> + <td> + <h2 class="green">Mailing Lists</h2> + <p><a href="groups.html">android-beginners</a></p> + <p><a href="groups.html">android-developers</a></p> + <p><a href="groups.html">android-internals</a></p> + <p><a href="groups.html">android-discuss</a></p> + <p><a href="groups.html">android-security-discuss</a></p> + <p><a href="groups.html">android-security-announce</a></p> + </td> + </tr> + <tr> + <td colspan="2"><div class="seperator"> </div></td> + </tr> + </table> + </div> +</div>
\ No newline at end of file diff --git a/docs/html/goodies/index.jd b/docs/html/goodies/index.jd new file mode 100644 index 0000000..c126098 --- /dev/null +++ b/docs/html/goodies/index.jd @@ -0,0 +1,85 @@ +page.title=Goodies +@jd:body + +<h1>Goodies</h1> + +<h2>Wallpaper</h2> + +<table class="columns"> + <tr> + <td> + <ul style="font-size: 85%; list-style: none; margin: 0 0 1em 0;"> + <li><img src="{@docRoot}goodies/wallpaper/android-wallpaper1_thumbnail.png" height="125" width="200" alt="Android Wallpaper #1"></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper1_1024x768.png">1024 x 768</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper1_1280x800.png">1280 x 800</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper1_1440x900.png">1440 x 900</a></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper1_1600x1200.png">1600 x 1200</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper1_1680x1050.png">1680 x 1050</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper1_1920x1200.png">1920 x 1200</a></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper1_2560x1600.png">2560 x 1600</a></li> + </ul> + </td> + <td> + <ul style="font-size: 85%; list-style: none; margin: 0 0 1em 0;"> + <li><img src="{@docRoot}goodies/wallpaper/android-wallpaper2_thumbnail.png" height="125" width="200" alt="Android Wallpaper #2"></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper2_1024x768.png">1024 x 768</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper2_1280x800.png">1280 x 800</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper2_1440x900.png">1440 x 900</a></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper2_1600x1200.png">1600 x 1200</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper2_1680x1050.png">1680 x 1050</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper2_1920x1200.png">1920 x 1200</a></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper2_2560x1600.png">2560 x 1600</a></li> + </ul> + </td> + <td> + <ul style="font-size: 85%; list-style: none; margin: 0 0 1em 0;"> + <li><img src="{@docRoot}goodies/wallpaper/android-wallpaper3_thumbnail.png" height="125" width="200" alt="Android Wallpaper #3"></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper3_1024x768.png">1024 x 768</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper3_1280x800.png">1280 x 800</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper3_1440x900.png">1440 x 900</a></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper3_1600x1200.png">1600 x 1200</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper3_1680x1050.png">1680 x 1050</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper3_1920x1200.png">1920 x 1200</a></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper3_2560x1600.png">2560 x 1600</a></li> + </ul> + </td> + <tr> + </tr> + <td> + <ul style="font-size: 85%; list-style: none; margin: 0 0 1em 0;"> + <li><img src="{@docRoot}goodies/wallpaper/android-wallpaper4_thumbnail.png" height="125" width="200" alt="Android Wallpaper #4"></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper4_1024x768.png">1024 x 768</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper4_1280x800.png">1280 x 800</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper4_1440x900.png">1440 x 900</a></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper4_1600x1200.png">1600 x 1200</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper4_1680x1050.png">1680 x 1050</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper4_1920x1200.png">1920 x 1200</a></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper4_2560x1600.png">2560 x 1600</a></li> + </ul> + </td> + <td> + <ul style="font-size: 85%; list-style: none; margin: 0 0 1em 0;"> + <li><img src="{@docRoot}goodies/wallpaper/android-wallpaper5_thumbnail.jpg" height="125" width="200" alt="Android Wallpaper #5"></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper5_1024x768.jpg">1024 x 768</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper5_1280x800.jpg">1280 x 800</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper5_1440x900.jpg">1440 x 900</a></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper5_1600x1200.jpg">1600 x 1200</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper5_1680x1050.jpg">1680 x 1050</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper5_1920x1200.jpg">1920 x 1200</a></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper5_2560x1600.jpg">2560 x 1600</a></li> + </ul> + </td> + <td> + <ul style="font-size: 85%; list-style: none; margin: 0 0 1em 0;"> + <li><img src="{@docRoot}goodies/wallpaper/android-wallpaper6_thumbnail.jpg" height="125" width="200" alt="Android Wallpaper #6"></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper6_1024x768.jpg">1024 x 768</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper6_1280x800.jpg">1280 x 800</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper6_1440x900.jpg">1440 x 900</a></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper6_1600x1200.jpg">1600 x 1200</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper6_1680x1050.jpg">1680 x 1050</a> / <a href="{@docRoot}goodies/wallpaper/android-wallpaper6_1920x1200.jpg">1920 x 1200</a></li> + <li><a href="{@docRoot}goodies/wallpaper/android-wallpaper6_2560x1600.jpg">2560 x 1600</a></li> + </ul> + </td> + </tr> +</table> + +<br> + +<div class="notice"><div id="notice" style="text-align: center; border: 1em 0em 1em 0em"> + Except as otherwise <a + href="http://code.google.com/policies.html#restrictions">noted</a>, + the content of this page is licensed under the <a rel="license" + href="http://creativecommons.org/licenses/by/3.0/">Creative Commons + Attribution 3.0 License</a>. +<!-- <rdf:RDF xmlns="http://web.resource.org/cc/" + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> + <Work rdf:about=""> + <license rdf:resource="http://creativecommons.org/licenses/by/3.0/" /> + </Work> + <License rdf:about="http://creativecommons.org/licenses/by/3.0/"> + <permits rdf:resource="http://web.resource.org/cc/Reproduction"/> + <permits rdf:resource="http://web.resource.org/cc/Distribution"/> + <requires rdf:resource="http://web.resource.org/cc/Notice"/> + <requires rdf:resource="http://web.resource.org/cc/Attribution"/> + <permits rdf:resource="http://web.resource.org/cc/DerivativeWorks"/> + </License> +</rdf:RDF> --> +</div> diff --git a/docs/html/goodies/wallpaper/android-wallpaper1_1024x768.png b/docs/html/goodies/wallpaper/android-wallpaper1_1024x768.png Binary files differnew file mode 100644 index 0000000..f33b16c --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper1_1024x768.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper1_1280x800.png b/docs/html/goodies/wallpaper/android-wallpaper1_1280x800.png Binary files differnew file mode 100644 index 0000000..391eb1a --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper1_1280x800.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper1_1440x900.png b/docs/html/goodies/wallpaper/android-wallpaper1_1440x900.png Binary files differnew file mode 100644 index 0000000..dcc49b5 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper1_1440x900.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper1_1600x1200.png b/docs/html/goodies/wallpaper/android-wallpaper1_1600x1200.png Binary files differnew file mode 100644 index 0000000..3799bd7 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper1_1600x1200.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper1_1680x1050.png b/docs/html/goodies/wallpaper/android-wallpaper1_1680x1050.png Binary files differnew file mode 100644 index 0000000..7ed9dca --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper1_1680x1050.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper1_1920x1200.png b/docs/html/goodies/wallpaper/android-wallpaper1_1920x1200.png Binary files differnew file mode 100644 index 0000000..74b937c --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper1_1920x1200.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper1_2560x1600.png b/docs/html/goodies/wallpaper/android-wallpaper1_2560x1600.png Binary files differnew file mode 100644 index 0000000..1fa8446 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper1_2560x1600.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper1_thumbnail.png b/docs/html/goodies/wallpaper/android-wallpaper1_thumbnail.png Binary files differnew file mode 100644 index 0000000..7c9b435 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper1_thumbnail.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper2_1024x768.png b/docs/html/goodies/wallpaper/android-wallpaper2_1024x768.png Binary files differnew file mode 100644 index 0000000..d3613e9 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper2_1024x768.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper2_1280x800.png b/docs/html/goodies/wallpaper/android-wallpaper2_1280x800.png Binary files differnew file mode 100644 index 0000000..f0ef459 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper2_1280x800.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper2_1440x900.png b/docs/html/goodies/wallpaper/android-wallpaper2_1440x900.png Binary files differnew file mode 100644 index 0000000..99b71f9 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper2_1440x900.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper2_1600x1200.png b/docs/html/goodies/wallpaper/android-wallpaper2_1600x1200.png Binary files differnew file mode 100644 index 0000000..4e145e7 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper2_1600x1200.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper2_1680x1050.png b/docs/html/goodies/wallpaper/android-wallpaper2_1680x1050.png Binary files differnew file mode 100644 index 0000000..eeb7508 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper2_1680x1050.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper2_1920x1200.png b/docs/html/goodies/wallpaper/android-wallpaper2_1920x1200.png Binary files differnew file mode 100644 index 0000000..ecabf82 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper2_1920x1200.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper2_2560x1600.png b/docs/html/goodies/wallpaper/android-wallpaper2_2560x1600.png Binary files differnew file mode 100644 index 0000000..cae1607 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper2_2560x1600.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper2_thumbnail.png b/docs/html/goodies/wallpaper/android-wallpaper2_thumbnail.png Binary files differnew file mode 100644 index 0000000..cac05de --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper2_thumbnail.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper3_1024x768.png b/docs/html/goodies/wallpaper/android-wallpaper3_1024x768.png Binary files differnew file mode 100644 index 0000000..18ccd88 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper3_1024x768.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper3_1280x800.png b/docs/html/goodies/wallpaper/android-wallpaper3_1280x800.png Binary files differnew file mode 100644 index 0000000..dffd997 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper3_1280x800.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper3_1440x900.png b/docs/html/goodies/wallpaper/android-wallpaper3_1440x900.png Binary files differnew file mode 100644 index 0000000..b62cae9 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper3_1440x900.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper3_1600x1200.png b/docs/html/goodies/wallpaper/android-wallpaper3_1600x1200.png Binary files differnew file mode 100644 index 0000000..7f4409b --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper3_1600x1200.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper3_1680x1050.png b/docs/html/goodies/wallpaper/android-wallpaper3_1680x1050.png Binary files differnew file mode 100644 index 0000000..5828234c --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper3_1680x1050.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper3_1920x1200.png b/docs/html/goodies/wallpaper/android-wallpaper3_1920x1200.png Binary files differnew file mode 100644 index 0000000..7e33515 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper3_1920x1200.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper3_2560x1600.png b/docs/html/goodies/wallpaper/android-wallpaper3_2560x1600.png Binary files differnew file mode 100644 index 0000000..d948b4e --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper3_2560x1600.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper3_thumbnail.png b/docs/html/goodies/wallpaper/android-wallpaper3_thumbnail.png Binary files differnew file mode 100644 index 0000000..abd2c92 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper3_thumbnail.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper4_1024x768.png b/docs/html/goodies/wallpaper/android-wallpaper4_1024x768.png Binary files differnew file mode 100644 index 0000000..536056d --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper4_1024x768.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper4_1280x800.png b/docs/html/goodies/wallpaper/android-wallpaper4_1280x800.png Binary files differnew file mode 100644 index 0000000..ba87529 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper4_1280x800.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper4_1440x900.png b/docs/html/goodies/wallpaper/android-wallpaper4_1440x900.png Binary files differnew file mode 100644 index 0000000..aa88c61 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper4_1440x900.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper4_1600x1200.png b/docs/html/goodies/wallpaper/android-wallpaper4_1600x1200.png Binary files differnew file mode 100644 index 0000000..cf10a81 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper4_1600x1200.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper4_1680x1050.png b/docs/html/goodies/wallpaper/android-wallpaper4_1680x1050.png Binary files differnew file mode 100644 index 0000000..00d19fc --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper4_1680x1050.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper4_1920x1200.png b/docs/html/goodies/wallpaper/android-wallpaper4_1920x1200.png Binary files differnew file mode 100644 index 0000000..3df19a9 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper4_1920x1200.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper4_2560x1600.png b/docs/html/goodies/wallpaper/android-wallpaper4_2560x1600.png Binary files differnew file mode 100644 index 0000000..4d693ef --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper4_2560x1600.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper4_thumbnail.png b/docs/html/goodies/wallpaper/android-wallpaper4_thumbnail.png Binary files differnew file mode 100644 index 0000000..f1a1841 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper4_thumbnail.png diff --git a/docs/html/goodies/wallpaper/android-wallpaper5_1024x768.jpg b/docs/html/goodies/wallpaper/android-wallpaper5_1024x768.jpg Binary files differnew file mode 100644 index 0000000..68bdee83 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper5_1024x768.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper5_1280x800.jpg b/docs/html/goodies/wallpaper/android-wallpaper5_1280x800.jpg Binary files differnew file mode 100644 index 0000000..fc441b8 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper5_1280x800.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper5_1440x900.jpg b/docs/html/goodies/wallpaper/android-wallpaper5_1440x900.jpg Binary files differnew file mode 100644 index 0000000..7f6bde8 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper5_1440x900.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper5_1600x1200.jpg b/docs/html/goodies/wallpaper/android-wallpaper5_1600x1200.jpg Binary files differnew file mode 100644 index 0000000..bb577bb --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper5_1600x1200.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper5_1680x1050.jpg b/docs/html/goodies/wallpaper/android-wallpaper5_1680x1050.jpg Binary files differnew file mode 100644 index 0000000..d28b06b --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper5_1680x1050.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper5_1920x1080.jpg b/docs/html/goodies/wallpaper/android-wallpaper5_1920x1080.jpg Binary files differnew file mode 100644 index 0000000..7239e51 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper5_1920x1080.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper5_1920x1200.jpg b/docs/html/goodies/wallpaper/android-wallpaper5_1920x1200.jpg Binary files differnew file mode 100644 index 0000000..862b5b6 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper5_1920x1200.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper5_2560x1600.jpg b/docs/html/goodies/wallpaper/android-wallpaper5_2560x1600.jpg Binary files differnew file mode 100644 index 0000000..7fc9a08 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper5_2560x1600.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper5_thumbnail.jpg b/docs/html/goodies/wallpaper/android-wallpaper5_thumbnail.jpg Binary files differnew file mode 100644 index 0000000..99f22f7 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper5_thumbnail.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper6_1024x768.jpg b/docs/html/goodies/wallpaper/android-wallpaper6_1024x768.jpg Binary files differnew file mode 100644 index 0000000..2074065 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper6_1024x768.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper6_1280x800.jpg b/docs/html/goodies/wallpaper/android-wallpaper6_1280x800.jpg Binary files differnew file mode 100644 index 0000000..d0fe49c --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper6_1280x800.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper6_1440x900.jpg b/docs/html/goodies/wallpaper/android-wallpaper6_1440x900.jpg Binary files differnew file mode 100644 index 0000000..52d3b4f --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper6_1440x900.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper6_1600x1200.jpg b/docs/html/goodies/wallpaper/android-wallpaper6_1600x1200.jpg Binary files differnew file mode 100644 index 0000000..b1b151e --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper6_1600x1200.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper6_1680x1050.jpg b/docs/html/goodies/wallpaper/android-wallpaper6_1680x1050.jpg Binary files differnew file mode 100644 index 0000000..d0f9c63 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper6_1680x1050.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper6_1920x1200.jpg b/docs/html/goodies/wallpaper/android-wallpaper6_1920x1200.jpg Binary files differnew file mode 100644 index 0000000..730ef98 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper6_1920x1200.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper6_2560x1600.jpg b/docs/html/goodies/wallpaper/android-wallpaper6_2560x1600.jpg Binary files differnew file mode 100644 index 0000000..eb80b5c --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper6_2560x1600.jpg diff --git a/docs/html/goodies/wallpaper/android-wallpaper6_thumbnail.jpg b/docs/html/goodies/wallpaper/android-wallpaper6_thumbnail.jpg Binary files differnew file mode 100644 index 0000000..eabfe71 --- /dev/null +++ b/docs/html/goodies/wallpaper/android-wallpaper6_thumbnail.jpg diff --git a/docs/html/guide/appendix/app-intents.jd b/docs/html/guide/appendix/app-intents.jd new file mode 100644 index 0000000..102183b --- /dev/null +++ b/docs/html/guide/appendix/app-intents.jd @@ -0,0 +1,106 @@ +page.title=Reference of Available Intents +@jd:body + +<p>This document describes the default applications and settings that Google provides + in their standard Android implementation. </p> +<h3>Intents handled by Google Android applications<a name="googleintents" id="googleintents"></a></h3> + <p> Android ships with Activities that handle the following Intent URI/Action pairs. </p> + <table width="100%" border="1"> + <tr> + <th scope="col">Scheme</th> + <th scope="col">Action<br /> + android.intent.action.<em>value</em></th> + <th scope="col">Description</th> + </tr> + <tr> + <td>http://<em>web_address</em><br /> + https://<em>web_address</em></td> + <td>VIEW</td> + <td>Open a browser window to the URL specified. </td> + </tr> + <tr> + <td>"" (empty string) <br /> + http://<em>web_address</em><br /> + https://<em>web_address</em></td> + <td>WEB_SEARCH</td> + <td>Opens the file at the location on the device in the browser. </td> + </tr> + <tr> + <td height="103">tel: <em>phone_number</em></td> + <td>CALL</td> + <td><p>Calls the entered phone number. Valid telephone numbers as defined + in <a href="http://tools.ietf.org/html/rfc3966">the IETF RFC 3966</a> are + accepted. Valid examples include the following:</p> + <ul> + <li>tel:2125551212 </li> + <li>tel: + (212) 555 1212</li> + </ul> + <p>The dialer is good at normalizing some kinds of schemes: for example + telephone numbers, so the schema described isn't strictly required + in the {@link android.net.Uri#parse(java.lang.String) + Uri(URI string)} factory. However, if you have not tried a + schema or are unsure whether it can be handled, use the {@link + android.net.Uri#fromParts(java.lang.String, java.lang.String, + java.lang.String) Uri.fromParts(scheme, ssp, fragment)} factory + instead.</p> + <p><strong><em>Note:</em></strong> This requires your + application to request the following permission in your manifest: <code><uses-permission + id="android.permission.CALL_PHONE" /></code></p></td> + </tr> + <tr> + <td><p>tel:<em>phone_number</em><br /> + voicemail:</p> </td> + <td>DIAL</td> + <td><p>Dials (but does not actually initiate the call) the number given + (or the stored voicemail on the phone). Telephone number normalization + described for CALL applies to DIAL as well. </p> </td> + </tr> + <tr> + <td>geo:<em>latitude</em>,<em>longitude</em><br /> + geo:<em>latitude</em>,<em>longitude</em>?z=<em>zoom</em><br /> + geo:0,0?q=<em>my+street+address</em><br /> + geo:0,0?q=<em>business+near+city</em><br /> + </td> + <td>VIEW</td> + <td>Opens the Maps application to the given location or query. The Geo URI scheme + (not fully supported) is <a href="http://tools.ietf.org/html/draft-mayrhofer-geo-uri-00">currently under + development</a>.<p> + The <em>z</em> field specifies the zoom level. A zoom level of 1 shows the whole Earth, centered at the + given <em>lat</em>,<em>lng</em>. A zoom level of 2 shows a quarter of the Earth, and so on. The highest + zoom level is 23. A larger zoom level will be clamped to 23. + </td> + </tr> + <tr> + <td>google.streetview:cbll=<em>lat</em>,<em>lng</em>&cbp=1,<em>yaw</em>,,<em>pitch</em>,<em>zoom</em>&mz=<em>mapZoom</em> + </td> + <td>VIEW</td> + <td>Opens the Street View application to the given location. The URI scheme is + based on the syntax used for Street View panorama information in Google Maps URLs.<p> + The cbll field is required. The cbp and mz fields are optional.<p> + <table border="1"> + <tr><th>Parameter</th><th>Description</th></tr> + <tr><td>lat</td><td>latitude</td></tr> + <tr><td>lng</td><td>longitude</td></tr> + <tr><td>yaw</td><td>Panorama center-of-view in degrees clockwise from North.<br /> + <b>Note:</b> The two commas after the yaw parameter are required. They are present + for backwards-compatibility reasons.</td></tr> + <tr><td>pitch</td><td>Panorama center-of-view in degrees from + -90 (look straight up) to 90 (look straight down.)</td></tr> + <tr><td>zoom</td><td>Panorama zoom. 1.0 = normal zoom, 2.0 = zoomed in 2x, 3.0 = zoomed in 4x, and so on.<br /> + A zoom of 1.0 is 90 degree horizontal FOV for a nominal + landscape mode 4 x 3 aspect ratio display. + Android phones in portrait mode will adjust the zoom so that + the vertical FOV is approximately the same as the landscape vertical + FOV. This means that the horizontal FOV of an Android phone in portrait + mode is much narrower than in landscape mode. This is done to minimize + the fisheye lens effect that would be present if a 90 degree horizontal + FOV was used in portrait mode.</td></tr> + <tr><td>mapZoom</td><td>The map zoom of the map location associated with this panorama. This value is passed on to the + Maps activity when the Street View "Go to Maps" menu item is chosen. It corresponds to the <em>z</em> paramaeter in + the geo: intent.</td></tr> + </table> + </td> + </tr> + </table> + <p></p> diff --git a/docs/html/guide/appendix/faq/commontasks.jd b/docs/html/guide/appendix/faq/commontasks.jd new file mode 100644 index 0000000..cdc7654 --- /dev/null +++ b/docs/html/guide/appendix/faq/commontasks.jd @@ -0,0 +1,969 @@ +page.title=Common Tasks and How to Do Them in Android +@jd:body + +<ul> + <li><a href="#neweclipseandroidproject">Creating an Android Application using + the Eclipse plugin</a></li> + <li><a href="#newandroidprojectnoeclipse">Creating an Android Application without + the Eclipse plugin</a></li> + <li><a href="#addexternallibrary">Adding an External Library (.jar) using Eclipse</a></li> + <li><a href="#implementcallbacks">Implementing Activity callbacks</a> (Android + calls your activity at various key moments in its life cycle. You must know + how to handle each of these to draw your screen, initialize class members, + and acquire data.)</li> + <li><a href="#opennewscreen">Opening a new screen</a></li> + <li><a href="#listening">Listening for button clicks </a></li> + <li><a href="#configurewindowproperties">Configuring general window properties </a></li> + <li><a href="#localhostalias">Referring to localhost from the emulated environment</a></li> + <li><a href="#appstate">Storing and retrieving state</a></li> + <li><a href="{@docRoot}devel/data/preferences.html">Storing and retrieving preferences</a></li> + <li><a href="#storingandretrieving">Storing and retrieving larger or more complex + persistent data</a> (files and data) </li> + <li><a href="#playback">Playing audio, video, still, or other media files</a></li> + <li><a href="#broadcastreceivers">Listening for and broadcasting global messages + and setting alarms</a></li> + <li><a href="#alerts">Displaying alerts </a></li> + <li><a href="#progressbar">Displaying a progress bar</a> </li> + <li><a href="#addmenuitems">Adding items to the screen menu</a> </li> + <li><a href="#webpage">Display a web page</a> </li> + <li><a href="#binding">Binding to data</a></li> + <li><a href="#handle">Getting a Handle to a Screen Element</a></li> + <li><a href="#captureimages">Capture images from the phone camera </a></li> + <li><a href="#threading">Handling expensive operations in the UI thread</a></li> + <li><a href="#selectingtext">Selecting, highlighting, or styling portions of + text</a></li> + <li><a href="#querymap">Utilizing attributes in a Map query</a></li> + <li><a href="#filelist">List of files for an Android application</a></li> + <li><a href="#logging">Print messages to a log file</a></li> +</ul> +<p>The ApiDemos sample application includes + many, many examples of common tasks and UI features. See the code inside samples/ApiDemos and + the other sample applications under the samples/ folder in the + SDK.</p> + +<a name="neweclipseandroidproject" id="neweclipseandroidproject"></a><h2>Creating an Android Application using the Eclipse Plugin</h2> +<p>Using the Android Eclipse plugin is the fastest and easiest way +to start creating a new Android application. The plugin automatically generates +the correct project structure for your application, and keeps the resources +compiled for you automatically.</p> +<p>It is still a good idea to know what is going on though. Take a look at +<a href="{@docRoot}intro/anatomy.html">Overview of an Android Application</a> to understand +the basics of how an Android application works.</p> +<p>It is also recommended that you take a look at the +ApiDemos application and the other +sample applications in the samples/ folder in the SDK.</p> +<p>Finally, a great way to started with Android development in Eclipse is to +follow both the <a href="{@docRoot}intro/hello-android.html">Hello Android</a> and +<a href="{@docRoot}intro/tutorial.html">Notepad</a> code tutorials. In particular, the start +of the Hello Android tutorial is an excellent introduction to creating a new +Android application in Eclipse.</p> + +<a name="newandroidprojectnoeclipse" id="newandroidprojectnoeclipse"></a><h2>Creating an Android Application without the Eclipse Plugin</h2> +<p>This topic describes the manual steps in creating an Android application. + Before reading this, you should read <a href="{@docRoot}intro/anatomy.html">Overview of an Android + Application</a> to understand the basics of how an Android application works. + You might also want to look at the sample applications that ship with Android + under the samples/ directory. </p> +<p>Here is a list of the basic steps in building an application.</p> +<ol> + <li><strong>Create your required resource files</strong> This includes + the AndroidManifest.xml global description file, string files that your application + needs, and layout files describing your user interface. A full list of optional + and required files and syntax details for each is given in <a href="#filelist">File + List for an Android Application</a>. </li> + <li><strong>Design your user interface</strong> See <a href="{@docRoot}devel/implementing-ui.html">Implementing + a UI</a> for details on elements of the Android screen. </li> + <li><strong>Implement your Activity </strong>(this page)<strong> </strong> You + will create one class/file for each screen in your application. Screens will + inherit from an {@link android.app android.app} class, typically {@link android.app.Activity + android.app.Activity} for basic screens, {@link android.app.ListActivity + android.app.ListActivity} for list screens, or {@link android.app.Dialog + android.app.Dialog} for dialog boxes. You will implement the required callbacks + that let you draw your screen, query data, and commit changes, and also perform + any required tasks such as opening additional screens or reading data from + the device. Common tasks, such as opening a new screen or reading data from + the device, are described below. + The list of files you'll need for your application are described in <a href="#filelist">List + of Files for an Android Application</a>. </li> + <li><strong><a href="{@docRoot}intro/installing.html#building">Build and install your + package</a>.</strong> The Android SDK has some nice tools for generating + projects and debugging code. </li> +</ol> + +<a name="addexternallibrary" id="addexternallibrary"></a><h2>Adding an External Library (.jar) using Eclipse</h2> +<p> +You can use a third party JAR in your application by adding it to your Eclipse project as follows: +</p> +<ol> +<li> +In the <strong>Package Explorer</strong> panel, right-click on your project and select <strong>Properties</strong>. +<li> +Select <strong>Java Build Path</strong>, then the tab <strong>Libraries</strong>. +<li> +Press the <strong>Add External JARs...</strong> button and select the JAR file. +</ol> +<p> +Alternatively, if you want to include third party JARs with your package, create a new directory for them within your project and select <strong>Add Library...</strong> instead.</p> +<p> +It is not necessary to put external JARs in the assets folder. +</p> + +<a name="implementcallbacks" id="implementcallbacks"></a><h2>Implementing Activity Callbacks</h2> +<p>Android calls a number of callbacks to let you draw your screen, store data before + pausing, and refresh data after closing. You must implement at least some of + these methods. See <a href="{@docRoot}intro/lifecycle.html">Lifetime of a Screen</a> to learn + when and in what order these methods are called. Here are some of the standard types of screen classes that Android provides:</p> +<ul> + <li>{@link android.app.Activity android.app.Activity} - This is a standard screen, + with no specialization.</li> + <li>{@link android.app.ListActivity android.app.ListActivity} - This is a screen + that is used to display a list of something. It hosts a ListView object, + and exposes methods to let you identify the selected item, receive callbacks + when the selected item changes, and perform other list-related actions. </li> + <li>{@link android.app.Dialog android.app.Dialog} - This is a small, popup dialog-style + window that isn't intended to remain in the history stack. (It is not resizeable + or moveable by the user.)</li> +</ul> + +<a name="opennewscreen" id="opennewscreen"></a><h2>Opening a New Screen</h2> +<p>Your Activity will often need to open another Activity screen as it progresses. + This new screen can be part of the same application or part of another application, + the new screen can be floating or full screen, it can return a result, and you + can decide whether to close this screen and remove it from the history stack + when you are done with it, or to keep the screen open in history. These next + sections describe all these options. </p> +<h3>Floating or full?<a name="floatingorfull" id="floatingorfull"></a></h3> +<p>When you open a new screen you can decide whether to make it transparent or floating, + or full-screen. The choice of new screen affects the event sequence of events + in the old screen (if the new screen obscures the old screen, a different series + of events is called in the old screen). See <a href="{@docRoot}intro/lifecycle.html">Lifetime + of an Activity</a> for details. </p> +<p>Transparent or floating windows are implemented in three standard ways: </p> +<ul> + <li>Create an {@link android.app.Dialog app.Dialog} class </li> + <li>Create an {@link android.app.AlertDialog app.AlertDialog} class </li> + <li>Set the {@link android.R.style#Theme_Dialog} <em>theme</em> attribute to <code>@android:style/Theme.Dialog</code> + in your AndroidManifest.xml file. For example: +</ul> +<blockquote> + <pre><activity class="AddRssItem" android:label="Add an item" android:theme="@android:style/Theme.Dialog"/> +</pre> +</blockquote> +<p>Calling startActivity() or startActivityForResult() will open a new screen in whatever + way it defines itself (if it uses a floating theme it will be floating, + otherwise it will be full screen). </p> +<h3>Opening a Screen </h3> +<p>When you want to open a new screen, you can either explicitly specify the activity + class to open, or you can let the operating system decide which screen to open, + based upon the data and various parameters you pass in. A screen is opened by + calling {@link android.app.Activity#startActivity(android.content.Intent) startActivity} + and passing in an {@link android.content.Intent Intent} object, which specifies + the criteria for the handling screen. To specify a specific screen, call Intent.setClass + or setClassName with the exact activity class to open. Otherwise, set a variety + of values and data, and let Android decide which screen is appropriate to open. + Android will find one or zero Activities that match the specified requirements; + it will never open multiple activities for a single request. More information + on Intents and how Android resolves them to a specific class is given in the + {@link android.content.Intent Intent} topic. </p> +<a name="intentexamples" id="intentexamples"></a><h3>Some Intent examples </h3> +<p>The following snippet loads the com.android.samples.Animation1 class, and + passes it some arbitrary data.:</p> +<pre>Intent myIntent = new Intent(); +myIntent.setClassName("com.android.samples", "com.android.samples.Animation1"); +myIntent.putExtra("com.android.samples.SpecialValue", "Hello, Joe!"); // key/value pair, where key needs current package prefix. +startActivity(myIntent); </pre> +<p>The next snippet requests that a Web page be opened by specifying the VIEW action, + and a URI data string starting with "http://" schema:</p> +<pre>Intent myIntent = new Intent(Intent.VIEW_ACTION, Uri.parse("http://www.google.com"));</pre> +<p>Here is the intent filter from the AndroidManifest.xml file for com.android.browser:</p> +<pre><intent-filter> + <action android:name="android.intent.action.VIEW" /> + <category android:name="android.intent.category.DEFAULT" /> + <scheme android:name="http" /> + <scheme android:name="https" /> + <scheme android:name="file" /> +</intent-filter> </pre> +<p>Android defines a number of standard values, for instance the action constants + defined by {@link android.content.Intent}. You can define custom values, but + both the caller and handler must use them. See the <intent-filter> + tag description in <a href="{@docRoot}devel/bblocks-manifest.html">AndroidManifest.xml + File Details</a> for more information on the manifest syntax for the handling + application. </p> +<a name="returningaresult" id="returningaresult"></a><h3>Returning a Result from a Screen</h3> +<p>A window can return a result after it closes. This result will be passed back + into the calling Activity's {@link android.app.Activity#onActivityResult(int,int,android.content.Intent) + onActivityResult()} method, which can supply an Intent containing arbitrary data, along with + the request code passed to startActivityForResult(). Note that you must call the {@link + android.app.Activity#startActivityForResult(android.content.Intent,int) startActivityForResult()} + method that accepts a request code parameter to get this callback. The following + code demonstrates opening a new screen and retrieving a result. </p> +<pre>// Open the new screen. +public void onClick(View v){ + // Start the activity whose result we want to retrieve. The + // result will come back with request code GET_CODE. + Intent intent = new Intent(this, com.example.app.ChooseYourBoxer.class); + startActivityForResult(intent, CHOOSE_FIGHTER); +} + +// Listen for results. +protected void onActivityResult(int requestCode, int resultCode, Intent data){ + // See which child activity is calling us back. + switch (resultCode) { + case CHOOSE_FIGHTER: + // This is the standard resultCode that is sent back if the + // activity crashed or didn't doesn't supply an explicit result. + if (resultCode == RESULT_CANCELED){ + myMessageboxFunction("Fight cancelled"); + } + else { + myFightFunction(data); + } + default: + break; + } +} + +// Class SentResult +// Temporary screen to let the user choose something. + private OnClickListener mLincolnListener = new OnClickListener(){ + public void onClick(View v) { + Bundle stats = new Bundle(); + stats.putString("height","6\'4\""); + stats.putString("weight", "190 lbs"); + stats.putString("reach", "74\""); + setResult(RESULT_OK, "Lincoln", stats); + finish(); + } + }; + + private OnClickListener mWashingtonListener = new OnClickListener() { + public void onClick(View v){ + Bundle stats = new Bundle(); + stats.putString("height","6\'2\""); + stats.putString("weight", "190 lbs"); + stats.putString("reach", "73\""); + setResult(RESULT_OK, "Washington", Bundle); + finish(); + } + }; +</pre> +<h3>Lifetime of the new screen </h3> +<p>An activity can remove itself from the history stack by calling {@link android.app.Activity#finish() + Activity.finish()} on itself, or the activity that opened the screen can call + {@link android.app.Activity#finishActivity(int) Activity.finishActivity()} + on any screens that it opens to close them. </p> +<a name="listening" id="listening"></a><h2>Listening for Button Clicks</h2> +<p>Button click and other UI event capturing are covered in <a href="{@docRoot}devel/ui/notifications.html">Listening + for UI Notifications</a> on the UI Design page.</p> +<a name="configurewindowproperties" id="configurewindowproperties"></a><h2>Configuring General Window Properties</h2> +<p>You can set a number of general window properties, such as whether to display + a title, whether the window is floating, and whether it displays an icon, by + calling methods on the {@link android.view.Window Window} member + of the underlying View object for the window. Examples include calling {@link + android.app.Activity#getWindow() getWindow().requestFeature()} (or the convenience + method {@link android.app.Activity#requestWindowFeature(int) requestWindowFeature(<em>some_feature</em>)}) + to hide the title. Here is an example of hiding the title bar:</p> +<pre>//Hide the title bar +requestWindowFeature(Window.FEATURE_NO_TITLE); +</pre> +<a name="localhostalias" id="localhostalias"></a><h2>Referring to localhost from the emulated environment</h2> +<p> +If you need to refer to your host computer's <em>localhost</em>, such as when you +want the emulator client to contact a server running on the same host, use the alias +<code>10.0.2.2</code> to refer to the host computer's loopback interface. +From the emulator's perspective, localhost (<code>127.0.0.1</code>) refers to its own +loopback interface. +</p> +<a name="appstate" id="appstate"></a><h2>Storing and Retrieving State</h2> +<p>If your application is dumped from memory because of space concerns, it will lose + all user interface state information such as checkbox state and text box values + as well as class member values. Android calls {@link android.app.Activity#onSaveInstanceState(android.os.Bundle) + Activity.onSaveInstanceState} before it pauses the application. This method hands in a {@link + android.os.Bundle Bundle} that can be used to store name/value pairs that will + persist and be handed back to the application even if it is dropped from memory. + Android will pass this Bundle back to you when it calls {@link android.app.Activity#onCreate(android.os.Bundle) + onCreate()}. This Bundle only exists while the application is still in the history + stack (whether or not it has been removed from memory) and will be lost when + the application is finalized. See the topics for {@link android.app.Activity#onSaveInstanceState} and + {@link android.app.Activity#onCreate} for + examples of storing and retrieving state.</p> +<p>Read more about the life cycle of an application in <a href="{@docRoot}intro/lifecycle.html">Lifetime + of an Activity</a>.</p> +<h3>Storing and Retrieving Larger or More Complex Persistent Data<a name="storingandretrieving" id="storingandretrieving"></a></h3> +<p>Your application can store files or complex collection objects, and reserve them + for private use by itself or other activities in the application, or it can expose + its data to all other applications on the device. See <a href="{@docRoot}devel/data.html">Storing, + Retrieving, and Exposing Data</a> to learn how to store and retrieve private data, + how to store and retrieve common data from the device, and how to expose your + private data to other applications.</p> +<a name="playback" id="playback"></a><h2>Playing Media Files</h2> +<p>Please see the document <a href="{@docRoot}toolbox/apis/media.html">Android +Media APIs</a> for more details.</p> +<a name="broadcastreceivers" id="broadcastreceivers"></a><h2>Listening For and Broadcasting Global Messages, and Setting Alarms</h2> +<p>You can create a listening class that can be notified or even instantiated whenever + a specific type of system message is sent. +</p> +<p>The listening classes, called broadcast receivers, extend {@link android.content.BroadcastReceiver + BroadcastReceiver}. If you want Android to instantiate the object whenever an appropriate + intent notification is sent, define the receiver with a <code><receiver></code> element + in the AndroidManifext.xml file. If the caller is expected to instantiate the + object in preparation to receive a message, this is not required. The receiver + will get a call to their {@link android.content.BroadcastReceiver#onReceive(android.content.Context,android.content.Intent) + BroadcastReceiver.onReceive()} method. A receiver can define an <code><intent-filter></code> tag + that describes the types of messages it will receive. Just as Android's IntentResolver + will look for appropriate Activity matches for a startActivity() call, it will + look for any matching Receivers (but it will send the message to all matching + receiver, not the "best" match). </p> +<p>To send a notification, the caller creates an {@link android.content.Intent Intent} + object and calls {@link android.app.Activity#sendBroadcast(android.content.Intent) + Context.sendBroadcast()} with that Intent. Multiple recipients can receive + the same message. You can broadcast an Intent message to an intent receiver in + any application, not only your own. If the receiving class is not registered + using <code><receiver></code> in its manifest, you can dynamically instantiate + and register a receiver by calling {@link android.content.Context#registerReceiver(android.content.BroadcastReceiver,android.content.IntentFilter) + Context.registerReceiver()}. </p> +<p>Receivers can include intent filters to specify what kinds of intents they are + listening for. Alternatively, if you expect a single known caller to contact + a single known receiver, the receiver does not specify an intent filter, and + the caller specifies the receiver's class name in the Intent by calling {@link + android.content.Intent#setClassName(java.lang.String, java.lang.String) Intent.setClassName()} + with the recipient's class name. The recipient receives a {@link android.content.Context + Context} object that refers to its own package, not to the package of the sender.</p> +<p><em><strong>Note:</strong></em> If a receiver or broadcaster + enforces permissions, your application might need to request permission + to send or receive messages from that object. You can request permission by using + the {@link android.R.styleable#AndroidManifestUsesPermission <uses-permission>} + tag in the manifest. </p> +<p>Here is a code snippet of a sender and receiver. This example does not demonstrate + registering receivers dynamically. For a full code example, see the AlarmService + class in the ApiDemos project.</p> +<h3>Sending the message</h3> +<pre>// We are sending this to a specific recipient, so we will +// only specify the recipient class name. +Intent intent = new Intent(this, AlarmReceiver.class); +intent.putExtra("message","Wake up."); +sendBroadcast(intent); +</pre> +<h3>Receiving the message</h3> +<p><strong>Receiver AndroidManifest.xml </strong>(because there is no intent filter + child, this class will only receive a broadcast when the receiver class is specified + by name, as is done in this example):</p> +<pre> +<receiver class=".AlarmReceiver" /></pre> +<p><strong>Receiver Java code: </strong></p> +<pre> +public class AlarmReceiver extends BroadcastReceiver{ + // Display an alert that we've received a message. + @Override + public void onReceive(Context context, Intent intent){ + // Send a text notification to the screen. + NotificationManager nm = (NotificationManager) + context.getSystemService(Context.NOTIFICATION_SERVICE); + nm.notifyWithText(R.id.alarm, + "Alarm!!!", + NotificationManager.LENGTH_SHORT, + null); + } +} </pre> +<h3>Other system messages</h3> +<p>You can listen for other system messages sent by Android as well, such as USB + connection/removal messages, SMS arrival messages, and timezone changes. See + {@link android.content.Intent} for a list of broadcast messages to listen for. + Messages are marked "Broadcast Action" in the documentation. </p> +<h3>Listening for phone events<a name="phoneevents" id="phoneevents"></a></h3> +<p>The {@link android.telephony android.telephony} package overview page describes how to + register to listen for phone events. </p> +<a name="alarms" id="alarms"></a><h3>Setting Alarms </h3> +<p>Android provides an {@link android.app.AlarmManager AlarmManager} service that + will let you specify an Intent to send at a designated time. This intent is typically + used to start an application at a preset time. (Note: If you want to send + a notification to a sleeping or running application, use {@link android.os.Handler + Handler} instead.)</p> +<a name="alerts" id="alerts"></a><h2>Displaying Alerts</h2> +<p>There are two major kinds of alerts that you may display to the user: +(1) Normal alerts are displayed in response to a user action, such as +trying to perform an action that is not allowed. (2) Out-of-band alerts, +called notifications, are +displayed as a result of something happening in the background, such as the +user receiving new e-mail.</p> + +<a name="dialogsandalerts" id="dialogsandalerts"></a><h3>Normal Alerts</h3> + +<p>Android provides a number of ways for you to show popup notifications to your + user as they interact with your application. </p> +<table width="100%" border="1"> + <tr> + <th scope="col">Class</th> + <th scope="col">Description</th> + </tr> + <tr> + <td>{@link android.app.Dialog app.Dialog}</td> + <td>A generic floating dialog box with a layout that you design. </td> + </tr> + <tr> + <td><p>{@link android.app.AlertDialog app.AlertDialog}</p></td> + <td>A popup alert dialog with two buttons (typically OK and Cancel) that + take callback handlers. See the section after this table for more details. </td> + </tr> + <tr> + <td>{@link android.app.ProgressDialog ProgressDialog} </td> + <td>A dialog box used to indicate progress of an operation with a known progress + value or an indeterminate length (setProgress(bool)). See <strong>Views</strong> > <strong>Progress Bar</strong> in + ApiDemos for examples. </td> + </tr> + <tr> + <td>Activity</td> + <td>By setting the theme of an activity to + {@link android.R.style#Theme_Dialog + android:theme="android:style/Theme.Dialog"}, + your activity will take on + the appearance of a normal dialog, floating on top of whatever was + underneath it. You usually set the theme through the + {@link android.R.attr#theme android:theme} attribute in your AndroidManifest.xml. + The advantage of this + over Dialog and AlertDialog is that Application has a much better managed + life cycle than dialogs: if a dialog goes to the background and is killed, + you cannot recapture state, whereas Application exposes a {@link android.os.Bundle + Bundle} of saved values in <code>onCreate()</code> to help you maintain state.</td> + </tr> +</table> +<h3>AlertDialog</h3> +<p>This is a basic warning dialog box that lets you configure a message, button text, + and callback. You can create one by calling using the {@link + android.app.AlertDialog.Builder} class, as shown here. </p> +<pre>private Handler mHandler = new Handler() { + public void handleMessage(Message msg) { + switch (msg.what) { + case ACCEPT_CALL: + answer(msg.obj); + break; + + case BOUNCE_TO_VOICEMAIL: + voicemail(msg.obj); + break; + + } + } +}; + + +private void IncomingMotherInlawCall(Connection c) { + String Text; + + // "Answer" callback. + Message acceptMsg = Message.obtain(); + acceptMsg.target = mHandler; + acceptMsg.what = ACCEPT_CALL; + acceptMsg.obj = c.getCall(); + + // "Cancel" callback. + final Message rejectMsg = Message.obtain(); + rejectMsg.target = mHandler; + rejectMsg.what = BOUNCE_TO_VOICEMAIL; + rejectMsg.obj = c.getCall(); + + new AlertDialog.Builder(this) + .setMessage("Phyllis is calling") + .setPositiveButton("Answer", acceptMsg) + .setOnCanceListener(new OnCancelListener() { + public void onCancel(DialogInterface dialog) { + rejectMsg.sendToTarget(); + }}); + .show(); +} </pre> + +<h3>Notifications</h3> + +<p>Out-of-band alerts should always be displayed using the +{@link android.app.NotificationManager}, which allows you to tell the user +about something they may be interested in without disrupting what they are +currently doing. A notification can be anything from a brief pop-up box +informing the user of the new information, through displaying a persistent +icon in the status bar, to vibrating, playing sounds, or flashing lights to +get the user's attention. In all cases, the user must explicitly shift their +focus to the notification before they can interact with it.</p> + +<p>The following code demonstrates using NotificationManager to display a basic text + popup when a new SMS message arrives in a listening service, and provides the + current message count. You can see several more examples in the ApiDemos application, + under app/ (named <em>notification</em>*.java).</p> +<pre>static void setNewMessageIndicator(Context context, int messageCount){ + // Get the static global NotificationManager object. + NotificationManager nm = NotificationManager.getDefault();</p> + + // If we're being called because a new message has been received, + // then display an icon and a count. Otherwise, delete the persistent + // message. + if (messageCount > 0) { + nm.notifyWithText(myApp.NOTIFICATION_GUID, // ID for this notification. + messageCount + " new message" + messageCount > 1 ? "s":"", // Text to display. + NotificationManager.LENGTH_SHORT); // Show it for a short time only. + } +}</pre> +<p>To display a notification in the status bar and have it launch an intent when + the user selects it (such as the new text message notification does), call {@link + android.app.NotificationManager#notify(int, android.app.Notification) NotificationManager.notify()}, + and pass in vibration patterns, status bar icons, or Intents to associate with + the notification. </p> +<a name="progressbar" id="progressbar"></a><h2>Displaying a Progress Bar</h2> +<p>An activity can display a progress bar to notify the user that something is happening. + To display a progress bar in a screen, call {@link android.app.Activity#requestWindowFeature(int) + Activity.requestWindowFeature(Window.FEATURE_PROGRESS)}. To set the value + of the progress bar, call {@link android.view.Window#setFeatureInt(int,int) + Activity.getWindow().setFeatureInt(Window.FEATURE_PROGRESS, <em>level</em>)}. + Progress bar values are from 0 to 9,999, or set the value to 10,000 to make the + progress bar invisible. </p> +<p>You can also use the {@link android.app.ProgressDialog ProgressDialog} class, + which enables a dialog box with an embedded progress bar to send a "I'm working + on it" notification to the user. </p> +<a name="addmenuitems" id="addmenuitems"></a><h2>Adding Items to the Screen Menu</h2> +<p>Every Android screen has a default menu with default options, such as adding the + activity to the favorites menu. You can add your own menu entries to the default + menu options by implementing {@link android.app.Activity#onCreateOptionsMenu(android.view.Menu) + Activity.onCreateOptionsMenu} or {@link android.app.Activity#onPrepareOptionsMenu(android.view.Menu) + Activity.onPrepareOptionsMenu()}, and adding {@link android.view.MenuItem Item} + objects to the {@link android.view.Menu Menu} passed in. To handle clicks + implement {@link android.app.Activity#onOptionsItemSelected(android.view.MenuItem) + Activity.onOptionsItemSelected()} to handle the click in your Activity class. + You may also pass the Item object a handler class that implements the + Runnable class (a handler) but this is less efficient and discouraged.</p> +<p>An application receives a callback at startup time to enable it to populate its + menu. Additionally, it receives callbacks each time the user displays the options + menu to let you perform some contextual modifications on the menu. To populate + the menu on startup, override {@link android.app.Activity#onCreateOptionsMenu(android.view.Menu) + Activity.onCreateOptionsMenu}; to populate it when the menu is called (somewhat + less efficient), you can override {@link android.app.Activity#onPrepareOptionsMenu(android.view.Menu) + Activity.onPrepareOptionsMenu()}. Each Activity has its own menu list.</p> +<p>Menu items are displayed in the order added, though you can group them as described + in the {@link android.view.Menu#add Menu.add} documentation. + The following code snippet adds three items to the default menu options and handles + them through the overridden Activity.onOptionsItemSelected() method. + You can show or hide menu items by calling {@link android.view.MenuItem#setVisible( + boolean) setVisible()} or {@link android.view.Menu#setGroupVisible(int, + boolean) setGroupVisible()}. +</p> +</p> +<pre>// Called only the first time the options menu is displayed. +// Create the menu entries. +// Menu adds items in the order shown. +@Override +public boolean onCreateOptionsMenu(Menu menu) { + super.onCreateOptionsMenu(menu); + + // Parameters for menu.add are: + // group -- Not used here. + // id -- Used only when you want to handle and identify the click yourself. + // title + menu.add(0, 0, "Zoom"); + menu.add(0, 1, "Settings"); + menu.add(0, 2, "Other"); + return true; +} + +// Activity callback that lets your handle the selection in the class. +// Return true to indicate that you've got it, false to indicate +// that it should be handled by a declared handler object for that +// item (handler objects are discouraged for reasons of efficiency). +@Override +public boolean onOptionsItemSelected(MenuItem item){ + switch (item.getId()) { + case 0: + showAlert("Menu Item Clicked", "Zoom", "ok", null, false, null); + return true; + case 1: + showAlert("Menu Item Clicked", "Settings", "ok", null, false, null); + return true; + case 2: + showAlert("Menu Item Clicked", "Other", "ok", null, false, null); + return true; + } + return false; +} +</pre> +<a name="menukeyshortcuts" id="menukeyshortcuts"></a> +<p>You can add key shortcuts by calling the + MenuItem.setAlphabeticShortcut() or + MenuItem.setNumericShortcut() methods, as demonstrated here to add a "c" shortcut + to a menu item:</p> +<pre>thisItem.setAlphabeticShortcut('c'); </pre> +<h3>Adding Submenus<a name="submenus" id="submenus"></a></h3> +<p>Add a submenu by calling {@link android.view.Menu#addSubMenu + Menu.addSubMenu()}, which returns a SubMenu object. You can then add additional + items to this menu. Menus can only be one level deep, and you can customize the + appearance of the submenu menu item. </p> +<pre> +@Override +public boolean onCreateOptionsMenu(Menu menu) { + super.onCreateOptionsMenu(menu); + + // Parameters for menu.add are: + // group -- Not used here. + // id -- Used only when you want to handle and identify the click yourself. + // title + menu.add(0, 0, "Send message"); + menu.add(0, 1, "Settings"); + menu.add(0, 2, "Local handler"); + menu.add(0, 3, "Launch contact picker"); + + // Add our submenu. + SubMenu sub = menu.addSubMenu(1, 4, "Days of the week"); + sub.add(0, 5, "Monday"); + sub.add(0, 6, "Tuesday"); + sub.add(0, 7, "Wednesday"); + sub.add(0, 8, "Thursday"); + sub.add(0, 9, "Friday"); + sub.add(0, 10, "Saturday"); + sub.add(0, 11, "Sunday"); + return true; +} +</pre> +<h3><strong>Adding yourself to menus on other applications</strong></h3> +<a name="addingtoothermenus" id="addingtoothermenus"></a> +<p>You can also advertise your Activity's services so that other Activities can add + your activity to their own option menu. For example, suppose you implement a + new image handling tool that shrinks an image to a smaller size + and you would like to offer this as a menu option to any other Activity that + handles pictures. To do this, you would exposes your capabilities inside an intent + filter in your manifest. If another application that handles photos asks Android + for any Activities that can perform actions on pictures, Android will perform + intent resolution, find your Activity, and add it to the other Activity's options + menu. </p> +<h4><strong>The offering application </strong></h4> +<p>The application offering the service must include an <code><intent-filter></code> element + in the manifest, inside the <code><activity></code> tag of the offering + Activity. The intent filter includes all the details describing what it can do, + such as a <code><type></code> element that describes the MIME type of data + that it can handle, a custom <code><action></code> value that describes + what your handling application can do (this is so that when it receives the Intent + on opening it knows what it is expected to do), and most important, include a <code><category></code> filter + with the value <code>android.intent.category.ALTERNATIVE </code>and/or <code>android.intent.category.SELECTED_ALTERNATIVE</code> (SELECTED_ALTERNATIVE + is used to handle only the currently selected element on the screen, rather than + the whole Activity intent.</p> +<p>Here's an example of a snip of a manifest that advertises picture shrinking technology + for both selected items and the whole screen. </p> +<pre><activity class="PictureShrink"> <!-- Handling class --> + <intent-filter label="Shrink picture"> <!-- Menu label to display --> + <action android:name="com.example.sampleapp.SHRINK_IT" /> + <data android:name="image/*" /> <!-- MIME type for generic images --> + <category android:name="android.intent.category.ALTERNATIVE " /> + <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> + </intent-filter> +</activity></pre> +<h4><strong>The menu-displaying application</strong></h4> +<p>An application that wants to display a menu that includes any additional external + services must, first of all, handle its menu creation callback. As part of that + callback it creates an intent with the category Intent.ALTERNATIVE_CATEGORY and/or + Intent.SELECTED_ALTERNATIVE, the MIME type currently selected, and any other + requirements, the same way as it would satisfy an intent filter to open a new + Activity. It then calls menu.addIntentOptions() to have Android search for and + add any services meeting those requirements. It can optionally add additional + custom menu items of its own. </p> +<p>You should implement SELECTED_ALTERNATIVE in onPrepareOptionsMenu() rather than + onCreateOptionsMenu(), because the user's selection can change after the application + is launched. </p> +<p>Here's a code snippet demonstrating how a picture application would search for + additional services to display on its menu.</p> +<pre>@Override public boolean +onCreateOptionsMenu(Menu menu){ + super.onCreateOptionsMenu(menu); + + // Create an Intent that describes the requirements to fulfill to be included + // in our menu. The offering app must include a category value of Intent.ALTERNATIVE_CATEGORY. + Intent intent = new Intent(null, getIntent().getData()); + intent.addCategory(Intent.ALTERNATIVE_CATEGORY); + + // Search for, and populate the menu with, acceptable offering applications. + menu.addIntentOptions( + 0, // Group + 0, // Any unique IDs we might care to add. + MySampleClass.class.getName(), // Name of the class displaying the menu--here, its this class. + null, // No specifics. + intent, // Previously created intent that describes our requirements. + 0, // No flags. + null); // No specifics. + + return true; +}</pre> +<p> </p> +<a name="webpage" id="webpage"></a><h2>Display a Web Page</h2> +<p>Use the {@link android.webkit.WebView webkit.WebView} object. </p> +<a name="binding" id="binding"></a><h2>Binding to Data</h2> +<p>You can bind a ListView to a set of underlying data by using a shim class called + {@link android.widget.ListAdapter ListAdapter} (or a subclass). ListAdapter subclasses + bind to a variety of data sources, and expose a common set of methods such as + getItem() and getView(), and uses them to pick View items to display in its list. + You can extend ListAdapter and override getView() to create your own custom list + items. There are essentially only two steps you need to perform to bind to data: </p> +<ol> + <li>Create a ListAdapter object and specify its data source</li> + <li>Give the ListAdapter to your ListView object.</li> +</ol> +<p>That's it!</p> +<p>Here's an example of binding a ListActivity screen to the results from a cursor + query. (Note that the setListAdapter() method shown is a convenience method that + gets the page's ListView object and calls setAdapter() on it.)</p> +<pre>// Run a query and get a Cursor pointing to the results. +Cursor c = People.query(this.getContentResolver(), null); +startManagingCursor(c); + +// Create the ListAdapter. A SimpleCursorAdapter lets you specify two interesting things: +// an XML template for your list item, and +// The column to map to a specific item, by ID, in your template. +ListAdapter adapter = new SimpleCursorAdapter(this, + android.R.layout.simple_list_item_1, // Use a template that displays a text view + c, // Give the cursor to the list adapter + new String[] {People.NAME} , // Map the NAME column in the people database to... + new String[] {"text1"}); // The "text1" view defined in the XML template +setListAdapter(adapter);</pre> +<p>See view/List4 in the ApiDemos project for an example of extending ListAdapter + for a new data type. </p> + +<a name="handle"></a> + +<h2>Getting a Handle to a Screen Element</h2> +<p>You can get a handle to a screen element by calling {@link +android.app.Activity#findViewById(int) Activity.findViewById}. You can then use +the handle to set or retrieve any values exposed by the object. </p> +<a name="captureimages" id="captureimages"></a><h2>Capture Images from the Phone Camera</h2> +<p>You can hook into the device's camera onto your own Canvas object by using the + {@link android.hardware.Camera Camera} class. See that class's documentation, + and the ApiDemos project's Camera Preview application (Graphics/Camera Preview) + for example code. </p> + + +<a name="threading" id="threading"></a><h2>Handling Expensive Operations in the UI Thread</h2> +<p>Avoid performing long-running operations (such as network I/O) directly in the UI thread — +the main thread of an application where the UI is run — or your application may be blocked +and become unresponsive. Here is a brief summary of the recommended approach for handling expensive operations:</p> +<ol> +<li>Create a Handler object in your UI thread</li> +<li>Spawn off worker threads to perform any required expensive operations</li> +<li>Post results from a worker thread back to the UI thread's handler either through a Runnable or a {@link android.os.Message}</li> +<li>Update the views on the UI thread as needed</li> +</ol> + +<p>The following outline illustrates a typical implementation:</p> + +<pre> +public class MyActivity extends Activity { + + [ . . . ] + // Need handler for callbacks to the UI thread + final Handler mHandler = new Handler(); + + // Create runnable for posting + final Runnable mUpdateResults = new Runnable() { + public void run() { + updateResultsInUi(); + } + }; + + @Override + protected void onCreate(Bundle icicle) { + super.onCreate(icicle); + + [ . . . ] + } + + protected void startLongRunningOperation() { + + // Fire off a thread to do some work that we shouldn't do directly in the UI thread + Thread t = new Thread() { + public void run() { + mResults = doSomethingExpensive(); + mHandler.post(mUpdateResults); + } + }; + t.start(); + } + + private void updateResultsInUi() { + + // Back in the UI thread -- update our UI elements based on the data in mResults + [ . . . ] + } +} +</pre> + +<p>For further discussions on this topic, see +<a href="{@docRoot}toolbox/responsiveness.html">Developing Responsive Applications</a> +and the {@link android.os.Handler} documentation.</p> + +<a name="selectingtext" id="selectingtext"></a><h2>Selecting, Highlighting, or Styling Portions of Text</h2> +<p>You can highlight or style the formatting of strings or substrings of text in + a TextView object. There are two ways to do this:</p> +<ul> + <li>If you use a <a href="{@docRoot}reference/available-resources.html#stringresources">string resource</a>, + you can add some simple styling, such as bold or italic using HTML notation. + The currently supported tags are: <code>B</code> (bold), + <code>I</code> (italic), <code>U</code> (underline), + <code>TT</code> (monospace), <code>BIG</code>, <code>SMALL</code>, + <code>SUP</code> (superscript), <code>SUB</code> (subscript), + and <code>STRIKE</code> (strikethrough). + So, for example, in res/values/strings.xml you could declare this:<br /> + <code><resource><br /> + <string>id="@+id/styled_welcome_message">We + are <b><i>so</i></b> glad to see you.</string><br /> + </resources></code></li> + <li>To style text on the fly, or to add highlighting or more complex styling, + you must use the Spannable object as described next. </li> +</ul> +<p>To style text on the fly, you must make sure the TextView is using {@link android.text.Spannable} + storage for the text (this will always be true if the TextView is an EditText), + retrieve its text with {@link android.widget.TextView#getText}, and call {@link + android.text.Spannable#setSpan}, passing in a new style class from the {@link + android.text.style} package and the selection range. </p> +<p>The following code snippet demonstrates creating a string with a highlighted section, + italic section, and bold section, and adding it to an EditText object. </p> +<pre>// Get our EditText object. +EditText vw = (EditText)findViewById(R.id.text); + +// Set the EditText's text. +vw.setText("Italic, highlighted, bold."); + +// If this were just a TextView, we could do: +// vw.setText("Italic, highlighted, bold.", TextView.BufferType.SPANNABLE); +// to force it to use Spannable storage so styles can be attached. +// Or we could specify that in the XML. + +// Get the EditText's internal text storage +Spannable str = vw.getText(); + +// Create our span sections, and assign a format to each. +str.setSpan(new StyleSpan(android.graphics.Typeface.ITALIC), 0, 7, Spannable.SPAN_EXCLUSIVE_EXCLUSIVE); +str.setSpan(new BackgroundColorSpan(0xFFFFFF00), 8, 19, Spannable.SPAN_EXCLUSIVE_EXCLUSIVE); +str.setSpan(new StyleSpan(android.graphics.Typeface.BOLD), 21, str.length() - 1, Spannable.SPAN_EXCLUSIVE_EXCLUSIVE); +</pre> + +<a name="querymap" id="querymap"></a><h2>Utilizing attributes in a Map query</h2> +<p> +When using a search intent to ask the Maps activity to search for something, the Maps activity responds to the following attributes in the optional context bundle: +</p> +<pre> + float "centerLatitude" default 0.0f + float "centerLongitude" default 0.0f + float "latitudeSpan" default 0.0f + float "longitudeSpan" default 0.0f + int "zoomLevel" default 10 +</pre> +<p> +This context information is used to center the search result in a particular area, and is equivalent to adjusting the Map activity to the described location and zoom level before issuing the query. +</p> +<p> +If the latitudeSpan, longitudeSpan, and zoomLevel attributes are not consistent, then it is undefined which one takes precedence. +</p> + +<a name="filelist" id="filelist"></a><h2>List of Files for an Android Application</h2> +<p>The following list describes the structure and files of an Android application. + Many of these files can be built for you (or stubbed out) by the activitycreator.py + application shipped in the tools/ menu of the SDK. See <a href="{@docRoot}intro/installing.html#building">Building + an Android Sample Application</a> for more information on using activitycreator.py. </p> +<table width="100%" border="0"> + <tr> + <td width="28%" valign="top">MyApp/<br /></td> + <td width="72%" valign="top"> </td> + </tr> + <tr> + <td valign="top"> AndroidManifest.xml</td> + <td valign="top">(<em>required</em>) Advertises the screens that this application provides, + where they can be launched (from the main program menu or elsewhere), + any content providers it implements and what kind of data they handle, + where the implementation classes are, and other application-wide + information. Syntax details for this file are described in <a href="{@docRoot}devel/bblocks-manifest.html">AndroidManifest.xml</a>.</td> + </tr> + <tr> + <td valign="top"> src/<br /> + /<em>myPackagePath</em>/.../<em>MyClass</em>.java</td> + <td valign="top">(<em>required</em>) This folder holds all the source code files for your + application, inside the appropriate package subfolders. </td> + </tr> + <tr> + <td valign="top"> res/</td> + <td valign="top">(<em>required</em>) This folder holds all the <em>resources</em> for + your application. Resources are external data files or description files + that are compiled into your code at build time. Files in different folders + are compiled differently, so you must put the proper resource into the + proper folder. (See <a href="{@docRoot}devel/resources-i18n.html">Resources</a> for details.)</td> + </tr> + <tr> + <td valign="top"> anim/<br /> + <em>animation1</em>.xml<br /> + <em>...</em></td> + <td valign="top">(<em>optional</em>) Holds any animation XML description files that the + application uses. The format of these files is described in <a href="{@docRoot}devel/resources-i18n.html">Resources</a>. </td> + </tr> + <tr> + <td valign="top"> drawable/<br /> + <em>some_picture</em>.png<br /> + <em>some_stretchable</em>.9.png<br /> + <em>some_background</em>.xml<br /> + ...</td> + <td valign="top">(<em>optional</em>) Zero or more files that will be compiled to {@link + android.graphics.drawable android.graphics.drawable} resources. Files + can be image files (png, gif, or other) or XML files describing other + graphics such as bitmaps, stretchable bitmaps, or gradients. Supported + bitmap file formats are PNG (preferred), JPG, and GIF (discouraged), + as well as the custom 9-patch stretchable bitmap format. These formats + are described in <a href="{@docRoot}devel/resources-i18n.html">Resources</a>. </td> + </tr> + <tr> + <td valign="top"> layout/<br /> + <em>screen_1_layout</em>.xml<br /> + ...<br /></td> + <td valign="top">(<em>optional</em>) Holds all the XML files describing screens or parts + of screens. Although you could create a screen in Java, defining them + in XML files is typically easier. A layout file is similar in concept + to an HTML file that describes the screen layout and components. See <a href="{@docRoot}devel/implementing-ui.html">Implementing a + UI</a> for more information about designing screens, and <a href="{@docRoot}reference/available-resources.html#layoutresources">Layout + Resources</a> for the syntax of these files.</td> + </tr> + <tr> + <td valign="top"> values/<br /> + arrays<br /> + classes.xml<br /> + colors.xml<br /> + dimens.xml<br /> + strings.xml<br /> + styles.xml<br /> + values.xml<br /></td> + <td valign="top"><p>(<em>optional</em>) XML files describing additional resources + such as strings, colors, and styles. The naming, quantity, and number + of these files are not enforced--any XML file is compiled, but these + are the standard names given to these files. However, the syntax + of these files is prescribed by Android, and described in <a href="{@docRoot}devel/resources-i18n.html">Resources</a>. </p> + </td> + </tr> + <tr> + <td valign="top"> xml/</td> + <td valign="top">(<em>optional</em>) XML files that can be read at run time on the device. </td> + </tr> + <tr> + <td valign="top"> raw/</td> + <td valign="top">(<em>optional</em>) Any files to be copied directly to the device. </td> + </tr> +</table> + + +<a name="logging" ></a> +<h2>Print Messages to a Log File</h2> + +<p>To write log messages from your application:</p> +<ol><li>Import <code>android.util.Log</code>.</li> + <li>Use <code>Log.v()</code>, <code>Log.d()</code>, <code>Log.i()</code>, + <code>Log.w()</code>, or <code>Log.e()</code> to log messages. + (See the {@link android.util.Log} class.)<br/> E.g., + <code>Log.e(this.toString(), "error: " + err.toString())</code></li> + <li>Launch <a href="/android/reference/ddms.html">DDMS</a> from a terminal + by executing <code>ddms</code> in your Android SDK <code>/tools</code> path.</li> + <li>Run your application in the Android emulator.</li> + <li>From the DDMS application, select the emulator + (e.g., "emulator-5554") and click <b>Device > Run logcat...</b> + to view all the log data.</li> +</ol> +<p class="note"><strong>Note:</strong> If you are running Eclipse and +encounter a warning about the VM debug port when opening DDMS, you can ignore it +if you're only interested in logs. However, if you want to further inspect and +control your processes from DDMS, then you should close Eclipse before launching DDMS so that +it may use the VM debugging port.</p> + + diff --git a/docs/html/guide/appendix/faq/framework.jd b/docs/html/guide/appendix/faq/framework.jd new file mode 100644 index 0000000..48db8da --- /dev/null +++ b/docs/html/guide/appendix/faq/framework.jd @@ -0,0 +1,194 @@ +page.title=Android Application Framework FAQ +@jd:body + +<ul> + <li><a href="#1">Do all the Activities and Services of an + application run in a single process?</a></li> + <li><a href="#2">Do all Activities run in the main thread of + an application process?</a></li> + <li><a href="#3">How do I pass complicated data structures + from one Activity/Service to another?</a></li> + <li><a href="#4">How can I check if an Activity is already + running before starting it?</a></li> + <li><a href="#5">If an Activity starts a remote service,is + there any way for the Service to pass a message back to the Activity?</a></li> + <li><a href="#6">How to avoid getting the Application not + responding dialog?</a></li> + <li><a href="#7">How does an application know if a package is + added or removed?</a></li> +</ul> + +<!-- ------------------------------------------------------------------ --> + +<a name="1" id="1"></a> + +<h2>Do all the Activities and Services of an application run in a +single process?</h2> + +<p>All Activities and Services in an application run in a single +process by default. The <a href="{@docRoot}reference/android/R.styleable.html#AndroidManifestActivity_process">android:process</a> attribute can be used to +explicitly place a component (Activity/Service) in another process.</p> + +<!-- ------------------------------------------------------------------ --> + +<a name="2" id="2"></a> + +<h2>Do all Activities run in the main thread of an application +process?</h2> + +<p>By default, all of the application code in a single process runs +in the main UI thread. This is the same thread +that also handles UI events. The only exception is the code that handles +IPC calls coming in from other processes. The system maintains a +separate pool of transaction threads in each process to dispatch all +incoming IPC calls. The developer should create separate threads for any +long-running code, to avoid blocking the main UI thread.</p> + +<!-- ------------------------------------------------------------------ --> + +<a name="3" id="3"></a> + +<h2>How do I pass data between Activities/Services within a single +application?</h2> + +<p>It depends on the type of data that you want to share:</p> + +<h3>Primitive Data Types</h3> + +<p>To share primitive data between Activities/Services in an +application, use Intent.putExtras(). For passing primitive data that +needs to persist use the +<a href="{@docRoot}devel/data/preferences.html">Application +Preferences</a>.</p> + +<h3>Non-Persistent Objects</h3> + +<p>For sharing complex non-persistent user-defined objects for short +duration, the following approaches are recommended: +</p> + <h4>The android.app.Application class</h4> + <p>The android.app.Application is a base class for those who need to +maintain global application state. It can be accessed via +getApplication() from any Activity or Service. It has a couple of +life-cycle methods and will be instantiated by Android automatically if +your register it in AndroidManifest.xml.</p> + + <h4>A public static field/method</h4> + <p>An alternate way to make data accessible across Activities/Services is to use <em>public static</em> +fields and/or methods. You can access these static fields from any other +class in your application. To share an object, the activity which creates your object sets a +static field to point to this object and any other activity that wants to use +this object just accesses this static field.</p> + + <h4>A HashMap of WeakReferences to Objects</h4> + <p>You can also use a HashMap of WeakReferences to Objects with Long +keys. When an activity wants to pass an object to another activity, it +simply puts the object in the map and sends the key (which is a unique +Long based on a counter or time stamp) to the recipient activity via +intent extras. The recipient activity retrieves the object using this +key.</p> + + <h4>A Singleton class</h4> + <p>There are advantages to using a static Singleton, such as you can +refer to them without casting getApplication() to an +application-specific class, or going to the trouble of hanging an +interface on all your Application subclasses so that your various +modules can refer to that interface instead. </p> +<p>But, the life cycle of a static is not well under your control; so +to abide by the life-cycle model, the application class should initiate and +tear down these static objects in the onCreate() and onTerminate() methods +of the Application Class</p> +</p> + +<h3>Persistent Objects</h3> + +<p>Even while an application appears to continue running, the system +may choose to kill its process and restart it later. If you have data +that you need to persist from one activity invocation to the next, you +need to represent that data as state that gets saved by an activity when +it is informed that it might go away.</p> + +<p>For sharing complex persistent user-defined objects, the +following approaches are recommended: +<ul> + <li>Application Preferences</li> + <li>Files</li> + <li>contentProviders</li> + <li>SQLite DB</li> +</ul> +</p> + +<p>If the shared data needs to be retained across points where the +application process can be killed, then place that data in persistent +storage like Application Preferences, SQLite DB, Files or ContentProviders. Please refer +to the <a href="{@docRoot}devel/data.html">Storing, Retrieving and Exposing Data</a> for further details on how to use these components.</p> + + +<!-- ------------------------------------------------------------------ --> + +<a name="4" id="4"></a> + +<h2>How can I check if an Activity is already running before starting +it?</h2> + +<p>The general mechanism to start a new activity if its not running— +or to bring the activity stack to the front if is already running in the +background— is the to use the NEW_TASK_LAUNCH flag in the startActivity() +call.</p> + +<!-- ------------------------------------------------------------------ --> + +<a name="5" id="5"></a> + +<h2>If an Activity starts a remote service, is there any way for the +Service to pass a message back to the Activity?</h2> + +<p>The remote service can define a callback interface and register +it with the clients to callback into the clients. The +<a href="{@docRoot}reference/android/os/RemoteCallbackList.html">RemoteCallbackList</a> provides methods to register and +unregister clients with the service, and send and receive messages.</p> + +<p>The sample code for remote service callbacks is given in +<a href="{@docRoot}samples/ApiDemos/src/com/example/android/apis/app/RemoteService.html">ApiDemos/RemoteService</a></p> + +<!-- ------------------------------------------------------------------ --> + +<a name="6" id="6"></a> + +<h2>How to avoid getting the Application not responding dialog?</h2> + +<p>Please check the <a href="{@docRoot}toolbox/responsiveness.html">Application +Responsiveness</a> section to design your application for +better responsiveness:</p> + + +<!-- ------------------------------------------------------------------ --> + +<a name="7" id="7"></a> + +<h2>How does an application know if a package is added or removed? +</h2> + +<p>Whenever a package is added, an intent with PACKAGE_ADDED action +is broadcast by the system. Similarly when a package is removed, an +intent with PACKAGE_REMOVED action is broadcast. To receive these +intents, you should write something like this: +<pre> + <receiver android:name ="com.android.samples.app.PackageReceiver"> + <intent-filter> + <action android:name="android.intent.action.PACKAGE_ADDED"/> + <action android:name="android.intent.action.PACKAGE_REMOVED"/> + + <data android:scheme="package" /> + </intent-filter> + </receiver> + </pre> + <br> +Here PackageReceiver is a BroadcastReceiver class.Its onReceive() +method is invoked, every time an application package is installed or +removed. + +</p> + +<!-- ------------------------------------------------------------------ --> + diff --git a/docs/html/guide/appendix/faq/index.jd b/docs/html/guide/appendix/faq/index.jd new file mode 100644 index 0000000..90415ae --- /dev/null +++ b/docs/html/guide/appendix/faq/index.jd @@ -0,0 +1,15 @@ +page.title=FAQs, Tips, and How-to +@jd:body + +<dl> + <dt><a href="commontasks.html">Common Development Tasks and How To Do Them</a></dt> + <dd>Quick and to the point — how-to's for a variety of development tasks you are likely to use.</dd> + <dt><a href="framework.html">Application Framework FAQ</a></dt> + <dd>Common questions about the Android Application Framework.</dd> + <dt><a href="troubleshooting.html">Troubleshooting Tips</a></dt> + <dd>Answers to help you troubleshoot common problems.</dd> + <dt><a href="licensingandoss.html">Open Source Licensing FAQ</a></dt> + <dd>Common topics around licensing and Android Open Source</dd> + <dt><a href="security.html">Android Security FAQ</a></dt> + <dd>Answers to common questions about Android security.</dd> +</dl> diff --git a/docs/html/guide/appendix/faq/licensingandoss.jd b/docs/html/guide/appendix/faq/licensingandoss.jd new file mode 100644 index 0000000..a907d68 --- /dev/null +++ b/docs/html/guide/appendix/faq/licensingandoss.jd @@ -0,0 +1,17 @@ +page.title=Android Open Source Licensing FAQ +@jd:body + +<ul> + <li><a href="#mirror">Where can I find the open source components of Android?</a></li> + <li><a href="#timeline">When will we see more code released under open source licenses?</a></li> + <li><a href="#apache2">Why are you releasing the code under the Apache License instead of GPLv2?</a></li> +</ul> + +<a name="mirror" id="mirror"></a><h2>Where can I find the open source components of Android?</h2> +<p>The source code for the full Android stack is available from the <a href="http://www.android.com/opensource">Android Open Source Project </a> site. + +<p>Other mirrored GPL and LGPL'd components are available at <a href="http://code.google.com/p/android/downloads/list"><code>http://code.google.com/p/android/downloads/list</code></a>.</p> +<p>Notices for other licenses can be found within the SDK.</p> + +<a name="apache2" id="apache2"></a><h2>Why are you releasing the code under the Apache License instead of GPLv2?</h2> +<p>One of the best explanations for the reasoning behind releasing code under Apache2 can be found in a <a href="http://arstechnica.com/news.ars/post/20071106-why-google-chose-the-apache-software-license-over-gplv2.html">ArsTechnica article</a> by Ryan Paul.</p> diff --git a/docs/html/guide/appendix/faq/security.jd b/docs/html/guide/appendix/faq/security.jd new file mode 100644 index 0000000..1c66f95 --- /dev/null +++ b/docs/html/guide/appendix/faq/security.jd @@ -0,0 +1,154 @@ +page.title=Android Security FAQ +@jd:body + +<ul> + <li><a href="#secure">Is Android Secure?</a></li> + <li><a href="#issue">I think I found a security flaw. How do I report + it?</a></li> + <li><a href="#informed">How can I stay informed of Android security + announcements?</a></li> + <li><a href="#use">How do I securely use my Android phone?</a></li> + <li><a href="#malware">I think I found malicious software being distributed + for Android. How can I help?</a></li> + <li><a href="#fixes">How will Android-powered devices receive security fixes?</a> + </li> + <li><a href="#directfix">Can I get a fix directly from the Android Platform + Project?</a></li> +</ul> + + +<a name="secure" id="secure"></a><h2>Is Android secure?</h2> + +<p>The security and privacy of our users' data is of primary importance to the +Android Open Source Project. We are dedicated to building and maintaining one +of the most secure mobile platforms available while still fulfilling our goal +of opening the mobile device space to innovation and competition.</p> + +<p>The Android Platform provides a rich <a +href="http://code.google.com/android/devel/security.html">security model</a> +that allows developers to request the capabilities, or access, needed by their +application and to define new capabilities that other applications can request. +The Android user can choose to grant or deny an application's request for +certain capabilities on the handset.</p> + +<p>We have made great efforts to secure the Android platform, but it is +inevitable that security bugs will be found in any system of this complexity. +Therefore, the Android team works hard to find new bugs internally and responds +quickly and professionally to vulnerability reports from external researchers. +</p> + + +<a name="issue" id="issue"></a><h2>I think I found a security flaw. How do I +report it?</h2> + +<p>You can reach the Android security team at <a +href="mailto:security@android.com">security@android.com</a>. If you like, you +can protect your message using our <a +href="http://code.google.com/android/security_at_android_dot_com.txt">PGP +key</a>.</p> + +<p>We appreciate researchers practicing responsible disclosure by emailing us +with a detailed summary of the issue and keeping the issue confidential while +users are at risk. In return, we will make sure to keep the researcher informed +of our progress in issuing a fix and will properly credit the reporter(s) when +we announce the patch. We will always move swiftly to mitigate or fix an +externally-reported flaw and will publicly announce the fix once patches are +available to users.</p> + + +<a name="informed" id="informed"></a><h2>How can I stay informed of Android +security announcements?</h2> + +<p>An important part of sustainably securing a platform, such as, Android is +keeping the user and security community informed of bugs and fixes. We will +publicly announce security bugs when the fixes are available via postings to +the <a +href="http://groups.google.com/group/android-security-announce">android-security-announce</a> +group on Google Groups. You can subscribe to this group as you would a mailing +list and view the archives here.</p> + +<p>For more general discussion of Android platform security, or how to use +security features in your Android application, please subscribe to <a +href="http://groups.google.com/group/android-security-discuss">android-security-discuss</a>. +</p> + + +<a name="use" id="use"></a><h2>How do I securely use my Android phone?</h2> + +<p>As an open platform, Android allows users to load software from any +developer onto a device. As with a home PC, the user must be +aware of who is providing the software they are downloading and must decide +whether they want to grant the application the capabilities it requests. +This decision can be informed by the user's judgment of the software +developer's trustworthiness, and where the software came from.</p> + +<p>Despite the security protections in Android, it is important +for users to only download and install software from developers they trust. +More details on how Android users can make smart security decisions will be +released when consumer devices become available.</p> + + +<a name="malware" id="malware"></a><h2>I think I found malicious software being +distributed for Android. How can I help?</h2> + +<p>Like any other open platform, it will be possible for unethical developers +to create malicious software, known as <a +href="http://en.wikipedia.org/wiki/Malware">malware</a>, for Android. If you +think somebody is trying to spread malware, please let us know at <a +href="mailto:security@android.com">security@android.com</a>. Please include as +much detail about the application as possible, with the location it is +being distributed from and why you suspect it of being malicious software.</p> + +<p>The term <i>malicious software</i> is subjective, and we cannot make an +exhaustive definition. Some examples of what the Android Security Team believes +to be malicious software is any application that: +<ul> + <li>drains the device's battery very quickly;</li> + <li>shows the user unsolicited messages (especially messages urging the + user to buy something);</li> + <li>resists (or attempts to resist) the user's effort to uninstall it;</li> + <li>attempts to automatically spread itself to other devices;</li> + <li>hides its files and/or processes;</li> + <li>discloses the user's private information to a third party, without the + user's knowledge and consent;</li> + <li>destroys the user's data (or the device itself) without the user's + knowledge and consent;</li> + <li>impersonates the user (such as by sending email or buying things from a + web store) without the user's knowledge and consent; or</li> + <li>otherwise degrades the user's experience with the device.</li> +</ul> +</p> + + +<a name="fixes" id="fixes"></a><h2>How will Android-powered devices receive security +fixes?</h2> + +<p>The manufacturer of each device is responsible for distributing software +upgrades for it, including security fixes. Many devices will update themselves +automatically with software downloaded "over the air", while some devices +require the user to upgrade them manually.</p> + +<p>When Android-powered devices are publicly available, this FAQ will provide links how +Open Handset Alliance members release updates.</p> + +<a name="directfix" id="directfix"></a><h2>Can I get a fix directly from the +Android Platform Project?</h2> + +<p>Android is a mobile platform that will be released as open source and +available for free use by anybody. This means that there will be many +Android-based products available to consumers, and most of them will be created +without the knowledge or participation of the Android Open Source Project. Like +the maintainers of other open source projects, we cannot build and release +patches for the entire ecosystem of products using Android. Instead, we will +work diligently to find and fix flaws as quickly as possible and to distribute +those fixes to the manufacturers of the products.</p> + +<p>In addition, We will add security fixes to the open source distribution of +Android and publicly announce the changes on <a +href="http://groups.google.com/group/android-security-announce">android-security-announce</a>. +</p> + +<p>If you are making an Android-powered device and would like to know how you can +properly support your customers by keeping abreast of software updates, please +contact us at <a +href="mailto:info@openhandsetalliance.com">info@openhandsetalliance.com</a>.</p> diff --git a/docs/html/guide/appendix/faq/troubleshooting.jd b/docs/html/guide/appendix/faq/troubleshooting.jd new file mode 100755 index 0000000..8096826 --- /dev/null +++ b/docs/html/guide/appendix/faq/troubleshooting.jd @@ -0,0 +1,283 @@ +page.title=Troubleshooting +@jd:body + + +<p>Here are some tips and tricks for common Android errors. Don't forget to use the + ddms logcat capability to get a deeper view when errors occur. See <a href="{@docRoot}guide/developing/debugging-tasks.html">Debugging Tasks</a> for more debugging tips. </p> +<ul> + <li><a href="#installeclipsecomponents">ADT Installation Error: "requires plug-in org.eclipse.wst.sse.ui".</a></li> + <li><a href="#nodevice">ADB reports "no device" when an emulator is running</a></li> + <li><a href="#noapp">My new application/activity isn't showing up in the device application + list </a></li> + <li><a href="#noupdate">I updated my app, but the updates don't seem to be showing up on + the device</a></li> + <li><a href="#layout_wilih">I'm getting a "Binary XML file line #2: You must supply a layout_wilih + attribute" error when I start an application</a></li> + <li><a href="#permission">My request to (<em>make a call, catch an incoming SMS, receive + a notification, send an intent to an Android application</em>) is being + ignored</a></li> + <li><a href="#build">Help! My project won't build in Eclipse</a></li> + <li><a href="#eclipse">Eclipse isn't talking to the emulator</a></li> + <li><a href="#majorminor">When I go to preferences in Eclipse and select "Android", I get the following error message: Unsupported major.minor version 49.0.</a></li> + <li><a href="#apidemosreinstall">I can't install ApiDemos apps in my IDE because of a signing error</a></li> + <li><a href="#signingcalendar">I can't compile my app because the build tools generated an expired debug certificate</a></li> + <li><a href="#addjunit">I can't run a JUnit test class in Eclipse/ADT</a></li> +</ul> + +<a name="installeclipsecomponents" id="installeclipsecomponents"></a><h2>ADT Installation Error: "requires plug-in org.eclipse.wst.sse.ui".</h2> +<p> +The "Android Editors" feature of the ADT Plugin requires specific Eclipse components, such as WST. If you +encounter this error message during ADT installation, you need to install the +required Eclipse components and then try the ADT installation again. The easiest way to install the required components for the +Android Editors feature of ADT is the following: +<ul> +<li>From the dialog where you select the <strong>Update sites to visit</strong>, select the checkboxes for both the +ADT site, and the Callisto/Europa/Ganymede Discovery Site (you may want to +check <strong>Automatically select mirrors</strong> at the bottom).</li> +<li>Click <strong>Finish</strong>.</li> +<li>In the <strong>Next</strong> dialog, select the Android Plugins.</li> +<li>Now, expand the tree item of the discovery site. It seems that if you +don't do it, it doesn't load the content of the discovery site.</li> +<li>On the right, click <strong>Select required</strong>. This will select all the components +that are required to install the Android plugin (wst, emf, etc...).</li> +<li>Click <strong>Next</strong>, accept the agreement, click <strong>Install All</strong>, and restart Eclipse.</li> + +</p> +<a name="nodevice"></a><h2>ADB reports "no device" when an emulator is running</h2> + <p>Try restarting adb by stopping it (<code>adb + kill-server</code>) then any other adb command to restart it.</p> + +<a name="noapp"></a><h2>My new application/activity isn't showing up in the + applications list </h2> +<ul> + <li>You often must restart your device or emulator before a new activity shows + up in the applications list. This is particularly true when it is a completely + new application with a new AndroidManifest.xml file.</li> + <li>If this is for a new activity in an existing AndroidManifest.xml file, did + you include an <code><activity></code> tag for your app (or a <code><service></code> tag + for a service, or a <code><receiver></code> tag for a receiver, etc.)? </li> + <li>Make sure that your AndroidManifest.xml file is valid. Errors in attribute + values, such as the <em>value </em> attribute in <code><action <em>value</em>="<em><something></em>"></code> + will often not be caught by compilers, but will prevent your application + from being displayed because the intent filter will not be matched. Extra + spaces or other characters can often sneak into these strings.</li> + <li>Did you send your .apk file to the device (<a href="{@docRoot}reference/adb.html#move">adb install</a>)?</li> + <li>Run logcat on your device (<code>adb logcat</code>) + and then install your .apk file. Check the logcat output to see whether the + application is being installed and recognized properly. Here's sample output + from a successful installation: +<pre>I/FileObserver( 414): *** onEvent wfd: 3 mask: 8 path: MyRSSReader.apk +D/PackageManager( 414): Scanning package: /data/app/MyRSSReader.apk +D/PackageManager( 414): Adding package com.example.codelab.rssexample +D/PackageManager( 414): Registered content provider: my_rss_item, className = com.example.codelab.rssexample.RssContentProvider, isSyncable = false +D/PackageManager( 414): Providers: com.example.codelab.rssexample.RssContentProvider +D/PackageManager( 414): Activities: com.example.codelab.rssexample.MyRssReader com.example.codelab.rssexample.MyRssReader2 </pre> + </li> + <li>If logcat shows that the package manager is having problems loading the manifest + file, force your manifest to be recompiled by adding a space in the file and + compiling it.</li> +</ul> +<a name="noupdate"></a><h2>I updated my app, but the updates don't seem to be showing up on the device</h2> + <p>Did you remember to send your .apk file to the device (<a href="{@docRoot}reference/adb.html#move">adb + install</a>)?</p> + +<a name="layout_wilih"></a><h2>I'm getting a "Binary XML file line #2: You must supply a layout_wilih + attribute" error + when I start an application (but I declare a layout_wilih attribute <em>right + there!!!</em>)</h2> +<ul> + <li>Make sure that the SDK you are building with is the same version as the Android + OS that you are running on. </li> + <li>Make sure that you're calling setContentView() early in your onCreate() method. + Calling other methods, such as setListAdapter() before calling setContentView() + can sometimes create odd errors when Android tries to access screen elements + that haven't been set before.</li> +</ul> +<a name="permission"></a><h2>My request to (<em>make a call, catch an incoming SMS, +receive a notification, send an intent to an Android application</em>) is being +ignored</h2> + <p>You might not have permission (or might not have requested permission) to + call this activity or receive this intent. Many standard Android activities, + such as making a call, have a permission assigned to it to prevent arbitrary + applications from sending or receiving requests. See <a href="{@docRoot}devel/security.html">Security + and Permissions</a> for more information on permissions, and {@link android.Manifest.permission + Manifest.permission} for a list of permissions enforced by Android. +</p> +<a name="build"></a><h2>Help! My project won't build in Eclipse</h2> +<p>If your project doesn't build, you may notice symptoms such as new +resources added in the <code>res/</code> sub-folders not showing up in the R class, +the emulator not being started, not being able to run the application, or even seeming to run an old version of the application.</p> +<p>To troubleshoot these types of problems, first try:</p> +<ol> + <li>Switch to the DDMS view in Eclipse (if you don't already have it open): + <ol type="a"> + <li>From the menu select <code>Window > Open Perspective > Other</code></li> + <li>Select DDMS from the list and hit OK</li> + </ol> + </li> + <li>In the Devices panel (top right panel by default), click on the down triangle + to bring up the panel menu</li> + <li>Select <code>Reset ADB</code> from the menu, and then try running the + application again</li> +</ol> +<p>If the above still doesn't work, you can try these steps:</p> +<ol> + <li> + Check the console and problems tabs at the bottom of the Eclipse UI + </li> + <li> + If there are problems listed in either place, they should give you a clue + what is wrong + </li> + <li> + If you aren't sure if the problems are fresh or stale, clear the console + with a right click > Clear, then clean the project + </li> + <li> + To clean the project (a good idea with any kind of build error), select + Project > Clean from the eclipse main menu, then select the project you + are working on (or clean all) + </li> +</ol> +<a name="eclipse"></a><h2>Eclipse isn't talking to the emulator</h2> +<p>When communication doesn't seem to be happening between Eclipse and the emulator, symptoms can include: nothing happening when you press run, the emulator hanging waiting +for a debugger to connect, or errors that Eclipse reports about not being able +to find the emulator or shell. By far the most common symptom is that when you press run, the emulator starts (or +is already running), but the application doesn't start.</p> +<p> +You may find any of these steps will fix the problem and with practice you +probably can figure out which one you need to do for your particular issue, but +to start with, the safest option is to run through all of them in order:</p> +<ol> + <li> + Quit the emulator if it is running + </li> + <li> + Check that any emulator processes are killed (sometimes they can hang, use ps on unix or mac, or task manager in the process view on + windows). + </li> + <li> + Quit Eclipse + </li> + <li> + From the command line, type: +<pre>adb kill-server </pre> + </li> + <li> + Start Eclipse and try again + </li> +</ol> + +<a name="majorminor"></a><h2>When I go to preferences in Eclipse and select "Android", I get the following error message: Unsupported major.minor version 49.0.</h2> +<p>This error is displayed if you are using an older version of the JDK. Please make sure you are using JDK version 5 or 6.</p> + +<h2 id="apidemosreinstall">I can't install ApiDemos apps in my IDE because of a signing error</a></h2> + +<p>The Android system requires that all applications be signed, as described in +<a href="{@docRoot}intro/develop-and-debug.html#signing">Signing Your Applications</a>. The ApiDemos +applications included with the SDK are preinstalled on the emulator and for that reason have been +compiled and signed with a private key.</p> + +If you want to modify or run one of the ApiDemos apps from Eclipse/ADT or other IDE, you can do so +so only after you uninstall the <em>preinstalled</em> version of the app from the emulator. If +you try to run an ApiDemos apps from your IDE without removing the preinstalled version first, +you will get errors similar to: </p> + +<pre>[2008-08-13 15:14:15 - ApiDemos] Re-installation failed due to different application signatures. +[2008-08-13 15:14:15 - ApiDemos] You must perform a full uninstall of the application. WARNING: ...This will remove the application data! +[2008-08-13 15:14:15 - ApiDemos] Please execute 'adb uninstall com.android.samples' in a shell.</pre> + +<p>The error occurs because, in this case, you are attempting to install another copy of ApiDemos +onto the emulator, a copy that is signed with a different certificate (the Android IDE tools will +have signed the app with a debug certificate, where the existing version was already signed with +a private certificate). The system does not allow this type of reinstallation. </p> + +<p>To resolve the issue, you need to fully uninstall the preinstalled and then reinstall it using +the adb tool. Here's how to do that:</p> + +<ol> + <li>In a terminal, change to the tools directory of the SDK.</li> + <li>If no emulator instance is running, start an emulator using using the command <code>emulator &</code>.</li> + <li>Uninstall the preinstalled app using the command <code>adb uninstall com.android.samples</code>.</li> + <li>Reinstall the app using the command <code>adb install <path to the ApiDemos.apk></code>. If you are + working in Eclipse/ADT, you can just compile and run the app in the normal way. </li> +</ol> + +<p>Note that if multiple emulator instances are running, you need to direct your uninstall/install +commands to the emulator instance that you are targeting. To do that you can add the +<code>-s <serialNumber></code> to the command, for example: </p> + +<pre>adb -s emulator-5556 install</pre> + +<p>For more information about adb, see the <a href="{@docRoot}reference/adb.html">Android Debug Bridge</a> +documentation.</p> + + +<h2 id="signingcalendar">I can't compile my app because the build tools generated an expired debug certificate</h2> + +<p>If your development machine uses a locale that has a non-Gregorian calendar, you may encounter problems when first trying to compile and run your application. Specifically, you may find that the Android build tools won't compile your application because the debug key is expired. </p> + +<p>The problem occurs because the Keytool utility — included in the JDK and used by the Android build tools — fails to properly handle non-Gregorian locales and may create validity dates that are in the past. That is, it may generate a debug key that is already expired, which results in the compile error.</p> + +<p>If you encounter this problem, follow these steps to work around it: </p> + +<ol> +<li>First, delete the debug keystore/key already generated by the Android build tools. Specifically, delete the <code>debug.keystore</code> file. On Linux/Mac OSX, the file is stored in <code>~/.android</code>. On Windows XP, the file is stored in <code> +C:\Documents and Settings\<user>\Local Settings\Application Data\Android</code>. On Windows Vista, the file is stored in <code> +C:\Users\<user>\AppData\Local\Android</code></li> +<li>Next, you can either +<ul> +<li>Temporarily change your development machine's locale (date and time) to one that uses a Gregorian calendar, for example, United States. Once the locale is changed, use the Android build tools to compile and install your app. The build tools will regenerate a new keystore and debug key with valid dates. Once the new debug key is generated, you can reset your development machine to the original locale. </li> +<li>Alternatively, if you do not want to change your machine's locale settings, you can generate the keystore/key on any machine using the Gregorian calendar, then copy the <code>debug.keystore</code> file from that computer to the proper location on your development machine. </li> +</ul> +</li> +</ol> + +<p>This problem has been verified on Windows and may apply to other platforms. </p> + +<p>For general information about signing Android applications, see +<a href="{@docRoot}intro/develop-and-debug.html#signing">Signing Your Applications</a>. </p> + +<h2 id="addjunit">I can't run a JUnit test class in Eclipse/ADT</h2> + +<p>If you are developing on Eclipse/ADT, you can add JUnit test classes to your application. However, you may get an error when trying to run such a class as a JUnit test:</p> + +<pre>Error occurred during initialization of VM +java/lang/NoClassDefFoundError: java/lang/ref/FinalReference</pre> + +<p>This error occurs because android.jar does not include complete Junit.* class implementations, but includes stub classes only. </p> + +<p>To add a JUnit class, you have to set up a JUnit configuration:. + +<ol> +<li>In the Package Explorer view, select your project. </li> +<li>Open the launch configuration manager. + <ul> + <li>In Eclipse 3.3 (Europa), select <strong>Run </strong>> + <strong>Open Run Dialog... </strong>or <strong>Run </strong>> + <strong>Open Debug Dialog... </strong>. + </li> + + <li>In Eclipse 3.4 (Ganymede), select <strong>Run </strong>> + <strong>Run Configurations... </strong>or <strong>Run </strong>> + <strong>Debug Configurations... </strong>. + </li> + </ul> + </li> +<li>In the configuration manager, right-click the "JUnit" configuration type and select <strong>New</strong></li> +<li>In the new configuration's <strong>Test</strong> tab, specify the project and test class, as well as any options for running the test. </li> +<li>In the new configuration's <strong>Classpath</strong> tab, find "Android Library" under Bootstrap Entries and remove it. </li> +<li>Still in the <strong>Classpath</strong> tab, select Bootstrap Entries and click the Advanced button. </li> +<ol type="a"> +<li>Choose Add Library and click OK.</li> +<li>Select JRE System Library and click Next. </li> +<li>Select Workspace Default JRE and click Finish.</li> +</ol> +<li>Select Bootstrap Entries again and click Advanced.</li> +<ol type="a"> +<li>Choose Add Library and click OK.</li> +<li>Select JUnit 3 and click Finish. </li> +</ol> +</ol> +<p>When configured in this way, your JUnit test class should now run properly.</p> + diff --git a/docs/html/guide/appendix/g-app-intents.jd b/docs/html/guide/appendix/g-app-intents.jd new file mode 100644 index 0000000..15fd8d0 --- /dev/null +++ b/docs/html/guide/appendix/g-app-intents.jd @@ -0,0 +1,111 @@ +page.title=Intents List: Invoking Google Applications on Android Devices +@jd:body + +<div class="sidebox"> +For more information about intents, see the <a href="{@docRoot}guide/topics/intents/">Intents and Intent Filters</a>. +</div> + +<p>The table below lists the intents that your application can send, to invoke Google applications on Android devices in certain ways. For each action/uri pair, the table describes how the receiving Google application handles the intent. </p> + +<p>Note that this list is not comprehensive.</p> + + <table> + <tr> + <th scope="col">Target Application</th> + <th scope="col">Intent URI</th> + <th scope="col">Intent Action</th> + <th scope="col">Result</th> + </tr> + <tr> + <td rowspan="2">Browser</td> + <td>http://<em>web_address</em><br /> + https://<em>web_address</em></td> + <td>VIEW</td> + <td>Open a browser window to the URL specified. </td> + </tr> + <tr> + <td>"" (empty string) <br /> + http://<em>web_address</em><br /> + https://<em>web_address</em></td> + <td>WEB_SEARCH</td> + <td>Opens the file at the location on the device in the browser. </td> + </tr> + <tr> + <td rowspan="2">Dialer</td> + <td height="103">tel: <em>phone_number</em></td> + <td>CALL</td> + <td><p>Calls the entered phone number. Valid telephone numbers as defined + in <a href="http://tools.ietf.org/html/rfc3966">the IETF RFC 3966</a> are + accepted. Valid examples include the following:</p> + <ul> + <li>tel:2125551212 </li> + <li>tel: + (212) 555 1212</li> + </ul> + <p>The dialer is good at normalizing some kinds of schemes: for example + telephone numbers, so the schema described isn't strictly required + in the {@link android.net.Uri#parse(java.lang.String) + Uri(URI string)} factory. However, if you have not tried a + schema or are unsure whether it can be handled, use the {@link + android.net.Uri#fromParts(java.lang.String, java.lang.String, + java.lang.String) Uri.fromParts(scheme, ssp, fragment)} factory + instead.</p> + <p><strong><em>Note:</em></strong> This requires your + application to request the following permission in your manifest: <code><uses-permission + id="android.permission.CALL_PHONE" /></code></p></td> + </tr> + <tr> + <td><p>tel:<em>phone_number</em><br /> + voicemail:</p> </td> + <td>DIAL</td> + <td><p>Dials (but does not actually initiate the call) the number given + (or the stored voicemail on the phone). Telephone number normalization + described for CALL applies to DIAL as well. </p> </td> + </tr> + <tr> + <td>Google Maps</td> + <td>geo:<em>latitude</em>,<em>longitude</em><br /> + geo:<em>latitude</em>,<em>longitude</em>?z=<em>zoom</em><br /> + geo:0,0?q=<em>my+street+address</em><br /> + geo:0,0?q=<em>business+near+city</em><br /> + </td> + <td>VIEW</td> + <td>Opens the Maps application to the given location or query. The Geo URI scheme + (not fully supported) is <a href="http://tools.ietf.org/html/draft-mayrhofer-geo-uri-00">currently under + development</a>.<p> + The <em>z</em> field specifies the zoom level. A zoom level of 1 shows the whole Earth, centered at the + given <em>lat</em>,<em>lng</em>. A zoom level of 2 shows a quarter of the Earth, and so on. The highest + zoom level is 23. A larger zoom level will be clamped to 23. + </td> + </tr> + <tr> + <td>Google Streetview</td> <td>google.streetview:cbll=<em>lat</em>,<em>lng</em>&cbp=1,<em>yaw</em>,,<em>pitch</em>,<em>zoom</em>&mz=<em>mapZoom</em> + </td> + <td>VIEW</td> + <td>Opens the Street View application to the given location. The URI scheme is + based on the syntax used for Street View panorama information in Google Maps URLs.<p> + The cbll field is required. The cbp and mz fields are optional.<p> + <table border:none> + <tr><td><em>lat</em></td><td>latitude</td></tr> + <tr><td><em>lng</em></td><td>longitude</td></tr> + <tr><td><em>yaw</em></td><td>Panorama center-of-view in degrees clockwise from North.<br /> + <b>Note:</b> The two commas after the yaw parameter are required. They are present + for backwards-compatibility reasons.</td></tr> + <tr><td><em>pitch</em></td><td>Panorama center-of-view in degrees from + -90 (look straight up) to 90 (look straight down.)</td></tr> + <tr><td><em>zoom</em></td><td>Panorama zoom. 1.0 = normal zoom, 2.0 = zoomed in 2x, 3.0 = zoomed in 4x, and so on.<br /> + A zoom of 1.0 is 90 degree horizontal FOV for a nominal landscape mode 4 +x 3 aspect ratio display Android phones in portrait mode will adjust the zoom so +that the vertical FOV is approximately the same as the landscape vertical FOV. +This means that the horizontal FOV of an Android phone in portrait mode is much +narrower than in landscape mode. This is done to minimize the fisheye lens +effect that would be present if a 90 degree horizontal FOV was used in portrait +mode.</td></tr> + <tr><td><em>mapZoom</em></td><td>The map zoom of the map location associated with this panorama. This value is passed on to the + Maps activity when the Street View "Go to Maps" menu item is chosen. It corresponds to the <em>z</em> paramaeter in + the geo: intent.</td></tr> + </table> + </td> + </tr> + </table> + <p></p> diff --git a/docs/html/guide/appendix/glossary.jd b/docs/html/guide/appendix/glossary.jd new file mode 100644 index 0000000..518e638 --- /dev/null +++ b/docs/html/guide/appendix/glossary.jd @@ -0,0 +1,121 @@ +page.title=Glossary +@jd:body +<style TYPE="text/css"> +dt{font-weight:bold} +</style> +<h1>Android Glossary</h1> +<p>The following terms are used in these documents. </p> +<dl> + <dt>.apk extension </dt> + <dd>The extension for an Android package file, which typically contains all of the files + related to a single Android application. The file itself is a compressed collection + of an AndroidManifest.xml file, application code (.dex files), resource + files, and other files. A project is compiled into a single .apk file.</dd> + <dt>.dex extension </dt> + <dd>Android programs are compiled into .dex (Dalvik Executable) files, which + are in turn zipped into a single .apk file on the device. .dex files can + be created by automatically translating compiled applications written in + the Java programming language.</dd> + <dt>Action</dt> + <dd>A description of something that an Intent sender wants done. An action is + a string value assigned to an Intent. Action strings can be defined by Android + or by a third-party developer. For example, android.intent.action.VIEW + for a Web URL, or com.example.rumbler.SHAKE_PHONE for a custom application + to vibrate the phone. </dd> + <dt>Activity</dt> + <dd>A single screen in an application, with supporting Java code, derived from + the {@link android.app.Activity} class. </dd> + <dt>adb</dt> + <dd>Android Debug Bridge, a command-line debugging application shipped with the + SDK. It provides tools to browse the device, copy tools on the device, and + forward ports for debugging. See <a href="adb.html">Using adb</a> for more information. </dd> + <dt>Application</dt> + <dd>A collection of one or more activities, services, listeners, and intent receivers. + An application has a single manifest, and is compiled into a single .apk + file on the device. </dd> + <dt>Content Provider</dt> + <dd>A class built on {@link android.content.ContentProvider} that handles content + query strings of a specific format to return data in a specific format. + See <a href="{@docRoot}devel/data/contentproviders.html">Reading + and writing data to a content provider</a> for information on using + content providers. </dd> + <dt>Content URI</dt> + <dd>A type of URI. See the URI entry. </dd> + <dt>Dalvik</dt> + <dd>The name of Android's virtual machine. The Dalvik VM is an interpreter-only + virtual machine that executes files in the Dalvik Executable (.dex) format, + a format that is optimized for efficient storage and memory-mappable execution. + The virtual machine is register-based, and it can run classes compiled by + a Java language compiler that have been transformed into its native format + using the included "dx" tool. + The VM runs on top of Posix-compliant operating systems, which it relies + on for underlying functionality (such as threading and low level memory management). + The Dalvik core class library is intended to provide a familiar + development base for those used to programming with Java Standard + Edition, but it is geared specifically to the needs of a small mobile + device.</dd> + <dt>DDMS</dt> + <dd>Dalvik Debug Monitor Service, a GUI debugging application shipped with the + SDK. It provides screen capture, log dump, and process examination capabilities. + See Using the <a href="{@docRoot}reference/ddms.html">Dalvik + Debug Monitor Server</a> to learn more about this + program. </dd> + <dt>Drawable</dt> + <dd>A compiled visual resource that can be used as a background, title, or other + part of the screen. It is compiled into an {@link android.graphics.drawable} + subclass. </dd> + <dt>Intent</dt> + <dd>A class ({@link android.content.Intent}) that contains several fields describing + what a caller would like to do. The caller sends this intent to Android's + intent resolver, which looks through the intent filters of all applications + to find the activity most suited to handle this intent. Intent fields include + the desired action, a category, a data string, the MIME type of the data, a handling + class, and other restrictions. </dd> + <dt>Intent Filter</dt> + <dd>Activities and intent receivers include one or more filters in their manifest + to describe what kinds of intents or messages they can handle or want to + receive. An intent filter lists a set of requirements, such as data type, + action requested, and URI format, that the Intent or message must fulfill. + For activities, Android searches for the activity with the most closely matching + valid match between the Intent and the activity filter. For messages, Android + will forward a message to all receivers with matching intent filters. </dd> + <dt></dt> + <dt>Intent Receiver </dt> + <dd>An application class that listens for messages broadcast by calling {@link + android.content.Context#sendBroadcast(android.content.Intent) Context.sendBroadcast()}. + For example code, see <a href="{@docRoot}kb/commontasks.html#broadcastreceivers">Listening + for and broadcasting global messages</a>.</dd> + <dt>Layout resource </dt> + <dd>An XML file that describes the layout of an Activity screen. </dd> + <dt>Manifest</dt> + <dd>An XML file associated with each Application that describes the various activies, + intent filters, services, and other items that it exposes. See <a href="{@docRoot}devel/bblocks-manifest.html">AndroidManifest.xml + File Details</a>.</dd> + <dt>Nine-patch / 9-patch / Ninepatch image</dt> + <dd>A resizeable bitmap resource that can be used for backgrounds or other images + on the device. See <a href="{@docRoot}reference/available-resources.html#ninepatch">Nine-Patch Stretchable + Image</a> for more information. </dd> + <dt>Query String</dt> + <dd>A type of URI. See the URI entry. </dd> + <dt>Resource</dt> + <dd>A user-supplied XML, bitmap, or other file, entered into an application build + process, which can later be loaded from code. Android can accept resources + of many types; see <a href="{@docRoot}devel/resources-i18n.html">Resources</a> for a full description. + Application-defined resources should be stored in the <code>res/</code> subfolders. </dd> + <dt>Service</dt> + <dd>A class that runs in the background to perform various persistent actions, + such as playing music or monitoring network activity. </dd> + <dt>Theme</dt> + <dd>A set of properties (text size, background color, and so on) bundled together + to define various default display settings. Android provides a few standard + themes, listed in {@link android.R.style} (starting with "Theme_"). </dd> + <dt>URIs</dt> + <dd>Android uses URI strings both for requesting data (e.g., a list of contacts) + and for requesting actions (e.g., opening a Web page in a browser). Both + are valid URI strings, but have different values. All requests for data must + start with the string "content://". Action strings are valid URIs + that can be handled appropriately by applications on the device; for example, + a URI starting with "http://" will be handled by the browser. </dd> +</dl> +<p> </p> + diff --git a/docs/html/guide/appendix/index.jd b/docs/html/guide/appendix/index.jd new file mode 100644 index 0000000..4ad5e5b --- /dev/null +++ b/docs/html/guide/appendix/index.jd @@ -0,0 +1,13 @@ +page.title=Appendix +@jd:body + +<dl> + <dt><a href="media-formats.html">Supported Android Media Formats</a></dt> + <dd>A list of media codecs included in the Android platform.</dd> + <dt><a href="g-app-intents.html">Intents List: Invoking Google Applications on Android Devices</a></dt> + <dd>Intents you can send to invoke Google applications on Android devices.</dd> + <dt><a href="faq/">FAQs, Tips, and How-to</a></dt> + <dd>How to get things done in Android.</dd> + <dt><a href="glossary.html">Glossary</a></dt> + <dd>Glossary of Android terms.</dd> +</dl> diff --git a/docs/html/guide/appendix/media-formats.jd b/docs/html/guide/appendix/media-formats.jd new file mode 100644 index 0000000..41dfd63 --- /dev/null +++ b/docs/html/guide/appendix/media-formats.jd @@ -0,0 +1,189 @@ +page.title=Android Supported Media Formats +@jd:body + +<p>The <a href="#core">Core Media Formats</a> table below describes the media format support built into the Android platform. Note that any given mobile device may provide support for additional formats or file types not listed here. </p> +<p>For your convenience, the table <a href="#g1">T-Mobile G1 Media Formats</a> describes the additional media formats supported by the T-Mobile G1 device. </p> + + +<h2 id="core">Core Media Formats</h2> + +<table> +<tbody> +<tr> + +<th>Type</th> +<th>Format</th> +<th>Encoder</th> +<th>Decoder</th> +<th>Details</th> +<th>File Type(s) Supported</th> +</tr> + +<tr> +<td rowspan="8">Audio</td> +<td>AAC LC/LTP</td> +<td> </td> +<td style="text-align: center;">X</td> +<td rowspan="3">Mono/Stereo content in any combination of standard bit rates up to 160 kbps and sampling rates from 8 to 48kHz</td> +<td rowspan="3">3GPP (.3gp) and MPEG-4 (.mp4, .m4a). No support for raw AAC (.aac)</td> +</tr> + +<tr> +<td>HE-AACv1 (AAC+)</td> +<td> </td> +<td style="text-align: center;">X</td> +</tr> + +<tr> +<td>HE-AACv2 (enhanced AAC+)</td> +<td> </td> +<td style="text-align: center;">X</td> +</tr> + +<tr> +<td>AMR-NB</td> +<td style="text-align: center;">X</td> +<td style="text-align: center;">X</td> +<td>4.75 to 12.2 kbps sampled @ 8kHz</td> +<td>3GPP (.3gp) +</td> +</tr> + +<tr> +<td>AMR-WB</td> +<td> </td> +<td style="text-align: center;">X</td> +<td>9 rates from 6.60 kbit/s to 23.85 kbit/s sampled @ 16kHz</td> +<td>3GPP (.3gp)</td> +</tr> + +<tr> +<td>MP3</td> +<td> </td> +<td style="text-align: center;">X</td> +<td>Mono/Stereo 8-320Kbps constant (CBR) or variable bit-rate (VBR) +</td> +<td>MP3 (.mp3)</td> +</tr> + +<tr> +<td>MIDI</td> +<td> </td> +<td style="text-align: center;">X</td> +<td>MIDI Type 0 and 1. DLS Version 1 and 2. XMF and Mobile XMF. Support for ringtone formats RTTTL/RTX, OTA, and iMelody </td> +<td>Type 0 and 1 (.mid, .xmf, .mxmf). Also RTTTL/RTX (.rtttl, .rtx), OTA (.ota), and iMelody (.imy)</td> +</tr> + +<tr> +<td>Ogg Vorbis</td> +<td> </td> +<td style="text-align: center;">X</td> +<td> </td> +<td>Ogg (.ogg)</td> +</tr> + +<tr> +<td rowspan="4">Image</td> +<td>JPEG</td> +<td style="text-align: center;">X</td> +<td style="text-align: center;">X</td> +<td>base+progressive</td> +<td>JPEG (.jpg)</td> +</tr> + +<tr> +<td>GIF</td> +<td> </td> +<td style="text-align: center;">X</td> +<td> </td> +<td>GIF (.gif)</td> +</tr> + +<tr> +<td>PNG</td> +<td> </td> +<td style="text-align: center;">X</td> +<td> </td> +<td>PNG (.png)</td> +</tr> + +<tr> +<td>BMP</td> +<td> </td> +<td style="text-align: center;">X</td> +<td> </td> +<td>BMP (.bmp)</td> +</tr> + + +<tr> +<td rowspan="3">Video</td> +<td>H.263</td> +<td style="text-align: center;">X</td> +<td style="text-align: center;">X</td> +<td> </td> +<td>3GPP (.3gp)</td> +</tr> + +<tr> +<td>H.264</td> +<td style="text-align: center;">X</td> +<td style="text-align: center;">X</td> +<td> </td> +<td>3GPP (.3gp) and MPEG-4 (.mp4)</td> +</tr> + +<tr> +<td>MPEG4 SP</td> +<td> </td> +<td> </td> +<td> </td> +<td>3GPP (.3gp)</td> +</tr> + +</tbody></table> + +<h2 id="g1">T-Mobile G1 Media Formats</h2> + +<p>In addition to the core media formats supported in the Android platform, the T-Mobile G1 also supports the formats listed below.</p> + +<table> +<tbody> + +<tr> +<th>Type</th> +<th>Format</th> +<th>Encoder</th> +<th>Decoder</th> +<th>Details</th> +<th>File Type(s) Supported</th> +</tr> + +<tr> +<td>Audio</td> +<td>WMA</td> +<td> </td> +<td>X</td> +<td>Supports WMA standard L1-L3: +<ul> +<li>L1: 64 kbps - 161 kbps @ 44.1kHz</li> +<li>L2: <=161 kbps <=48 kHz</li> +<li>L3: <385 kbps <=48 kHz</li> +</ul> +Mono and stereo profiles with 16-bits per sample. Decoder does not support WMA Pro, Lossless, or Speech codecs. +</td> +<td>Windows Media Audio (.wma)</td> +</tr> + +<tr> +<td>Video</td> +<td>WMV</td> +<td> </td> +<td>X</td> +<td>Versions 7, 8 and 9. Simple profile only</td> +<td>Windows Media Video (.wmv)</td> +</tr> +</tbody></table> + + +<p>Note that Windows Media codecs are not part of the Android platform and require special licensing from Microsoft or an authorized developer such as Packet Video.</p> diff --git a/docs/html/guide/basics/anatomy.jd b/docs/html/guide/basics/anatomy.jd new file mode 100755 index 0000000..f4b2ad0 --- /dev/null +++ b/docs/html/guide/basics/anatomy.jd @@ -0,0 +1,134 @@ +page.title=Anatomy of an Android Application +@jd:body +<h1>Anatomy of an Android Application</h1> + +<p> +There are four building blocks to an Android application: +</p> + +<ul> + <li>Activity</li> + <li>Broadcast Receiver</li> + <li>Service</li> + <li>Content Provider</li> +</ul> + +<p> +Not every application needs to have all four, but your application will be written with some +combination of these. +</p> + +<p> +Once you have decided what components you need for your application, you should list them in a file +called AndroidManifest.xml. This is an XML file where you declare the components of your application +and what their capabilities and requirements are. See the +<a href="{@docRoot}devel/bblocks-manifest.html">Android manifest file documentation</a> +for complete details. +</p> + +<h2>Activity</h2> +<p> +Activities are the most common of the four Android building blocks. An activity is usually a single +screen in your application. Each activity is implemented as a single class that extends the +{@link android.app.Activity Activity} base class. Your class will display a user interface composed +of {@link android.view.View Views} and respond to events. Most applications consist of multiple +screens. For example, a text messaging application might have one screen that shows a list of +contacts to send messages to, a second screen to write the message to the chosen contact, and other +screens to review old messages or change settings. Each of these screens would be implemented as an +activity. Moving to another screen is accomplished by a starting a new activity. In some cases an +activity may return a value to the previous activity -- for example an activity that lets the user +pick a photo would return the chosen photo to the caller. +</p> + +<p> +When a new screen opens, the previous screen is paused and put onto a history stack. The user can +navigate backward through previously opened screens in the history. Screens can also choose to be +removed from the history stack when it would be inappropriate for them to remain. Android retains +history stacks for each application launched from the home screen. +</p> + +<h3>Intent and Intent Filters</h3> + +<p> +Android uses a special class called an {@link android.content.Intent Intent} to move from screen to +screen. An intent describes what an application wants done. The two most important parts of the +intent data structure are the action and the data to act upon. Typical values for action are MAIN +(the front door of the application), VIEW, PICK, EDIT, etc. The data is expressed as a URI. +For example, to view contact information for a person, you would create an intent with the VIEW +action and the data set to a URI representing that person. +</p> + +<p> +There is a related class called an {@link android.content.IntentFilter IntentFilter}. While an +intent is effectively a request to do something, an intent filter is a description of what intents + an activity (or broadcast receiver, see below) is capable of handling. An activity that is able to + display contact information for a person would publish an IntentFilter that said that it knows + how to handle the action VIEW when applied to data representing a person. + Activities publish their IntentFilters in the AndroidManifest.xml file. +</p> + +<p> +Navigating from screen to screen is accomplished by resolving intents. To navigate forward, an +activity calls <code>{@link android.app.Activity#startActivity startActivity(myIntent)}</code>. +The system then looks at the intent filters for all installed applications and picks the activity +whose intent filters best matches <code>myIntent</code>. The new activity is informed of the intent, which causes +it to be launched. The process of resolving intents happens at run time when startActivity is +called, which offers two key benefits: +</p> + +<ul> + <li>Activities can reuse functionality from other components simply by making a request in the form of an Intent</li> + <li>Activities can be replaced at any time by a new Activity with an equivalent IntentFilter</li> +</ul> + + +<h2>Broadcast Receiver</h2> + +<p> +You can use a {@link android.content.BroadcastReceiver BroadcastReceiver} when you want code in your +application to execute in reaction to an external event, for example, when the phone rings, or when +the data network is available, or when it's midnight. Broadcast receivers do not display a UI, although +they may use the {@link android.app.NotificationManager NotificationManager} to alert the user if +something interesting has happened. Broadcast receivers are registered in AndroidManifest.xml, but you +can also register them from code using +<code>{@link android.content.Context#registerReceiver Context.registerReceiver()}</code>. +Your application does not have to be running for its broadcast receivers to be called; the system will +start your application, if necessary, when a broadcast receiver is triggered. Applications can also send +their own intent broadcasts to others with +<code>{@link android.content.Context#sendBroadcast Context.sendBroadcast()}</code>. +</p> + +<h2>Service</h2> + +<p> +A {@link android.app.Service Service} is code that is long-lived and runs without a UI. A good +example of this is a media player playing songs from a play list. In a media player application, +there would probably be one or more activities that allow the user to choose songs and start +playing them. However, the music playback itself should not be handled by an activity because the +user will expect the music to keep playing even after navigating to a new screen. In this case, the +media player activity could start a service using +<code>{@link android.content.Context#startService Context.startService()}</code> +to run in the background to keep the music going. The system will then keep the music playback +service running until it has finished. (You can learn more about the priority given to services in +the system by reading +<a href="{@docRoot}intro/lifecycle.html">Life Cycle of an Android Application</a>.) +Note that you can connect to a +service (and start it if it's not already running) with the +<code>{@link android.content.Context#bindService Context.bindService() }</code> method. +When connected to a service, you can communicate with it through an interface exposed by the +service. For the music service, this might allow you to pause, rewind, etc. +</p> + +<h2>Content Provider</h2> +<p> +Applications can store their data in files, an SQLite database, or any other mechanism that makes +sense. A content provider, however, is useful if you want your application's data to be shared with +other applications. A content provider is a class that implements a standard set of methods to let +other applications store and retrieve the type of data that is handled by that content provider. +</p> + +<p> +To get more details on content providers, see +<a href="{@docRoot}devel/data/contentproviders.html">Accessing Content Providers</a>. +</p> + diff --git a/docs/html/guide/basics/appmodel.jd b/docs/html/guide/basics/appmodel.jd new file mode 100644 index 0000000..af5f037 --- /dev/null +++ b/docs/html/guide/basics/appmodel.jd @@ -0,0 +1,256 @@ +page.title=Application Model +@jd:body +<h1>Android Application Model: Applications, Tasks, Processes, and Threads</h1> + +<p>In most operating systems, there is a strong 1-to-1 correlation between +the executable image (such as the .exe on Windows) that an application lives in, +the process it runs in, and the icon and application the user interacts with. +In Android these associations are much more fluid, and it is important to +understand how the various pieces can be put together.</p> + +<p>Because of the flexible nature of Android applications, there is some +basic terminology that needs to be understood when implementing the +various pieces of an application:</p> + +<ul> +<li><p>An <strong>android package</strong> (or <strong>.apk</strong> for short) +is the file containing an application's code and its resources. This is the +file that an application is distributed in and downloaded by the user when +installing that application on their device.</p></li> + +<li><p>A <strong>task</strong> is generally what the user perceives as +an "application" that can be launched: usually a task has an icon in the +home screen through which it is accessed, and it is available as a top-level +item that can be brought to the foreground in front of other +tasks.</p></li> + +<li><p>A <strong>process</strong> is a low-level kernel process in which +an application's code is running. Normally all of the code in a +.apk is run in one, dedicated process for that .apk; however, the +{@link android.R.styleable#AndroidManifestApplication_process process} tag +can be used to modify where that code is run, either for +{@link android.R.styleable#AndroidManifestApplication the entire .apk} +or for individual +{@link android.R.styleable#AndroidManifestActivity activity}, +{@link android.R.styleable#AndroidManifestReceiver receiver}, +{@link android.R.styleable#AndroidManifestService service}, or +{@link android.R.styleable#AndroidManifestProvider provider}, components.</p></li> +</ul> + +<h2 id="Tasks">Tasks</h2> + +<p>A key point here is: <em>when the user sees as an "application," what +they are actually dealing with is a task</em>. If you just create a .apk +with a number of activities, one of which is a top-level entry point (via +an {@link android.R.styleable#AndroidManifestIntentFilter intent-filter} for +the action <code>android.intent.action.MAIN</code> and +category <code>android.intent.category.LAUNCHER</code>), then there will indeed +be one task created for your .apk, and any activities you start from there +will also run as part of that task.</p> + +<p>A task, then, from the user's perspective your application; and from the +application developer's perspective it is one or more activities the user +has traversed through in that task and not yet closed, or an activity stack. +A new task is created by +starting an activity Intent with the {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK +Intent.FLAG_ACTIVITY_NEW_TASK} flag; this Intent will be used as the root Intent of +the task, defining what task it is. Any activity started without this flag +will run in the same task as the activity that is starting it (unless that +activity has requested a special launch mode, as discussed later). Tasks can +be re-ordered: if you use FLAG_ACTIVITY_NEW_TASK but there is already a task +running for that Intent, the current task's activity stack will be brought +to the foreground instead of starting a new task.</p> + +<p>FLAG_ACTIVITY_NEW_TASK must only be used with care: using it says that, +from the user's perspective, a new application starts at this point. If this +is not the behavior you desire, you should not be creating a new task. In +addition, you should only use the new task flag if it is possible for the user +to navigate from home back to where they are and launch the same Intent as a +new task. Otherwise, if the user presses HOME instead of BACK from the task +you have launched, your task and its activities will be ordered behind the +home screen without a way to return to them.</p> + +<h3>Task Affinities</h3> + +<p>In some cases Android needs to know which task an activity belongs to even when +it is not being launched in to a specific task. This is accomplished through +task affinities, which provide a unique static name for the task that one or more +activities are intended to run in. The default task affinity for an activity +is the name of the .apk package name the activity is implemented in. This +provides the normally expected behavior, where all of the activities in a +particular .apk are part of a single application to the user.</p> + +<p>When starting a new activity without the +{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK +Intent.FLAG_ACTIVITY_NEW_TASK} flag, task affinities have no impact on the +task the new activity will run in: it will always run in the task of the +activity that is starting it. However, if the NEW_TASK flag is being used, +then the affinity will be used to determine if a task already exists with +the same affinity. If so, that task will be brought to the front and the +new activity launched at the top of that task.</p> + +<p>This behavior is most useful for situations where you must use the +NEW_TASK flag, in particular launching activities from status bar notifications +or home screen shortcuts. The result is that, when the user launches your +application this way, its current task state will be brought to the foreground, +and the activity they now want to look at placed on top of it.</p> + +<p>You can assign your own task affinities in your manifest's +{@link android.R.styleable#AndroidManifestApplication application} tag for +all activities in the .apk, or the +{@link android.R.styleable#AndroidManifestActivity activity} tag of +individual activities. Some examples of how this can be used are:</p> + +<ul> +<li>If your .apk contains multiple top-level applications that the user can +launch, then you will probably want to assign different affinities to each +of the activities that the users sees for your .apk. A good convention for +coming up with distinct names is to append your .apk's package name with +a colon separated string. For example, the "com.android.contacts" .apk +may have the affinities "com.android.contacts:Dialer" and +"com.android.contacts:ContactsList".</ul> +<li>If you are replacing a notification, shortcut, or other such "inner" +activity of an application that can be launched from outside of it, you may +need to explicitly set the taskAffinity of your replacement activity to be +the same as the application you are replacing. For example, if you are +replacing the contacts details view (which the user can make and invoke +shortcuts to), you would want to set the taskAffinity to +"com.android.contacts".</li> +</ul> + +<h3>Launch Modes and Launch Flags</h3> + +<p>The main way you control how activities interact with tasks is through +the activity's +{@link android.R.styleable#AndroidManifestActivity_launchMode launchMode} +attribute and the {@link android.content.Intent#setFlags flags} associated +with an Intent. These two parameters can work together in various ways +to control the outcome of the activity launch, as described in their +associated documentation. Here we will look at some common use cases and +combinations of these parameters.</p> + +<p>The most common launch mode you will use (besides the default +<code>standard</code> mode) is <code>singleTop</code>. This does not have +an impact on tasks; it just avoids starting the same activity multiple times +on the top of a stack. + +<p>The <code>singleTask</code> launch mode has a major +impact on tasks: it causes the activity to always be started in +a new task (or its existing task to be brought to the foreground). Using +this mode requires a lot of care in how you interact with the rest of the +system, as it impacts every path in to the activity. It should only be used +with activities that are front doors to the application (that is, which +support the MAIN action and LAUNCHER category).</p> + +<p>The <code>singleInstance</code> launch mode is even more specialized, and +should only be used in applications that are implemented entirely as one +activity.</p> + +<p>A situation you will often run in to is when another entity (such as the +{@link android.app.SearchManager} or {@link android.app.NotificationManager}) +starts one of your activities. In this case, the +{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK +Intent.FLAG_ACTIVITY_NEW_TASK} flag must be used, because the activity is +being started outside of a task (and the application/task may not even +exist). As described previously, the standard behavior in this situation +is to bring to the foreground the current task matching the new activity's +affinity and start the new activity at the top of it. There are, however, +other types of behavior that you can implement.</p> + +<p>One common approach is to also use the +{@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP +Intent.FLAG_ACTIVITY_CLEAR_TOP} flag in conjunction with NEW_TASK. By doing so, +if your task is already running, then it will be brought to the foreground, +all of the activities on its stack cleared except the root activity, and the +root activity's {@link android.app.Activity#onNewIntent} called with the +Intent being started. Note that the activity often also use the <code>singleTop</code> +or <code>singleTask</code> launch mode when using this approach, so that +the current instance is given the new intent instead of requiring that it +be destroyed and a new instance started.</p> + +<p>Another approach you can take is to set the notification activity's task +affinity to the empty string "" (indicating no affinity) and setting the +{@link android.R.styleable#AndroidManifestActivity_finishOnTaskLaunch +finishOnBackground} attribute. This approach is useful if you would like the notification +to take the user to a separate activity describing it, rather than return +to the application's task. By specifying this attribute, the activity will +be finished whether the user leaves it with BACK or HOME; if the attribute +isn't specified, pressing HOME will result in the activity and its task +remaining in the system, possibly with no way to return to it.</p> + +<p>Be sure to read the documentation on the +{@link android.R.styleable#AndroidManifestActivity_launchMode launchMode attribute} +and the {@link android.content.Intent#setFlags Intent flags} for the details +on these options.</p> + +<h2 id="Processes">Processes</h2> + +<p>In Android, processes are entirely an implementation detail of applications +and not something the user is normally aware of. Their main uses are simply:</p> + +<ul> +<li> Improving stability or security by putting untrusted or unstable code +into another process. +<li> Reducing overhead by running the code of multiple .apks in the same +process. +<li> Helping the system manage resources by putting heavy-weight code in +a separate process that can be killed independently of other parts of the +application. +</ul> + +<p>As described previously, the +{@link android.R.styleable#AndroidManifestApplication_process process} attribute +is used to control the process that particular application components run in. +Note that this attribute can not be used to violate security of the system: if +two .apks that are not sharing the same user ID try to run in the same process, +this will not be allowed and different distinct processes will be created for +each of them.</p> + +<p>See the <a href="{@docRoot}devel/security.html">security</a> document for +more information on these security restrictions.</p> + +<h2 id="Threads">Threads</h2> + +<p>Every process has one or more threads running in it. In most situations, Android +avoids creating additional threads in a process, keeping an application +single-threaded unless it creates its own threads. An important repercussion +of this is that all calls to {@link android.app.Activity}, +{@link android.content.BroadcastReceiver}, and {@link android.app.Service} +instances are made only from the main thread of the process they are running in.</p> + +<p>Note that a new thread is <strong>not</strong> created for each +Activity, BroadcastReceiver, Service, or ContentProvider instance: +these application components are instantiated in the desired process (all in the +same process unless otherwise specified), in the main thread of that process. +This means that none of these components (including services) should perform +long or blocking operations (such as networking calls or computation loops) +when called by the system, since this will block +all other components in the process. You can use the standard library +{@link java.lang.Thread} class or Android's {@link android.os.HandlerThread} +convenience class to perform long operations on another thread.</p> + +<p>There are a few important exceptions to this threading rule:</p> + +<ul> +<li><p>Calls on to an {@link android.os.IBinder} or interface implemented on +an IBinder are dispatched from the thread calling them or a thread pool in the +local process if coming from another process, <em>not</em> +from the main thread of their process. In particular, calls on to the IBinder +of a {@link android.app.Service} will be called this way. (Though +calls to methods on Service itself are done from the main thread.) +This means that <em>implementations of IBinder interfaces must always be +written in a thread-safe way, since they can be called from any number of +arbitrary threads at the same time</em>.</p></li> + +<li><p>Calls to the main methods of {@link android.content.ContentProvider} +are dispatched from the calling thread or main thread as with IBinder. The +specific methods are documented in the ContentProvider class. +This means that <em>implementations of these methods must always be +written in a thread-safe way, since they can be called from any number of +arbitrary threads at the same time</em>.</p></li> + +<li><p>Calls on {@link android.view.View} and its subclasses are made from the +thread that the view's window is running in. Normally this will be the main +thread of the process, however if you create a thread and show a window from +there then the window's view hierarchy will be called from that thread.</p></li> +</ul> diff --git a/docs/html/guide/basics/building-blocks.jd b/docs/html/guide/basics/building-blocks.jd new file mode 100644 index 0000000..b8a609e --- /dev/null +++ b/docs/html/guide/basics/building-blocks.jd @@ -0,0 +1,76 @@ +page.title=Building Blocks +@jd:body +<h1>Android Building Blocks</h1> + +<p>You can think of an Android application as a collection of components, of +various kinds. These components are for the most part quite loosely coupled, +to the degree where you can accurately describe them as a federation of +components rather than a single cohesive application.</p> + +<p>Generally, these components all run in the same system process. It's +possible (and quite common) to create multiple threads within that process, +and it's also possible to create completely separate child processes if you +need to. Such cases are pretty uncommon though, because Android tries very +hard to make processes transparent to your code.</p> + +<p>These are the most important parts of the Android APIs:</p> + +<dl> + <dt><a href="{@docRoot}devel/bblocks-manifest.html">AndroidManifest.xml</a></dt> + <dd>The AndroidManifest.xml file is the control file that tells the system + what to do with all the top-level components (specifically activities, + services, intent receivers, and content providers described below) + you've created. For instance, this is the + "glue" that actually specifies which Intents your Activities receive.</dd> + + <dt>{@link android.app.Activity Activities}</dt> + <dd>An Activity is, fundamentally, an object that has a life cycle. An + Activity is a chunk of code that does some work; if necessary, that work + can include displaying a UI to the user. It doesn't have to, though - some + Activities never display UIs. Typically, you'll designate one of your + application's Activities as the entry point to your application. </dd> + + + <dt>{@link android.view.View Views}</dt> + <dd>A View is an object that knows how to draw itself to the screen. + Android user interfaces are comprised of trees of Views. If you want to + perform some custom graphical technique (as you might if you're writing a + game, or building some unusual new user interface widget) then you'd + create a View.</dd> + + + <dt>{@link android.content.Intent Intents}</dt> + <dd>An Intent is a simple message object that represents an "intention" to + do something. For example, if your application wants to display a web + page, it expresses its "Intent" to view the URI by creating an Intent + instance and handing it off to the system. The system locates some other + piece of code (in this case, the Browser) that knows how to handle that + Intent, and runs it. Intents can also be used to broadcast interesting + events (such as a notification) system-wide.</dd> + + + <dt>{@link android.app.Service Services}</dt> + <dd>A Service is a body of code that runs in the background. It can run in + its own process, or in the context of another application's process, + depending on its needs. Other components "bind" to a Service and invoke + methods on it via remote procedure calls. An example of a Service is a + media player; even when the user quits the media-selection UI, she + probably still intends for her music to keep playing. A Service keeps the + music going even when the UI has completed.</dd> + + + <dt>{@link android.app.NotificationManager Notifications}</dt> + <dd>A Notification is a small icon that appears in the status bar. Users + can interact with this icon to receive information. The most well-known + notifications are SMS messages, call history, and voicemail, but + applications can create their own. Notifications are the + strongly-preferred mechanism for alerting the user of something that needs + their attention.</dd> + + <dt>{@link android.content.ContentProvider ContentProviders}</dt> + <dd>A ContentProvider is a data storehouse that provides access to data on + the device; the classic example is the ContentProvider that's used to + access the user's list of contacts. Your application can access data that + other applications have exposed via a ContentProvider, and you can also + define your own ContentProviders to expose data of your own.</dd> +</dl> diff --git a/docs/html/guide/basics/fixme-gs-core-packages.jd b/docs/html/guide/basics/fixme-gs-core-packages.jd new file mode 100644 index 0000000..5281990 --- /dev/null +++ b/docs/html/guide/basics/fixme-gs-core-packages.jd @@ -0,0 +1,92 @@ +page.title=Getting Started +@jd:body +<h1>Getting Started with Android</h1> + +<p>To get started with Android, please read the following sections first:</p> +<dl> + <dt><a href="{@docRoot}intro/installing.html">Installing the SDK and + Plugin</a></dt> + <dd>How to install the Android SDK and Eclipse plugin.</dd> + <dt><a href="{@docRoot}intro/develop-and-debug.html">Developing and Debugging</a></dt> + <dd>An introduction to developing and debugging Android applications in Eclipse, + plus information on using other IDEs.</dd> + <dt><a href="{@docRoot}intro/hello-android.html">Hello Android</a></dt> + <dd>Writing your first Android Application, the ever popular Hello World, + Android style.</dd> + <dt><a href="{@docRoot}intro/anatomy.html">Anatomy of an App</a></dt> + <dd>A guide to the structure and architecture of an Android + Application. This guide will help you understand the pieces that make up + an Android app.</dd> + <dt><a href="{@docRoot}intro/tutorial.html">Notepad Tutorial</a></dt> + <dd>This tutorial document will lead you through + constructing a real Android Application: A notepad which can create, edit + and delete notes, and covers many of the basic concepts with practical + examples.</dd> + <dt><a href="{@docRoot}intro/tools.html">Development Tools</a></dt> + <dd>The + command line tools included with the SDK, what they do, and how to use + them.</dd> + <dt><a href="{@docRoot}intro/appmodel.html">Application Model</a></dt> + <dd>A guide to Applications, Tasks, Processes, and Threads. + These are the elements that define the way your application is run by the + system and presented to the user.</dd> + <dt><a href="{@docRoot}intro/lifecycle.html">Application Life Cycle</a></dt> + <dd>The important life-cycle details for + Applications and the Activities running inside of them.</dd> + +</dl> + +<h2>Other Introductory Material</h2> +<p>After reading the sections above, the following Getting Started information is also very useful:</p> + + +<h3>Core Packages</h3> +<p> These are the basic packages that make up the Android SDK for writing +applications. The packages are organized as layers, listed here from +lowest-level to highest.</p> + +<dl> + <dt>{@link android.util}</dt> + <dd>contains various low-level utility classes, such + as specialized container classes, XML utilities, etc.</dd> + <dt>{@link android.os}</dt> + <dd> provides basic operating system services, message + passing, and inter-process communication.</dd> + <dt>{@link android.graphics}</dt><dd>is the core rendering package.</dd> + <dt>{@link android.text}, {@link android.text.method}, {@link + android.text.style}, and {@link android.text.util} </dt> + <dd>supply a rich set of + text processing tools, supporting rich text, input methods, etc.</dd> + <dt>{@link android.database}</dt> + <dd>contains low-level APIs for working with + databases.</dd> + <dt>{@link android.content}</dt> + <dd>provides various services for accessing data + on the device: applications installed on the device and their associated + resources, and content providers for persistent dynamic data.</dd> + <dt>{@link android.view}</dt> + <dd>is the core user-interface framework.</dd> + <dt>{@link android.widget}</dt> + <dd>supplies standard user interface elements + (lists, buttons, layout managers, etc) built from the view package.</dd> + <dt>{@link android.app}</dt> + <dd>provides the high-level application model, + implemented using Activities.</dd> +</dl> + +<h3>Other Notable Packages</h3> + +<p> These packages provide additional domain-specific features of the Android +platform. They are not necessary for basic application development.</p> + +<dl> + <dt>{@link android.provider}</dt> + <dd>contains definitions for various standard + content providers included with the platform.</dd> + <dt>{@link android.telephony}</dt> + <dd>provides APIs for interacting with the + device's phone stack.</dd> + <dt>{@link android.webkit}</dt> + <dd>includes various APIs for working with + web-based content.</dd> +</dl> diff --git a/docs/html/guide/basics/index.html b/docs/html/guide/basics/index.html new file mode 100644 index 0000000..4881acf --- /dev/null +++ b/docs/html/guide/basics/index.html @@ -0,0 +1,8 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=../index.html"> +</head> +<body> +<a href="../index.html">click here</a> if you are not redirected. +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/basics/index.jd b/docs/html/guide/basics/index.jd new file mode 100644 index 0000000..e1bbc52 --- /dev/null +++ b/docs/html/guide/basics/index.jd @@ -0,0 +1,58 @@ +page.title=Developing Applications +@jd:body +<h1>Developing Android Applications</h1> +<p>You can develop Android applications with the same high-quality tools you +use to develop Java applications. The Android core libraries provide the +functionality needed to build some amazingly rich mobile applications, and +the Android development tools make running, debugging, and testing your +applications a snap.</p> + +<p>This section explains the ins and outs of developing Android +applications. It outlines the philosophy +behind the system and then describes each of the +key subsystems in detail. After reading this section, you'll have the knowledge +and confidence to begin writing that real-world Android app you have in +mind.</p> + +<p>Before reading this section you should read the <a +href="{@docRoot}intro/index.html">Getting Started Guide</a>, which helps you get +up and running with the Android SDK and shows you how to build a basic +app. This section builds on the information in the Getting Started +section.</p> + +<p>Here's the content you'll find in this section:</p> + +<dl> + <dt><a href="{@docRoot}devel/implementing-ui.html">Implementing a UI</a></dt> + <dd>Explains how to construct and interact with user interfaces for Android + applications. After reading this page you'll have a solid understanding of + how Android layouts are built, how they operate at runtime, and how you can + make them pretty.</dd> + <dt><a href="{@docRoot}devel/building-blocks.html">Building Blocks</a></dt> + <dd>Detailed descriptions of Android components. Covers the ins and outs + of the components summarized in Anatomy of an Android App, plus more. This + section goes into detail on each of the key Android components (Intents, + Activities, Views, and events.)</dd> + <dt><a href="{@docRoot}devel/data.html">Storing and Retrieving Data</a></dt> + <dd>How to read and write data to the various storage mechanisms + provided by Android, and to network services. There are several + different ways to read and write data from an Android application, + each aimed at different needs. This page describes them all and + explains how to pick the right one for your needs.</dd> + <dt><a href="{@docRoot}devel/security.html">Security Model</a></dt> + <dd>Gaining access to secure system resources and features, and + declaring permissions to control access to your own secure features. + Permissions control whether a given application is able to access + piece of functionality provided by another application (for example, + which applications can dial the phone). This page describes how + permissions work and how to request permissions as well as define your + own.</dd> + <dt><a href="{@docRoot}devel/resources-i18n.html">Resources and i18n</a></dt> + <dd>Detailed descriptions of Android's application-resource management + system, including how it's used for internationalization and + localization. "Resources" are application assets (such as images, + localized strings, and XML layouts) that need to be resolved at + runtime. This page describes how Android resolves which resource to + load from a selection of them, as well as how to create and use + resources.</dd> +</dl> diff --git a/docs/html/guide/basics/what-is-android.jd b/docs/html/guide/basics/what-is-android.jd new file mode 100755 index 0000000..926b433 --- /dev/null +++ b/docs/html/guide/basics/what-is-android.jd @@ -0,0 +1,135 @@ +page.title=What is Android? +@jd:body + +<p>Android is a software stack for mobile devices that includes an operating +system, middleware and key applications. This beta version of the <a +href="http://code.google.com/android/download.html">Android SDK</a> +provides the tools and APIs necessary to begin developing applications on the +Android platform using the Java programming language.</p> + +<h2>Features</h2> + +<ul> + <li><strong>Application framework</strong> enabling reuse and replacement + of components</li> + <li><strong>Dalvik virtual machine</strong> optimized for mobile + devices</li> + <li><strong>Integrated browser</strong> based on the open source <a + href="http://webkit.org/">WebKit</a> engine </li> + <li><strong>Optimized graphics</strong> powered by a custom 2D graphics library; 3D + graphics based on the OpenGL ES 1.0 specification (hardware acceleration + optional)</li> + <li><strong>SQLite</strong> for structured data storage</li> + <li><strong>Media support</strong> for common audio, video, and still + image formats (MPEG4, H.264, MP3, AAC, AMR, JPG, PNG, + GIF)</li> + <li><strong>GSM Telephony</strong> (hardware dependent)</li> + <li><strong>Bluetooth, EDGE, 3G, and WiFi</strong> (hardware dependent)</li> + <li><strong>Camera, GPS, compass, and accelerometer</strong> (hardware dependent)</li> + <li><strong>Rich development environment</strong> including a device + emulator, tools for debugging, memory and performance profiling, and a plugin for the Eclipse IDE</li> +</ul> + +<a name="os_architecture" id="os_architecture"></a> +<h2>Android Architecture</h2> + +<p>The following diagram shows the major components of the Android operating +system. Each section is described in more detail below.</p> + +<p><img src="{@docRoot}images/system-architecture.jpg" alt="Android System Architecture" width="713" height="512"></p> + +<a name="applications" id="applications"></a> +<h2>Applications</h2> + +<p>Android will ship with a set of core applications including an email +client, SMS program, calendar, maps, browser, contacts, and +others. All applications are written using the Java programming language.</p> + +<a name="application_framework" id="application_framework"></a> +<h2>Application Framework</h2> + +<p>Developers have full access to the same framework APIs used by the core +applications. The application architecture is designed to simplify the reuse +of components; any application can publish its capabilities and any other +application may then make use of those capabilities (subject to security +constraints enforced by the framework). This same mechanism allows components +to be replaced by the user.</p> + +<p>Underlying all applications is a set of services and systems, including: +<ul> + <li>A rich and extensible set of <a + href="{@docRoot}reference/view-gallery.html">Views</a> that can be used to + build an application, including lists, grids, text boxes, buttons, and even + an embeddable web browser</li> + <li><a href="{@docRoot}devel/data/contentproviders.html">Content + Providers</a> that enable applications to access data from other + applications (such as Contacts), or to share their own data</li> + <li>A <a href="{@docRoot}devel/resources-i18n.html">Resource Manager</a>, + providing access to non-code resources such as localized strings, graphics, + and layout files</li> + <li>A {@link android.app.NotificationManager Notification Manager} that enables + all applications to display custom alerts in the status bar</li> + <li>An {@link android.app.Activity Activity Manager} that manages the + life cycle of applications and provides a common navigation backstack</li> +</ul> + +<p>For more details and a walkthrough of an application, see <a +href="{@docRoot}intro/tutorial.html">Writing an Android Application</a>.</p> + +<a name="libraries" id="libraries"></a> +<h2>Libraries</h2> + +<p>Android includes a set of C/C++ libraries used by various components of the +Android system. These capabilities are exposed to developers through the +Android application framework. Some of the core libraries are listed below:</p> +<ul> + <li><strong>System C library</strong> - a BSD-derived implementation of + the standard C system library (libc), tuned for embedded Linux-based + devices</li> + <li><strong>Media Libraries</strong> - based on PacketVideo's OpenCORE; + the libraries support playback and recording of many popular audio and video + formats, as well as static image files, including MPEG4, H.264, MP3, AAC, + AMR, JPG, and PNG</li> + <li><strong>Surface Manager</strong> - manages access to the display + subsystem and seamlessly composites 2D and 3D graphic layers from multiple + applications</li> + <li><strong>LibWebCore</strong> - a modern web browser engine which + powers both the Android browser and an embeddable web view</li> + <li><strong>SGL</strong> - the underlying 2D graphics + engine</li> + <li><strong>3D libraries</strong> - an implementation based on + OpenGL ES 1.0 APIs; the libraries use either hardware 3D acceleration + (where available) or the included, highly optimized 3D software + rasterizer</li> + <li><strong>FreeType</strong> - bitmap and vector font rendering</li> + <li><strong>SQLite</strong> - a powerful and lightweight relational + database engine available to all applications</li> +</ul> + +<a name="runtime" id="runtime"></a> + +<h2>Android Runtime</h2> + +<p>Android includes a set of core libraries that provides most of +the functionality available in the core libraries of the Java programming +language.</p> + +<p>Every Android application runs in its own process, with its own instance of +the Dalvik virtual machine. Dalvik has been written so that a device can run +multiple VMs efficiently. The Dalvik VM executes files in the Dalvik +Executable (.dex) format which is optimized for minimal memory +footprint. The VM is register-based, and runs classes +compiled by a Java language compiler that have been transformed into the .dex +format by the included "dx" tool.</p> + +<p>The Dalvik VM relies on the Linux kernel for underlying functionality such +as threading and low-level memory management.</p> + +<a name="kernel" id="kernel"></a> + +<h2>Linux Kernel</h2> + +<p>Android relies on Linux version 2.6 for core system services such as +security, memory management, process management, network stack, and driver +model. The kernel also acts as an abstraction layer between the hardware and +the rest of the software stack.</p> diff --git a/docs/html/guide/developing/aapt.jd b/docs/html/guide/developing/aapt.jd new file mode 100644 index 0000000..40a209d --- /dev/null +++ b/docs/html/guide/developing/aapt.jd @@ -0,0 +1,20 @@ +page.title=Using aapt +@jd:body + +<p><strong>aapt</strong> stands for Android Asset Packaging Tool and is included in the <code>tools/</code> directory of the SDK. This tool allows you to view, create, and update Zip-compatible archives (zip, jar, apk). It can also compile resources into binary assets. +</p> +<p> +Though you probably won't often use <strong>aapt</strong> directly, build scripts and IDE plugins can utilize this tool to package the apk file that constitutes an Android application. +</p> +<p> +For more usage details, open a terminal, go to the <code>tools/</code> directory, and run the command: +</p> +<ul> + <li><p>Linux or Mac OS X:</p> + <pre>./aapt</pre> + </li> + <li><p>Windows:</p> + <pre>aapt.exe</pre> + </li> +</ul> + diff --git a/docs/html/guide/developing/adb.jd b/docs/html/guide/developing/adb.jd new file mode 100644 index 0000000..25b5e29 --- /dev/null +++ b/docs/html/guide/developing/adb.jd @@ -0,0 +1,668 @@ +page.title=Android Debug Bridge +@jd:body + +<p>Android Debug Bridge (adb) is a versatile tool that lets you manage the state of a device or <a href="{@docRoot}reference/emulator.html">emulator</a>. </p> + +<p>Some of ways you can use adb include:</p> + +<ul> +<li>Run shell commands on a device</li> +<li>Manage port forwarding on an emulator or device</li> +<li>Copy files to/from an emulator or device</li> +</ul> +<p>The sections below introduce adb and describe many of its common uses. </p> + +<h2>Contents</h2> +<dl> +<dt><a href="#overview">Overview</a></dt> +<dt><a href="#issuingcommands">Issuing adb Commands</a></dt> +<dt><a href="#devicestatus">Querying for Emulator/Device Instances</a></dt> +<dt><a href="#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a></dt> +<dt><a href="#move">Installing an Application</a></dt> +<dt><a href="#forwardports">Forwarding Ports</a></dt> +<dt><a href="#copyfiles">Copying Files to or from an Emulator/Device Instance</a></dt> +<dt><a href="#commandsummary">Listing of adb Commands </a></dt> +<dt><a href="#shellcommands">Issuing Shell Commands</a></dt> + <dd><a href="#sqlite">Examining sqlite3 Databases from a Remote Shell</a></dd> + <dd><a href="#monkey">UI/Application Exerciser Monkey</a></dd> + <dd><a href="#othershellcommands">Other Shell Commands</a></dd> +<dt><a href="#logcat">Enabling logcat Logging</a> </dt> + <dd><a href="#usinglogcat">Using logcat Commands</a></dd> + <dd><a href="#filteringoutput">Filtering Log Output</a></dd> + <dd><a href="#outputformat">Controlling Log Output Format</a></dd> + <dd><a href="#alternativebuffers">Viewing Alternative Log Buffers</a></dd> + <dd><a href="#stdout">Viewing stdout and stderr</a></dd> + <dd><a href="#logcatoptions">Listing of logcat Command Options</a></dd> +<dt><a href="#stopping">Stopping the adb Server</a> </dt> +</dl> + +<a name="overview"></a> + +<h2>Overview</h2> + +<p>The adb tool is a client-server program that includes three components: </p> + +<ul> + <li>A client, which runs on your development machine. You can invoke a client from a shell by issuing an adb command. Other Android tools such as the ADT plugin and DDMS also create adb clients. </li> + <li>A server, which runs as a background process on your development machine. The server manages communication between the client and the adb daemon running on an emulator or device. </li> + <li>A daemon, which runs as a background process on each emulator or device instance. </li> +</ul> + +<p>When you start an adb client, the client first checks whether there is an adb server process already running. If there isn't, it starts the server process. When the server starts, it binds to local TCP port 5037 and listens for commands sent from adb clients—all adb clients use port 5037 to communicate with the adb server. </p> + +<p>The server then sets up connections to all running emulator/device instances. It locates emulator/device instances by scanning odd-numbered ports in the range 5555 to 5585, the range used by emulators/devices. Where the server finds an adb daemon, it sets up a connection to that port. Note that each emulator/device instance acquires a pair of sequential ports — an even-numbered port for console connections and an odd-numbered port for adb connections. For example: </p> + +<blockquote> +Emulator 1, console: 5554<br/> +Emulator 1, adb: 5555<br> +Emulator 2, console: 5556<br> +Emulator 2, adb: 5557 ... +</blockquote> + +<p>As shown, the emulator instance connected to adb on port 5555 is the same as the instance whose console listens on port 5554. </p> + +<p>Once the server has set up connections to all emulator instances, you can use adb commands to control and access those instances. Because the server manages connections to emulator/device instances and handles commands from multiple adb clients, you can control any emulator/device instance from any client (or from a script).</p> + +<p>The sections below describe the commands that you can use to access adb capabilities and manage the state of an emulator/device. Note that if you are developing Android applications in Eclipse and have installed the ADT plugin, you do not need to access adb from the command line. The ADT plugin provides a trasparent integration of adb into the Eclipse IDE. However, you can still use adb directly as necessary, such as for debugging.</p> + +<a name="issuingcommands"></a> + +<h2>Issuing adb Commands</h2> + +<p>You can issue adb commands from a command line on your development machine or from a script. The usage is: </p> + + <pre>adb [-d|-e|-s <serialNumber>] <command> </pre> + +<p>When you issue a command, the program invokes an adb client. The client is not specifically associated with any emulator instance, so if multiple emulators/devices are running, you need to use the <code>-d</code> option to specify the target instance to which the command should be directed. For more information about using this option, see <a href"#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a>. </p> + +<a name="devicestatus"></a> + +<h2>Querying for Emulator/Device Instances</h2> + +<p>Before issuing adb commands, it is helpful to know what emulator/device instances are connected to the adb server. You can generate a list of attached emulators/devices using the <code>devices</code> command: </p> + + <pre>adb devices</pre> + +<p>In response, adb prints this status information for each instance:</p> + +<ul> + <li>Serial number — A string created by adb to uniquely identify an emulator/device instance by its + console port number. The format of the serial number is <code><type>-<consolePort></code>. + Here's an example serial number: <code>emulator-5554</code></li> + <li>State — The connection state of the instance. Three states are supported: + <ul> + <li><code>offline</code> — the instance is not connected to adb or is not responding.</li> + <li><code>device</code> — the instance is now connected to the adb server. Note that this state does not + imply that the Android system is fully booted and operational, since the instance connects to adb + while the system is still booting. However, after boot-up, this is the normal operational state of + an emulator/device instance.</li> + </ul> + </li> +</ul> + +<p>The output for each instance is formatted like this: </p> + + <pre>[serialNumber] [state]</pre> + +<p>Here's an example showing the <code>devices</code> command and its output:</p> + + <pre>$ adb devices +List of devices attached +emulator-5554 device +emulator-5556 device +emulator-5558 device</pre> + +<p>If there is no emulator/device running, adb returns <code>no device</code>.</p> + + +<a name="directingcommands"></a> + +<h2>Directing Commands to a Specific Emulator/Device Instance</h2> + +<p>If multiple emulator/device instances are running, you need to specify a target instance when issuing adb commands. To so so, use the <code>-s</code> option in the commands. The usage for the <code>-s</code> option is:</p> + + <pre>adb -s <serialNumber> <command> </pre> + +<p>As shown, you specify the target instance for a command using its adb-assigned serial number. You can use the <code>devices</code> command to obtain the serial numbers of running emulator/device instances. </p> + +<p>Here is an example: </p> + + <pre>adb -s emulator-5556 install helloWorld.apk</pre> + +<p>Note that, if you issue a command without specifying a target emulator/device instance using <code>-s</code>, adb generates an error. + +<a name="move"></a> + +<h2>Installing an Application</h2> +<p>You can use adb to copy an application from your development computer and install it on an emulator/device instance. To do so, use the <code>install</code> command. With the command, you must specify the path to the .apk file that you want to install:</p> + +<pre>adb install <path_to_apk></pre> + +<p>For more information about how to create an .apk file that you can install on an emulator/device instance, see <a href="{@docRoot}reference/aapt.html">Android Asset Packaging Tool</a> (aapt). </p> + +<p>Note that, if you are using the Eclipse IDE and have the ADT plugin installed, you do not need to use adb (or aapt) directly to install your application on the emulator/device. Instead, the ADT plugin handles the packaging and installation of the application for you. </p> + + +<a name="forwardports"></a> + +<h2>Forwarding Ports</h2> + + <p>You can use the <code>forward</code> command to set up arbitrary port forwarding — forwarding of requests on a specific host port to a different port on an emulator/device instance. Here's how you would set up forwarding of host port 6100 to emulator/device port 7100:</p> +<pre>adb forward tcp:6100 tcp:7100</pre> + <p>You can also use adb to set up forwarding to named abstract UNIX domain sockets, as illustrated here:</p> +<pre>adb forward tcp:6100 local:logd </pre> + +<a name="copyfiles"></a> + +<h2>Copying Files to or from an Emulator/Device Instance</h2> + +<p>You can use the adb commands <code>pull</code> and <code>push</code> to copy files to and from an emulator/device instance's data file. Unlike the <code>install</code> command, which only copies an .apk file to a specific location, the <code>pull</code> and <code>push</code> commands let you copy arbitrary directories and files to any location in an emulator/device instance. </p> + +<p>To copy a file or directory (recursively) <em>from</em> the emulator or device, use</p> +<pre>adb pull <remote> <local></pre> + +<p>To copy a file or directory (recursively) <em>to</em> the emulator or device, use</p> + <pre>adb push <local> <remote></pre> + +<p>In the commands, <code><local></code> and <code><remote></code> refer to the paths to the target files/directory on your development machine (local) and on the emulator/device instance (remote).</p> + +<p>Here's an example: </p> +<pre>adb push foo.txt /sdcard/foo.txt</pre> + +<a name="commandsummary"></a> + +<h2>Listing of adb Commands</h2> + +<p>The table below lists all of the supported adb commands and explains their meaning and usage. </p> + + +<table> +<tr> + <th>Category</th> + <th>Command</th> + <th>Description</th> + <th>Comments</th> +</tr> + +<tr> +<td rowspan="3">Options</td> +<td><code>-d</code></td> +<td>Direct an adb command to the only attached USB device.</td> +<td>Returns an error if more than one USB device is attached.</td> +</tr> + +<tr> +<td><code>-e</code></td> +<td>Direct an adb command to the only running emulator instance.</td> +<td>Returns an error if more than one emulator instance is running. </td> +</tr> + +<tr> +<td><code>-s <serialNumber></code></td> +<td>Direct an adb command a specific emulator/device instance, referred to by its adb-assigned serial number (such as "emulator-5556").</td> +<td>If not specified, adb generates an error.</td> +</tr> + +<tr> +<td rowspan="3">General</td> +<td><code>devices</code></td> +<td>Prints a list of all attached emulator/device instances.</td> +<td>See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information.</td> +</tr> + +<tr> +<td><code>help</code></td> +<td>Prints a list of supported adb commands.</td> +<td> </td> +</tr> + +<tr> +<td><code>version</code></td> +<td>Prints the adb version number. </td> +<td> </td> +</tr> + +<tr> +<td rowspan="3">Debug</td> +<td ><code>logcat [<option>] [<filter-specs>]</code></td> +<td>Prints log data to the screen. </td> +<td> </td> +</tr> + +<tr> +<td><code>bugreport</code></td> +<td>Prints <code>dumpsys</code>, <code>dumpstate</code>, and <code>logcat</code> data to the screen, for the purposes of bug reporting. </td> +<td> </td> +</tr> + +<tr> +<td><code>jdwp</code></td> +<td>Prints a list of available JDWP processes on a given device. </td> +<td>You can use the <code>forward jdwp:<pid></code> port-forwarding specification to connect to a specific JDWP process. For example: <br> + <code>adb forward tcp:8000 jdwp:472</code><br> + <code>jdb -attach localhost:8000</code></p> + </td> +</tr> + +<tr> +<td rowspan=3">Data</td> +<td><code>install <path-to-apk></code></td> +<td>Pushes an Android application (specified as a full path to an .apk file) to the data file of an emulator/device. </td> +<td> </td> +</tr> + +<tr> +<td><code>pull <remote> <local></code></td> +<td>Copies a specified file from an emulator/device instance to your development computer. </td> +<td> </td> +</tr> + +<tr> +<td><code>push <local> <remote></code></td> +<td>Copies a specified file from your development computer to an emulator/device instance. </td> +<td> </td> +</tr> + +<tr> +<td rowspan="2">Ports and Networking</td> +<td><code>forward <local> <remote></code></td> +<td>Forwards socket connections from a specified local port to a specified remote port on the emulator/device instance. </td> +<td>Port specifications can use these schemes: +<ul><li><code>tcp:<portnum></code></li> +<li><code>local:<UNIX domain socket name></code></li> +<li><code>dev:<character device name></code></li> +<li><code>jdwp:<pid></code></li></ul> +</td> +</tr> + +<tr> +<td><code>ppp <tty> [parm]...</code></td> +<td>Run PPP over USB. +<ul> +<li><code><tty></code> — the tty for PPP stream. For example <code>dev:/dev/omap_csmi_ttyl</code>. </li> +<li><code>[parm]... </code> &mdash zero or more PPP/PPPD options, such as <code>defaultroute</code>, <code>local</code>, <code>notty</code>, etc.</li></ul> + +<p>Note that you should not automatically start a PDP connection. </p></td> +<td></td> +</tr> + +<tr> +<td rowspan="3">Scripting</td> +<td><code>get-serialno</code></td> +<td>Prints the adb instance serial number string.</td> +<td rowspan="2">See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information. </td> +</tr> + +<tr> +<td><code>get-state</code></td> +<td>Prints the adb state of an emulator/device instance.</td> +</td> +</tr> + +<tr> +<td><code>wait-for-device</code></td> +<td>Blocks execution until the device is online — that is, until the instance state is <code>device</code>.</td> +<td>You can prepend this command to other adb commands, in which case adb will wait until the emulator/device instance is connected before issuing the other commands. Here's an example: +<pre>adb wait-for-device shell getprop</pre> + +Note that this command does <em>not</em> cause adb to wait until the entire system is fully booted. For that reason, you should not prepend it to other commands that require a fully booted system. As an example, the <code>install</code> requires the Android package manager, which is available only after the system is fully booted. A command such as + +<pre>adb wait-for-device install <app>.apk</pre> + +would issue the <code>install</code> command as soon as the emulator or device instance connected to the adb server, but before the Android system was fully booted, so it would result in an error. </td> +</tr> + + + +<tr> +<td rowspan="2">Server</td> +<td><code>start-server</code></td> +<td>Checks whether the adb server process is running and starts it, if not.</td> +<td> </td> +</tr> + +<tr> +<td><code>kill-server</code></td> +<td>Terminates the adb server process.</td> +<td> </td> +</tr> + + + +<tr> +<td rowspan="2">Shell</td> +<td><code>shell</code></td> +<td>Starts a remote shell in the target emulator/device instance.</td> +<td rowspan="2">See <a href="#shellcommands">Issuing Shell Commands</a> for more information. </td> +</tr> + +<tr> +<td><code>shell [<shellCommand>]</code></td> +<td>Issues a shell command in the target emulator/device instance and then exits the remote shell.</td> +</tr> + +</table> + + +<a name="shellcommands"></a> + +<h2>Issuing Shell Commands</h2> + +<p>Adb provides an ash shell that you can use to run a variety of commands on an emulator +or device. The command binaries are stored in the file system of the emulator or device, +in this location: </p> + +<pre>/system/bin/...</pre> + +<p>You can use the <code>shell</code> command to issue commands, with or without entering the adb remote shell on the emulator/device. </p> + +<p>To issue a single command without entering a remote shell, use the <code>shell</code> command like this: </p> + + <pre>adb [-d|-e|-s {<serialNumber>}] shell <shellCommand></pre> + +<p>To drop into a remote shell on a emulator/device instance, use the <code>shell</code> command like this:</p> + + <pre>adb [-d|-e|-s {<serialNumber>}] shell</pre> + +<p>When you are ready to exit the remote shell, use <code>CTRL+D</code> or <code>exit</code> to end the shell session. </p> + +<p>The sections below provide more information about shell commands that you can use.</p> + +<a name="sqlite" id="sqlite"></a> + +<h3>Examining sqlite3 Databases from a Remote Shell</h3> + +<p>From an adb remote shell, you can use the +<a href="http://www.sqlite.org/sqlite.html">sqlite3</a> command-line program to +manage SQLite databases created by Android applications. The +<code>sqlite3</code> tool includes many useful commands, such as +<code>.dump</code> to print out the contents of a table and +<code>.schema</code> to print the SQL CREATE statement for an existing table. +The tool also gives you the ability to execute SQLite commands on the fly.</p> + +<p>To use <code>sqlite3</code>, enter a remote shell on the emulator instance, as described above, then invoke the tool using the <code>sqlite3</code> command. Optionally, when invoking <code>sqlite3</code> you can specify the full path to the database you want to explore. Emulator/device instances store SQLite3 databases in the folder <code><span chatdir="1"><span chatindex="259474B4B070F261">/data/data/<em><package_name></em>/databases</span></span>/</code>. </p> + +<p>Here's an example: </p> + +<pre>$ adb -s emulator-5554 shell +# sqlite3 /data/data/com.example.google.rss.rssexample/databases/rssitems.db +SQLite version 3.3.12 +Enter ".help" for instructions +<em>.... enter commands, then quit...</em> +sqlite> .exit </pre> + +<p>Once you've invoked <code>sqlite3</code>, you can issue <code>sqlite3</code> commands in the shell. To exit and return to the adb remote shell, use <code>exit</code> or <code>CTRL+D</code>. + + +<a name="monkey"></a> + +<h3>UI/Application Exerciser Monkey</h3> + +<p>The Monkey is a program that runs on your emulator or device and generates pseudo-random +streams of user events such as clicks, touches, or gestures, as well as a number of system-level +events. You can use the Monkey to stress-test applications that you are developing, +in a random yet repeatable manner.</p> + +<p>The simplest way to use the monkey is with the following command, which will launch your +application and send 500 pseudo-random events to it.</p> + +<pre>$ adb shell monkey -v -p your.package.name 500</pre> + +<p>For more information about command options for Monkey, see the complete +<a href="{@docRoot}reference/monkey.html" title="monkey">UI/Application Exerciser Monkey</a> documentation page.</p> + + +<a name="othershellcommands"></a> + +<h3>Other Shell Commands</h3> + +<p>The table below lists several of the adb shell commands available. For a complete list of commands and programs, start an emulator instance and use the <code>adb -help</code> command. </p> + +<pre>adb shell ls /system/bin</pre> + +<p>Help is available for most of the commands. </p> + +<table> +<tr> + <th>Shell Command</th> + <th>Description</th> + <th>Comments</th> +</tr> + +<tr> +<td><code>dumpsys</code></td> +<td>Dumps system data to the screen.</td> +<td rowspan=4">The <a href="{@docRoot}reference/ddms.html">Dalvik Debug Monitor Service</a> (DDMS) tool offers integrated debug environment that you may find easier to use.</td> +</tr> + +<tr> +<td><code>dumpstate</code></td> +<td>Dumps state to a file.</td> +</tr> + +<tr> +<td><code>logcat [<option>]... [<filter-spec>]...</code></td> +<td>Enables radio logging and prints output to the screen. </td> +</tr> + +<tr> +<td><code>dmesg</code></td> +<td>Prints kernel debugging messages to the screen. </td> +</tr> + +<tr> +<td><code>start</code></td> +<td>Starts (restarts) an emulator/device instance.</td> +<td> </td> +</tr> + +<tr> +<td><code>stop</code></td> +<td>Stops execution of an emulator/device instance.</td> +<td> </td> +</tr> + +</table> + +<a name="logcat"></a> + +<h2>Enabling logcat Logging</h2> + +<p>The Android logging system provides a mechanism for collecting and viewing system debug output. Logs from various applications and portions of the system are collected in a series of circular buffers, which then can be viewed and filtered by the <code>logcat</code> command.</p> + +<a name="usinglogcat"></a> + +<h3>Using logcat Commands</h3> + +<p>You can use the <code>logcat</code> command to view and follow the contents of the system's log buffers. The general usage is:</p> + +<pre>[adb] logcat [<option>] ... [<filter-spec>] ...</pre> + +<p>The sections below explain filter specifications and the command options. See <a href="#logcatoptions">Listing of logcat Command Options</a> for a summary of options. </p> + +<p>You can use the <code>logcat</code> command from your development computer or from a remote adb shell in an emulator/device instance. To view log output in your development computer, you use</p> + +<pre>$ adb logcat</pre> + +<p>and from a remote adb shell you use</p> + +<pre># logcat</pre> + +<a name="filteringoutput"></a> + +<h3>Filtering Log Output</h3> + +<p>Every Android log message has a <em>tag</em> and a <em>priority</em> associated with it. </p> + +<ul> +<li>The tag of a log message is a short string indicating the system component from which the message originates (for example, "View" for the view system). </li> + +<li>The priority is one of the following character values, ordered from lowest to highest priority:</li> + +<ul> + <li><code>V</code> — Verbose (lowest priority)</li> + <li><code>D</code> — Debug</li> + <li><code>I</code> — Info</li> + <li><code>W</code> — Warning</li> + <li><code>E</code> — Error</li> + <li><code>F</code> — Fatal</li> + <li><code>S</code> — Silent (highest priority, on which nothing is ever printed)</li> +</ul> +</ul> + +<p>You can obtain a list of tags used in the system, together with priorities, by running <code>logcat</code> and observing the first two columns +of each message, given as <code><priority>/<tag></code>. </p> + +<p>Here's an example of logcat output that shows that the message relates to priority level "I" and tag "ActivityManager":</p> + +<pre>I/ActivityManager( 585): Starting activity: Intent { action=android.intent.action...}</pre> + +<p>To reduce the log output to a manageable level, you can restrict log output using <em>filter expressions</em>. Filter expressions let you indicate to the system the tags-priority combinations that you are interested in — the system suppresses other messages for the specified tags. </p> + +<p>A filter expression follows this format <code>tag:priority ...</code>, where <code>tag</code> indicates the tag of interest and <code>priority</code> indicates the <em>minimum</em> level of priority to report for that tag. Messages for that tag at or above the specified priority are written to the log. You can supply any number of <code>tag:priority</code> specifications in a single filter expression. The series of specifications is whitespace-delimited. </p> + +<p>Here's an example of a filter expression that suppresses all log messages except those with the tag "ActivityManager", at priority "Info" or above, and all log messages with tag "MyApp", with priority "Debug" or above:</p> + +<pre>adb logcat ActivityManager:I MyApp:D *:S</pre> + +<p>The final element in the above expression, <code>*:S</code>, sets the priority level for all tags to "silent", thus ensuring only log messages with "View" and "MyApp" are displayed. Using <code>*:S</code> is an excellent way to ensure that log output is restricted to the filters that you have explicitly specified — it lets your filters serve as a "whitelist" for log output.</p> + +<p>The following filter expression displays all log messages with priority level "warning" and higher, on all tags:</p> + +<pre>adb logcat *:W</pre> + +<p>If you're running <code>logcat</code> from your development computer (versus running it on a remote adb shell), you can also set a default filter expression by exporting a value for the environment variable <code>ANDROID_LOG_TAGS</code>:</p> + +<pre>export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"</pre> + +<p>Note that <code>ANDROID_LOG_TAGS</code> filter is not exported to the emulator/device instance, if you are running <code>logcat</code> from a remote shell or using <code>adb shell logcat</code>.</p> + + +<a name="outputformat"></a> + +<h3>Controlling Log Output Format</h3> + +<p>Log messages contain a number of metadata fields, in addition to the tag and priority. You can modify the output format for messages so that they display a specific metadata field. To do so, you use the <code>-v</code> option and specify one of the supported output formats listed below. </p> + +<ul> + <li><code>brief</code> — Display priority/tag and PID of originating process (the default format).</li> + <li><code>process</code> — Display PID only.</li> + <li><code>tag</code> — Display the priority/tag only. </li> + <li><code>thread</code> — Display process:thread and priority/tag only. </li> + <li><code>raw</code> — Display the raw log message, with no other metadata fields.</li> + <li><code>time</code> — Display the date, invocation time, priority/tag, and PID of the originating process.</li> + <li><code>long</code> — Display all metadata fields and separate messages with a blank lines.</li> +</ul> + +<p>When starting <code>logcat</code>, you can specify the output format you want by using the <code>-v</code> option:</p> + +<pre>[adb] logcat [-v <format>]</pre> + +<p>Here's an example that shows how to generate messages in <code>thread</code> output format: </p> + +<pre>adb logcat -v thread</pre> + +<p>Note that you can only specify one output format with the <code>-v</code> option. </p> + +<a name="alternativebuffers"></a> + +<h3>Viewing Alternative Log Buffers </h3> + +<p>The Android logging system keeps multiple circular buffers for log messages, and not all of the log messages are sent to the default circular buffer. To see additional log messages, you can start <code>logcat</code> with the <code>-b</code> option, to request viewing of an alternate circular buffer. You can view any of these alternate buffers: </p> + +<ul> +<li><code>radio</code> — View the buffer that contains radio/telephony related messages.</li> +<li><code>events</code> — View the buffer containing events-related messages.</li> +<li><code>main</code> — View the main log buffer (default)</li> +</ul> + +<p>The usage of the <code>-b</code> option is:</p> + +<pre>[adb] logcat [-b <buffer>]</pre> + +<p>Here's an example of how to view a log buffer containing radio and telephony messages: </p> + +<pre>adb logcat -b radio</b></pre> + +<a name="stdout"></a> + +<h3>Viewing stdout and stderr</h3> + +<p>By default, the Android system sends <code>stdout</code> and <code>stderr</code> (<code>System.out</code> and <code>System.err</code>) output to <code>/dev/null</code>. In +processes that run the Dalvik VM, you can have the system write a copy of the output to the log file. In this case, the system writes the messages to the log using the log tags <code>stdout</code> and <code>stderr</code>, both with priority <code>I</code>. </p> + +<p>To route the output in this way, you stop a running emulator/device instance and then use the shell command <code>setprop</code> to enable the redirection of output. Here's how you do it: </p> + +<pre>$ adb shell stop +$ adb shell setprop log.redirect-stdio true +$ adb shell start</pre> + +<p>The system retains this setting until you terminate the emulator/device instance. To use the setting as a default on the emulator/device instance, you can add an entry to <code>/data/local.prop</code> +on the device.</p> + +<a name="logcatoptions"></a> + +<h3>Listing of logcat Command Options</h3> + +<table> +<tr> + <th>Option</th> + <th>Description</th> +</tr> + +<tr> +<td><code>-b <buffer></code></td> +<td>Loads an alternate log buffer for viewing, such as <code>event</code> or <code>radio</code>. The <code>main</code> buffer is used by default. See <a href="#alternativebuffers">Viewing Alternative Log Buffers</a>.</td> +</tr> + +<tr> +<td><code>-c</code></td> +<td>Clears (flushes) the entire log and exits. </td> +</tr> + +<tr> +<td><code>-d</code></td> +<td>Dumps the log to the screen and exits.</td> +</tr> + +<tr> +<td><code>-f <filename></code></td> +<td>Writes log message output to <code><filename></code>. The default is <code>stdout</code>.</td> +</tr> + +<tr> +<td><code>-g</code></td> +<td>Prints the size of the specified log buffer and exits. </td> +</tr> + +<tr> +<td><code>-n <count></code></td> +<td>Sets the maximum number of rotated logs to <code><count></code>. The default value is 4. Requires the <code>-r</code> option. </td> +</tr> + +<tr> +<td><code>-r <kbytes></code></td> +<td>Rotates the log file every <code><kbytes></code> of output. The default value is 16. Requires the <code>-f</code> option. </td> +</tr> + +<tr> +<td><code>-s</code></td> +<td>Sets the default filter spec to silent. </td> +</tr> + +<tr> +<td><code>-v <format></code></td> +<td>Sets the output format for log messages. The default is <code>brief</code> format. For a list of supported formats, see <a href="#outputformat">Controlling Log Output Format</a>.</td> +</tr> + +</table> + +<a name="stopping"></a> + +<h2>Stopping the adb Server</h2> + +<p>In some cases, you might need to terminate the adb server process and then restart it. For example, if adb does not respond to a command, you can terminate the server and restart it and that may resolve the problem. </p> + +<p>To stop the adb server, use the <code>kill-server</code>. You can then restart the server by issuing any adb command. </p> + + diff --git a/docs/html/guide/developing/aidl.jd b/docs/html/guide/developing/aidl.jd new file mode 100755 index 0000000..145fd93 --- /dev/null +++ b/docs/html/guide/developing/aidl.jd @@ -0,0 +1,301 @@ +page.title=Designing a Remote Interface Using AIDL +@jd:body + +<p>Since each application runs in its own process, and you can write a service that +runs in a different process from your Application's UI, sometimes you need to pass objects +between processes. On the Android platform, one process can not normally access the memory +of another process. So to talk, they need to decompose their objects into primitives that +the operating system can understand, and "marshall" the object across that boundary for you.</p> + +<p>The code to do that marshalling is tedious to write, so we provide the AIDL tool to do it +for you.</p> + +<p> AIDL (Android Interface Definition Language) is an <a +href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</a> +language used to generate code that enables two processes on an Android-powered device +to talk using interprocess communication (IPC). If you have code +in one process (for example, in an Activity) that needs to call methods on an +object in another process (for example, a Service), you would use AIDL to +generate code to marshall the parameters.</p> +<p>The AIDL IPC mechanism + is interface-based, similar to COM or Corba, but lighter weight. It uses a proxy + class to pass values between the client and the implementation. </p> +<p>This page includes the following main topics: </p> +<ul> + <li><a href="#implementing">Implementing IPC Using AIDL</a></li> + <li><a href="#calling">Calling an .aidl (IPC) Class </a></li> +</ul> +<h2>Implementing IPC Using AIDL <a name="implementing"></a></h2> +<p>Follow these steps to implement an IPC service using AIDL.</p> +<ol> + <li><strong><a href="#aidlsyntax">Create your .aidl file</a> </strong>- This + file defines an interface (<em>YourInterface</em>.aidl) that defines the + methods and fields available to a client. </li> + <li><strong>Add the .aidl file to your makefile</strong> - (the <a href="{@docRoot}intro/installing.html#developingwitheclipse">Eclipse + plugin</a> manages this for you). Android includes the compiler, called + AIDL, in the <code>tools/</code> directory. </li> + <li><strong><a href="#implementtheinterface">Implement your interface methods</a></strong> - + The AIDL compiler creates an interface in the Java programming language from your AIDL interface. + This interface has an inner abstract class named Stub that inherits the + interface (and implements a few additional methods necessary for the IPC + call). You must create a class that extends <em>YourInterface</em>.Stub + and implements the methods you declared in your .aidl file. </li> + <li><strong><a href="#exposingtheinterface">Expose your interface to clients</a></strong> - + If you're writing a service, you should extend {@link + android.app.Service Service} and override {@link android.app.Service#onBind + Service.onBind(Intent)} to return an instance of your class that implements your + interface. </li> +</ol> +<h3>Create an .aidl File <a name="aidlsyntax"></a></h3> +<p>AIDL is a simple syntax that lets you declare an interface with one or more + methods, that can take parameters and return values. These parameters and return + values can be of any type, even other AIDL-generated interfaces. <em>However, it + is important to note</em> that you <em>must</em> import all non-built-in types, + <em>even if they are defined in the same package as your interface</em>. + Here are the data types that AIDL can support: </p> +<ul> + <li>Primitive Java programming language types (int, boolean, etc) + — No <code>import</code> statement is needed. </li> + <li>One of the following classes (no <code>import</code> statements needed): + <ul> + <li><strong>String</strong></li> + <li><strong>List</strong> - All elements in the List must be one of the types + in this list, including other AIDL-generated interfaces and + parcelables. List may optionally be used as a "generic" class (e.g. + List<String>). + The actual concrete class that the other side will receive + will always be an ArrayList, although the method will be generated + to use the List interface. </li> + <li><strong>Map</strong> - All elements in the Map must be of one of the + types in this list, including other AIDL-generated interfaces and + parcelables. Generic maps, (e.g. of the form Map<String,Integer> + are not supported. + The actual concrete class that the other side will receive + will always be a HashMap, although the method will be generated + to use the Map interface.</li> + <li><strong>CharSequence</strong> - This is useful for the CharSequence + types used by {@link android.widget.TextView TextView} and other + widget objects. </li> + </ul> + </li> + <li>Other AIDL-generated interfaces, which are always passed by reference. + An <code>import</code> statement is always needed for these.</li> + <li>Custom classes that implement the <a href="#parcelable">Parcelable + protocol</a> and are passed by value. + An <code>import</code> statement is always needed for these.</li> +</ul> +<p>Here is the basic AIDL syntax:</p> +<pre>// My AIDL file, named <em>SomeClass</em>.aidl +// Note that standard comment syntax is respected. +// Comments before the import or package statements are not bubbled up +// to the generated interface, but comments above interface/method/field +// declarations are added to the generated interface. + +// Include your fully-qualified package statement. +package com.android.sample; + +// See the list above for which classes need +// import statements (hint--most of them) +import com.android.sample.IAtmService; + +// Declare the interface. +interface IBankAccountService { + + // Methods can take 0 or more parameters, and + // return a value or void. + int getAccountBalance(); + void setOwnerNames(in List<String> names); + + // Methods can even take other AIDL-defined parameters. + BankAccount createAccount(in String name, int startingDeposit, in IAtmService atmService); + + // All non-Java primitive parameters (e.g., int, bool, etc) require + // a directional tag indicating which way the data will go. Available + // values are in, out, inout. (Primitives are in by default, and cannot be otherwise). + // Limit the direction to what is truly needed, because marshalling parameters + // is expensive. + int getCustomerList(in String branch, out String[] customerList); +}</pre> + +<h3>Implementing the Interface <a name="implementtheinterface"></a></h3> +<p>AIDL generates an interface file for you with the same name as your .aidl + file. If you are using the Eclipse plugin, AIDL will automatically be run as part of + the build process (you don't need to run AIDL first and then build your project). + If you are not using the plugin, you should run AIDL first. </p> +<p>The generated interface + includes an abstract inner class named Stub that declares all the methods + that you declared in your .aidl file. Stub also defines a few helper methods, + most notably asInterface(), which takes an IBinder (passed to a client's onServiceConnected() + implementation when applicationContext.bindService() succeeds), and returns an + instance of the interface used to call the IPC methods. See the section + <a href="#calling">Calling an IPC Method</a> for more details on how to make this cast.</p> +<p>To implement your interface, extend <em>YourInterface</em>.Stub, + and implement the methods. (You can create the .aidl file and implement the stub + methods without building between--the Android build process will process .aidl +files before .java files.) </p> +<p>Here is an example of implementing an interface called IRemoteService, which exposes + a single method, getPid(), using an anonymous instance:</p> +<pre>// No need to import IRemoteService if it's in the same project. +private final IRemoteService.Stub mBinder = new IRemoteService.Stub(){ + public int getPid(){ + return Process.myPid(); + } +}</pre> +<p>A few rules about implementing your interface: </p> +<ul> + <li>No exceptions that you throw will be sent back to the caller.</li> + <li>IPC calls are synchronous. If you know that an IPC service takes more than + a few milliseconds to complete, you should not call it in the Activity/View thread, + because it might hang the application (Android might display an "Application + is Not Responding" dialog). + Try to call them in a separate thread. </li> + <li>Only methods are supported; you cannot declare static fields in an AIDL interface.</li> +</ul> + +<h3>Exposing Your Interface to Clients<a name="exposingtheinterface" id="exposingtheinterface"></a></h3> +<p>Now that you've got your interface implementation, you need to expose it to clients. + This is known as "publishing your service." To publish a service, + inherit {@link android.app.Service Service} and implement {@link android.app.Service#onBind + Service.onBind(Intent)} to return an instance of the class that implements your interface. + Here's a code snippet of a service that exposes the IRemoteService + interface to clients. </p> +<pre>public class RemoteService extends Service { +... +{@include development/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.java exposing_a_service} +}</pre> + +<a name="parcelable"></a> +<h3>Pass by value Parameters using Parcelables</h3> + +<p>If you have a class that you would like to send from one process to another through +an AIDL interface, you can do that. You must ensure that the code for your class is available +to the other side of the IPC. Generally, that means that you're talking to a service that you +started.</p> +<p>There are five parts to making a class support the Parcelable protocol:</b> +<ol> +<li>Make your class implement the {@link android.os.Parcelable} interface.</li> +<li>Implement the method <code>public void writeToParcel(Parcel out)</code> that takes the +current state of the object and writes it to a parcel.</li> +<li>Implement the method <code>public void readFromParcel(Parcel in)</code> that reads the +value in a parcel into your object.</li> +<li>Add a static field called <code>CREATOR</code> to your class which is an object implementing +the {@link android.os.Parcelable.Creator Parcelable.Creator} interface.</li> +<li>Last but not least: +<ul> +<li>If you are developing with Eclipse/ADT, follow these steps: +<ol type="a"> +<li>In the Package Explorer view, right-click on the project.</li> +<li>Choose <strong>Android Tools</strong> > <strong>Create Aidl preprocess file +for Parcelable classes</strong>.</li> +<li>This will create a file called "project.aidl" in the root of the project. +The file will be automatically used when compiling an aidl file that uses the +parcelable classes.</li> +</ol> +</li> +<li>If you are developing with Ant or are using a custom build process, create an aidl file +that declares your parcelable class (as shown below). If you are using a custom build process, +do not add the aidl file to your build. Similar to a header file in C, the aidl file isn't +compiled.</li> +</ul> +</li> +</ul> +<p>AIDL will use these methods and fields in the code it generates to marshall and unmarshall +your objects.</p> +<p>Here is an example of how the {@link android.graphics.Rect} class implements the +Parcelable protocol.</p> + +<pre class="prettyprint"> +import android.os.Parcel; +import android.os.Parcelable; + +public final class Rect implements Parcelable { + public int left; + public int top; + public int right; + public int bottom; + + public static final Parcelable.Creator<Rect> CREATOR = new Parcelable.Creator<Rect>() { + public Rect createFromParcel(Parcel in) { + return new Rect(in); + } + + public Rect[] newArray(int size) { + return new Rect[size]; + } + }; + + public Rect() { + } + + private Rect(Parcel in) { + readFromParcel(in); + } + + public void writeToParcel(Parcel out) { + out.writeInt(left); + out.writeInt(top); + out.writeInt(right); + out.writeInt(bottom); + } + + public void readFromParcel(Parcel in) { + left = in.readInt(); + top = in.readInt(); + right = in.readInt(); + bottom = in.readInt(); + } +} +</pre> + +<p>Here is Rect.aidl for this example</p> + +<pre class="prettyprint"> +package android.graphics; + +// Declare Rect so AIDL can find it and knows that it implements +// the parcelable protocol. +parcelable Rect; +</pre> + +<p>The marshalling in the Rect class is pretty simple. Take a look at the other +methods on {@link android.os.Parcel} to see the other kinds of values you can write +to a Parcel.</p> + +<p class="warning"><b>Warning:</b> Don't forget the security implications of receiving data from +other processes. In this case, the rect will read four numbers from the parcel, +but it is up to you to ensure that these are within the acceptable range of +values for whatever the caller is trying to do. See +<a href="{@docRoot}devel/security.html">Security and Permissions in Android</a> for more +on how to keep your application secure from malware.</p> + +<h2>Calling an IPC Method <a name="calling"></a></h2> +<p>Here are the steps a calling class should make to call your remote interface: </p> +<ol> + <li>Declare a variable of the interface type that your .aidl file defined. </li> + <li>Implement {@link android.content.ServiceConnection ServiceConnection}. </li> + <li>Call {@link android.content.Context#bindService(android.content.Intent,android.content.ServiceConnection,int) + Context.bindService()}, passing in your ServiceConnection implementation. </li> + <li>In your implementation of {@link android.content.ServiceConnection#onServiceConnected(android.content.ComponentName,android.os.IBinder) + ServiceConnection.onServiceConnected()}, you will receive an {@link android.os.IBinder + IBinder} instance (called <em>service</em>). Call <code><em>YourInterfaceName</em>.Stub.asInterface((IBinder)<em>service</em>)</code> to + cast the returned parameter to <em>YourInterface</em> type.</li> + <li>Call the methods that you defined on your interface. You should always trap + {@link android.os.DeadObjectException} exceptions, which are thrown when + the connection has broken; this will be the only exception thrown by remote + methods.</li> + <li>To disconnect, call {@link android.content.Context#unbindService(android.content.ServiceConnection) + Context.unbindService()} with the instance of your interface. </li> +</ol> +<p>A few comments on calling an IPC service:</p> +<ul> + <li>Objects are reference counted across processes. </li> + <li>You can send anonymous objects + as method arguments. </li> +</ul> +<p>Here is some sample code demonstrating calling an AIDL-created service, taken + from the Remote Activity sample in the ApiDemos project.</p> +<p>{@sample development/samples/ApiDemos/src/com/example/android/apis/app/RemoteServiceBinding.java + exposing_a_service}</p> + + + diff --git a/docs/html/guide/developing/app-signing.jd b/docs/html/guide/developing/app-signing.jd new file mode 100644 index 0000000..582dfb2 --- /dev/null +++ b/docs/html/guide/developing/app-signing.jd @@ -0,0 +1,428 @@ +page.title=Signing Your Applications +@jd:body + +<p>The Android system requires that all installed applications be digitally +signed with a certificate whose private key is held by the application's +developer. The system uses the certificate as a means of identifying the author of +an application and establishing trust relationships between applications, rather +than for controlling which applications the user can install. The certificate +does not need to be signed by a certificate authority: it is perfectly +allowable, and typical, for Android applications to use self-signed +certificates.</p> + +<p>The important points to understand about signing Android applications are:</p> + +<ul> + <li>All applications <em>must</em> be signed. The system will not install an application +that is not signed.</li> + <li>You can use self-signed certificates to sign your applications. No certificate authority +is needed.</li> + <li>When you are ready to publish your application, you must sign it with a suitable private +key. You can not publish an application that is signed with the default key generated +by the SDK tools. + </li> + <li>The system tests a signer certificate's expiration date only at install time. If an +application's signer certificate expires after the application is installed, the application +will continue to function normally.</li> + <li>You can use standard tools — Keytool and Jarsigner — to generate keys and +sign your application .apk files.</li> +</ul> + +<p>The Android system will not install or run an application that is not signed appropriately. This +applies wherever the Android system is run, whether on an actual device or on the emulator. +For this reason, you must set up signing for your application before you will be able to +run or debug it on an emulator or device.</p> + +<p>The Android SDK tools assist you in signing your applications when debugging. Both the ADT Plugin +for Eclipse and the Ant build tool offer two signing modes — debug mode and release mode. + +<ul> +<li>In debug mode, the build tools use the Keytool utility, included in the JDK, to create +a keystore and key with a known alias and password. At each compilation, the tools then use +the debug key to sign the application .apk file. Because the password is known, the tools +don't need to prompt you for the keystore/key password each time you compile.</li> + +<li>When your application is ready for release, you compile it in release signing mode. +In this mode, the tools compile your .apk <em>without</em> signing it. You must then sign +the .apk manually — <span style="color:red">with your private key</span> — +using Jarsigner (or similar tool). If you do not have a suitable private key already, +you can run Keytool manually to generate your own keystore/key and then sign your +application with Jarsigner.</li> +</ul> + +<h2>Signing Strategies</h2> + +<p>Some aspects of application signing may affect how you approach the development +of your application, especially if you are planning to release multiple +applications. </p> + +<p>In general, the recommended strategy for all developers is to sign +all of your applications with the same certificate, throughout the expected +lifespan of your applications. There are several reasons why you should do so: </p> + +<ul> +<li>Application upgrade — As you release upgrades to your +application, you will want to sign the upgrades with the same certificate, if you +want users to upgrade seamlessly to the new version. When the system is +installing an update to an application, if any of the certificates in the +new version match any of the certificates in the old version, then the +system allows the update. If you sign the version without using a matching +certificate, you will also need to assign a different package name to the +application — in this case, the user installs the new version as a +completely new application. + +<li>Application modularity — The Android system allows applications that +are signed by the same certificate to run in the same process, if the +applications so request, so that the system treats them as a single application. +In this way you can deploy your application in modules, and users can update +each of the modules independently if needed.</li> + +<li>Code/data sharing through permissions — The Android system provides +signature-based permissions enforcement, so that an application can expose +functionality to another application that is signed with a specified +certificate. By signing multiple applications with the same certificate and +using signature-based permissions checks, your applications can share code and +data in a secure manner. </li> + +</li> + +</ul> + +<p>Another important consideration in determining your signing strategy is +how to set the validity period of the key that you will use to sign your +applications.</p> + +<ul> +<li>If you plan to support upgrades for a single application, you should ensure +that your key has a validity period that exceeds the expected lifespan of +that application. A validity period of 25 years or more is recommended. +When your key's validity period expires, users will no longer be +able to seamlessly upgrade to new versions of your application.</li> + +<li>If you will sign multiple distinct applications with the same key, +you should ensure that your key's validity period exceeds the expected +lifespan of <em>all versions of all of the applications</em>, including +dependent applications that may be added to the suite in the future. </li> + +<li>If you plan to publish your application(s) on Android Market, the +key you use to sign the application(s) must have a validity period +ending after 22 October 2033. The Market server enforces this requirement +to ensure that users can seamlessly upgrade Market applications when +new versions are available. </li> +</ul> + +<p>As you design your application, keep these points in mind and make sure to +use a <a href="#cert">suitable certificate</a> to sign your applications. </p> + +<h2 id="setup">Basic Setup for Signing</h2> + +<p>To support the generation of a keystore and debug key, you should first make sure that +Keytool is available to the SDK build +tools. In most cases, you can tell the SDK build tools how to find Keytool by making sure +that your JAVA_HOME environment variable is set and that it references a suitable JDK. +Alternatively, you can add the JDK version of Keytool to your PATH variable.</p> + +<p>If you are developing on a version of Linux that originally came with GNU Compiler for +Java, make sure that the system is using the JDK version of Keytool, rather than the gcj +version. If Keytool is already in your PATH, it might be pointing to a symlink at +/usr/bin/keytool. In this case, check the symlink target to make sure that it points +to the Keytool in the JDK.</p> + +<p>If you will release your application to the public, you will also need to have +the Jarsigner tool available on your machine. Both Jarsigner and Keytool are included +in the JDK. </p> + +<h2>Signing in Debug Mode</h2> + +<p>The Android build tools provide a debug signing mode that makes it easier for you +to develop and debug your application, while still meeting the Android system +requirement for signing your .apk when it is installed in the emulator or a device. </p> + +<p>If you are developing in Eclipse/ADT and have set up Keytool as described +above, signing in debug mode is enabled by default. When you run or debug your +application, ADT signs the .apk for you and installs it on the emulator. No +specific action on your part is needed, provided ADT has access to Keytool.</p> + +<p>If you use Ant to build your .apk files, debug signing mode +is enabled by default, assuming that you are using a build.xml file generated by the +activitycreator tool included in the latest SDK. When you run Ant against build.xml to +compile your app, the build script generates a keystore/key and signs the .apk for you. +No specific action on your part is needed.</p> + +<p>Note that you can not release your application to the public if it is signed only with +the debug key. </p> + +<h2>Signing for Public Release</h2> + +<p>When your application is ready for release to other users, you must:</p> +<ol> +<li>Compile the application in release mode</li> +<li>Obtain a suitable private key, and then</li> +<li>Sign the application with your private key</li> +<li>Secure your private key</li> +</ol> + +<p>The sections below provide information about these steps. </p> + +<h3>Compiling for Release</h3> + +<p>To prepare your application for release, you must first compile it in release mode. +In release mode, the Android build tools compile your application as usual, +but without signing it with the debug key. </p> + +<p>If you are developing in Eclipse/ADT, right-click the project in the Package +pane and select <strong>Android Tools</strong> > <strong>Export Application +Package</strong>. You can then specify the file location for the unsigned .apk. +Alternatively, you can follow the "Exporting the unsigned .apk" +link in the Manifest Editor overview page. </p> + +<p>If you are using Ant, all you need to do is specify the build target +"release" in the Ant command. For example, if you are running Ant from the +directory containing your build.xml file, the command would look like this:</p> + +<pre>$ ant release</pre> + +<p>The build script compiles the application .apk without signing it. + +<p>Note that you can not release your application unsigned, or signed with the debug key.</p> + +<h3 id="cert">Obtaining a Suitable Private Key</h3> + +<p>In preparation for signing your application, you must first ensure that +you have a suitable private key with which to sign. A suitable private +key is one that:</p> + +<ul> +<li>Is in your possession</li> +<li>Represents the personal, corporate, or organizational entity to be identified +with the application</li> +<li>Has a validity period that exceeds the expected lifespan of the application +or application suite. A validity period of more than 25 years is recommended. +<p>If you plan to publish your application(s) on Android Market, note that a +validity period ending after 22 October 2033 is a requirement. You can not upload an +application if it is signed with a key whose validity expires before that date. +</p></li> +<li>Is not the debug key generated by the Android SDK tools. </li> +</ul> + +<p>The key may be self-signed. If you do not have a suitable key, you must +generate one using Keytool. Make sure that you have Keytool available, as described +in <a href="#setup">Basic Setup</a>.</p> + +<p>To generate a self-signed key with Keytool, use the <code>keytool</code> +command and pass any of the options listed below (and any others, as +needed). </p> + +<p class="warning">Before you run Keytool, make sure to read <a +href="#secure-key">Securing Your Key</a> for a discussion of how to keep your +key secure and why doing so is critically important to you and to users. In +particular, when you are generating your key, you should select strong +passwords for both the keystore and key.</p> + +<table> +<tr> +<th>Keytool Option</th> +<th>Description</th> +</tr> +<tr> +<td><code>-genkey</code></td><td>Generate a key pair (public and private +keys)</td> +</tr> +<tr> +<td><code>-v</code></td><td>Enable verbose output.</td> +</tr> +<tr> +<td><code>-keystore <keystore-name>.keystore</code></td><td>A name +for the keystore containing the private key.</td> +</tr> +<tr> +<td><code>-storepass <password></code></td><td><p>A password for the +keystore.</p><p>As a security precaution, do not include this option +in your command line unless you are working at a secure computer. +If not supplied, Keytool prompts you to enter the password. In this +way, your password is not stored in your shell history.</p></td> +</tr> +<tr> +<td><code>-alias <alias_name></code></td><td>An alias for the key.</td> +</tr> +<tr> +<td><code>-keyalg <alg></code></td><td>The encryption algorithm to use +when generating the key.</td> +</tr> +<tr> +<td><code>-dname <name></code></td><td><p>A Distinguished Name that describes +who created the key. The value is used as the issuer and subject fields in the +self-signed certificate. </p><p>Note that you do not need to specify this option +in the command line. If not supplied, Jarsigner prompts you to enter each +of the Distinguished Name fields (CN, OU, and so on).</p></td> +</tr> +<tr> +<td><code>-validity <valdays></code></td><td><p>The validity period for the +key, in days. </p><p><strong>Note:</strong> A value of 9500 or greater is recommended.</p></td> +</tr> +<tr> +<td><code>-keypass <password></code></td><td><p>The password for the key.</p> +<p>As a security precaution, do not include this option +in your command line unless you are working at a secure computer. +If not supplied, Keytool prompts you to enter the password. In this +way, your password is not stored in your shell history.</p></td> +</tr> +</table> + + +<p>Here's an example of a Keytool command that generates a private key:</p> + +<pre>$ keytool -genkey -v -keystore my-release-key.keystore +-alias alias_name -keyalg RSA -validity 9500</pre> + +<p>Running the example command above, Keytool prompts you to provide +passwords for the keystore and key, and to provide the Distinguished +Name fields for your key. It then generates the keystore as a file called +<code>my-release-key.keystore</code>. The keystore and key are +protected by the passwords you entered. The keystore contains +a single key, valid for 9500 days. The alias is a name that you — +will use later, to refer to this keystore when signing your application. </p> + +<p>For more information about Keytool, see the documentation at +<a +href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> +http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> + +<h3>Signing Your Application</h3> + +<p>When you are ready to actually sign your .apk for release, you can do so +using the Jarsigner tool. Make sure that you have Jarsigner available on your +machine, as described in <a href="#setup">Basic Setup</a>. Also, make sure that +the keystore containing your private key is available.</p> + +<p>To sign your application, you run Jarsigner, referencing both the +application's .apk and the keystore containing the private key with which to +sign the .apk. The table below shows the options you could use. <p> + +<table> +<tr> +<th>Jarsigner Option</th> +<th>Description</th> +</tr> +<tr> +<td><code>-keystore <keystore-name>.keystore</code></td><td>The name of +the keystore containing your private key.</td> +</tr> +<tr> +<td><code>-verbose</code></td><td>Enable verbose output.</td> +</tr> +<tr> +<td><code>-storepass <password></code></td><td><p>The password for the +keystore. </p><p>As a security precaution, do not include this option +in your command line unless you are working at a secure computer. +If not supplied, Jarsigner prompts you to enter the password. In this +way, your password is not stored in your shell history.</p></td> +</tr> +<tr> +<td><code>-keypass <password></code></td><td><p>The password for the private +key. </p><p>As a security precaution, do not include this option +in your command line unless you are working at a secure computer. +If not supplied, Jarsigner prompts you to enter the password. In this +way, your password is not stored in your shell history.</p></td> +</tr> +</table> + +<p>Here's how you would use Jarsigner to sign an application package called +<code>my_application.apk</code>, using the example keystore created above. +</p> + +<pre>$ jarsigner -verbose -keystore my-release-key.keystore +my_application.apk alias_name</pre> + +<p>Running the example command above, Jarsigner prompts you to provide +passwords for the keystore and key. It then modifies the APK +in-place, meaning the .apk is now signed. Note that you can sign an +APK multiple times with different keys.</p> + +<p>To verify that your .apk is signed, you can use a command like this:</p> + +<pre>$ jarsigner -verify my_signed.apk</pre> + +<p>If the .apk is signed properly, Jarsigner prints "jar verified". +If you want more details, you can try one of these commands:</p> + +<pre>$ jarsigner -verify -verbose my_application.apk</pre> + +<p>or</p> + +<pre>$ jarsigner -verify -verbose -certs my_application.apk</pre> + +<p>The command above, with the <code>-certs</code> option added, will show you the +"CN=" line that describes who created the key.</p> + +<p class="note">Note: if you see "CN=Android Debug", this means the .apk was +signed with the debug key generated by the Android SDK. If you intend to release +your application, you must sign it with your private key instead of the debug +key.</p> + +<p>For more information about Jarsigner, see the documentation at +<a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> +http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> + +<h3 id="secure-key">Securing Your Private Key</h3> + +<p>Maintaining the security of your private key is of critical importance, both +to you and to the user. If you allow someone to use your key, or if you leave +your keystore and passwords in an unsecured location such that a third-party +could find and use them, your authoring identity and the trust of the user +are compromised. </p> + +<p>If a third party should manage to take your key without your knowledge or +permission, that person could sign and distribute applications that maliciously +replace your authentic applications or corrupt them. Such a person could also +sign and distribute applications under your identity that attack other +applications or the system itself, or corrupt or steal user data. </p> + +<p>Your reputation as a developer entity depends on your securing your private +key properly, at all times, until the key is expired. Here are some tips for +keeping your key secure: </p> + +<ul> +<li>Select strong passwords for the keystore and key.</li> +<li>When you generate your key with Keytool, <em>do not</em> supply the +<code>-storepass</code> and <code>-keypass</code> options at the command line. +If you do so, your passwords will be available in your shell history, +which any user on your computer could access.</li> +<li>Similarly, when signing your applications with Jarsigner, +<em>do not</em> supply the <code>-storepass</code> and <code>-keypass</code> +options at the command line. </li> +<li>Do not give or lend anyone your private key, and do not let unauthorized +persons know your keystore and key passwords.</li> +</ul> + +<p>In general, if you follow common-sense precautions when generating, using, +and storing your key, it will remain secure. </p> + +<h2>Expiry of the Debug Certificate</h2> + +<p>The self-signed certificate used to sign your application in debug mode (the default on +Eclipse/ADT and Ant builds) will have an expiration date of 365 days from its creation date.</p> + +<p>When the certificate expires, you will get a build error. On Ant builds, the error +looks like this:</p> + +<pre>debug: +[echo] Packaging bin/samples-debug.apk, and signing it with a debug key... +[exec] Debug Certificate expired on 8/4/08 3:43 PM</pre> + +<p>In Eclipse/ADT, you will see a similar error in the Android console.</p> + +<p>To fix this problem, simply delete the <code>debug.keystore</code> file. On Linux/Mac OSX, +the file is stored in <code>~/.android</code>. OOn Windows XP, the file is stored in <code> +C:\Documents and Settings\<user>\Local Settings\Application Data\Android</code>. +On Windows Vista, the file is stored in <code> +C:\Users\<user>\AppData\Local\Android</code>.</p> + +<p>The next time you build, the build tools will regenerate a new keystore and debug key.</p> + +<p>Note that, if your development machine is using a non-Gregorian locale, the build +tools may erroneously generate an already-expired debug certificate, so that you get an +error when trying to compile your application. For workaround information, see the +troubleshooting topic <a href="{@docRoot}kb/troubleshooting.html#signingcalendar"> +I can't compile my app because the build tools generated an expired debug +certificate</a>. </p>
\ No newline at end of file diff --git a/docs/html/guide/developing/ddms.jd b/docs/html/guide/developing/ddms.jd new file mode 100644 index 0000000..79ae66a --- /dev/null +++ b/docs/html/guide/developing/ddms.jd @@ -0,0 +1,250 @@ +page.title=Using Dalvik Debug Monitor Service (DDMS) +@jd:body + +<p>Android ships with a debugging tool called the Dalvik Debug Monitor Service (DDMS), + which provides port-forwarding services, screen capture on the device, thread + and heap information on the device, logcat, process, and radio state information, + incoming call and SMS spoofing, location data spoofing, and more. This page + provides a modest discussion of DDMS features; it is not an exhaustive exploration of + all the features and capabilities.</p> + +<p>DDMS ships in the <code>tools/</code> directory of the SDK. + Enter this directory from a terminal/console and type <code>ddms</code> (or <code>./ddms</code> + on Mac/Linux) to run it. DDMS will work with both the emulator and a connected device. If both are + connected and running simultaneously, DDMS defaults to the emulator.</p> + +<h2 id="how-ddms-works">How DDMS works</h2> +<p>DDMS acts as a middleman to connect the IDE to the applications running on +the device. On Android, every application runs in its own process, +each of which hosts its own virtual machine (VM). And each process +listens for a debugger on a different port.</p> + +<p>When it starts, DDMS connects to <a href="{@docRoot}reference/adb.html">adb</a> and +starts a device monitoring service between the two, which will notify DDMS when a device is +connected or disconnected. When a device is connected, a VM monitoring service is created +between adb and DDMS, which will notify DDMS when a VM on the device is started +or terminated. Once a VM is running, DDMS retrieves the the VM's process ID (pid), via adb, +and opens a connection to the VM's debugger, through the adb daemon (adbd) on the device. +DDMS can now talk to the VM using a custom wire protocol.</p> + +<p>For each VM on the device, DDMS opens a port upon which it will listen for a debugger. For the first VM, DDMS listens for a debugger on port 8600, the next on 8601, and so on. When a debugger connects to one of these ports, all traffic is forwarded between the debugger and the associated VM. Debugging can then process like any remote debugging session.</p> + +<p>DDMS also opens another local port, the DDMS "base port" (8700, by default), upon which it also listens for a debugger. When a debugger connects to this base port, all traffic is forwarded to the VM currently selected in DDMS, so this is typically where you debugger should connect.</p> + +<p>For more information on port-forwarding with DDMS, +read <a href="{@docRoot}intro/installing.html#eclipse">Configuring your IDE to attach +to port 8700 for debugging</a>.</p> + +<p class="note"><strong>Tip:</strong> +You can set a number of DDMS preferences in <strong>File</strong> > <strong>Preferences</strong>. +Preferences are saved to "$HOME/.ddmsrc". </p> + +<p class="warning"><strong>Known debugging issues with Dalvik</strong><br/> +Debugging an application in the Dalvik VM should work the same as it does +in other VMs. However, when single-stepping out of synchronized code, the "current line" +cursor may jump to the last line in the method for one step.</p> + + +<h2 id="left-pane">Left Pane</h2> +<p>The left side of the Debug Monitor shows each emulator/device currently found, with a list of + all the VMs currently running within each. + VMs are identified by the package name of the application it hosts.</p> +<p>Use this list to find and attach to the VM + running the activity(ies) that you want to debug. Next to each VM in the + list is a "debugger pass-through" port (in the right-most column). + If you connect your debugger to one of the the ports listed, you + will be connected to the corresponding VM on the device. However, when using + DDMS, you need only connect to port 8700, as DDMS forwards all traffic here to the + currently selected VM. (Notice, as you select a VM in the list, the listed port includes 8700.) + This way, there's no need to reconfigure the debugger's port each time you switch between VMs.</p> +<p>When an application running on the device calls {@link android.os.Debug#waitForDebugger()} + (or you select this option in the <a href="{@docRoot}intro/installing.html#additionaldebugging">developer + options</a>), a red icon will be shown next to the client name, while it waits for the + debugger to attach to the VM. When a debugger is connected, the icon will turn green. </p> +<p>If you see a crossed-out bug icon, this means that the DDMS was unable to complete a +connection between the debugger and the VM because it was unable to open the VM's local port. +If you see this for all VMs on the device, it is likely because you have another instance of +DDMS running (this includes the Eclipse plugin).</p> +<p>If you see a question mark in place of an application package, this means that, +once DDMS received the application pid from adb, it +somehow failed to make a successful handshake with the VM process. Try restarting DDMS.</p> + + +<h2 id="right-pane">Right pane</h2> +<p>On the right side, the Debug Monitor provides tabs that display useful information +and some pretty cool tools.</p> + +<h3 id="info">Info</h3> +<p>This view shows some general information about the selected VM, including the process + ID, package name, and VM version.</p> + +<h3 id="threads">Threads</h3> +<p> The threads view has a list of threads running in the process of the target VM. + To reduce the amount + of data sent over the wire, the thread updates are only sent when explicitly + enabled by toggling the "threads" button + in the toolbar. This toggle is maintained per VM. This tab includes the following + information: </p> +<ul> + <li> <strong>ID</strong> - a VM-assigned unique thread ID. In Dalvik, these are + odd numbers starting from 3. </li> + <li> <strong>Tid</strong> - the Linux thread ID. For the main thread in a process, + this will match the process ID. </li> + <li> <strong>Status</strong> - the VM thread status. Daemon threads are + shown with an asterisk (*). This will be one of the following: + <ul> + <li> <em>running</em> - executing application code </li> + <li> <em>sleeping</em> - called Thread.sleep() </li> + <li> <em>monitor</em> - waiting to acquire a monitor lock </li> + <li> <em>wait</em> - in Object.wait() </li> + <li> <em>native</em> - executing native code </li> + <li> <em>vmwait</em> - waiting on a VM resource </li> + <li> <em>zombie</em> - thread is in the process of dying </li> + <li> <em>init</em> - thread is initializing (you shouldn't see this) </li> + <li> <em>starting</em> - thread is about to start (you shouldn't see + this either) </li> + </ul> + </li> + <li> <strong>utime</strong> - cumulative time spent executing user code, in "jiffies" (usually + 10ms). Only available under Linux. </li> + <li> <strong>stime</strong> - cumulative time spent executing system code, in "jiffies" (usually + 10ms). </li> + <li> <strong>Name</strong> - the name of the thread</li> +</ul> +<p> "ID" and "Name" are set when the thread is started. The remaining + fields are updated periodically (default is every 4 seconds). </p> + +<h3 id="vm-heap">VM Heap</h3> +<p> Displays some heap stats, updated during garbage collection. If, when a VM is selected, +the VM Heap view says that heap updates are not enabled, click the "Show heap updates" button, +located in the top-left toolbar. Back in the VM Heap view, click <strong>Cause GC</strong> +to perform garbage collection and update the heap stats.</p> + + +<h3 id="allocation-tracker">Allocation Tracker</h3> +<p>In this view, you can track the memory allocation of each virtual machine. +With a VM selected in the left pane, click <strong>Start Tracking</strong>, then +<strong>Get Allocations</strong> to view all allocations since tracking started. +The table below will be filled with all the relevant +data. Click it again to refresh the list.</p> + + +<h3 id="emulator-control">Emulator Control</h3> +<p>With these controls, you can simulate special device states and activities. +Features include:</p> +<ul> +<li><strong>Telephony Status</strong> - change the state of the phone's Voice and Data plans + (home, roaming, searching, etc.), and simulate different kinds of network Speed and Latency + (GPRS, EDGE, UTMS, etc.).</li> +<li><strong>Telephony Actions</strong> - perform simulated phone calls and SMS messages to the emulator.</li> +<li><strong>Location Controls</strong> - send mock location data to the emulator so that you can perform + location-aware operations like GPS mapping. + +<p>To use the Location Controls, launch your application in the Android emulator and open DDMS. +Click the Emulator Controls tab and scroll down to Location Controls. +From here, you can:</p> +<ul class="listhead"> + <li>Manually send individual longitude/latitude coordinates to the device. + <p>Click <strong>Manual</strong>, + select the coordinate format, fill in the fields and click <strong>Send</strong>. + </p> + </li> + <li>Use a GPX file describing a route for playback to the device. + <p>Click <strong>GPX</strong> and load the file. Once loaded, + click the play button to playback the route for your location-aware application.</p> + <p>When performing playback from GPX, you can adjust the speed of + playback from the DDMS panel and control playback with the pause and skip buttons. + DDMS will parse both the waypoints (<code><wpt></code>, in the first table), + and the tracks (<code><trk></code>, + in the second table, with support for multiple segments, <code><trkseg></code>, + although they are simply + concatenated). Only the tracks can be played. Clicking a waypoint in the first list simply + sends its coordinate to the device, while selecting a track lets you play it.</p> + </li> + <li>Use a KML file describing individual placemarks for sequenced playback to the device. + <p>Click <strong>KML</strong> and load the file. Once loaded, + click the play button to send the coordinates to your location-aware application.</p> + <p>When using a KML file, it is parsed for a <code><coordinates></code> + element. The value of which should be a single + set of longitude, latitude and altitude figures. For example:</p> + <pre><coordinates>-122.084143,37.421972,4</coordinates></pre> + <p>In your file, you may include multiple <code><Placemark></code> elements, each containing + a <code><coordinates></code> element. When you do so, the collection of placemarks will + be added as tracks. DDMS will send one placemark per second to the device.</p> + <p>One way to generate a suitable KML file is to find a location in Google Earth. + Right-click the location entry that appears on the left and select "Save place as..." + with the save format set to Kml.</p> +<p class="note"><strong>Note:</strong> DDMS does not support routes created with the +<code><MultiGeometry><LineString>lat1, long1, lat2, long2, ....</LineString></MultiGeometry></code> methods. + There is also currently no support for the <code><TimeStamp></code> node inside + the <code><Placemark></code>. + Future releases may support timed placement and routes within a single coordinate element.</p> + </li> + </ul> + <p>For <em>additional</em> methods of spoofing location-based data, see the + <a href="{@docRoot}toolbox/apis/lbs.html">Location-based Service APIs</a> document.</p> + </li> +</ul> + + +<!-- <h4>Event Log</h4> --> + + +<h2 id="file-explorer">File Explorer</h2> +<p>With the File Explorer, you can view the device file system and perform basic management, +like pushing and pulling files. This circumvents using the <a href="{@docRoot}reference/adb.html">adb</a> +<code>push</code> and <code>pull</code> commands, with a GUI experience.</p> +<p>With DDMS open, select <strong>Device</strong> > <strong>File Explorer...</strong> to open the +File Explorer window. You can drag-and-drop into the device directories, but cannot drag <em>out</em> of them. +To copy files from the device, select the file and click the <strong>Pull File from Device</strong> +button in the toolbar. To delete files, use the <strong>Delete</strong> button in the toolbar.</p> +<p>If you're interested in using an SD card image on the emulator, you're still required to use +the <code>mksdcard</code> command to create an image, and then mount it during emulator bootup. +For example, from the <code>/tools</code> directory, execute:</p> +<pre> +<b>$</b> mksdcard 1024M ./img +<b>$</b> emulator -sdcard ./img +</pre> +<p>Now, when the emulator is running, the DDMS File Explorer will be able to read and write to the +sdcard directory. However, your files may not appear automatically. For example, if you add an +MP3 file to the sdcard, the media player won't see them until you restart the emulator. (When restarting +the emulator from command line, be sure to mount the sdcard again.)</p> +<p>For more information on creating an SD card image, see the +<a href="{@docRoot}/reference/othertools.html#mksdcard">Other Tools</a> document.</p> + +<h2 id="screen-capture">Screen Capture</h2> +<p>You can capture screen images on the device or emulator by selecting <strong>Device</strong> + > <strong>Screen capture...</strong> in the menu bar, or press CTRL-S.</p> + +<h2 id="exploring-processes">Exploring Processes</h2> +<p>You can see the output of <code>ps -x</code> for a specific VM by selecting <strong>Device</strong> + > <strong>Show process status</strong>... in the menu bar.</p> + +<h2 id="cause-a-gc-to-occur">Cause a GC to Occur</h2> +<p>Cause garbage collection to occury by pressing the trash can button on the toolbar. </p> + +<h2 id="running-dumpsys-and-dumpstate">Running Dumpsys and Dumpstate on the Device (logcat)<a name="logcat" id="logcat"></a> </h2> +<ul> + <li>To run <strong>dumpsys</strong> (logcat) from Dalvik, select <strong>Device</strong> > + <strong>Run logcat...</strong> in the menu bar.</li> + <li>To run <strong>dumpstate</strong> from Dalvik, select <strong>Device</strong> > <strong>Dump device + state...</strong> in the menu bar. </li> +</ul> + +<h2 id="examine-radio-state">Examine Radio State</h2> +<p>By default, radio state is not output during a standard logcat (it is a lot of + information). To see radio information, either click <strong>Device</strong> > <strong>Dump radio + state...</strong> or run logcat as described in <a href="{@docRoot}intro/installing.html#logradio">Logging + Radio Information</a>. </p> + +<h2 id="stop-a-vitrual-machine">Stop a Virtual Machine </h2> +<p>You can stop a virtual machine by selecting <strong>Actions</strong> > <strong>Halt +VM</strong>. Pressing this button causes the VM to call <code>System.exit(1)</code>.</p> + +<h2 id="known-issues" style="color:#FF0000">Known issues with DDMS </h2> +<p>DDMS has the following known limitations:</p> +<ul> + <li>If you connect and disconnect a debugger, ddms drops and reconnects the + client so the VM realizes that the debugger has gone away. This will be fixed + eventually. </li> +</ul> diff --git a/docs/html/guide/developing/debug-tasks.jd b/docs/html/guide/developing/debug-tasks.jd new file mode 100644 index 0000000..bd63dcf --- /dev/null +++ b/docs/html/guide/developing/debug-tasks.jd @@ -0,0 +1,180 @@ +page.title=Debugging +@jd:body + +<p>Android has a fairly extensive set of tools to help you debug your programs: </p> +<ul> + <li><a href="{@docRoot}reference/ddms.html"><strong>DDMS</strong></a> - A graphical program that + supports port forwarding (so you can set up breakpoints in your code in your + IDE), screen captures on the emulator, thread and stack information, + and many other features. You can also run logcat to retrieve your Log messages. + See the linked topic for more information. </li> + <li><strong><a href="{@docRoot}reference/ddms.html#logcat">logcat</a></strong> - Dumps a log of system + messages. The messages include a stack trace when the emulator throws an error, + as well as Log messages. To run logcat, see the linked topic. + + <pre>... +I/MemoryDealer( 763): MemoryDealer (this=0x54bda0): Creating 2621440 bytes heap at 0x438db000 +<span style="background-color:#CCCCCC; border-bottom:medium">I/Logger( 1858): getView() requesting item number 0 +I/Logger( 1858): getView() requesting item number 1 +I/Logger( 1858): getView() requesting item number 2</span> +D/ActivityManager( 763): Stopping: HistoryRecord{409dbb20 com.android.home.AllApps} +...</pre> + + </li> + <li><p><strong>{@link android.util.Log Android Log}</strong>- A logging + class to print out messages to a log file on the emulator. You can read messages + in real time if you run logcat on DDMS (covered next). Add a few logging + method calls to your code.</p> + <p>To use the <code>Log</code> class, you just call <code>Log.v()</code> + (verbose), <code>Log.d()</code> (debug), <code>Log.i()</code> (information), + <code>Log.w()</code> (warning) or <code>Log.e</code> (error) depending + on the importance you wish to assign the log message.</p> + <code>Log.i("MyActivity", "MyClass.getView() + — Requesting item number " + position)</code> + <p>You can use logcat to read these messages</p></li> + <li><strong><a href="{@docRoot}reference/traceview.html">Traceview</a> </strong>- Android can save + a log of method calls and times to a logging file that you can view in a + graphical reader called Traceview. See the linked topic for more information. </li> +</ul> +<ul> + <li><a href="#developingwitheclipse"><strong>Eclipse plugin</strong></a> - The Eclipse + Android plugin incorporates a number of these tools (ADB, DDMS, logcat output, + and other functionality). See the linked topic for more information. </li> + <li><strong>Debug and Test Device Settings</strong> - Android exposes several settings + that expose useful information such as CPU usage and frame rate. See <a href="#additionaldebugging">Debug + and Test Settings on the Emulator</a> below. </li> +</ul> +<p>Also, see the <a href="{@docRoot}kb/troubleshooting.html">Troubleshooting</a> section + of the doc to figure out why your application isn't appearing on the emulator, + or why it's not starting. </p> + +<a name="additionaldebugging" id="additionaldebugging"></a> + +<h2>Debug and Test Settings on the Device</h2> + +<p>Android lets you set a number of settings that will make it easier to test + and debug your applications. To get to the development settings page on the emulator, + go to <strong>Dev Tools </strong>> <strong>Development Settings</strong>. + This will open the development settings page with the following options (among + others):</p> +<ul> + <li><strong>Debug app</strong> Selects the application that + will be debugged. You do not need to set this to attach a debugger, but setting + this value has two effects: + <ul> + <li>It will prevent Android from throwing an error if you pause on + a breakpoint for a long time while debugging.</li> + <li>It will enable you to select the <em>Wait for Debugger</em> option + to pause application startup until your debugger attaches (described + next). </li> + </ul> + </li> + <li><strong>Wait for debugger </strong> + Blocks the selected application from loading until a debugger attaches. This + way you can set a breakpoint in onCreate(), which is important to debug + the startup process of an Activity. When you change this option, any + currently running instances of the selected application will be killed. + In order to check this box, you must have selected a debug application + as described in the previous option. You can do the same thing by adding + {@link android.os.Debug#waitForDebugger()} to your code. </li> + <li><strong>Immediately destroy activities</strong> Tells the + system to destroy an activity as soon as it is stopped (as if Android had to + reclaim memory). This is very useful for testing the {@link android.app.Activity#onSaveInstanceState} + / {@link android.app.Activity#onCreate(android.os.Bundle)} code path, which would + otherwise be difficult to force. Choosing this option will probably reveal + a number of problems in your application due to not saving state.</li> + <li><strong>Show screen updates</strong> + Flashes a momentary pink rectangle on any screen sections that are being + redrawn. This is very useful for discovering unnecessary screen drawing. </li> + <li><strong>Show CPU usage</strong> Displays CPU meters at the + top of the screen, showing how much the CPU is being used. The top red bar + shows overall CPU usage, and the green bar underneath it shows the CPU time + spent in compositing the screen. <em>Note: You cannot turn this feature off + once it is on, without restarting the emulator.</em> </li> + <li><strong>Show background</strong> Displays a background pattern + when no activity screens are visible. This typically does not happen, but + can happen during debugging. </li> +</ul> +<p>These settings will be remembered across emulator restarts. </p> + +<a name="toptips" id="toptips"></a> + +<div class="sidebox"> +<h2>Top Debugging Tips</h2> +<!-- +<ul> + <li><a href="#stackdump">Quick stack dump</a></li> + <li><a href="#displayinfo">Displaying useful info on the emulator screen </a></li> + <li><a href="#dumpstate">Getting system state information from the emulator (dumpstate)</a></li> + <li><a href="#dumpsys">Getting application state information from the emulator (dumpsys)</a></li> + <li><a href="#radioinfo">Getting wireless connectivity information</a></li> + <li><a href="#loggingdata">Logging Trace Data</a></li> + <li><a href="#logradio">Logging Radio Data </a></li> + <li><a href="#adb">Running adb</a></li> + <li><a href="#screencaps">Getting screen captures from the emulator</a></li> + <li><a href="#debughelpers">Using debug helper classes</a></li> +</ul> +--> +<dl> +<dt>Quick stack dump <a name="stackdump" id="stackdump"></a></dt> +<dd>To obtain a stack dump from emulator, you can log +in with <code>adb shell</code>, use "ps" to find the process you +want, and then "kill -3 ". The stack trace appears in the log file. +</dd> + +<dt>Displaying useful info on the emulator screen<a name="displayinfo" id="displayinfo"></a></dt> +<dd>The device can display useful information such as CPU usage or highlights +around redrawn areas. Turn these features on and off in the developer settings +window as described in <a href="#additionaldebugging">Setting debug and test +configurations on the emulator</a>. +</dd> + +<dt>Getting system state information from the emulator (dumpstate)<a name="dumpstate" id="dumpstate"></a> </dt> +<dd>You can access dumpstate information from the Dalvik Debug Monitor Service +tool. See <a href="{@docRoot}reference/adb.html#dumpsys">dumpsys and +dumpstate</a> on the adb topic page.</dd> + +<dt>Getting application state information from the emulator (dumpsys)<a name="dumpsys" id="dumpsys"></a></dt> +<dd>You can access dumpsys information from the Dalvik Debug Monitor Service +tool. See <a href="{@docRoot}reference/adb.html#dumpsys">dumpsys and +dumpstate</a> on the adb topic page.</dd> + +<dt>Getting wireless connectivity information <a name="radioinfo" id="radioinfo"></a></dt> +<dd>You can get information about wireless connectivity using the Dalvik Debug +Monitor Service tool. From the <strong>Device</strong> menu, select "Dump +radio state".</dd> + +<dt>Logging Trace Data<a name="loggingdata" id="loggingdata"></a></dt> +<dd>You can log method calls and other tracing data in an activity by calling +android.os.Debug.startMethodTracing(). See <a +href="{@docRoot}reference/traceview.html">Running the Traceview Debugging +Program</a> for details. </dd> + +<dt>Logging Radio Data<a name="logradio" id="logradio"></a></dt> +<dd>By default, radio information is not logged to the system (it is a lot of +data). However, you can enable radio logging using the following commands: + +<pre> +adb shell +logcat -b radio +</pre> +</dd> + +<dt>Running adb<a name="adb" id="adb"></a></dt> +<dd>Android ships with a tool called adb that provides various capabilities, including +moving and syncing files to the emulator, forwarding ports, and running a UNIX +shell on the emulator. See <a href="{@docRoot}reference/adb.html">Using adb</a> for details.</dd> + +<dt>Getting screen captures from the emulator<a name="screencaps" id="screencaps"></a></dt> +<dd> Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator.</dd> + + +<a name="debughelpers"></a> + +<dt>Using debugging helper classes</dt> + +<dd>Android provides debug helper classes such as {@link android.util.Log + util.Log} and {@link android.os.Debug} for your convenience. </dd> +</dl> +<a name="building"></a> +</div>
\ No newline at end of file diff --git a/docs/html/guide/developing/develop-and-debug.jd b/docs/html/guide/developing/develop-and-debug.jd new file mode 100644 index 0000000..6a337a9 --- /dev/null +++ b/docs/html/guide/developing/develop-and-debug.jd @@ -0,0 +1,675 @@ +page.title=Develop and Debug +@jd:body + +<p>This page offers an introduction to developing and debugging +applications on Android. It teaches how to +create, build, run and debug your Android code. Alternatively, you may like +to begin with the +<a href="/android/intro/hello-android.html">Hello Android tutorial</a>. </p> + +<h2>Contents</h2> + +<ol class="toc"> +<li><a href="#developingwitheclipse">Developing Android Applications on Eclipse</a></li> +<li><a href="#otherides">Developing Android Applications with Other IDEs and Tools</a></li> +<li><a href="#signing">Signing Your Applications</a></li> +<li><a href="#apidemos">Using the ApiDemos Sample Applications</a></li> +<li><a href="#debugging">Debugging</a></li> +<li><a href="#additionaldebugging">Debug and Test Settings on the Device</a></li> +<li><a href="#toptips">Top Debugging Tips</a></li> +<li><a href="#building">Building and Installing an Android Application</a></li> +<li><a href="#uninstalling">Removing an Android Application</a></li> +<li><a href="#tips">Eclipse Tips</a></li> +</ol> + + + +<a name="developingwitheclipse"></a> + +<h2 style="clear: right;"> +Developing Android Applications on Eclipse</h2> + +<p>To begin developing Android applications in the Eclipse IDE, you first create an Android +project and then set up a launch configuration. After that, you can write, run, and debug +your application. </p> + +<p>The sections below provide instructions assuming that you have installed the ADT plugin +in your Eclipse environment. If you haven't installed the ADT plugin, you should do that +before using the instructions below. See the <a href="{@docRoot}intro/installing.html#installingplugin">Installing the +Eclipse Plugin (ADT)</a> for more information. + +<a name="creatingaproject" id="creatingaproject"></a> + +<h3>Creating an Android Project</h3> + +<p>The ADT plugin provides a New Project Wizard that you can use to quickly create an +Eclipse project for new or existing code. To create the project, follow these steps:</p> + +<a name="existingcode"></a> + +<ol> + <li>Select <strong>File</strong> > <strong>New</strong> > <strong>Project</strong></li> + <li>Select <strong>Android</strong> > <strong>Android Project</strong>, and press <strong>Next</strong></li> + <li>Select the contents for the project: + <ul> + <li>Select <strong>Create new project in workspace</strong> to start a project for new code. + <p>Enter the project name, the base package name, the name of a single Activity class to create as a stub .java file, and a name to use for your application.</p></li> + <li>Select <strong>Create project from existing source</strong> to start a project from existing code. Use this option if you want to build and run any of the sample applications included with the SDK. The sample applications are located in the samples/ directory in the SDK. + <p>Browse to the directory containing the existing source code and click OK. If the directory contains a valid Android manifest file, the ADT plugin fills in the package, activity, and application names for you.</p> + </li> + </ul> + </li> + <li>Press <strong>Finish</strong>.</li> +</ol> + +<p>The ADT plugin creates the these folders and + files for you as appropriate for the type of project:</p> + + <ul> + <li>src/ A + folder that includes your stub .java Activity file.</li> + <li>res/ A folder for your + resources.</li> + <li>AndroidManifest.xml The + manifest for your project. </li> + </ul> + +</ol> + +<a name="launchconfig" id="launchconfig"></a> + +<h3>Creating a Launch Configuration </h3> + +<p>Before you can run and debug your application in Eclipse, you must create a launch configuration for it. A launch configuration specifies the project to launch, the Activity to start, the emulator options to use, and so on. </p> + +<p>To create a launch configuration for the application, follow these steps as appropriate for your Eclipse version:</p> + +<ol> + + <li>Open the launch configuration manager. + <ul> + <li>In Eclipse 3.3 (Europa), select <strong>Run </strong>> + <strong>Open Run Dialog... </strong>or <strong>Run </strong>> + <strong>Open Debug Dialog... </strong>as appropriate. + </li> + <li>In Eclipse 3.4 (Ganymede), select <strong>Run </strong>> + <strong>Run Configurations... </strong>or <strong>Run </strong>> + <strong>Debug Configurations... </strong>as appropriate. + </li> + </ul> + </li> + <li>In the project type list on the left, locate the <strong> Android Application</strong> item and double-click it (or right-click > <strong>New</strong>), to create a new launch configuration.</li> + <li>Enter a name for your configuration.</li> + <li>On the Android tab, browse for the project and Activity to start.</li> + <li>On the Target tab, set the desired screen and network properties, as well as any other <a href="{@docRoot}reference/emulator.html#startup-options">emulator startup options</a>.</li> + <li>You can set additional options on the Common tab as desired.</li> + <li>Press <strong>Apply</strong> to save the launch configuration, or press <strong>Run</strong> or <strong>Debug</strong> (as appropriate).</li> + +</ol> + +<a name="installingrunningdebugging" id="installingrunningdebugging"></a> + +<h3>Running and Debugging an Application</h3> + +<p>Once you've set up the project and launch configuration for your application, you can run or debug it as described below.</p> + +From the Eclipse main menu, select <strong>Run</strong> > <strong>Run</strong> or <strong>Run</strong> > <strong>Debug</strong> as appropriate, to run or debug the active launch configuration. </li> + +<p>Note that the active launch configuration is the one most recently selected in the Run configuration manager. It does not necessarily correspond to the application that is selected in the Eclipse Navigation pane (if any).</p> + +<p>To set or change the active launch configuration, use the launch configuration manager. See <a href="#launchconfig">Creating a Launch Configuration</a> for information about how to access the launch configuration manager.</strong>.</p> + +<p>Running or debugging the application triggers these actions:</p> +<ul><li>Starts the emulator, if it is not already running. </li> + <li>Compiles the project, if there have been changes since the last build, and installs the application on the emulator. </li> + <li><strong>Run</strong> starts the application. </li> + <li><strong>Debug</strong> starts the application in "Wait for debugger" mode, then opens the Debug perspective and attaches the Eclipse Java debugger to the application.</li> + + </ul> + +<a name="otherides" id="otherides"></a> +<h2>Developing Android Applications with Other IDEs and Tools</h2> +<p>The recommended way to develop an Android application is to use + <a href="#developingwitheclipse">Eclipse + with the ADT plugin</a>. This plugin provides editing, building, + and debugging functionality integrated right into the IDE. </p> + +<p>However, if you'd rather develop your application in another IDE, such as IntelliJ, + or use Eclipse without the ADT plugin, you can do that instead. The SDK + provides the tools you need to set up, build, and debug your application. + </p> + + +<h3>Creating an Android Project </h3> + +<p>The Android SDK includes <code>activityCreator</code>, a program that generates a number of stub files for your project, as well as a build file. You can use the program to create an Android project for new code or from existing code, such as the sample applications included in the SDK. For Linux and Mac, the SDK provides <code>activitycreator</code> and for Windows, <code>activityCreator.bat</code>, a batch script. Regardless of platform, you can use <code>activitycreator</code> in the same way. </p> + +<p>To run <code>activityCreator</code> and create an Android project, follow these steps:</p> + +<ol> + <li> In the command line, change to the <code>tools/</code> directory of the SDK and create a new directory for your project files. If you are creating a project from existing code, change to the root folder of your application instead. </li> + + <li><p>Run <code>activityCreator</code>. In the command, you must specify a fully-qualified class name as an argument. If you are creating a project for new code, the class represents the name of a stub class that the script will create. If you are creating a project from existing code, you must specify the name of one Activity class in the package. Command options for the script include: +<ul> + <li><code>--out <folder></code> which sets the output directory. By default, the output directory is the current directory. If you created a new directory for your project files, use this option to point to it. </li> + <li><code>--ide intellij</code>, which generates IntelliJ IDEA project files in the newly created project</li> +</ul> +</li> +</ol> + +<p>Here's an example:</p> +<pre> +~/android_linux_sdk/tools $ ./activityCreator.py --out myproject your.package.name.ActivityName +package: your.package.name +out_dir: myproject +activity_name: ActivityName +~/android_linux_sdk/tools $ </pre> + +<p>The <code>activityCreator</code> script generates the following files and directories (but will not overwrite existing ones):</p> + +<ul> + <li><code>AndroidManifest.xml</code> The application manifest file, synced to the specified Activity class for the project.</li> + <li><code>build.xml</code> An <code>Ant</code> file that you can use to build/package the application.</li> + <li><code>src<em>/your/package/name/ActivityName</em>.java</code> The Activity class you specified on input.</li> + <li><code><em>your_activity</em>.iml, <em>your_activity</em>.ipr, + <em>your_activity</em>.iws </code> [<em>only + with the <code>-ide intelliJ</code> flag</em>] intelliJ project + files. </li> + <li><code>res/</code> A directory to hold resources. </li> + <li><code>src/</code> The source directory. + <li><code>bin/</code> The output directory for the build script.</li> +</ul> + +<p>You can now move your folder wherever you want for development, but keep in mind + that you'll have to use the <a href="{@docRoot}reference/adb.html">adb</a> program in the <code>tools/</code> folder to + send files to the emulator, so you'll need access between your solution and + the <code>tools/</code> folder. </p> + +<p>Also, you should refrain from moving the + location of the SDK directory, since this will break the build scripts (they + will need to be manually updated to reflect the new SDK location before they will + work again).</p> + +<a name="buildingwithant"></a> + +<h3>Building an Android Application</h3> +<p>Use the Ant <code>build.xml</code> file generated by + <code>activityCreator</code> to build your application.</p> +<ol> + <li>If you don't have it, you can obtain Ant from the + <a href="http://ant.apache.org/">Apache Ant home page</a>. Install it and make + sure it is on your executable path. </li> + <li>Before calling Ant, you need to declare the JAVA_HOME environment variable to specify the path to where the JDK is installed. + <p class="note"><strong>Note:</strong> When installing JDK on Windows, the default is to install in the "Program Files" directory. This location will cause <code>ant</code> to fail, because of the space. To fix the problem, you can specify the JAVA_HOME variable like this: <code>set JAVA_HOME=c:\Prora~1\Java\<jdkdir></code>. The easiest solution, however, is to install JDK in a non-space directory, for example: <code>c:\java\jdk1.6.0_02</code>. </p> + </li> + + + <li>If you have not done so already, follow the instructions for Creating a + New Project above to set up the project.</li> + <li>You can now run the Ant build file by simply typing ant in the same folder + as the build.xml file for your project. Each time you change + a source file or resource, you should run ant again and it will package up the + latest version of the application for you to deploy.</li> +</ol> + +<h3>Running an Android Application</h3> +<p>To run a compiled + application, you will upload the .apk file to the <code>/data/app/ </code>directory + in the emulator using the <a href="{@docRoot}reference/adb.html">adb</a> tool as described here:</p> +<ol> + <li>Start the emulator (run <code><em><your_sdk_dir></em>/tools/emulator</code> from the command line)</li> + <li>On the emulator, navigate to the home screen (it is best not to have that + application running when you reinstall it on the emulator; press the <strong>Home</strong> key + to navigate away from that application).</li> + <li>Run <code>adb install <em>myproject</em>/bin/<<em>appname</em>>.apk</code> to upload + the executable. So, for example, to install the Lunar Lander sample, navigate + in the command line to <code><em><your_sdk_dir></em>/sample/LunarLander</code> and type <code>../../tools/adb install bin/LunarLander.apk</code></li> + <li>In the emulator, open the list of available applications, and scroll down to + select and start your application. </li> +</ol> +<p class="note"><strong>Note:</strong> When you install an Activity for the + first time, you might have to restart the emulator before it shows up in the + application launcher, or other applications can call it. This is because + the package manager usually only examines manifests completely on emulator + startup.</p> + +<h3>Attaching a Debugger to Your Application</h3> +<p>This section describes how to display debug information on the screen (such + as CPU usage), as well as how to hook up your IDE to debug running applications + on the emulator. </p> + +<p>Attaching a debugger is automated using the Eclipse plugin, + but you can configure other IDEs to listen on a debugging port to receive debugging + information.</p> +<ol> + <li><strong>Start the <a href="{@docRoot}reference/ddms.html">Dalvik Debug Monitor Server (DDMS) + tool </a>, </strong> which + acts as a port forwarding service between your IDE and the emulator.</li> + <li><strong>Set + optional debugging configurations on + your emulator</strong>, such as blocking application startup for an activity + until a debugger is attached. Note that many of these debugging options + can be used without DDMS, such as displaying CPU usage or screen refresh + rate on the emulator.</li> + <li><strong>Configure your IDE to attach to port 8700 for debugging.</strong> We + include information on <a href="#eclipse">how to set up Eclipse to debug + your project</a>. </li> + +<a name="eclipse" id="eclipse"></a> + +</ol> +<h3>Configuring your IDE to attach to the debugging port</h3> + +<p>DDMS will assign a specific debugging port to every virtual machine that it + finds on the emulator. You must either attach your IDE to that + port (listed on the Info tab for that VM), or you can use a default port 8700 + to connect to whatever application is currently selected on the list of discovered + virtual machines.</p> +<p>Your IDE should attach to your application running on the emulator, showing you + its threads and allowing you to suspend them, inspect their state, and set breakpoints. + If you selected "Wait for debugger" in the Development settings panel + the application will run when Eclipse connects, so you will need to set any breakpoints + you want before connecting.</p> +<p>Changing either the application being debugged or the "Wait for debugger" + option causes the system to kill the selected application if it is currently + running. You can use this to kill your application if it is in a bad state + by simply going to the settings and toggling the checkbox.</p> + +<a name="signing" id="signing"></a> + +<h2>Signing Your Applications</h2> + +<p>The Android system requires that all installed applications are digitally signed — +the system will not install or run an application that is not signed appropriately. This +applies wherever the Android system is run, whether on an actual device or on the emulator. +For this reason, you must set up signing for your application before you will be able to +run or debug it on an emulator or device.</p> + +<p>The important points to understand about signing Android applications are:</p> + +<ul> + <li>All applications <em>must</em> be signed. The system will not install an application +that is not signed.</li> + <li>You can use self-signed certificates to sign your applications. No certificate authority +is needed.</li> + <li>The system tests a signer certificate's expiration date only at install time. If an +application's signer certificate expires after the application is installed, the application +will continue to function normally.</li> + <li>You can use standard tools — Keytool and Jarsigner — to generate keys and +sign your application .apk files.</li> +</ul> + +<p>The Android SDK tools assist you in signing your applications when debugging. Both the ADT Plugin +for Eclipse and the Ant build tool offer two signing modes — debug mode and release mode. + +<ul> + <li>In debug mode, the build tools use the Keytool utility, included in the JDK, to create +a keystore and key with a known alias and password. At each compilation, the tools then use +the debug key to sign the application .apk file. Because the password is known, the tools +don't need to prompt you for the keystore/key password each time you compile.</li> + + <li>When your application is ready for release, you compile it in release signing mode. +In release mode, the tools compile your .apk without signiing it. You must then use Keytool +to generate your own keystore/key and then use the Jarsigner tool, also included in the JDK, +to sign the .apk.</li> +</ul> + +<h3>Basic Setup for Signing</h3> + +<p>To support the generation of a keystore and debug key, you should first make sure that +Keytool is available to the SDK build +tools. In most cases, you can tell the SDK build tools how to find Keytool by making sure +that your JAVA_HOME environment variable is set and that it references a suitable JDK. +Alternatively, you can add the JDK version of Keytool to your PATH variable.</p> + +<p>If you are developing on a version of Linux that originally came with Gnu Compiler for +Java, make sure that the system is using the JDK version of Keytool, rather than the gcj +version. If Keytool is already in your PATH, it might be pointing to a symlink at +/usr/bin/keytool. In this case, check the symlink target to make sure that it points +to the Keytool in the JDK.</p> + +<h3>Signing in Eclipse/ADT</h3> + +<p>If you are developing in Eclipse and have set up Keytool as described above, signing +in debug mode is enabled by default. When you run or debug your app, ADT signs the .apk +for you and installs it on the emulator. No specific action on your part is needed, +provided ADT has access to Keytool.</p> + +<p>To compile your application in release mode, right-click the project in the Package +pane and select Android Tools > Export Application Package. Alternatively, you can follow the +"Exporting the unsigned .apk" link in the Manifest Editor overview page. After you have saved +the exported .apk, you need to use Jarsigner to sign the .apk with your own key before +distribution. If you don't have a key, you can use Keystore to create a keystore and key with +all the appropriate fields. If you already have a key, such as a corporate key, you can use +that to sign the .apk.</p> + +<h3>Signing in Ant</h3> + +<p>If you use Ant to build your .apk files, debug signing mode +is enabled by default, assuming that you are using a build.xml file generated by the +activitycreator tool included in the latest SDK. When you run Ant against build.xml to +compile your app, the build script generates a keystore/key and signs the .apk for you. +No specific action on your part is needed.</p> + +<p>To compile your application in release mode, all you need to do is specify a build target +"release" in the Ant command. For example, if you are running Ant from the directory containing +your build.xml file, the command would look like this:</p> + +<pre>ant release</pre> + +<p>The build script compiles the application .apk without signing it. After you have compiled +the.apk, you need to use Jarsigner to sign the .apk with your own key before +distribution. If you don't have a key, you can use Keystore to create a keystore and key +with all the appropriate fields. If you already have a key, such as a corporate key, you +can use that to sign the .apk.</p> + +<h3>Expiry of the Debug Certificate</h3> + +<p>The self-signed certificate used to sign your application in debug mode (the default on +Eclipse/ADT and Ant builds) will have an expiration date of 1 year from its creation date.</p> + +<p>When the certificate expires, you will get a build error. On Ant builds, the error +looks like this:</p> + +<pre>debug: +[echo] Packaging bin/samples-debug.apk, and signing it with a debug key... +[exec] Debug Certificate expired on 8/4/08 3:43 PM</pre> + +<p>In Eclipse/ADT, you will see a similar error in the Android console.</p> + +<p>To fix this problem, simply delete the <code>debug.keystore</code> file. On Linux/Mac OSX, +the file is stored in <code>~/.android</code>. OOn Windows XP, the file is stored in <code> +C:\Documents and Settings\<user>\Local Settings\Application Data\Android</code>. +On Windows Vista, the file is stored in <code> +C:\Users\<user>\AppData\Local\Android</code>.</p> + +<p>The next time you build, the build tools will regenerate a new keystore and debug key.</p> + +<p>Note that, if your development machine is using a non-Gregorian locale, the build +tools may erroneously generate an already-expired debug certificate, so that you get an +error when trying to compile your application. For workaround information, see the +troubleshooting topic <a href="{@docRoot}kb/troubleshooting.html#signingcalendar"> +I can't compile my app because the build tools generated an expired debug +certificate</a>. </p> + +<h2 id="apidemos">Using the ApiDemos Sample Applications</h2> + +<p>The Android SDK includes a set of sample applications that demonstrate much of +the functionality and API usage needed for your applications. The ApiDemos package is +preinstalled on the emulator, so you can access it by starting an emulator and sliding +open the home screen's application drawer. </p> + +<p>You can find the source code corresponding to the ApiDemos apps in <code><SDK> +/samples/ApiDemos</code> and look at it to learn more about how it is implemented.</p> + +<p>If you want, you can load the ApiDemos sample applications as source projects and modify +them, then run them in the emulator. However, to do so, you need to uninstall the preinstalled +version of ApiDemos first. If you try to run or modify ApiDemos from your development environment +without removing the preinstalled version first, you will get an install error.</p> + +<p>For information about how to uninstall and then reinstall ApiDemos so that you can work with +them in your development environment, see the troubleshooting topic +<a href="{@docRoot}kb/troubleshooting.html#apidemosreinstall">I can't install ApiDemos +apps in my IDE because of a signing error</a>.</p> + +<a name="debugging" id="debugging"></a> + +<h2>Debugging</h2> + +<p>Android has a fairly extensive set of tools to help you debug your programs: </p> +<ul> + <li><a href="{@docRoot}reference/ddms.html"><strong>DDMS</strong></a> - A graphical program that + supports port forwarding (so you can set up breakpoints in your code in your + IDE), screen captures on the emulator, thread and stack information, + and many other features. You can also run logcat to retrieve your Log messages. + See the linked topic for more information. </li> + <li><strong><a href="{@docRoot}reference/ddms.html#logcat">logcat</a></strong> - Dumps a log of system + messages. The messages include a stack trace when the emulator throws an error, + as well as Log messages. To run logcat, see the linked topic. + + <pre>... +I/MemoryDealer( 763): MemoryDealer (this=0x54bda0): Creating 2621440 bytes heap at 0x438db000 +<span style="background-color:#CCCCCC; border-bottom:medium">I/Logger( 1858): getView() requesting item number 0 +I/Logger( 1858): getView() requesting item number 1 +I/Logger( 1858): getView() requesting item number 2</span> +D/ActivityManager( 763): Stopping: HistoryRecord{409dbb20 com.android.home.AllApps} +...</pre> + + </li> + <li><p><strong>{@link android.util.Log Android Log}</strong>- A logging + class to print out messages to a log file on the emulator. You can read messages + in real time if you run logcat on DDMS (covered next). Add a few logging + method calls to your code.</p> + <p>To use the <code>Log</code> class, you just call <code>Log.v()</code> + (verbose), <code>Log.d()</code> (debug), <code>Log.i()</code> (information), + <code>Log.w()</code> (warning) or <code>Log.e</code> (error) depending + on the importance you wish to assign the log message.</p> + <code>Log.i("MyActivity", "MyClass.getView() + — Requesting item number " + position)</code> + <p>You can use logcat to read these messages</p></li> + <li><strong><a href="{@docRoot}reference/traceview.html">Traceview</a> </strong>- Android can save + a log of method calls and times to a logging file that you can view in a + graphical reader called Traceview. See the linked topic for more information. </li> +</ul> +<ul> + <li><a href="#developingwitheclipse"><strong>Eclipse plugin</strong></a> - The Eclipse + Android plugin incorporates a number of these tools (ADB, DDMS, logcat output, + and other functionality). See the linked topic for more information. </li> + <li><strong>Debug and Test Device Settings</strong> - Android exposes several settings + that expose useful information such as CPU usage and frame rate. See <a href="#additionaldebugging">Debug + and Test Settings on the Emulator</a> below. </li> +</ul> +<p>Also, see the <a href="{@docRoot}kb/troubleshooting.html">Troubleshooting</a> section + of the doc to figure out why your application isn't appearing on the emulator, + or why it's not starting. </p> + +<a name="additionaldebugging" id="additionaldebugging"></a> + +<h2>Debug and Test Settings on the Device</h2> + +<p>Android lets you set a number of settings that will make it easier to test + and debug your applications. To get to the development settings page on the emulator, + go to <strong>Dev Tools </strong>> <strong>Development Settings</strong>. + This will open the development settings page with the following options (among + others):</p> +<ul> + <li><strong>Debug app</strong> Selects the application that + will be debugged. You do not need to set this to attach a debugger, but setting + this value has two effects: + <ul> + <li>It will prevent Android from throwing an error if you pause on + a breakpoint for a long time while debugging.</li> + <li>It will enable you to select the <em>Wait for Debugger</em> option + to pause application startup until your debugger attaches (described + next). </li> + </ul> + </li> + <li><strong>Wait for debugger </strong> + Blocks the selected application from loading until a debugger attaches. This + way you can set a breakpoint in onCreate(), which is important to debug + the startup process of an Activity. When you change this option, any + currently running instances of the selected application will be killed. + In order to check this box, you must have selected a debug application + as described in the previous option. You can do the same thing by adding + {@link android.os.Debug#waitForDebugger()} to your code. </li> + <li><strong>Immediately destroy activities</strong> Tells the + system to destroy an activity as soon as it is stopped (as if Android had to + reclaim memory). This is very useful for testing the {@link android.app.Activity#onSaveInstanceState} + / {@link android.app.Activity#onCreate(android.os.Bundle)} code path, which would + otherwise be difficult to force. Choosing this option will probably reveal + a number of problems in your application due to not saving state.</li> + <li><strong>Show screen updates</strong> + Flashes a momentary pink rectangle on any screen sections that are being + redrawn. This is very useful for discovering unnecessary screen drawing. </li> + <li><strong>Show CPU usage</strong> Displays CPU meters at the + top of the screen, showing how much the CPU is being used. The top red bar + shows overall CPU usage, and the green bar underneath it shows the CPU time + spent in compositing the screen. <em>Note: You cannot turn this feature off + once it is on, without restarting the emulator.</em> </li> + <li><strong>Show background</strong> Displays a background pattern + when no activity screens are visible. This typically does not happen, but + can happen during debugging. </li> +</ul> +<p>These settings will be remembered across emulator restarts. </p> + +<a name="toptips" id="toptips"></a> + +<h2>Top Debugging Tips</h2> +<!-- +<ul> + <li><a href="#stackdump">Quick stack dump</a></li> + <li><a href="#displayinfo">Displaying useful info on the emulator screen </a></li> + <li><a href="#dumpstate">Getting system state information from the emulator (dumpstate)</a></li> + <li><a href="#dumpsys">Getting application state information from the emulator (dumpsys)</a></li> + <li><a href="#radioinfo">Getting wireless connectivity information</a></li> + <li><a href="#loggingdata">Logging Trace Data</a></li> + <li><a href="#logradio">Logging Radio Data </a></li> + <li><a href="#adb">Running adb</a></li> + <li><a href="#screencaps">Getting screen captures from the emulator</a></li> + <li><a href="#debughelpers">Using debug helper classes</a></li> +</ul> +--> +<dl> +<dt>Quick stack dump <a name="stackdump" id="stackdump"></a></dt> +<dd>To obtain a stack dump from emulator, you can log +in with <code>adb shell</code>, use "ps" to find the process you +want, and then "kill -3 ". The stack trace appears in the log file. +</dd> + +<dt>Displaying useful info on the emulator screen<a name="displayinfo" id="displayinfo"></a></dt> +<dd>The device can display useful information such as CPU usage or highlights +around redrawn areas. Turn these features on and off in the developer settings +window as described in <a href="#additionaldebugging">Setting debug and test +configurations on the emulator</a>. +</dd> + +<dt>Getting system state information from the emulator (dumpstate)<a name="dumpstate" id="dumpstate"></a> </dt> +<dd>You can access dumpstate information from the Dalvik Debug Monitor Service +tool. See <a href="{@docRoot}reference/adb.html#dumpsys">dumpsys and +dumpstate</a> on the adb topic page.</dd> + +<dt>Getting application state information from the emulator (dumpsys)<a name="dumpsys" id="dumpsys"></a></dt> +<dd>You can access dumpsys information from the Dalvik Debug Monitor Service +tool. See <a href="{@docRoot}reference/adb.html#dumpsys">dumpsys and +dumpstate</a> on the adb topic page.</dd> + +<dt>Getting wireless connectivity information <a name="radioinfo" id="radioinfo"></a></dt> +<dd>You can get information about wireless connectivity using the Dalvik Debug +Monitor Service tool. From the <strong>Device</strong> menu, select "Dump +radio state".</dd> + +<dt>Logging Trace Data<a name="loggingdata" id="loggingdata"></a></dt> +<dd>You can log method calls and other tracing data in an activity by calling +android.os.Debug.startMethodTracing(). See <a +href="{@docRoot}reference/traceview.html">Running the Traceview Debugging +Program</a> for details. </dd> + +<dt>Logging Radio Data<a name="logradio" id="logradio"></a></dt> +<dd>By default, radio information is not logged to the system (it is a lot of +data). However, you can enable radio logging using the following commands: + +<pre> +adb shell +logcat -b radio +</pre> +</dd> + +<dt>Running adb<a name="adb" id="adb"></a></dt> +<dd>Android ships with a tool called adb that provides various capabilities, including +moving and syncing files to the emulator, forwarding ports, and running a UNIX +shell on the emulator. See <a href="{@docRoot}reference/adb.html">Using adb</a> for details.</dd> + +<dt>Getting screen captures from the emulator<a name="screencaps" id="screencaps"></a></dt> +<dd> Dalvik Debug Monitor Server (DDMS) can capture screenshots from the emulator.</dd> + + +<a name="debughelpers"></a> + +<dt>Using debugging helper classes</dt> + +<dd>Android provides debug helper classes such as {@link android.util.Log + util.Log} and {@link android.os.Debug} for your convenience. </dd> +</dl> +<a name="building"></a> + +<h2>Building and Installing an Android Application</h2> +<p>Android requires custom build tools to be able to properly build the resource + files and other parts of an Android application. Because of this, you must have + a specialized build environment for your application. </p> +<p>Custom + Android compilation steps include compiling the XML and other resource files, and creating + the proper output format. A compiled Android application is an .apk file, which + is a compressed file containing <a href="{@docRoot}reference/glossary.html">.dex</a> files, resource files, raw data files, and + other files. You can create a properly structured Android project either from +scratch, or from existing source files. </p> +<p>Android does not currently support development of third party applications in native code (C/C++).</p> +<p><strong>The recommended way</strong> to develop an Android + application is to <a href="#developingwitheclipse">use Eclipse with the Android plugin</a>, + which provides support for building, running, and debugging Android applications. </p> +<p><strong>If you have another IDE</strong>, <a href="#otherides">Android + provides tools for other IDEs</a> to build and debug Android applications, + but they are not as integrated. </p> + +<a name="uninstalling" id="uninstalling"></a> + + <h2>Removing an Android Application</h2> + + <p>To remove an application that you have installed on the emulator, you will + need to <a href="{@docRoot}reference/adb.html">run adb</a> and delete the .apk + file you sent to the emulator when you installed it. Use <code>adb + shell</code> to drop into a shell on the device as described in the linked + topic, navigate to <code>data/app/</code>, and then remove the file using + <code>rm <em>your_app</em>.apk</code>. </p> + +<a name="tips" id="tips"></a> + + <h2>Eclipse Tips </h2> + <h3>Executing arbitrary Java expressions in Eclipse<a name="arbitraryexpressions" id="arbitraryexpressions"></a></h3> + <p>You can execute arbitrary code when paused at a breakpoint in Eclipse. For example, + when in a function with a String argument called "zip", you can get + information about packages and call class methods. You can also invoke arbitrary + static methods: for example, entering <code>android.os.Debug.startMethodTracing()</code> will + start dmTrace. </p> + <p>Open a code execution window, select <strong>Window</strong>><strong>Show + View</strong>><strong>Display</strong> from the main menu to open the + Display window, a simple text editor. Type your expression, highlight the + text, and click the 'J' icon (or CTRL + SHIFT + D) to run your + code. The code runs in the context of the selected thread, which must be + stopped at a breakpoint or single-step point. (If you suspend the thread + manually, you have to single-step once; this doesn't work if the thread is + in Object.wait().)</p> + <p>If you are currently paused on a breakpoint, you can simply highlight and execute + a piece of source code by pressing CTRL + SHIFT + D. </p> + <p>You can highlight a block of text within the same scope by pressing ALT +SHIFT + + UP ARROW to select larger and larger enclosing blocks, or DOWN ARROW to select + smaller blocks. </p> + <p>Here are a few sample inputs and responses in Eclipse using the Display window.</p> + <table width="100%" border="1"> + <tr> + <th scope="col">Input</th> + <th scope="col">Response</th> + </tr> + <tr> + <td><code>zip</code></td> + <td><code>(java.lang.String) /work/device/out/linux-x86-debug/android/app/android_sdk.zip</code></td> + </tr> + <tr> + <td><code>zip.endsWith(".zip")</code></td> + <td><code>(boolean) true</code></td> + </tr> + <tr> + <td><code>zip.endsWith(".jar")</code></td> + <td><code>(boolean) false</code></td> + </tr> + </table> + <p>You can also execute arbitrary code when not debugging by using a scrapbook page. + Search the Eclipse documentation for "scrapbook".</p> + + <h3>Running DDMS Manually</h3> + + <p>Although the recommended way to debug is to use the ADT plugin, you can manually run DDMS and configure Eclipse to debug on port 8700. (<strong>Note: </strong>Be sure that you have first started <a href="{@docRoot}reference/ddms.html">DDMS</a>). </p> + +<h3>Adding JUnit test classes</h3> + +<p>In Eclipse/ADT, you can add JUnit test classes to your application. However, you need to set up a custom JUnit configuration before your tests will run properly. For detailed information about how to set up the JUnit configuration, see the troubleshooting topic <a href="{@docRoot}kb/troubleshooting.html#addjunit">I can't run a Junit test class in Eclipse</a>.</p> + diff --git a/docs/html/guide/developing/draw9patch.jd b/docs/html/guide/developing/draw9patch.jd new file mode 100644 index 0000000..25604f8 --- /dev/null +++ b/docs/html/guide/developing/draw9patch.jd @@ -0,0 +1,61 @@ +page.title=Draw 9-patch +@jd:body + +<p>The Draw 9-patch tool allows you to easily create a + {@link android.graphics.NinePatch} graphic using a WYSIWYG editor.</p> +<p>To learn more about what a Nine-patch graphic is, and how they work, please read +the section on Nine-patch in the +<a href="{@docRoot}reference/available-resources.html#ninepatch">Available Resource +Types</a> document.</p> + +<div class="sidebox" style="width:auto"><br/> +<img src="/android/images/draw9patch-norm.png" alt="" height="300" width="341" /> +</div> + +<p>Here's a quick guide to create a Nine-patch graphic using the Draw 9-patch tool. +You'll need the PNG image with which you'd like to create a NinePatch.</p> + +<ol> + <li>From a terminal, launch the <code>draw9patch</code> application from your SDK + <code>/tools</code> directory. + </li> + <li>Drag your PNG image into the Draw 9-patch window + (or <strong>File</strong> > <strong>Open 9-patch...</strong> to locate the file). + Your workspace will now open. + <p>The left pane is your drawing area, in which you can edit the lines for the + stretchable patches and content area. The right + pane is the preview area, where you can preview your graphic when stretched.</p> + </li> + <li>Click within the 1-pixel perimeter to draw the lines that define the stretchable + patches and (optional) content area. Right-click (or hold Shift and click, on Mac) to erase + previously drawn lines. + </li> + <li>When done, select <strong>File</strong> > <strong>Save 9-patch...</strong> + <p>Your image will be saved with the <code>.9.png</code> file name.</p> + </li> +</ol> + <p class="note"><strong>Note:</strong> A normal PNG file (<code>*.png</code>) will be + loaded with an empty one-pixel border added around the image, in which you can draw + the stretchable patches and content area. + A previously saved 9-patch file (<code>*.9.png</code>) will be loaded as-is, + with no drawing area added, because it already exists.</p> + +<div class="sidebox" style="width:auto"><br/> +<img src="/android/images/draw9patch-bad.png" alt="" height="300" width="341" /> +</div> + +<p>Optional controls include:</p> +<ul> + <li><strong>Zoom</strong>: Adjust the zoom level of the graphic in the drawing area.</li> + <li><strong>Patch scale</strong>: Adjust the scale of the images in the preview area.</li> + <li><strong>Show lock</strong>: Visualize the non-drawable area of the graphic on mouse-over.</li> + <li><strong>Show patches</strong>: Preview the stretchable patches in the drawing area (pink is a + stretchable patch).</li> + <li><strong>Show content</strong>: Highlight the content area in the preview images + (purple is the area in which content is allowed).</li> + <li><strong>Show bad patches</strong>: Adds a red border around patch areas that may + produce artifacts in the graphic when stretched. Visual coherence of your stretched + image will be maintained if you eliminate all bad patches.</li> +<ul> + +<p><strong><a href="/android/intro/tools.html">Back to Development Tools</a></strong></p>
\ No newline at end of file diff --git a/docs/html/guide/developing/eclipse-adt.jd b/docs/html/guide/developing/eclipse-adt.jd new file mode 100644 index 0000000..94087bf --- /dev/null +++ b/docs/html/guide/developing/eclipse-adt.jd @@ -0,0 +1,146 @@ +page.title=In Eclipse, with ADT +@jd:body + +<p>To begin developing Android applications in the Eclipse IDE with ADT, you first create an Android +project and then set up a launch configuration. After that, you can write, run, and debug +your application. </p> + +<p>The sections below provide instructions assuming that you have installed the ADT plugin +in your Eclipse environment. If you haven't installed the ADT plugin, you should do that +before using the instructions below. See the <a href="{@docRoot}intro/installing.html#installingplugin">Installing the +Eclipse Plugin (ADT)</a> for more information. + +<a name="creatingaproject" id="creatingaproject"></a> + +<h3>Creating an Android Project</h3> + +<p>The ADT plugin provides a New Project Wizard that you can use to quickly create an +Eclipse project for new or existing code. To create the project, follow these steps:</p> + +<a name="existingcode"></a> + +<ol> + <li>Select <strong>File</strong> > <strong>New</strong> > <strong>Project</strong></li> + <li>Select <strong>Android</strong> > <strong>Android Project</strong>, and press <strong>Next</strong></li> + <li>Select the contents for the project: + <ul> + <li>Select <strong>Create new project in workspace</strong> to start a project for new code. + <p>Enter the project name, the base package name, the name of a single Activity class to create as a stub .java file, and a name to use for your application.</p></li> + <li>Select <strong>Create project from existing source</strong> to start a project from existing code. Use this option if you want to build and run any of the sample applications included with the SDK. The sample applications are located in the samples/ directory in the SDK. + <p>Browse to the directory containing the existing source code and click OK. If the directory contains a valid Android manifest file, the ADT plugin fills in the package, activity, and application names for you.</p> + </li> + </ul> + </li> + <li>Press <strong>Finish</strong>.</li> +</ol> + +<p>The ADT plugin creates the these folders and + files for you as appropriate for the type of project:</p> + + <ul> + <li>src/ A + folder that includes your stub .java Activity file.</li> + <li>res/ A folder for your + resources.</li> + <li>AndroidManifest.xml The + manifest for your project. </li> + </ul> + +</ol> + +<a name="launchconfig" id="launchconfig"></a> + +<h3>Creating a Launch Configuration </h3> + +<p>Before you can run and debug your application in Eclipse, you must create a launch configuration for it. A launch configuration specifies the project to launch, the Activity to start, the emulator options to use, and so on. </p> + +<p>To create a launch configuration for the application, follow these steps as appropriate for your Eclipse version:</p> + +<ol> + + <li>Open the launch configuration manager. + <ul> + <li>In Eclipse 3.3 (Europa), select <strong>Run </strong>> + <strong>Open Run Dialog... </strong>or <strong>Run </strong>> + <strong>Open Debug Dialog... </strong>as appropriate. + </li> + <li>In Eclipse 3.4 (Ganymede), select <strong>Run </strong>> + <strong>Run Configurations... </strong>or <strong>Run </strong>> + <strong>Debug Configurations... </strong>as appropriate. + </li> + </ul> + </li> + <li>In the project type list on the left, locate the <strong> Android Application</strong> item and double-click it (or right-click > <strong>New</strong>), to create a new launch configuration.</li> + <li>Enter a name for your configuration.</li> + <li>On the Android tab, browse for the project and Activity to start.</li> + <li>On the Target tab, set the desired screen and network properties, as well as any other <a href="{@docRoot}reference/emulator.html#startup-options">emulator startup options</a>.</li> + <li>You can set additional options on the Common tab as desired.</li> + <li>Press <strong>Apply</strong> to save the launch configuration, or press <strong>Run</strong> or <strong>Debug</strong> (as appropriate).</li> + +</ol> + +<a name="installingrunningdebugging" id="installingrunningdebugging"></a> + +<h3>Running and Debugging an Application</h3> + +<p>Once you've set up the project and launch configuration for your application, you can run or debug it as described below.</p> + +From the Eclipse main menu, select <strong>Run</strong> > <strong>Run</strong> or <strong>Run</strong> > <strong>Debug</strong> as appropriate, to run or debug the active launch configuration. </li> + +<p>Note that the active launch configuration is the one most recently selected in the Run configuration manager. It does not necessarily correspond to the application that is selected in the Eclipse Navigation pane (if any).</p> + +<p>To set or change the active launch configuration, use the launch configuration manager. See <a href="#launchconfig">Creating a Launch Configuration</a> for information about how to access the launch configuration manager.</strong>.</p> + +<p>Running or debugging the application triggers these actions:</p> +<ul><li>Starts the emulator, if it is not already running. </li> + <li>Compiles the project, if there have been changes since the last build, and installs the application on the emulator. </li> + <li><strong>Run</strong> starts the application. </li> + <li><strong>Debug</strong> starts the application in "Wait for debugger" mode, then opens the Debug perspective and attaches the Eclipse Java debugger to the application.</li> + + </ul> + + <h2 id="tips">Eclipse Tips </h2> + <h3>Executing arbitrary Java expressions in Eclipse<a name="arbitraryexpressions" id="arbitraryexpressions"></a></h3> + <p>You can execute arbitrary code when paused at a breakpoint in Eclipse. For example, + when in a function with a String argument called "zip", you can get + information about packages and call class methods. You can also invoke arbitrary + static methods: for example, entering <code>android.os.Debug.startMethodTracing()</code> will + start dmTrace. </p> + <p>Open a code execution window, select <strong>Window</strong>><strong>Show + View</strong>><strong>Display</strong> from the main menu to open the + Display window, a simple text editor. Type your expression, highlight the + text, and click the 'J' icon (or CTRL + SHIFT + D) to run your + code. The code runs in the context of the selected thread, which must be + stopped at a breakpoint or single-step point. (If you suspend the thread + manually, you have to single-step once; this doesn't work if the thread is + in Object.wait().)</p> + <p>If you are currently paused on a breakpoint, you can simply highlight and execute + a piece of source code by pressing CTRL + SHIFT + D. </p> + <p>You can highlight a block of text within the same scope by pressing ALT +SHIFT + + UP ARROW to select larger and larger enclosing blocks, or DOWN ARROW to select + smaller blocks. </p> + <p>Here are a few sample inputs and responses in Eclipse using the Display window.</p> + <table width="100%" border="1"> + <tr> + <th scope="col">Input</th> + <th scope="col">Response</th> + </tr> + <tr> + <td><code>zip</code></td> + <td><code>(java.lang.String) /work/device/out/linux-x86-debug/android/app/android_sdk.zip</code></td> + </tr> + <tr> + <td><code>zip.endsWith(".zip")</code></td> + <td><code>(boolean) true</code></td> + </tr> + <tr> + <td><code>zip.endsWith(".jar")</code></td> + <td><code>(boolean) false</code></td> + </tr> + </table> + <p>You can also execute arbitrary code when not debugging by using a scrapbook page. + Search the Eclipse documentation for "scrapbook".</p> + + <h3>Running DDMS Manually</h3> + + <p>Although the recommended way to debug is to use the ADT plugin, you can manually run DDMS and configure Eclipse to debug on port 8700. (<strong>Note: </strong>Be sure that you have first started <a href="{@docRoot}reference/ddms.html">DDMS</a>). </p> diff --git a/docs/html/guide/developing/emulator.jd b/docs/html/guide/developing/emulator.jd new file mode 100755 index 0000000..0516fdd --- /dev/null +++ b/docs/html/guide/developing/emulator.jd @@ -0,0 +1,1724 @@ +page.title=Android Emulator +@jd:body + +<img src="{@docRoot}images/emulator-hvga-p.png" alt="Image of the Android Emulator" width="271" height="524" style="margin-left:0em;float:right;"/> + +<p>The Android SDK includes a mobile device emulator -- a virtual mobile device +that runs on your computer. The emulator lets you prototype, develop, and test +Android applications without using a physical device. </p> + +<p>The Android emulator mimics all of the typical hardware and software features +of a typical mobile device, except that it can not receive or place actual phone +calls. It provides a variety of navigation and control keys, which you can "press" +using your mouse or keyboard to generate events for your application. It also +provides a screen in which your application is displayed, together with any other +Android applications running. </p> + +<p>To help you model and test your application, the emulator lets your application +use the services of the Android platform to invoke other applications, access the +network, play audio and video, store and retrieve data, notify the user, and render +graphical transitions and themes. </p> + +<p>The emulator also includes a variety of debug capabilities, such as a console +from which you can log kernel output, simulate application interrupts (such as +arriving SMS messages or phone calls), and simulate latency effects and dropouts +on the data channel.</p> + + +<h2 style="clear:right;">Contents</h2> + +<div class="g-section g-tpl-50-50"> +<div class="g-unit g-first"> + +<dl> +<dt><a href="#overview">Overview</a></dt> +<dt><a href="#starting">Starting and Stopping the Emulator</a></dt> +<dt><a href="#controlling">Controlling the Emulator</a></dt> +<dt><a href="#startup-options">Emulator Startup Options</a></dt> +<dt><a href="#diskimages">Working with Emulator Disk Images</a></dt> + <dd><a href="#systemimages">System Images</a></dd> + <dd><a href="#runtimeimages">Runtime Images: User Data and SD Card</a></dd> + <dd><a href="#temporaryimages">Temporary Images</a></dd> +<dt><a href="#emulatornetworking">Emulator Networking</a></dt> + <dd><a href="#networkaddresses">Network Address Space</a></dd> + <dd><a href="#networkinglimitations">Local Networking Limitations</a></dd> + <dd><a href="#redirections">Using Network Redirections</a></dd> + <dd><a href="#dns">Configuring the Emulator's DNS Settings</a></dd> + <dd><a href="#proxy">Using the Emulator with a Proxy</a></dd> + <dd><a href="#connecting">Interconnecting Emulator Instances</a></dd> + <dd><a href="#calling">Sending a Voice Call or SMS to Another Emulator Instance</a></dd> +</dl> +</div> + +<div class="g-unit"> +<dl> +<dt><a href="#console">Using the Emulator Console</a></dt> + <dd><a href="#portredirection">Port Redirections</a></dd> + <dd><a href="#geo">Geo Location Provider Emulation</a></dd> + <dd><a href="#events">Sending Events</a></dd> + <dd><a href="#power">Emulating Device Power Characteristics</a></dd> + <dd><a href="#netstatus">Network Status</a></dd> + <dd><a href="#netdelay">Network Delay Emulation</a></dd> + <dd><a href="#netspeed">Network Speed Emulation</a></dd> + <dd><a href="#telephony">Telephony Emulation</a></dd> + <dd><a href="#sms">SMS Emulation</a></dd> + <dd><a href="#vm">VM State</a></dd> + <dd><a href="#window">Emulator Window</a></dd> + <dd><a href="#terminating">Terminating an Emulator Instance</a></dd> +<dt><a href="#skins">Using Emulator Skins</a></dt> +<dt><a href="#multipleinstances">Running Multiple Instances of the Emulator</a></dt> +<dt><a href="#apps">Installing Applications on the Emulator</a></dt> +<dt><a href="#sdcard">SD Card Emulation</a></dt> + <dd><a href="#creating">Creating a Disk Image</a></dd> + <dd><a href="#copying">Copying Files to a Disk Image</a></dd> + <dd><a href="#loading">Loading the Disk Image at Emulator Startup</a></dd> +<dt><a href="#troubleshooting">Troubleshooting Emulator Problems</a></dt> +<dt><a href="#limitations">Emulator Limitations</a></dt> +</dl> +</div> + +</div> + +<a name="overview"></a> + +<h2>Overview</h2> + +<p>The Android emulator is a QEMU-based application that provides a virtual ARM +mobile device on which you can run your Android applications. It provides a full +Android system stack, down to the kernel level, and includes a set of +preinstalled applications (such as the dialer) that you can access from your +applications. It provides a skinnable mobile device UI, customizable key +mappings, and a variety of commands and options for controlling the behaviors of +the emulated environment. </p> + +<p>The Android system image distributed in the SDK contains ARM machine code for +the Android Linux kernel, the native libraries, the Dalvik VM, and the various +Android package files (such as for for the Android framework and preinstalled +applications). The emulator's QEMU layers provide dynamic binary translation of +the ARM machine code to the OS and processor architecture of your development +machine. </p> + +<p>Adding custom capabilities to the underlying QEMU services, the Android +emulator supports many hardware features likely to be found on mobile devices, +including: </p> + +<ul> + <li>An ARMv5 CPU and the corresponding memory-management unit (MMU)</li> + <li>A 16-bit LCD display</li> + <li>One or more keyboards (a Qwerty-based keyboard and associated Dpad/Phone +buttons)</li> + <li>A sound chip with output and input capabilities</li> + <li>Flash memory partitions (emulated through disk image files on the +development machine)</li> + <li>A GSM modem, including a simulated SIM Card</li> +</li> +</ul> + +<p>The sections below provide more information about the emulator and how to use +it for developing Android applications.</p> + +<a name="starting"></a> + +<h2>Starting and Stopping the Emulator</h2> + +<p>During development and testing of your application, you install and run your +application in the Android emulator. You can launch the emulator as a standalone +application, from a command line, or you can use it as part of your Eclipse +development environment. In either case, you can specify the startup options +described in this document to control the emulator. + </p> + +<p>You can run your application on a single instance of the emulator or, +depending on your needs, you can start multiple emulator instances and run your +application in more than one emulated device. You can use the emulator's +built-in commands to simulate GSM phone calling or SMS between emulator +instances, and you can set up network redirections that allow emulators to send +data to one another. For more information, see <a href="#telephony">Telephony +Emulation</a>, <a href="#sms">SMS Emulation</a>, and +<a href="#emulatornetworking">Emulator Networking</a></p> + +<p>To start an instance of the emulator from the command line, change to the +<code>tools/</code> folder of the SDK and enter <code>emulator</code> or +<code>./emulator</code>. This initializes the Android system and you will see +the emulator window appear on your screen. </p> + +<p>If you are working in Eclipse, the ADT plugin for Eclipse installs your +application and starts the emulator automatically, when you run or debug +the application. You can specify emulator startup options in the Run/Debug +dialog, in the Target tab. When the emulator is running, you can issue +console commands as described later in this document.</p> + +<p>If you are not working in Eclipse, see <a href="#apps">Installing Applications +on the Emulator</a> for information about how to install your application.</p> + +<p>To stop an emulator instance, just close the emulator's window.</p> + +<a name="controlling"></a> + +<h2>Controlling the Emulator</h2> + +<p>You can use emulator <a href="#startup-options">startup options</a> and <a +href="#console">console commands</a> to control the behaviors and +characteristics of the emulated environment itself. +</p> + +<p>When the emulator is running, you can interact with the emulated mobile +device just as you would an actual mobile device, except that you use your mouse +pointer to "touch" the touchscreen and your keyboard keys to +"press" the simulated device keys. </p> + +<p>The table below summarizes the mappings between the emulator keys and and +the keys of your keyboard. </p> + +<table border="0" style="clear:left;"> + <tr> + <th>Emulated Device Key </th> + <th>Keyboard Key </th> + </tr> + <tr> + <td>Home</td> + <td>HOME</td> + </tr> + <tr> + <td>Menu (left softkey)</td> + <td>F2 <em>or</em> Page-up button</td> + </tr> + <tr> + <td>Star (right softkey)</td> + <td>Shift-F2 <em>or </em>Page Down</td> + </tr> + <tr> + <td>Back</td> + <td>ESC</td> + </tr> + <tr> + <td>Call/dial button </td> + <td>F3</td> + </tr> + <tr> + <td>Hangup/end call button</td> + <td>F4</td> + </tr> + <tr> + <td>Search</td> + <td>F5 </td> + </tr> + <tr> + <td>Power button</td> + <td>F7 </td> + </tr> + <tr> + <td>Audio volume up button</td> + <td>KEYPAD_PLUS, Ctrl-F5</td> + </tr> + + <tr> + <td>Audio volume down button</td> + <td>KEYPAD_MINUS, Ctrl-F6</td> + </tr> + <tr> + <td>Camera button</td> + <td>Ctrl-KEYPAD_5, Ctrl-F3</td> + </tr> + <tr> + <td>Switch to previous layout orientation (for example, portrait, landscape)</td> + <td>KEYPAD_7, F11</td> + </tr> + <tr> + <td>Switch to next layout orientation (for example, portrait, landscape)</td> + <td>KEYPAD_9, F12</td> + </tr> + <tr> + <td>Toggle cell networking on/off</td> + <td>F8</td> + </tr> + <tr> + <td>Toggle code profiling</td> + <td>F9 (only with <code>-trace</code> startup option)</td> + </tr> + <tr> + <td>Toggle fullscreen mode</td> + <td>Alt-Enter</td> + </tr> + <tr> + <td>Toggle trackball mode</td> + <td>Ctrl-T</td> + </tr> + <tr> + <td>DPad left/up/right/down</td> + <td>KEYPAD_4/8/6/2</td> + </tr> + <tr> + <td>DPad center click</td> + <td>KEYPAD_5</td> + </tr> + <tr> + <td>Onion alpha increase/decrease</td> + <td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td> + </tr> +</table> + +<p>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p> + +<a name="startup-options"></a> + +<h2> Emulator Startup Options</h2> +<p>The emulator supports a variety of options that you can specify +when launching the emulator, to control its appearance or behavior. +Here's the command-line usage for launching the emulator with options: </p> + +<pre>emulator [-<option> [<value>]] ... [-<qemu args>]</pre> + +<p>The table below summarizes the available options.</p> + +<table> +<tr> + <th width="10%" >Category</th> + <th width="20%" >Option</th> + <th width="30%" >Description</th> + <th width="40%" >Comments</th> +</tr> + +<tr> + <td rowspan="8">Help</td> + <td><code>-help</code></td> + <td>Print a list of all emulator options.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-all</code></td> + <td>Print help for all startup options.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-<option></code></td> + <td>Print help for a specific startup option.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-debug-tags</code></td> + <td>Print a list of all tags for <code>-debug <tags></code>.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-disk-images</code></td> + <td>Print help for using emulator disk images.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-environment</code></td> + <td>Print help for emulator environment variables.</td> + <td> </td> +</tr><tr> + <td><code>-help-keys</code></td> + <td>Print the current mapping of keys.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-keyset-file</code></td> + <td>Print help for defining a custom key mappings file.</td> + <td> </td> +</tr> + +<tr> + <td rowspan="10">Disk Images</td> + <td><code>-cache <filepath></code></td> + <td>Use <filepath> as the working cache partition image. </td> + <td>Optionally, you can specify a path relative to the current working directory. + If no cache file is specified, the emulator's default behavior is to use a temporary file instead. + <p>For more information on disk images, use <code>-help-disk-images</code>.</p> +</td></tr> +<tr> + <td><code>-data <filepath></code></td> + <td>Use <filepath> as the working user-data disk image. </td> + <td>Optionally, you can specify a path relative to the current working directory. + If <code>-data</code> is not used, the emulator looks for a file named "userdata-qemu.img" + in the directory specified in <datadir>. ~/.android (on Linux/Mac) or + C:\Documents and Settings\<user>\Local Settings\Application Data\Android (on Windows). + <p> If you use <code>-data <filepath></code> but the file does not exist, the emulator creates + a file at that location using the specified name. </p> + <p>See <a href="#multipleinstances">Running Multiple Emulator Instances</a> for information about how + to use <code>-data</code> to let multiple emulator instances preserve their user data across sessions.</p> + <p>For more information on disk images, use <code>-help-disk-images</code>.</p> +</td></tr> +<!-- +<tr> + <td><code>-datadir <dir></code></td> + <td>Search for the user-data disk image specified in <code>-data</code> in <dir></td> + <td><code><dir></code> is a path relative to the current working directory. + +<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image in the + directory ~/.android (on Linux/Mac) or C:\Documents and Settings\<user>\Local Settings\Application + Data\Android (on Windows). </p><p>For more information on disk images, use <code>-help-disk-images</code>.</p> +</td></tr> +--> +<tr> + <td><code>-image <filepath></code></td> + <td>Use <filepath> as the system image.</td> + <td>Optionally, you can specify a path relative to the current working directory. + Default is <system>/system.img.</td> +</tr> +<tr> + <td><code>-initdata <filepath></code></td> + <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents + of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td> + <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>. <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td> +</tr> +<tr> + <td><code>-kernel <filepath></code></td> + <td>Use <filepath> as the emulated kernel.</td> + <td>Optionally, you can specify a path relative to the current working directory. </td> +</tr> +<tr> + <td><code>-nocache</code></td> + <td>Start the emulator without a cache partition.</td> + <td>See also <code>-cache <file></code>.</td> +</tr> +<tr> + <td><code>-ramdisk <filepath></code></td> + <td>Use <filepath> as the ramdisk image.</td> + <td>Default value is <code><system>/ramdisk.img</code>. + <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p> +</td> +</tr> +<tr> + <td><code>-sdcard <filepath></code></td> + <td>Use <file> as the SD card image.</td> + <td>Default value is <code><system>/sdcard.img</code>. + <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p> +</td> +</tr> +<tr> + <td><code>-system <dirpath></code></td> + <td>Search for system, ramdisk and user data images in <dir>.</td> + <td><code><dir></code> is a directory path relative to the current + working directory.</td> +</tr> +<tr> + <td><code>-wipe-data</code></td> + <td>Reset the current user-data disk image (that is, the file specified by <code>-datadir</code> and + <code>-data</code>, or the default file). The emulator deletes all data from the user data image file, + then copies the contents of the file at <code>-inidata</code> data to the image file before starting. + </td> + <td>See also <code>-initdata</code>. + <p>For more information on disk images, use <code>-help-disk-images</code>.</p> +</td> +</tr> +<tr> + <td rowspan="9">Debug</td> + <td><code>-debug <tags></code></td> + <td>Enable/disable debug messages for the specified debug tags.</td> + <td><code><tags></code> is a space/comma/column-separated list of debug component names. + Use <code>-help-debug-tags</code> to print a list of debug component names that you can use. </td> +</tr> +<tr> + <td><code>-debug-<tag></code></td> + <td>Enable/disable debug messages for the specified debug tag.</td> + <td rowspan="2">Use <code>-help-debug-tags</code> to print a list of debug component names that you can use in <code><tag></code>. </td> +</tr> +<tr> + <td><code>-debug-no-<tag></code></td> + <td>Disable debug messages for the specified debug tag.</td> +</tr> +<tr> + <td><code>-logcat <logtags></code></td> + <td>Enable logcat output with given tags.</td> + <td>If the environment variable ANDROID_LOG_TAGS is defined and not + empty, its value will be used to enable logcat output by default.</td> +</tr> +<tr> + <td><code>-shell</code></td> + <td>Create a root shell console on the current terminal.</td> + <td>You can use this command even if the adb daemon in the emulated system is broken. + Pressing Ctrl-c from the shell stops the emulator instead of the shell.</td> +</tr> +<tr> + <td><code>-shell-serial <device></code></td> + <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character + device to use for communication with the shell.</td> + <td><device> must be a QEMU device type. See the documentation for 'serial -dev' at + <a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a> + for a list of device types.</p> + +<p>Here are some examples: </p> +<ul> + <li><code>-shell-serial stdio</code> is identical to <code>-shell</code></li> + <li><code>-shell-serial tcp::4444,server,nowait</code> lets you communicate with the shell over TCP port 4444</li> + <li><code>-shell-serial fdpair:3:6</code> lets a parent process communicate with the shell using fds 3 (in) and 6 (out)</li> + <li><code>-shell-serial fdpair:0:1</code> uses the normal stdin and stdout fds, except that QEMU won't tty-cook the data.</li> + </ul> +</td> +</tr> +<tr> + <td><code>-show-kernel <name></code></td> + <td>Display kernel messages.</td> + <td> </td> +</tr> +<tr> + <td><code>-trace <name></code></td> + <td>Enable code profiling (press F9 to start), written to a specified file.</td> + <td> </td> +</tr> +<tr> + <td><code>-verbose</code></td> + <td>Enable verbose output.</td> + <td>Equivalent to <code>-debug-init</code>. +<p>You can define the default verbose output options used by emulator instances in the Android environment variable +ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option: +<code>-debug-<tags>.</code> </p> +<p>Here's an example showing ANDROID_VERBOSE defined with the <code>-debug-init</code> and <code>-debug-modem</code> options: +<p><code>ANDROID_VERBOSE=init,modem</code></p> +<p>For more information about debug tags, use <code><-help-debug-tags></code>.</p> +</td> +</tr> +<tr> + <td rowspan="6">Media</td> + <td><code>-audio <backend></code></td> + <td>Use the specified audio backend.</td> + <td> </td> +</tr> +<tr> + <td><code>-audio-in <backend></code></td> + <td>Use the specified audio-input backend.</td> + <td> </td> +</tr> +<tr> + <td><code>-audio-out <backend></code></td> + <td>Use the specified audio-output backend.</td> + <td> </td> +</tr> +<!--<tr> + <td><code>-mic <device or file></code></td> + <td>Use device or WAV file for audio input.</td> + <td> </td> +</tr> +--> +<tr> + <td><code>-noaudio</code></td> + <td>Disable audio support in the current emulator instance.</td> + <td> </td> +</tr> +<tr> + <td><code>-radio <device></code></td> + <td>Redirect radio modem interface to a host character device.</td> + <td> </td></tr> +<tr> + <td><code>-useaudio</code></td> + <td>Enable audio support in the current emulator instance.</td> + <td>Enabled by default. </td> +</tr> + +<tr> + <td rowspan="7">Network</td> + <td><code>-dns-server <servers></code></td> + <td>Use the specified DNS server(s). </td> + <td>The value of <code><servers></code> must be a comma-separated list of up to 4 DNS server names or + IP addresses.</td> +</tr> +<tr> + <td><code>-http-proxy <proxy></code></td> + <td>Make all TCP connections through a specified HTTP/HTTPS proxy</td> + <td>The value of <code><proxy></code> can be one of the following:<br> + <code>http://<server>:<port></code><br> + <code>http://<username>:<password>@<server>:<port></code> + <p>The <code>http://</code> prefix can be omitted. If the <code>-http-proxy <proxy></code> command is not supplied, + the emulator looks up the <code>http_proxy</code> environment variable and automatically uses any value matching + the <code><proxy></code> format described above.</p></td> +</tr> +<tr> + <td><code>-netdelay <delay></code></td> + <td>Set network latency emulation to <delay>.</td> + <td>Default value is <code>none</code>. See the table in <a href="#netdelay">Network Delay Emulation</a> for + supported <code><delay></code> values. </td> +</tr> +<tr> + <td><code>-netfast</code></td> + <td>Shortcut for <code>-netspeed full -netdelay none</code></td> + <td> </td></tr> +<tr> + <td><code>-netspeed <speed></code></td> + <td>Set network speed emulation to <speed>.</td> + <td>Default value is <code>full</code>. See the table in <a href="#netspeed">Network Speed Emulation</a> for + supported <code><speed></code> values. </td> +</tr> +<tr> + <td><code>-port <port></code></td> + <td>Set the console port number for this emulator instance to <code><port></code>.</td> + <td>The console port number must be an even integer between 5554 and 5584, inclusive. <code><port></code>+1 + must also be free and will be reserved for ADB.</td> +</tr> +<tr> + <td><code>-report-console <socket></code></td> + <td>Report the assigned console port for this emulator instance to a remote third party + before starting the emulation. </td> + <td><code><socket></code> must use one of these formats: + +<p><code>tcp:<port>[,server][,max=<seconds>]</code></br> +<code>unix:<port>[,server][,max=<seconds>]</code></p> + +<p>Use <code>-help-report-console</code></p> to view more information about this topic. </td> +</tr> +<tr> + <td rowspan="8">System</td> + <td><code>-cpu-delay <delay></code></td> + <td>Slow down emulated CPU speed by <delay> </td> + <td>Supported values for <delay> are integers between 0 and 1000. + +<p>Note that the <delay> does not correlate to clock speed or other absolute metrics +— it simply represents an abstract, relative delay factor applied non-deterministically +in the emulator. Effective performance does not always +scale in direct relationship with <delay> values.</p> +</td> +</tr> +<tr> + <td><code>-gps <device></code></td> + <td>Redirect NMEA GPS to character device.</td> + <td>Use this command to emulate an NMEA-compatible GPS unit connected to + an external character device or socket. The format of <code><device></code> must be QEMU-specific + serial device specification. See the documentation for 'serial -dev' at + <a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. +</td> +</tr> +<tr> + <td><code>-nojni</code></td> + <td>Disable JNI checks in the Dalvik runtime.</td><td> </td></tr> +<tr> + <td><code>-qemu</code></td> + <td>Pass arguments to qemu.</td> + <td> </td></tr> +<tr> + <td><code>-qemu -h</code></td> + <td>Display qemu help.</td> + <td></td></tr> +<tr> + <td><code>-radio <device></code></td> + <td>Redirect radio mode to the specified character device.</td> + <td>The format of <code><device></code> must be QEMU-specific + serial device specification. See the documentation for 'serial -dev' at +<a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. +</td> +</tr> +<tr> + <td><code>-timezone <timezone></code></td> + <td>Set the timezone for the emulated device to <timezone>, instead of the host's timezone.</td> + <td><code><timezone></code> must be specified in zoneinfo format. For example: +<p>"America/Los_Angeles"<br> +"Europe/Paris"</p> +</td> +</tr> +<tr> + <td><code>-version</code></td> + <td>Display the emulator's version number.</td> + <td> </td> +</tr> +<tr> + <td rowspan="12">UI</td> + <td><code>-dpi-device <dpi></code></td> + <td>Scale the resolution of the emulator to match the screen size + of a physical device.</td> + <td>The default value is 165. See also <code>-scale</code>.</td> +</tr> +<tr> + <td><code>-no-boot-anim</code></td> + <td>Disable the boot animation during emulator startup.</td> + <td>Disabling the boot animation can speed the startup time for the emulator.</td> +</tr> +<tr> + <td><code>-no-window</code></td> + <td>Disable the emulator's graphical window display.</td> + <td> </td> +</tr> +<tr> + <td><code>-scale <scale></code></td> + <td>Scale the emulator window. </td> + <td><code><scale></code> is a number between 0.1 and 3 that represents the desired scaling factor. You can + also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" + tells the emulator to select the best window size.</td> +</tr> +<tr> + <td><code>-raw-keys</code></td> + <td>Disable Unicode keyboard reverse-mapping.</td> + <td> </td></tr> +<tr> + <td><code>-noskin</code></td> + <td>Don't use any emulator skin.</td> + <td> </td></tr> +<tr> + <td><code>-keyset <file></code></td> + <td>Use the specified keyset file instead of the default.</td> + <td>The keyset file defines the list of key bindings between the emulator and the host keyboard. + For more information, use <code>-help-keyset</code> to print information about this topic. +</td> +</tr> +<tr> + <td><code>-onion <image></code></td> + <td>Use overlay image over screen.</td> + <td>No support for JPEG. Only PNG is supported.</td></tr> +<tr> + <td><code>-onion-alpha <percent></code></td> + <td>Specify onion skin translucency value (as percent). + <td>Default is 50.</td> +</tr> +<tr> + <td><code>-onion-rotation <position></code></td> + <td>Specify onion skin rotation. + <td><code><position></code> must be one of the values 0, 1, 2, 3.</td> +</tr> +<tr> + <td><code>-skin <skinID></code></td> + <td>Start the emulator with the specified skin. </td> + <td>The SDK includes a <a href="#skins">choice of four skins</a>:<br /> + <li>HVGA-L (480x320, landscape)</li> + <li>HVGA-P (320x480, portrait) (default) </li> + <li>QVGA-L (320x240, landscape)</li> + <li>QVGA-P (240x320, portrait) </li> +</td> +</tr> +<tr> + <td><code>-skindir <dir></code></td> + <td>Search for emulator skins in <dir>. </td> + <td> </td></tr> +</table> + +<a name="diskimages"></a> + +<h2>Working with Emulator Disk Images</h2> + +<p>The emulator uses mountable disk images stored on your development machine to +simulate flash (or similar) partitions on an actual device. For example, it uses +disk image containing an emulator-specific kernel, the Android system, a +ramdisk image, and writeable images for user data and simulated SD card.</p> + +<p>To run properly, the emulator requires access to a specific set of disk image +files. The Android SDK includes default versions of the required images, stored +in predetermined locations in the SDK directory structure. At startup, the +emulator looks for and reads the image files, using their default names and +storage locations. </p> + +<p>To let you use alternate or custom versions of the image files, the emulator +provides startup options that override the default locations and filenames of +the image files. When you use the options, the emulator searches for the image +file under the image name or location that you specify; if it can not locate the +image, it reverts to using the default names and location.</p> + +<p>The emulator uses three types of image files: system image files, runtime +image files, and temporary image files. The sections below describe how to +override the location/name of each type of file. </p> + +<a name="systemimages"></a> +<h3>System Images</h3> + +<p>System images contain system data and default settings without which the +emulator can not run. The image files are read-only — the emulator reads +the images at startup and does not modify them during the session.</p> + +<p>All of the system image files are stored in a single directory. By default, +the system images are stored in the <code>lib/images</code>' under the +emulator's program location. </p> + +<p>The emulator provides the <code>-system <dir></code> startup option to +let you override the location under which the emulator looks for the system +images files. </p> + +<p>The emulator also provides startup options that let you override the names of +the system images, as described in the table below. When you use one of the +options, the emulator looks in the default directory, or in a custom location +(if you specified <code>-system <dir></code>). Note that, if you provide +alternate system image file, it must contain the same type of data as the +default. For example, your override of the system.img file must point to a disk +image containing an Android system. </p> + + +<table> +<tr> + <th width="10%" >Name</th> + <th width="30%" >Description</th> + <th width="40%" >Comments</th> +</tr> + +<tr> + <td><code>kernel-qemu.img</code></td> + <td>The emulator-specific Linux kernel image</td> + <td>Override using <code>-kernel <file></code></td> +</tr> + +<tr> + <td><code>ramdisk.img</code></td> + <td>The ramdisk image used to boot the system.</td> + <td>Override using <code>-ramdisk <file></code></td> +</tr> + +<tr> + <td><code>system.img</code></td> + <td>The <em>initial</em> Android system image.</td> + <td>Override using <code>-image <file></code></td> +</tr> + +<tr> + <td><code>userdata.img</code></td> + <td>The <em>initial</em> user-data disk image</td> + <td>Override using <code>-initdata <file></code>. Also see +<code>-data <file></code>, below.</td> +</tr> + +</table> + +<a name="runtimeimages"></a> +<h3>Runtime Images: User Data and SD Card</h3> + +<p>At runtime, the emulator reads and writes data on two disk images: a +user-data image and (optionally) an SD card image. This emulates the user-data +partition and removable storage media on actual device. </p> + +<p>The emulator provides a default user-data disk image. At startup, the emulator +creates the default image as a copy of the system user-data image (user-data.img), +described above. The emulator stores the default image in this location on +on your development machine: </p> + +<ul> + <li>Linux and OS X: <code>~/.android</code></li> + <li>Windows: <code>C:\Documents and Settings\<user>\Local Settings\Application Data\Android</code></li> +</ul> + +<!-- +<p>The emulator provides a startup option, <code>-datadir <dir></code>, +that you can use to override the location under which the emulator looks for the runtime +image files. </p> +--> + +<p>The emulator provides startup options to let you override the actual names and storage +locations of the runtime images to load, as described in the table below. When you use one +of these options, the emulator looks for the specified file(s) in the current working directory, +in the default directory, or in a custom location (if you specified a path with the filename. </p> + +<table> +<tr> + <th width="10%" >Name</th> + <th width="30%" >Description</th> + <th width="40%" >Comments</th> +</tr> +<tr> + <td><code>userdata-qemu.img</code></td> + <td>An image to which the emulator writes runtime user-data for a unique user.</td> + <td>Override using <code>-data <;filepath></code>, where <code><filepath></code> is the +path the image, relative to the current working directory. If you supply a filename only, +the emulator looks for the file in the current working directory. If the file at <code><filepath></code> does +not exist, the emulator creates an image from the default userdata.img, stores it under the name you +specified, and persists user data to it at shutdown. </td> +</tr> + +<tr> + <td><code>sdcard.img</code></td> + <td>An image representing an SD card inserted into the emulated device.</td> + <td>Override using <code>-sdcard <filepath></code>, where <code><filepath></code> is the +path the image, relative to the current working directory. If you supply a filename only, +the emulator looks for the file in the current working directory. </td> +</tr> + +</table> + +<h4>User-Data Image</h4> + +<p>Each emulator instance uses a writeable user-data image to store user- and +session-specific data. For example, it uses the image to store a unique user's +installed application data, settings, databases, and files. </p> + +<p>At startup, the emulator attempts to load a user-data image stored during +a previous session. It looks for the file in the current working directory, +at the default location, as described above, and at the custom location/name +that you specified at startup. </p> + +<ul> +<li>If it finds a user-data image, it mounts the image and makes it available to the system +for reading/writing of user data. </li> +<li>If it does not find one, it creates an image by copying the system user-data +image (userdata.img), described above. At device power-off, the system persists +the user data to the image, so that it will be available in the next session. +Note that the emulator stores the new disk image at the location/name that you +specify in <code>-data</code> startup option.</li> +</ul> + +<p>If you are planning to run multiple emulator instances concurrently, note +that only the first emulator instance can persist user-data, if no explicit +user-data image file is specified in the startup command. When running multiple +emulator instances, you must specify a name for the image file to use (or +create), by using the <code>-data <name></code> option with a unique +<code><name></code> value. For more information, see +<a href="#multipleinstances">Running Multiple Emulator Instances</a>.</p> + +<h4>SD Card</h4> + +<P>Optionally, you can create a writeable disk image that the emulator can use +to simulate removeable storage in an actual device. For information about how to create an +emulated SD card and load it in the emulator, see <a href="#sdcard">SD Card Emulation</a></p> + +<a name="temporaryimages"></a> +<h3>Temporary Images</h3> + +<p>The emulator creates two writeable images at startup that it deletes at +device power-off. The images are: </p> + +<ul> + <li>A writable copy of the Android system image</li> + <li>The <code>/cache</code> partition image</li> +</ul> + +<p>The emulator does not permit renaming the temporary system image or +persisting it at device power-off. </p> + +<p>The <code>/cache</code> partition image is initially empty, and is used by +the browser to cache downloaded web pages and images. The emulator provides an +<code>-cache <file></code>, which specifies the name of the file at which +to persist the <code>/cache</code> image at device power-off. If <code><file> +</code> does not exist, the emulator creates it as an empty file. </p> + +<p>You can also disable the use of the cache partition by specifying the +<code>-nocache</code> option at startup. </p> + + +<a name="emulatornetworking"></a> +<h2>Emulator Networking</h2> + +<p>The emulator provides versatile networking capabilities that you can use to +set up complex modeling and testing environments for your application. The +sections below introduce the emulator's network architecture and capabilities. +</p> + +<a name="networkaddresses"></a> +<h3>Network Address Space</h3> + +<p>Each instance of the emulator runs behind a virtual router/firewall service +that isolates it from your development machine's network interfaces and settings +and from the internet. An emulated device can not see your development machine +or other emulator instances on the network. Instead, it sees only that it is +connected through Ethernet to a router/firewall.</p> + +<p>The virtual router for each instance manages the 10.0.2/24 network address +space — all addresses managed by the router are in the form of +10.0.2.<xx>, where <xx> is a number. Addresses within this space are +pre-allocated by the emulator/router as follows:</p> + +<table> + <tr> + <th>Network Address</th> + <th>Description</th> + </tr> + <tr> + <td>10.0.2.1</td> + <td>Router/gateway address </td> + </tr> + <tr> + <td>10.0.2.2</td> + <td>Special alias to your host loopback interface (i.e., 127.0.0.1 on your +development machine)</td> + </tr> + <tr> + <td>10.0.2.3</td> + <td>First DNS server</td> + </tr> + <tr> + <td>10.0.2.4 / 10.0.2.5 / 10.0.2.6</td> + <td>Optional second, third and fourth DNS server (if any) </td> + </tr> + <tr> + <td>10.0.2.15</td> + <td>The emulated device's own network/ethernet interface</td> + </tr> + <tr> + <td>127.0.0.1</td> + <td>The emulated device's own loopback interface </td> + </tr> +</table> + +<p>Note that the same address assignments are used by all running emulator +instances. That means that if you have two instances running concurrently on +your machine, each will have its own router and, behind that, each will have an +IP address of 10.0.2.15. The instances are isolated by a router and can +<em>not</em> see each other on the same network. For information about how to +let emulator instances communicate over TCP/UDP, see <a +href="#connecting">Connecting Emulator Instances</a>.</p> + +<p>Also note that the address 127.0.0.1 on your development machine corresponds +to the emulator's own loopback interface. If you want to access services running +on your development machine's loopback interface (a.k.a. 127.0.0.1 on your +machine), you should use the special address 10.0.2.2 instead.</p> + +<p>Finally, note that each emulated device's pre-allocated addresses are +specific to the Android emulator and will probably be very different on real +devices (which are also very likely to be NAT-ed, i.e., behind a +router/firewall)</p> + +<a name="networkinglimitations"></a> +<h3>Local Networking Limitations</h3> + +<p>Each emulator instance runs behind a virtual router, but unlike an actual +device connected to a physical router, the emulated device doesn't have access +to a physical network. Instead it runs as part of a normal application on your +development machine. This means that it is subject to the same networking +limitations as other applications on your machine:</p> + +<ul> + <li>Communication with the emulated device may be blocked by a firewall +program running on your machine.</li> + <li>Communication with the emulated device may be blocked by another +(physical) firewall/router to which your machine is connected.</li> +</ul> + +<p>The emulator's virtual router should be able to handle all outbound TCP and +UDP connections/messages on behalf of the emulated device, provided your +development machine's network environment allows it to do so. There are no +built-in limitations on port numbers or ranges except the one imposed by your +host operating system and network.</p> + +<p>Depending on the environment, the emulator may not be able to support other +protocols (such as ICMP, used for "ping") might not be supported. Currently, the +emulator does not support IGMP or multicast. </p> + +<a name="redirections"></a> +<h3>Using Network Redirections</h3> + +<p>To communicate with an emulator instance behind its virtual router, you need +to set up network redirections on the virtual router. Clients can then connect +to a specified guest port on the router, while the router directs traffic +to/from that port to the emulated device's host port. </p> + +<p>To set up the network redirections, you create a mapping of host and guest +ports/addresses on the the emulator instance. There are two ways to set up +network redirections: using emulator console commands and using the ADB tool, as +described below. </p> + +<a name="consoleredir"></a> +<h4>Setting up Redirections through the Emulator Console</h4> + +<p>Each emulator instance provides a control console the you can connect to, to +issue commands that are specific to that instance. You can use the +<code>redir</code> console command to set up redirections as needed for an +emulator instance. </p> + +<p>First, determine the console port number for the target emulator instance. +For example, the console port number for the first emulator instance launched is +5554. Next, connect to the console of the target emulator instance, specifying +its console port number, as follows: </p> + +<pre><code>telnet localhost 5554</code></pre> + +<p>Once connected, use the <code>redir</code> command to work with redirections. +To add a redirection, use:</a>. </p> + +<pre><code>add <protocol>:<host-port>:<guest-port></code> +</pre> + +<p>where <code><protocol></code> is either <code>tcp</code> or <code>udp</code>, +and <code><host-port></code> and <code><guest-port></code> sets the +mapping between your own machine and the emulated system, respectively. </p> + +<p>For example, the following command sets up a redirection that will handle all +incoming TCP connections to your host (development) machine on 127.0.0.1:5000 +and will pass them through to the emulated system's 10.0.2.15:6000.:</p> + +<pre>redir add tcp:5000:6000</pre> + +<p>To delete a redirection, you can use the <code>redir del</code> command. To +list all redirections for a specific instance, you can use <code>redir +list</code>. For more information about these and other console commands, see +<a href="#console">Using the Emulator Console</a>. </p> + +<p>Note that port numbers are restricted by your local environment. this typically +means that you cannot use host port numbers under 1024 without special +administrator privileges. Also, you won't be able to set up a redirection for a +host port that is already in use by another process on your machine. In that +case, <code>redir</code> generates an error message to that effect. </p> + +<a name="adbredir"></a> +<h4>Setting Up Redirections through ADB</h4> + +<p>The Android Debug Bridge (ADB) tool provides port forwarding, an alternate +way for you to set up network redirections. For more information, see <a +href="{@docRoot}reference/adb.html#forwardports">Forwarding Ports</a> in the ADB +documentation.</p> + +<p>Note that ADB does not currently offer any way to remove a redirection, +except by killing the ADB server.</p> + +<a name="dns"></a> +<h3>Configuring the Emulator's DNS Settings</h3> + +<p>At startup, the emulator reads the list of DNS servers that your system is +currently using. It then stores the IP addresses of up to four servers on this +list and sets up aliases to them on the emulated addresses 10.0.2.3, 10.0.2.4, +10.0.2.5 and 10.0.2.6 as needed. </p> + +<p>On Linux and OS X, the emulator obtains the DNS server addresses by parsing +the file <code>/etc/resolv.conf</code>. On Windows, the emulator obtains the +addresses by calling the <code>GetNetworkParams()</code> API. Note that this +usually means that the emulator ignores the content of your "hosts" file +(<code>/etc/hosts</code> on Linux/OS X, <code>%WINDOWS%/system32/HOSTS</code> + on Windows).</P> + +<p>When starting the emulator at the command line, you can also use the +<code>-dns-server <serverList></code> option to manually specify the +addresses of DNS servers to use, where <serverList> is a comma-separated +list of server names or IP addresses. You might find this option useful if you +encounter DNS resolution problems in the emulated network (for example, an +"Unknown Host error" message that appears when using the web browser).</p> + +<a name="proxy"></a> +<h3>Using the Emulator with a Proxy</h3> + +<p>If your emulator must access the Internet through a proxy server, you can use +the <code>-http-proxy <proxy></code> option when starting the emulator, to +set up the appropriate redirection. In this case, you specify proxy information +in <code><proxy></code> in one of these formats:</p> + +<pre>http://<machineName>:<port></pre> + +<p>or</p> + +<pre>http://<username>:<password>@<machineName>:<port></pre> + +<p>The <code>-http-proxy</code> option forces the emulator to use the specified +HTTP/HTTPS proxy for all outgoing TCP connections. Redirection for UDP is not +currently supported.</p> + +<p>Alternatively, you can define the environment variable +<code>http_proxy</code> to the value you want to use for +<code><proxy></code>. In this case, you do not need to specify a value for +<code><proxy></code> in the <code>-http-proxy</code> command — the +emulator checks the value of the <code>http_proxy</code> environment variable at +startup and uses its value automatically, if defined. </p> + +<p>You can use the <code>-verbose-proxy</code> option to diagnose proxy +connection problems.</p> + +<a name="connecting"></a> +<h3>Interconnecting Emulator Instances</h3> + +<p>To allow one emulator instance to communicate with another, you must set up +the necessary network redirections as illustrated below. </p> + +<p>Assume that your environment is</p> + +<ul> + <li>A is you development machine</li> + <li>B is your first emulator instance, running on A</li> + <li>C is your second emulator instance, running on A too</li> +</ul> + +<p>and you want to run a server on B, to which C will connect, here is how you +could set it up: </p> + +<ol> + <li>Set up the server on B, listening to +<code>10.0.2.15:<serverPort></code></li> + <li>On B's console, set up a redirection from +<code>A:localhost:<localPort></code> to <code> +B:10.0.2.15:<serverPort></code></li> + <li>On C, have the client connect to 10.0.2.2:<localPort></code></li> +</ol> + +<p>For example, if you wanted to run an HTTP server, you can select +<code><serverPort></code> as 80 and <code><localPort></code> as +8080:</p> + +<ul> + <li>B listens on 10.0.2.15:80</li> + <li>On B's console, issue <code>redir add tcp:8080:80</code></li> + <li>C connects to 10.0.2.2:8080</li> +</ul> + +<a name="calling"></a> +<h3>Sending a Voice Call or SMS to Another Emulator Instance</h3> + +<p>The emulator automatically forwards simulated voice calls and SMS messages from one instance to another. To send a voice call or SMS, you use the dialer application and SMS application (if available) installed on one emulator </p> + +<p>To initiate a simulated voice call to another emulator instance:</p> +<ol> +<li>Launch the dialer application on the originating emulator instance.</li> +<li>As the number to dial, enter the console port number of the instance you'd like to call. You can determine + the console port number of the target instance by checking its window title, where the + console port number is reported as "Android Emulator (<port>). </li> +<li>Press "Dial". A new inbound call appears in the target emulator instance. </li> +</ol> + +<p>To send an SMS message to another emulator instance, launch the SMS application (if available). Specify the console port number of the target emulator instance as as the SMS address, enter the message text, and send the message. The message is delivered to the target emulator instance. </p> + +<p>You can also connect to an emulator instance's console to simulate an incoming voice call or SMS. For more information, see <a href="#telephony">Telephony Emulation</a> and <a href="#sms">SMS Emulation</a>. + +<a name="console"></a> + +<h2>Using the Emulator Console</h2> + +<p>Each running emulator instance includes a console facility that lets you dynamically query and control the simulated device environment. For example, you can use the console to dynamically manage port redirections and network characteristics and simulate telephony events. To access the console and enter commands, you use telnet to connect to the console's port number. </p> +<p>To connect to the console of any running emulator instance at any time, use this command: </p> + +<pre>telnet localhost <console-port></pre> + +<p>An emulator instance occupies a pair of adjacent ports: a console port and an adb port. The port numbers differ by 1, with the adb port having the higher port number. The console of the first emulator instance running on a given machine uses console port 5554 and adb port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557, 5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility. </p> + +<p>To connect to the emulator console, you must specify a valid console port. If multiple emulator instances are running, you need to determine the console port of the emulator instance you want to connect to. You can find the instance's console port listed in the title of the instance window. For example, here's the window title for an instance whose console port is 5554:</p> + +<p><code>Android Emulator (5554)</code></p> + +<p>Alternatively, you can use the <code>adb devices</code> command, which prints a list of running emulator instances and their console port numbers. For more information, see <a href="{@docRoot}reference/adb.html#devicestatus">Querying for Emulator/Device Instances</a> in the adb documentation.</p> + +<p class="note">Note: The emulator listens for connections on ports 5554-5587 and accepts connections only from localhost.</p> + +<p>Once you are connected to the console, you can then enter <code>help [command]</code> to see a list of console commands and learn about specific commands. </p> + +<p>To exit the console session, use <code>quit</code> or <code>exit</code>.</p> + +<p>The sections below describe the major functional areas of the console.</p> + +<a name="portredirection"></a> + +<h3>Port Redirection</h3> +<p>You can use the console to add and remove port redirections while the emulator is running. After connecting to the console, you can manage port redirections in this way:</p> +<pre>redir <list|add|del> </pre> + +<p>The <code>redir</code> command supports the subcommands listed in the table below. </p> + +<table> +<tr> + <th width="25%" >Subcommand + <th width="30%" >Description</th> + <th width="35%">Comments</th> +</tr> + + <tr> + <td><code>list</code></td> + <td>List the current port redirections.</td> + <td> </td> + </tr> + + +<tr> + <td><code>add <protocol>:<host-port>:<guest-port></code></td> + <td>Add a new port redirection.</td> +<td><li><protocol> must be either "tcp" or "udp"</li> +<li><host-port> is the port number to open on the host</li> +<li><guest-port> is the port number to route data to on the emulator/device</li></td> +</tr> +<tr> + <td><code>del <protocol>:<host-port></code></td> + <td>Delete a port redirection.</td> +<td>See above for meanings of <protocol> and <host-port>.</td> +</tr> +</table> + +<a name="geo"></a> +<h3>Geo Location Provider Emulation</h3> + +<p>The console provides commands to let you set the geo position used by an emulator emulated device. You can use the <code>geo</code> command to send a simple GPS fix to the emulator, without needing to use NMEA 1083 formatting. The usage for the command is: </p> + +<pre>geo <fix|nmea></pre> + +<p>The <code>geo</code> command supports the subcommands listed in the table below. </p> + +<table> +<tr> + <th width="25%" >Subcommand + <th width="30%" >Description</th> + <th width="35%">Comments</th> +</tr> + + <tr> + <td><code>fix <longitude> <latitude> [<altitude>]</code></td> + <td>Send a simple GPS fix to the emulator instance.</td> + <td>Specify longitude and latitude in decimal degrees. Specify altitude in meters.</td> + </tr> +<tr> + <td><code>nmea <sentence></code></td> + <td>Send an NMEA 0183 sentence to the emulated device, as if it were sent from an emulated GPS modem.</td> +<td><code><sentence></code> must begin with '$GP'. Only '$GPGGA' and '$GPRCM' sentences are currently supported.</td> +</tr> +</table> + +<p>You can issue the <code>geo</code> command to fix the GPS location as soon as an emulator instance is running. The emulator creates a mock location provider that sends the location to GPS-aware applications as soon as they start and register location listeners. Any application can query the location manager to obtain the current GPS fix for the emulated device by calling: + +<pre>LocationManager.getLastKnownLocation("gps")</pre> + +<p>For more information about the Location Manager, see {@link android.location.LocationManager} and its methods.</p> + +<a name="events"></a> +<h3>Hardware Events Emulation</h3> + +<p>You can use the <code>event</code> command to send various events to the emulator.The usage for the command is: </p> + +<pre>event <send|types|codes|text></pre> + +<p>The <code>event</code> command supports the subcommands listed in the table below. </p> + +<table> +<tr> + <th width="25 %" >Subcommand + <th width="30%" >Description</th> + <th width="35%">Comments</th> +</tr> + + <tr> + <td><code>send <type>:<code>:<value> [...]</code></td> + <td>Send one or more events to the Android kernel. </td> + <td>You can use text names or integers for <code><type></code> and <code><value></code>.</td> + </tr> +<tr> + <td><code>types</code></td> + <td>List all <code><type></code> string aliases supported by the <code>event</code> subcommands.</td> +<td> </td> +</tr> +<tr> + <td><code>codes <type></code></td> + <td>List all <code><codes></code> string aliases supported by the <code>event</code> + subcommands for the specified <code><type></code>.</td> +<td> </td> +</tr> +<tr> + <td><code>event text <message></code></td> + <td>Simulate keypresses to send the specified string of characters as a message,</td> +<td>The message must be a UTF-8 string. Unicode posts will be reverse-mapped according to the current device keyboard. Unsupported characters will be discarded silently.</td> +</tr> +</table> + +<a name="power"></a> +<h3>Device Power Characteristics</h3> + +<p>You can use the <code>power</code> command to control the simulated power state of the emulator instance.The usage for the command is: </p> + +<pre>power <display|ac|status|present|health|capactiy></pre> + +<p>The <code>event</code> command supports the subcommands listed in the table below. </p> + +<table> +<tr> + <th width="25 %" >Subcommand + <th width="30%" >Description</th> + <th width="35%">Comments</th> +</tr> + + <tr> + <td><code>display</code></td> + <td>Display battery and charger state.</td> + <td> </td> + </tr> +<tr> + <td><code>ac <on|off></code></td> + <td>Set AC charging state to on or off. </td> +<td> </td> +</tr> +<tr> + <td><code>status <unknown|charging|discharging|not-charging|full></code></td> + <td>Change battery status as specified.</td> +<td> </td> +</tr> + +<tr> + <td><code>present <true|false></code></td> + <td>Set battery presence state.</td> +<td> </td> +</tr> +<tr> + <td><code>health <unknown|good|overheat|dead|overvoltage|failure></code></td> + <td>Set battery health state.</td> +<td> </td> +</tr> +<tr> + <td><code>power health <percent></code></td> + <td>Set remaining battery capacity state (0-100).</td> +<td> </td> +</tr> +</table> + +<a name="netstatus"></a> +<h3>Network Status</h3> + +<p>You can use the console to check the network status and current delay and speed characteristics. To do so, connect to the console and use the <code>netstatus</code> command. Here's an example of the command and its output. </p> + +<pre>network status +</pre> + +<a name="netdelay"></a> +<h3>Network Delay Emulation</h3> + +<p>The emulator lets you simulate various network latency levels, so that you can test your applicaton in an environment more typical of the actual conditions in which it will run. You can set a latency level or range at emulator startup or you can use the console to change the latency dynamically, while the application is running in the emulator. </p> +<p>To set latency at emulator startup, use the <code>-netdelay</code> emulator option with a supported <code><delay></code> value, as listed in the table below. Here are some examples:</p> +<pre>emulator -netdelay gprs +emulator -netdelay 40 100</pre> + +<p>To make dynamic changes to network delay while the emulator is running, connect to the console and use the <code>netdelay</code> command with a supported <code><delay></code> value from the table below. </p> + +<pre>network delay gprs</pre> + +<p>The format of network <delay> is one of the following (numbers are milliseconds):</p> + +<table style="clear:right;width:100%;"> +<tr> + <th width="30%" >Value</td> + <th width="35%" >Description</th><th width="35%">Comments</th></tr> + + <tr><td><code>gprs</code></td><td>GPRS</td> + <td>(min 150, max 550)</td> + </tr> + +<tr><td><code>edge</code></td><td>EDGE/EGPRS</td> +<td>(min 80, max 400)</td> +</tr> +<tr><td><code>umts</code></td><td>UMTS/3G</td> +<td>(min 35, max 200)</td> +</tr> +<tr><td><code>none</code></td><td>No latency</td><td>(min 0, max 0)</td></tr> +<tr><td><code><num></code></td> +<td>Emulate an exact latency (milliseconds).</td> +<td> </td></tr> +<tr><td><code><min>:<max></code></td> +<td>Emulate an specified latency range (min, max milliseconds).</td> +<td> </td></tr> +</table> + +<a name="netspeed"></a> +<h3>Network Speed Emulation</h3> + +<p>The emulator also lets you simulate various network transfer rates. You can set a transfer rate or range at emulator startup or you can use the console to change the rate dynamically, while the application is running in the emulator. </p> +<p>To set the network speed at emulator startup, use the <code>-netspeed</code> emulator option with a supported <code><speed></code> value, as listed in the table below. Here are some examples:</p> +<pre>emulator -netspeed gsm +emulator -netspeed 14.4 80</pre> + +<p>To make dynamic changes to network speed while the emulator is running, connect to the console and use the <code>netspeed</code> command with a supported <code><speed></code> value from the table below. </p> + +<pre>network speed 14.4 80</pre> + +<p>The format of network <code><speed></code> is one of the following (numbers are +kilobits/sec):</p> +<table style="clear:right;width:100%;"> +<tbody> +<tr> + <th width="30%">Value</td> + <th width="35%">Description</th><th width="35%">Comments</th></tr> + + <tr> + <td><code>gsm</code></td> + <td>GSM/CSD</td><td>(Up: 14.4, down: 14.4)</td></tr> +<tr> + <td><code>hscsd</code></td> + <td>HSCSD</td><td>(Up: 14.4, down: 43.2)</td></tr> +<tr> + <td><code>gprs</code></td> + <td>GPRS</td><td>(Up: 40.0, down: 80.0)</td></tr> +<tr> + <td><code>edge</code></td> + <td>EDGE/EGPRS</td> + <td>(Up: 118.4, down: 236.8)</td> +</tr> +<tr> + <td><code>umts</code></td> + <td>UMTS/3G</td><td>(Up: 128.0, down: 1920.0)</td></tr> +<tr> + <td><code>hsdpa</code></td> + <td>HSDPA</td><td>(Up: 348.0, down: 14400.0)</td></tr> +<tr> + <td><code>full</code></td> + <td>no limit</td><td>(Up: 0.0, down: 0.0)</td></tr> +<tr> + <td><code><num></code></td> + <td>Set an exact rate used for both upload and download.</td><td></td></tr> +<tr> + <td><code><up>:<down></code></td> + <td>Set exact rates for upload and download separately.</td><td></td></tr> +</table> + + +<a name="telephony"></a> + +<h3>Telephony Emulation</h3> + +<p>The Android emulator includes its own GSM emulated modem that lets you simulate telephony functions in the emulator. For example, you can simulate inbound phone calls and establish/terminate data connections. The Android system handles simulated calls exactly as it would actual calls. The emulator does not support call audio in this release. </p> +<p>You can use the console to access the emulator's telephony functions. After connecting to the console, you can use</p> +<pre>gsm <call|accept|busy|cancel|data|hold|list|voice|status> </pre> +<p>to invoke telephony functions. </p> +<p>The <code>gsm</code> command supports the subcommands listed in the table below. </p> +<table> + <tr> + <th >Subcommand </th> + <th width="25%">Description</th> + <th>Comments</th> + </tr> + <tr> + <td><code>call <phonenumber></code></td> + <td>Simulate an inbound phone call from <phonenumber>.</td> + <td>See also <a href="#calling">Sending a Voice Call or SMS to another Emulator Instance</a>.</td> + </tr> + <tr> + <td><code>accept <phonenumber></code></td> + <td>Accept an inbound call from <phonenumber> and change the call's state "active".</td> + <td>You can change a call's state to "active" only if its current state is "waiting" or "held".</td> + </tr> + <tr> + <td><code>busy <phonenumber></code></td> + <td>Close an outbound call to <phonenumber> and change the call's state to "busy".</td> + <td>You can change a call's state to "busy" only if its current state is "waiting".</td> + </tr> + <tr> + <td><code>cancel <phonenumber></code></td> + <td>Terminate an inbound or outbound phone call to/from <phonenumber>.</td> + <td> </td> + </tr> + <tr> + <td><code>data <state></code></td> + <td>Change the state of the GPRS data connection to <state>.</td> + <td>Supported <state> values are:<br /> + <li><code>unregistered</code> -- No network available</li> + <li><code>home</code> -- On local network, non-roaming</li> + <li><code>roaming</code> -- On roaming network</li> + <li><code>searching</code> -- Searching networks</li> + <li><code>denied</code> -- Emergency calls only</li> + <li><code>off</code> -- Same as 'unregistered'</li> + <li><code>on</code> -- same as 'home'</li> </td> + </tr> + <tr> + <td><code>hold</code></td> + <td>Change the state of a call to "held". </td> + <td>You can change a call's state to "held" only if its current state is "active" or "waiting". </td> + </tr> + <tr> + <td><code>list</code></td> + <td>List all inbound and outbound calls and their states.</td> + <td> </td> + </tr> + <tr> + <td><code>voice <state></code></td> + <td>Change the state of the GPRS voice connection to <state>.</td> + <td>Supported <state> values are:<br /> + <li><code>unregistered</code> -- No network available</li> + <li><code>home</code> -- On local network, non-roaming</li> + <li><code>roaming</code> -- On roaming network</li> + <li><code>searching</code> -- Searching networks</li> + <li><code>denied</code> -- Emergency calls only</li> + <li><code>off</code> -- Same as 'unregistered'</li> + <li><code>on</code> -- Same as 'home'</li></td> + </tr> + + <tr> + <td><code>status</code></td> + <td>Report the current GSM voice/data state.</td> + <td>Values are those described for the <code>voice</code> and <code>data</code> commands.</td> + </tr> +</table> + +<a name="sms"></a> + +<h3>SMS Emulation</h3> + +<p>The Android emulator console lets you generate an SMS message and direct it to an emulator instance. Once you connect to an emulator instance, you can generate an emulated incoming SMS using this command:</p> + +<pre>sms send <senderPhoneNumber> <textmessage></pre> + +<p>where <code><senderPhoneNumber></code> contains an arbitrary numeric string. </p> + +<p>The console forwards the SMS message to the Android framework, which passes it through to an application that handles that message type. </p> + +<a name="vm"></a> + +<h3>VM State</h3> + +<p>You can use the <code>vm</code> command to control the VM on an emulator instance.The usage for the command is: </p> + +<pre>vm <start|stop|status></pre> + +<p>The <code>vm</code> command supports the subcommands listed in the table below. </p> + +<table> +<tr> + <th width="25%" >Subcommand + <th width="30%" >Description</th> + <th width="35%">Comments</th> +</tr> +<tr> + <td><code>start</code></td> + <td>Start the VM on the instance. </td> + <td> </td> +</tr> +<tr> + <td><code>stop</code></td> + <td>Stop the VM on the instance. </td> + <td> </td> +</tr> +<tr> + <td><code>start</code></td> + <td>Display the current status of the VM (running or stopped). </td> + <td> </td> +</tr> +</table> + + +<a name="window"></a> + +<h3>Emulator Window</h3> + +<p>You can use the <code>window</code> command to manage the emulator window. The usage for the command is: </p> + +<pre>window <scale></pre> + +<p>The <code>vm</code> command supports the subcommands listed in the table below. </p> + +<table> +<tr> + <th width="25%" >Subcommand + <th width="30%" >Description</th> + <th width="35%">Comments</th> +</tr> +<tr> + <td><code>scale <scale></code></td> + <td>Scale the emulator window.</td> + <td><scale> must be a number between 0.1 and 3 that describes the desired scaling factor. You can + also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" + tells the emulator to select the best window size.</td> +</tr> +</table> + + +<a name="terminating"></a> + +<h3>Terminating an Emulator Instance</h3> + +<p>You can terminate an emulator instance through the console, using the <code>kill</code> command.</p> + + +<a name="skins"></a> + +<h2>Using Emulator Skins</h2> + +<p>You can run the emulator with any of four default skins, as described in the table below. To specify a skin, use <code>-skin <skinID></code> when starting the emulator. </p> + +<p>For example: </p> + +<pre>emulator -skin HVGA-L</pre> + +<p>Note that you must enter the <code><skinID></code> in uppercase letters (if your development computer is case-sensitive).</p> + +<table border="0" style="clear:left;padding:2em;"> + <tr> + <th width="20%">skinID</th> + <th >Description</th> + <th >Skin</th> + </tr> + <tr> + <td><code>HVGA-L</code></td> + <td>480x320, landscape</td> + <td><img src="{@docRoot}images/e-mini-hvga-l.png" width="219" height="113"></td> + </tr> + <tr> + <td><code>HVGA-P</code></td> + <td>320x480, portrait (default)</td> + <td><img src="{@docRoot}images/e-mini-hvga-p.png" width="113" height="219"></td> + </tr> + <tr> + <td><code>QVGA-L</code></td> + <td>320x240, landscape</td> + <td><img src="{@docRoot}images/e-mini-qvga-l.png" width="119" height="197"></td> + </tr> + <tr> + <td><code>QVGA-P</code></td> + <td>240x320, portrait</td> + <td><img src="{@docRoot}images/e-mini-qvga-p.png" width="95" height="173"></td> + </tr> +</table> + +<a name="multipleinstances"></a> + +<h2>Running Multiple Emulator Instances</h2> + +<p>You can run multiple instances of the emulator concurrently, if necessary. Each emulator instance can use a separate user-data image file and a different console port. This lets you manage each instance in isolation. </p> + +<p>However, if you will run multiple emulator instances, note that there are limitations on the capability of each instance to maintain its persistent user data — user settings and installed applications — across sessions. Specifically:</p> + +<ul> + <li>By default, only the first-launched emulator instance can preserve user data across sessions. When a session closes, + the emulator stores the user data to a user-data image file — by default, it stores the data in the file + <code>~/.android/userdata-qemu.img </code>(on Linux and Mac) or <code>C:\Documents and Settings\<user>\Local + Settings\Application Data\Android\userdata-qemu.img</code> (on Windows) in your development computer.</li> + +<li>Emulator instances that you start after the first instance (that are running concurrently) can also store user data during a session, but they <em>do not</em> preserve it for the next session, unless you have specified a unique user-data image file in which the data should be stored. </li> + +</ul> + +<p>To run multiple emulator instances and let each maintain user data across sessions, start the instances with the <code>-data</code> option (see <a href="#startup-options">Startup Options</a>) and supply the path to a user-data file. </p> + +<a name="apps"></a> + +<h2>Installing Applications on the Emulator</h2> + +<p>If you don't have access to Eclipse or the ADT Plugin, you can install +your application on the emulator <a href="{@docRoot}reference/adb.html#move">using +the adb utility</a>. Before installing the application, you need to package it +in a .apk file using the <a href="aapt.html">Android Asset Packaging Tool</a>. +Once the application is installed, you can start the emulator from the command +line, as described in this document, using any startup options necessary. +When the emulator is running, you can also connect to the emulator instance's +console to issue commands as needed.</p> + +<p>As you update your code, you periodically package and install it on the emulator. +The emulator preserves the application and its state data across restarts, +in a user-data disk partition. To ensure that the application runs properly +as you update it, you may need to delete the emulator's user-data partition. +To do so, start the emulator with the <code>-wipe-data</code> option. +For more information about the user-data partition and other emulator storage, +see <a href="#diskimages">Working with Emulator Disk Images</a>.</p> + +<a name="sdcard"></a> + +<h2>SD Card Emulation</h2> +<p>You can create a disk image and then load it to the emulator at startup, to simulate the presence of a user's SD card in the device. The sections below describe how to create the disk image, how to copy files to it, and how to load it in the emulator at startup. </p> + +<p>Note that you can only load disk image at emulator startup. Similarly, you can not remove a simulated SD card from a running emulator. However, you can browse, send files to, and copy/remove files from a simulated SD card either with adb or the emulator. </p> + +<p>The emulator supports emulated SDHC cards, so you can create an SD card image of any size up to 128 gigabytes.</p> + +<a name="creating"></a> + +<h3>Creating a Disk Image</h3> + +<p>You can use the mksdcard tool, included in the SDK, to create a FAT32 disk image that you can load in the emulator at startup. You can access mksdcard in the tools/ directory of the SDK and create a disk image like this: </p> + +<pre>mksdcard <size> <file></pre> + +<p>For example:</p> + +<pre>mksdcard 1024M sdcard1.iso</pre> + +<p>For more information, see <a href="{@docRoot}reference/othertools.html">Other Tools</a>. </p> + +<a name="copying"></a> +<h3>Copying Files to a Disk Image</h3> + +<p>Once you have created the disk image, you can copy files to it prior to loading it in the emulator. To copy files, you can mount the image as a loop device and then copy the files to it, or you can use a utility such as mtools to copy the files directly to the image. The mtools package is available for Linux, Mac, and Windows.</p> + +<a name="loading"></a> +<a name="step3" id="step3"></a> + +<h3>Loading the Disk Image at Emulator Startup</h3> +<p>To load FAT32 disk image in the emulator, start the emulator with the <code>-sdcard</code> flag and specify the name and path of your image (relative to the current working directory): </p> + +<pre>emulator -sdcard <filepath></pre> + +<a name="troubleshooting"></a> + +<h2>Troubleshooting Emulator Problems</h2> + +<p>The adb utility sees the emulator as an actual physical device. For this reason, you might have to use the -d flag with some common adb commands, such as <code>install</code>. The -d flag lets you specify which of several connected devices to use as the target of a command. If you don't specify -d, the emulator will target the first device in its list. For more information about adb, see <a href="{@docRoot}reference/adb.html">Android Debug Bridge</a>.</p> + +<p>For emulators running on Mac OS X, if you see an error "Warning: No DNS servers found" when starting the emulator, check to see whether you have an <code>/etc/resolv.conf</code> file. If not, please run the following line in a command window:</p> + <pre>ln -s /private/var/run/resolv.conf /etc/resolv.conf</pre> + +<p>See <a href="{@docRoot}kb/index.html">Frequently Asked Questions</a> for more troubleshooting information. </p> + +<a name="limitations"></a> + <h2>Emulator Limitations</h2> + <p>In this release, the limitations of the emulator include: </p> + <ul> + <li>No support for placing or receiving actual phone calls. You can simulate phone calls (placed and received) through the emulator console, however. </li> + <li>No support for USB connections</li> + <li>No support for camera/video capture (input).</li> + <li>No support for device-attached headphones</li> + <li>No support for determining connected state</li> + <li>No support for determining battery charge level and AC charging state</li> + <li>No support for determining SD card insert/eject</li> + <li>No support for Bluetooth</li> + </ul> diff --git a/docs/html/guide/developing/hierarchy-viewer.jd b/docs/html/guide/developing/hierarchy-viewer.jd new file mode 100644 index 0000000..065211c --- /dev/null +++ b/docs/html/guide/developing/hierarchy-viewer.jd @@ -0,0 +1,99 @@ +page.title=Hierarchy Viewer +@jd:body + +<p>The Hierarchy Viewer application allows you to debug and optimize your user +interface. It provides a visual representation of the layout's View hierarchy +(the Layout View) and a magnified inspector of the display (the Pixel Perfect View). +</p> + +<p>To get the Hierarchy Viewer started:</p> +<ol> + <li>Connect your device or launch an emulator.</li> + <li>From a terminal, launch <code>hierarchyviewer</code> from your SDK + <code>/tools</code> directory. + </li> + <li>In the window that opens, you'll see a list of <strong>Devices</strong>. When a device is + selected, a list of currently active <strong>Windows</strong> is displayed + on the right. The <em><Focused Window></em> is the window currently in + the foreground, and also the default window loaded if you do not select another. + </li> + <li>Select the window that you'd like to inspect and click + <strong>Load View Hierarchy</strong>. The Layout View will be loaded. + You can then load the Pixel Perfect View by clicking the second + icon at the bottom-left of the window. + </li> +</ol> + +<p>If you've navigated to a different window on the device, press <strong>Refresh Windows</strong> +to refresh the list of available windows on the right.</p> + +<h2>Layout View</h2> +<p>The Layout View offers a look at the View layout and properties. It has three views:</p> +<ul> + <li>Tree View: a hierarchy diagram of the Views, on the left.</li> + <li>Properties View: a list of the selected View's properties, on the top-right.</li> + <li>Wire-frame View: a wire-frame drawing of the layout, on the bottom-right.</li> +</ul> +<br/> +<img src="/android/images/hierarchyviewer-layout.png" alt="" height="509" width="700" /> + +<p>Select a node in the Tree View to display the properties of that element in +the Properties View. When a node is selected, the Wire-frame View +also indicates the bounds of the element with a red rectangle. +Double click a node in the tree (or select it, and click <strong>Display +View</strong>) to open a new window with a rendering of that element.</p> + +<p>The Layout View includes a couple other helpful features for debugging your layout: +<strong>Invalidate</strong> and <strong>Request Layout</strong>. These buttons execute the +respective View calls, {@link android.view.View#invalidate()} and {@link android.view.View#requestLayout()}, +on the View element currently selected in the tree. Calling these methods on any View can +be very useful when simultaneously running a debugger on your application.</p> + +<p>The Tree View can be resized by adjusting the zoom slider, below +the diagram. The number of View elements in the window is also given here. You +should look for ways to minimize the number of Views. The fewer View elements there +are in a window, the faster it will perform.</p> + +<p>If you interact with the device and change the focused View, the diagram will not automatically refresh. +You must reload the Layout View by clicking <strong>Load View Hierarchy</strong>. + + +<h2>Pixel Perfect View</h2> +<p>The Pixel Perfect View provides a magnified look at the current device window. It has three views:</p> +<ul> + <li>Explorer View: shows the View hierarchy as a list, on the left.</li> + <li>Normal View: a normal view of the device window, in the middle.</li> + <li>Loupe View: a magnified, pixel-grid view of the device window, on the right.</li> +</ul> +<br/> +<img src="/android/images/hierarchyviewer-pixelperfect.png" alt="" height="509" width="700" /> + +<p>Click on an element in the Explorer View and a "layout box" will be drawn in the +Normal View to indicate the layout position of that element. The layout box uses multiple rectangles, to indicate the normal bounds, the padding and the margin (as needed). The purple or green rectangle indicates +the normal bounds of the element (the height and width). The inner white or black rectangle indicates +the content bounds, when padding is present. A black or white rectangle outside the normal purple/green +rectangle indicates any present margins. +(There are two colors for each rectangle, in order to provide the best contrast +based on the colors currently in the background.)</p> + +<p>A very handy feature for designing your UI is the ability to overlay an image in the Normal and Loupe +Views. For example, you might have a mock-up image of how you'd like to layout your interface. +By selecting <strong>Load...</strong> from the controls in the Normal View, you can choose the +image from your computer and it will be placed atop the preview. Your chosen image will anchor at the bottom left corner of the screen. You can then adjust the opacity of the overlay and begin fine-tuning your layout to match the mock-up.</p> + +<p>The Normal View and Loupe View refresh at regular intervals (5 seconds by default), but the +Explorer View does not. If you navigate away and focus on a different View, then you should refresh the +Explorer's hierarchy by clicking <strong>Load View Hierarchy</strong>. This is even true +when you're working in a window that holds multiple Views that are not always visible. If you do not, +although the previews will refresh, clicking a View in the Explorer will not provide the proper layout box +in the Normal View, because the hierarchy believes you are still focused on the prior View.</p> + +<p>Optional controls include:</p> +<ul> + <li><strong>Overlay</strong>: Load an overlay image onto the view and adjust its opacity.</li> + <li><strong>Refresh Rate</strong>: Adjust how often the Normal and Loupe View refresh their display.</li> + <li><strong>Zoom</strong>: Adjust the zoom level of the Loupe View.</li> +</ul> + +<p><strong><a href="/android/intro/tools.html">Back to Development Tools</a></strong></p> + diff --git a/docs/html/guide/developing/index.html b/docs/html/guide/developing/index.html new file mode 100644 index 0000000..4881acf --- /dev/null +++ b/docs/html/guide/developing/index.html @@ -0,0 +1,8 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=../index.html"> +</head> +<body> +<a href="../index.html">click here</a> if you are not redirected. +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/developing/instrumentation/index.jd b/docs/html/guide/developing/instrumentation/index.jd new file mode 100644 index 0000000..1c1ab14 --- /dev/null +++ b/docs/html/guide/developing/instrumentation/index.jd @@ -0,0 +1,54 @@ +page.title=Instrumentation +@jd:body + +<dl> + <dt><a href="inst-framework.html">Instrumentation Framework</a></dt> + <dt><a href="inst-testing">Instrumentation Testing</a></dt> +</dl> + +<!-- +<p>Android provides an instrumentation framework that lets you create a bundle of instrumentation tests and attach them to your application. When you run the instrumentation from the command line, the Android system d + + through an <code><instrumentation></code> element in its manifest file. You write your instrumentation tests in a subclass of {@link android.app.Instrumentation}, from which you have access to a variety of methods for managing the state of the application, from within the application's process. For example, you can write instrumentation to +<ul> +<li>Instantiate the process's Application object +<li>Instantiate an Activity and change it's lifecycle state +<li>Send keypad events to the currently focused window +<li>Execute a menu item +<li>Take a performance snapshot, and +<li>Attach an + +When running with instrumentation turned on, the system instantiates class will be instantiated for you before any of the application code, allowing you to monitor all of the interaction the system has with the application. An Instrumentation implementation is described to the system through an AndroidManifest.xml's <instrumentation> tag. + + +<ul> + <li> + <a href="hierarchy.html">IntroducHierarchy of Screen Elements</a> + </li> + <li> + <a href="layout.html">Common Layout Objects</a> + </li> + <li> + <a href="ui-xml.html">Declaring a UI in XML</a> + </li> + <li> + <a href="binding.html">Binding to Data with AdapterView</a> + </li> + <li> + <a href="ui-events.html">Handling UI Events</a> + </li> + <li> + <a href="themes.html">Applying Styles and Themes to Your Application</a> + </li> + <li> + <a href="custom-views.html">Building Custom Views</a> + </li> + <li> + <a href="glossary.html">UI Elements and Concepts Glossary</a> + </li> + <li> + <a href="{@docRoot}guide/tutorials/views/hello-views-index.html">Hello Views</a> + </li> + +</ul> +-->
\ No newline at end of file diff --git a/docs/html/guide/developing/instrumentation/inst-framework.jd b/docs/html/guide/developing/instrumentation/inst-framework.jd new file mode 100644 index 0000000..16f78bb --- /dev/null +++ b/docs/html/guide/developing/instrumentation/inst-framework.jd @@ -0,0 +1,169 @@ +page.title=Instrumentation Framework +@jd:body + +<p>This document describes how to use the Android Instrumentation Framework to write test cases. You should have a working knowledge of the following:</p> +<ul> + <li> Android Application Framework </li> + <li> Using <code>adb</code>, <code>am</code> and various logging functionality </li> + <li> A brief understanding of the application of interest, that is, he names of the classes which handle the intents etc. </li> + <li> Junit testing. </li> +</ul> +<p> Each Android application runs in its own process. Instrumentation kills the application process and restarts the process with Instrumentation. Instrumentation gives a handle to the application context used to poke around the application to validate test assertions, allowing you to write test cases to test applications at a much lower level than UI screen shot tests. Note that Instrumentation cannot catch UI bugs. </p> + +<p>This document covers these topics:</p> + +<ul> +<li><a href="#androidInstrumentationFrameworkamCommand">Understanding the am Command</a></li> +<li><a href="#androidInstrumentationFrameworkWritingRunning">Writing and Running Test Cases</a></li> +<li><a href="#androidInstrumentationFrameworkTestCase">Exploring a Test Case</a></li> +<li><a href="#androidInstrumentationFrameworkTroubleshooting">Troubleshooting</a></li> +</ul> + +<a name="androidInstrumentationFrameworkamCommand"></a><h2>Understanding the am Command</h2> + +<p><code>am</code> is used to start and instrument activities using the adb shell command, as shown in the snippet below:</p> +<pre class="prettify"> +> adb shell am +usage: am [start|instrument] + am start [-a <ACTION>] [-d <DATA_URI>] [-t <MIME_TYPE>] + [-c <CATEGORY> [-c <CATEGORY>] ...] + [-e <EXTRA_KEY> <EXTRA_VALUE> [-e <EXTRA_KEY> <EXTRA_VALUE> ...] + [-n <COMPONENT>] [-D] [<URI>] + am instrument [-e <ARG_NAME> <ARG_VALUE>] [-p <PROF_FILE>] + [-w] <COMPONENT> +For example, to start the Contacts application you can use +> adb shell am start -n com.google.android.contacts/.ContactsActivity +</pre> + + +<a name="androidInstrumentationFrameworkWritingRunning"></a><h2>Writing and Running Test Cases</h2> + +<p>Each instrumentation test case is similar to an Android application with the distinction that it starts another application. For example, have a look in the <code>tests/Contacts</code> directory. </p> +<ul> + <li> There should be a Makefile and an Android Manifest file. </li> + <li> Tests are located in <code>tests/Contacts/src/com/google/android/contactstests</code>. </li> + <li> The Instrumentation Test Runner is located at <code>tests/Contacts/src/com/google/android/contactstests/functional/ContactsInstrumentationTestRunner.java</code>.</li> +</ul> +<p>Suppose you have a makefile with <code>Contactstests</code> as the target. </p> +<ul> + <li> <code>make Contactstests</code>: Compiles the test cases. </li> + <li> <code>adb install Contactstests.apk</code>: Installs the apk on the device. </li> + <li> Use the adb shell <code>am</code> command to run them. </li> +</ul> +<p> For options and other details, please see <a href="instrumentation_testing.html" target="_top">Instrumentation Testing</a>.</p> + + +<a name="androidInstrumentationFrameworkTestCase"></a><h2>Exploring a Test Case</h2> + +<p> The test case described in this section adds and tests a new Contact. Note that you can send intents, register broadcast receivers, etc. </p> +<p><code>Instrumentation.java</code> has helper functions that send key events and string, for example: </p> +<ul> + <li><code>getInstrumentation()</code>: Returns the handle to the instrumentation </li> + <li><code>sendCharacterSync</code>: Sends a character. </li> + <li><code>sendStringSync</code>: Sends a string to an input box. </li> + <li><code>sendKeyDownUpSync</code>: Sends a specific keyevent. </li> + <li><code>sendTrackballEventSync</code>: Send a trackball event.</li> +</ul> +<p> You can find the test case below at <code>device/tests/Contacts.</code></p> +<pre class="prettify"> +private void addNewContact(String name, int star, int phoneType, String number, String label, + String email, int emailType){ + ContentValues values = new ContentValues(); + Uri phoneUri = null; + Uri emailUri = null; + + values.put(Contacts.People.NAME, name); + values.put(Contacts.People.STARRED, star); + + //Add Phone Numbers + Uri uri = mActivity.getContentResolver().insert(Contacts.People.CONTENT_URI, values); + phoneUri = Uri.withAppendedPath(uri, Contacts.People.Phones.CONTENT_DIRECTORY); + + values.clear(); + values.put(Contacts.Phones.TYPE, phoneType); + values.put(Contacts.Phones.NUMBER, number); + values.put(Contacts.Phones.LABEL, label); + mActivity.getContentResolver().insert(phoneUri, values); + + //Add Email + emailUri = Uri.withAppendedPath(uri, ContactMethods.CONTENT_DIRECTORY); + + values.clear(); + values.put(ContactMethods.KIND, Contacts.KIND_EMAIL); + values.put(ContactMethods.DATA, email); + values.put(ContactMethods.LABEL, ""); + values.put(ContactMethods.TYPE, emailType); + mActivity.getContentResolver().insert(emailUri, values); +} + + + public void testAddSaveSingleContact(){ + int previousCount = mActivity.getListView().getCount(); + String message; + + addNewContact(INPUT_NAME_1 + "1", "5435754532", "1" + INPUT_EMAIL_1, CONFIRM_OPTION); + + message = "Added 1 to initial length=" + previousCount + ", but resulted with a count=" + + mActivity.getListView().getCount(); + assertEquals(message, ++previousCount, mActivity.getListView().getCount()); + + // Check Content; Name; Num; Starred + assertEquals(INPUT_NAME_1 + "1", getTextFromView(0, android.R.id.text1)); + assertEquals("5435754532", getTextFromView(0, android.R.id.text2)); + + //Check email is saved + //cursor = returnEmailCursorAtId("1"); + Uri uri = Uri.parse("content://contacts/people/1"); + uri = Uri.withAppendedPath(uri, ContactMethods.CONTENT_DIRECTORY); + Cursor cursor = mActivity.getContentResolver().query(uri, CONTACTS_COLUMNS, null, null, null); + assertTrue("returnEmailCursorAtId: Moving cursor to first row has failed", cursor.first()); + + int dataIndex = cursor.getColumnIndexOrThrow("data"); + assertEquals("1" + INPUT_EMAIL_1, cursor.getString(dataIndex)); + cursor.deactivate(); +} + </pre> + + +<a name="androidInstrumentationFrameworkTroubleshooting"></a><h2>Troubleshooting</h2> + +<p>If you run your test cases and nothing appears to happen, have a look at <code>adb logcat</code>. The following is a common problem:</p> +<pre class="prettify"> +I/dalvikvm( 688): threadid=11: attached from native, name=Binder Thread #1 +I/dalvikvm( 688): threadid=13: attached from native, name=Binder Thread #2 +W/ActivityManager( 469): Unable to find instrumentation info for: ComponentInfo{com.google.android.browser_instrumentation/com.google.android.browser_instrumentation.BrowserWebkitLayoutInstrumentation} +D/AndroidRuntime( 688): Shutting down VM +E/AndroidRuntime( 688): ERROR: thread attach failed +</pre> +<p>It's possible that the instrumentation apk isn't installed on your device or that the package name is incorrect in the Manifest file. </p> + + +<p><span class="lh2"><a name="androidFooter"></a></span> + + </div> + </div> + <!-- end gc-pagecontent --> + </div> + <!-- end gooey wrapper --> + </div> + <!-- end codesearchresults --> + <div id="gc-footer" dir="ltr"> + <div class="text"> ©2008 Google<!-- - <a href="/">Code Home</a> - <a href="http://www.google.com/accounts/TOS">Site Terms of Service</a> - <a href="http://www.google.com/privacy.html">Privacy Policy</a> - <a href="/more">Site Directory</a> --></div> + </div> + <!-- end gc-footer --> +</div> +<!-- end gc-containter --> +<script src="http://www.google-analytics.com/ga.js" type="text/javascript"> +</script> +<script type="text/javascript"> + try { + var pageTracker = _gat._getTracker("UA-18071-1"); + pageTracker._setAllowAnchor(true); + pageTracker._initData(); + pageTracker._trackPageview(); + } catch(e) {} +</script> +<div id="jd-build-id"> v0.3 - 9 June 2008</div> +</div></div></div></body> +</html> + diff --git a/docs/html/guide/developing/instrumentation/inst-testing.jd b/docs/html/guide/developing/instrumentation/inst-testing.jd new file mode 100644 index 0000000..09b0196 --- /dev/null +++ b/docs/html/guide/developing/instrumentation/inst-testing.jd @@ -0,0 +1,236 @@ + +page.title=Instrumentation Testing +@jd:body + +<p>Sometimes you may want to manually interact with your applications to verify that a particular feature or behavior is working properly; why not automate this verification with a JUnit TestCase that can instrument applications?</p> +<p>Instrumentation testing allows you to verify a particular feature or behavior with an automated JUnit TestCase. You can launch activities and providers within an application, send key events, and make assertions about various UI elements.</p> + +This document provides an overview of how to use instrumentation on Android and covers these topics: + +<ul> +<li><a href="#androidInstrumentationTestingClasses">Classes</a></li> +<li><a href="#androidInstrumentationTestingRunning">Running Tests</a></li> +<li><a href="#androidInstrumentationTestingCreating">Creating Tests</a></li> +<li><a href="#androidInstrumentationAliases">Aliases for Running Framework Instrumentation Tests</a></li> +</ul> + + + + +<a name="androidInstrumentationTestingClasses"></a><h2>Classes</h2> + +<p> The following classes help glue together <code>Instrumentation</code> with JUnit testing. </p> +<table> + <tr> + <th scope="col">Class</th> + <th scope="col">Description</th></tr> + <tr> + <td valign="top"><code>InstrumentationTestCase</code></td> + <td valign="top"> + <p>This extends the standard JUnit <code>TestCase</code> and offers access to an <code>Instrumentation</code> class. Write tests inside your instrumentation class any way you see fit. For example, your test might launch activities and send key events. For this to work properly, the instrumentation needs to be injected into the test case.</p> + </td> + </tr> + <tr> + <td valign="top"><code>InstrumentationTestRunner</code></td> + <td valign="top">The instrumentation test runner is an instrumentation that runs instrumentation test cases and injects itself into each test case. Instrumentation test cases need to be grouped together with an instrumentation test runner with the appropriate target package.</td> + </tr> + <tr> + <td valign="top"><code>InstrumentationTestSuite</code></td> + <td valign="top">The instrumentation test suite is a simple extension of the standard JUnit <code>TestSuite</code> that keeps a member <code>Instrumentation</code> variable on hand to inject into each <code>TestCase</code> before running them. It is used by <code>InstrumentationTestRunner</code>.</td> + </tr> +</table> +<p> Three additional base classes extend <code>InstrumentationTestCase</code> to allow you to test <code>Activity</code> and <code>Provider</code> classes:</p> +<table> + <tr> + <th scope="col">Class</th> + <th scope="col">Description</th> + </tr> + <tr> + <td valign="top"><code>ActivityTestCase</code></td> + <td valign="top"><p>This class can be used to write tests for a specific activity. An activity is launched in its <code>setUp()</code> method and finished with <code>tearDown</code>. If you write a test case that extends <code>ActivityTestCase</code>, you can write tests that access the activity using <code>getActivity()</code> and assume it has been set up properly.</p></td> + </tr> + <tr> + <td valign="top"><code>SingleLaunchActivityTestCase</code></td> + <td valign="top">This class is similar to <code>ActivityTestCase</code> except that the activity is launched once per class instead of every time the test case calls setup. </td> + </tr> + <tr> + <td valign="top"><code>ProviderTestCase</code></td> + <td valign="top">This class is similar to <code>ActivityTestCase</code> except that it will setup, tear down, and provide access to the <code>Provider</code> of your choice.</td> + </tr> +</table> + + +<a name="androidInstrumentationTestingRunning"></a><h2>Running Tests</h2> + +<p> To run your tests, use the <code>am instrument</code> command with your <code>InstrumentationTestRunner</code> as its argument. Results are printed as a result of the instrumentation. For example, the following snippet displays the output after running the framework tests with one test failing (note the unusual syntax caused by how instrumentations are run via <code>am</code>):</p> +<pre class="prettify"> +$ adb shell am instrument -w com.google.android.frameworktest/.tests.FrameworkInstrumentationTestRunner +INSTRUMENTATION_RESULT: test results:=.......F....... +Time: 6.837 +There was 1 failure: +1) testSetUpConditions(com.google.android.frameworktest.tests.focus.RequestFocusTest)junit.framework.AssertionFailedError: requestFocus() should work from onCreate. + at com.google.android.frameworktest.tests.focus.RequestFocusTest.testSetUpConditions(RequestFocusTest.java:66) + at java.lang.reflect.Method.invokeNative(Native Method) + at android.test.InstrumentationTestSuite.runTest(InstrumentationTestSuite.java:73) + at android.test.InstrumentationTestSuite.runTest(InstrumentationTestSuite.java:73) + at android.test.InstrumentationTestRunner.onStart(InstrumentationTestRunner.java:151) + at android.app.Instrumentation$InstrumentationThread.run(Instrumentation.java:1088) + +FAILURES!!! +Tests run: 14, Failures: 1, Errors: 0 + +<RETURN> to continue + +INSTRUMENTATION_CODE: -1 +$ +</pre> + + +<a name="androidInstrumentationTestingRunningAll"></a><h3>All Tests</h3> + +<pre class="prettify"> +$ adb shell am instrument -w MyInstrumentationTestRunner +</pre> + + +<a name="androidInstrumentationTestingRunningSingleTestCase"></a><h3>A Single Test Case</h3> + +<pre class="prettify"> +$ adb shell am instrument \ + -e class MyInstrumentationTestCase \ + -w MyInstrumentationTestRunner +</pre> + + +<a name="androidInstrumentationTestingRunningSingleTest"></a><h3>A Single Test</h3> + +<pre class="prettify"> +$ adb shell am instrument \ + -e class MyInstrumentationTestCase#myTestMethod \ + -w MyInstrumentationTestRunner +</pre> + + +<a name="androidInstrumentationTestingCreating"></a><h2>Creating Tests</h2> + + + +<a name="androidInstrumentationTestingCreatingTestRunner"></a> + +<h3>New Instrumentation TestRunner</h3> + +<pre> +public class FrameworkInstrumentationTestRunner extends InstrumentationTestRunner { + + @Override + public TestSuite getAllTests() { + InstrumentationTestSuite suite = new InstrumentationTestSuite(this); + + suite.addTestSuite(FocusAfterRemovalTest.class); + suite.addTestSuite(RequestFocusTest.class); + suite.addTestSuite(RequestRectangleVisibleTest.class); + return suite; + } + + @Override + public ClassLoader getLoader() { + return FrameworkInstrumentationTestRunner.class.getClassLoader(); + } +} +</pre> + +<p> Next, in an appropriate <code>AndroidManifest.xml</code>, define the instrumentation for the derived class with the appropriate <code>android:targetPackage</code> set. For example, the snippet below defines the instrumentation runner for the framework tests.</p> + +<pre> +<uses-permission android:name="android.permission.RUN_INSTRUMENTATION" /> + +<instrumentation android:name="android.tests.FrameworkInstrumentationTestRunner" + android:targetPackage="com.google.android.frameworktest" + android:label="framework instrumentation test runner" /> +</pre> + + +<a name="androidInstrumentationTestingCreatingTestCase"></a> + +<h3>New InstrumentationTestCase</h3> + +<p> To create a new test case, write a class that extends <code>InstrumentationTestCase</code> in the same application archive as your test runner. The following snippet illustrates an example <code>ActivityTestCase</code> that tests an activity named <code>MyActivity</code>.</p> +<pre> +public class ButtonPressTest extends ActivityTestCase<MyActivity> { + + Button mLeftButton; + + public ButtonPressTest() { + super("com.example", MyActivity.class); + } + + @Override + public void setUp() throws Exception { + super.setUp(); + mLeftButton = (Button) getActivity().findViewById(R.id.leftButton); + } + + public void testFocusMovesToRight() throws Exception { + assertTrue(mLeftButton.hasFocus()); + getInstrumentation().sendCharacterSync(KeyEvent.KEYCODE_DPAD_RIGHT); + + Button rightButton = (Button) getActivity().findViewById(R.id.rightButton); + assertTrue(rightButton.hasFocus()); + } + + // could have several more tests... +} +</pre> + + +<a name="androidInstrumentationAliases"></a><h2>Aliases for Running Framework Instrumentation Tests</h2> + +<pre class="prettify"> +# compiles and installs FrameworkTests +alias deploytests="(cd tests/FrameworkTests/ && mm) && adb install out/target/product/dream/system/app/FrameworkTest.apk" + +# runs all of FrameworkTests unit tests +alias runtests="adb shell am instrument -w com.google.android.frameworktest/.tests.FrameworkInstrumentationTestRunner" + +# runtest TEST: runs a single unit test, for instance runtest view.VisibilityTest +# -- for convenience, you don't have to type the com.google.android.frameworktest.tests. +function runtest { + adb shell am instrument -e class com.google.android.frameworktest.tests.$1 -w com.google.android.frameworktest/.tests.FrameworkInstrumentationTestRunner +} + +# debugtest TEST: runs a single unit test in debug mode, for instance runtest view.VisibilityTest +function debugtest { + adb shell am instrument -e debug true -e class com.google.android.frameworktest.tests.$1 -w com.google.android.frameworktest/.tests.FrameworkInstrumentationTestRunner +} +</pre> + + +<p><span class="lh2"><a name="androidFooter"></a></span> + + </div> + </div> + <!-- end gc-pagecontent --> + </div> + <!-- end gooey wrapper --> + </div> + <!-- end codesearchresults --> + <div id="gc-footer" dir="ltr"> + <div class="text"> ©2008 Google<!-- - <a href="/">Code Home</a> - <a href="http://www.google.com/accounts/TOS">Site Terms of Service</a> - <a href="http://www.google.com/privacy.html">Privacy Policy</a> - <a href="/more">Site Directory</a> --></div> + </div> + <!-- end gc-footer --> +</div> +<!-- end gc-containter --> +<script src="http://www.google-analytics.com/ga.js" type="text/javascript"> +</script> +<script type="text/javascript"> + try { + var pageTracker = _gat._getTracker("UA-18071-1"); + pageTracker._setAllowAnchor(true); + pageTracker._initData(); + pageTracker._trackPageview(); + } catch(e) {} +</script> +<div id="jd-build-id"> v0.3 - 9 June 2008</div> +</div></div></div></body> +</html> + diff --git a/docs/html/guide/developing/monkey.jd b/docs/html/guide/developing/monkey.jd new file mode 100644 index 0000000..d829f5b --- /dev/null +++ b/docs/html/guide/developing/monkey.jd @@ -0,0 +1,240 @@ +page.title=UI/Application Exerciser Monkey +@jd:body + +<p>The Monkey is a program that runs on your +<a href="{@docRoot}reference/emulator.html">emulator</a> or device and generates pseudo-random +streams of user events such as clicks, touches, or gestures, as well as a number of system-level +events. You can use the Monkey to stress-test applications that you are developing, in a random +yet repeatable manner.</p> + +<a name="overview"></a> +<h2>Overview</h2> + +<p>The Monkey is a command-line tool that that you can run on any emulator +instance or on a device. It sends a pseudo-random stream of +user events into the system, which acts as a stress test on the application software you are +developing.</p> + +<p>The Monkey includes a number of options, but they break down into four primary +categories:</p> + +<ul> + <li>Basic configuration options, such as setting the number of events to attempt.</li> + <li>Operational constraints, such as restricting the test to a single package.</li> + <li>Event types and frequencies.</li> + <li>Debugging options.</li> +</ul> + +<p>When the Monkey runs, it generates events and sends them to the system. It also <i>watches</i> +the system under test and looks for three conditions, which it treats specially:</p> + +<ul> + <li>If you have constrained the Monkey to run in one or more specific packages, it + watches for attempts to navigate to any other packages, and blocks them.</li> + <li>If your application crashes or receives any sort of unhandled exception, the Monkey + will stop and report the error.</li> + <li>If your application generates an <i>application not responding</i> error, the Monkey + will stop and report the error.</li> +</ul> + +<p>Depending on the verbosity level you have selected, you will also see reports on the progress +of the Monkey and the events being generated.</p> + +<a name="basics"></a> +<h2>Basic Use of the Monkey</h2> + +<p>You can launch the Monkey using a command line on your development machine or from a script. +Because the Monkey runs in the emulator/device environment, you must launch it from a shell in +that environment. You can do this by prefacing <code>adb shell</code> to each command, +or by entering the shell and entering Monkey commands directly.</p> +<p>The basic syntax is: </p> + +<pre>$ adb shell monkey [options] <event-count></pre> + +<p>With no options specified, the Monkey will launch in a quiet (non-verbose) mode, and will send +events to any (and all) packages installed on your target. Here is a more typical command line, +which will launch your application and send 500 pseudo-random events to it:</p> + +<pre>$ adb shell monkey -p your.package.name -v 500</pre> + +<a name="reference"></a> +<h2>Command Options Reference</h2> + +<p>The table below lists all options you can include on the Monkey command line.</p> + +<table> +<tr> + <th>Category</th> + <th>Option</th> + <th>Description</th> +</tr> + +<tr> +<td rowspan="2">General</td> +<td><code>--help</code></td> +<td>Prints a simple usage guide.</td> +</tr> + +<tr> +<td><code>-v</code></td> +<td>Each -v on the command line will increment the verbosity level. +Level 0 (the default) provides little information beyond startup notification, test completion, and +final results. +Level 1 provides more details about the test as it runs, such as individual events being sent to +your activities. +Level 2 provides more detailed setup information such as activities selected or not selected for +testing.</td> +</tr> + +<tr> +<td rowspan="10">Events</td> +<td><code>-s <seed></code></td> +<td>Seed value for pseudo-random number generator. If you re-run the Monkey with the same seed +value, it will generate the same sequence of events.</td> +</tr> + +<tr> +<td><code>--throttle <milliseconds></code></td> +<td>Inserts a fixed delay between events. You can use this option to slow down the Monkey. +If not specified, there is no delay and the events are generated as rapidly as possible.</td> +</tr> + +<tr> +<td><code>--pct-touch <percent></code></td> +<td>Adjust percentage of touch events. +(Touch events are a down-up event in a single place on the screen.)</td> +</tr> + +<tr> +<td><code>--pct-motion <percent></code></td> +<td>Adjust percentage of motion events. +(Motion events consist of a down event somewhere on the screen, a series of pseudo-random +movements, and an up event.)</td> +</tr> + +<tr> +<td><code>--pct-trackball <percent></code></td> +<td>Adjust percentage of trackball events. +(Trackball events consist of one or more random movements, sometimes followed by a click.)</td> +</tr> + +<tr> +<td><code>--pct-nav <percent></code></td> +<td>Adjust percentage of "basic" navigation events. +(Navigation events consist of up/down/left/right, as input from a directional input device.)</td> +</tr> + +<tr> +<td><code>--pct-majornav <percent></code></td> +<td>Adjust percentage of "major" navigation events. +(These are navigation events that will typically cause actions within your UI, such as +the center button in a 5-way pad, the back key, or the menu key.)</td> +</tr> + +<tr> +<td><code>--pct-syskeys <percent></code></td> +<td>Adjust percentage of "system" key events. +(These are keys that are generally reserved for use by the system, such as Home, Back, Start Call, +End Call, or Volume controls.)</td> +</tr> + +<tr> +<td><code>--pct-appswitch <percent></code></td> +<td>Adjust percentage of activity launches. At random intervals, the Monkey will issue a startActivity() call, as a way of maximizing +coverage of all activities within your package.</td> +</tr> + +<tr> +<td><code>--pct-anyevent <percent></code></td> +<td>Adjust percentage of other types of events. This is a catch-all for all other types of events such as keypresses, other less-used +buttons on the device, and so forth.</td> +</tr> + +<tr> +<td rowspan="2">Constraints</td> +<td><code>-p <allowed-package-name></code></td> +<td>If you specify one or more packages this way, the Monkey will <i>only</i> allow the system +to visit activities within those packages. If your application requires access to activities in +other packages (e.g. to select a contact) you'll need to specify those packages as well. +If you don't specify any packages, the Monkey will allow the system to launch activities +in all packages. To specify multiple packages, use the -p option multiple times — one -p +option per package.</td> +</tr> + +<tr> +<td><code>-c <main-category></code></td> +<td>If you specify one or more categories this way, the Monkey will <i>only</i> allow the +system to visit activities that are listed with one of the specified categories. +If you don't specify any categories, the Monkey will select activities listed with the category +Intent.CATEGORY_LAUNCHER or Intent.CATEGORY_MONKEY. To specify multiple categories, use the -c +option multiple times — one -c option per category.</td> +</tr> + +<tr> +<td rowspan="8">Debugging</td> +<td><code>--dbg-no-events</code></td> +<td>When specified, the Monkey will perform the initial launch into a test activity, but +will not generate any further events. +For best results, combine with -v, one or more package constraints, and a non-zero throttle to keep the Monkey +running for 30 seconds or more. This provides an environment in which you can monitor package +transitions invoked by your application.</td> +</tr> + +<tr> +<td><code>--hprof</code></td> +<td>If set, this option will generate profiling reports immediately before and after +the Monkey event sequence. +This will generate large (~5Mb) files in data/misc, so use with care. See +<a href="{@docRoot}reference/traceview.html" title="traceview">Traceview</a> for more information +on trace files.</td> +</tr> + +<tr> +<td><code>--ignore-crashes</code></td> +<td>Normally, the Monkey will stop when the application crashes or experiences any type of +unhandled exception. If you specify this option, the Monkey will continue to send events to +the system, until the count is completed.</td> +</tr> + +<tr> +<td><code>--ignore-timeouts</code></td> +<td>Normally, the Monkey will stop when the application experiences any type of timeout error such +as a "Application Not Responding" dialog. If you specify this option, the Monkey will continue to +send events to the system, until the count is completed.</td> +</tr> + +<tr> +<td><code>--ignore-security-exceptions</code></td> +<td>Normally, the Monkey will stop when the application experiences any type of permissions error, +for example if it attempts to launch an activity that requires certain permissions. If you specify +this option, the Monkey will continue to send events to the system, until the count is +completed.</td> +</tr> + +<tr> +<td><code>--kill-process-after-error</code></td> +<td>Normally, when the Monkey stops due to an error, the application that failed will be left +running. When this option is set, it will signal the system to stop the process in which the error +occurred. +Note, under a normal (successful) completion, the launched process(es) are not stopped, and +the device is simply left in the last state after the final event.</td> +</tr> + +<tr> +<td><code>--monitor-native-crashes</code></td> +<td>Watches for and reports crashes occurring in the Android system native code. If --kill-process-after-error is set, the system will stop.</td> +</tr> + +<tr> +<td><code>--wait-dbg</code></td> +<td>Stops the Monkey from executing until a debugger is attached to it.</td> +</tr> + +</table> + +<!-- TODO: add a section called "debugging" that covers ways to use it, +need to clear data, use of the seed, etc. --> + +<!-- TODO: add a section that lays down a contract for Monkey output so it can be +scripted safely. --> + diff --git a/docs/html/guide/developing/other-ide.jd b/docs/html/guide/developing/other-ide.jd new file mode 100644 index 0000000..dc7c11d --- /dev/null +++ b/docs/html/guide/developing/other-ide.jd @@ -0,0 +1,148 @@ +page.title=In Other IDEs +@jd:body + +<p>The recommended way to develop an Android application is to use + <a href="#developingwitheclipse">Eclipse + with the ADT plugin</a>. This plugin provides editing, building, + and debugging functionality integrated right into the IDE. </p> + +<p>However, if you'd rather develop your application in another IDE, such as IntelliJ, + or use Eclipse without the ADT plugin, you can do that instead. The SDK + provides the tools you need to set up, build, and debug your application. + </p> + + +<h2>Creating an Android Project </h2> + +<p>The Android SDK includes <code>activityCreator</code>, a program that generates a number of stub files for your project, as well as a build file. You can use the program to create an Android project for new code or from existing code, such as the sample applications included in the SDK. For Linux and Mac, the SDK provides <code>activitycreator</code> and for Windows, <code>activityCreator.bat</code>, a batch script. Regardless of platform, you can use <code>activitycreator</code> in the same way. </p> + +<p>To run <code>activityCreator</code> and create an Android project, follow these steps:</p> + +<ol> + <li> In the command line, change to the <code>tools/</code> directory of the SDK and create a new directory for your project files. If you are creating a project from existing code, change to the root folder of your application instead. </li> + + <li><p>Run <code>activityCreator</code>. In the command, you must specify a fully-qualified class name as an argument. If you are creating a project for new code, the class represents the name of a stub class that the script will create. If you are creating a project from existing code, you must specify the name of one Activity class in the package. Command options for the script include: +<ul> + <li><code>--out <folder></code> which sets the output directory. By default, the output directory is the current directory. If you created a new directory for your project files, use this option to point to it. </li> + <li><code>--ide intellij</code>, which generates IntelliJ IDEA project files in the newly created project</li> +</ul> +</li> +</ol> + +<p>Here's an example:</p> +<pre> +~/android_linux_sdk/tools $ ./activityCreator.py --out myproject your.package.name.ActivityName +package: your.package.name +out_dir: myproject +activity_name: ActivityName +~/android_linux_sdk/tools $ </pre> + +<p>The <code>activityCreator</code> script generates the following files and directories (but will not overwrite existing ones):</p> + +<ul> + <li><code>AndroidManifest.xml</code> The application manifest file, synced to the specified Activity class for the project.</li> + <li><code>build.xml</code> An <code>Ant</code> file that you can use to build/package the application.</li> + <li><code>src<em>/your/package/name/ActivityName</em>.java</code> The Activity class you specified on input.</li> + <li><code><em>your_activity</em>.iml, <em>your_activity</em>.ipr, + <em>your_activity</em>.iws </code> [<em>only + with the <code>-ide intelliJ</code> flag</em>] intelliJ project + files. </li> + <li><code>res/</code> A directory to hold resources. </li> + <li><code>src/</code> The source directory. + <li><code>bin/</code> The output directory for the build script.</li> +</ul> + +<p>You can now move your folder wherever you want for development, but keep in mind + that you'll have to use the <a href="{@docRoot}reference/adb.html">adb</a> program in the <code>tools/</code> folder to + send files to the emulator, so you'll need access between your solution and + the <code>tools/</code> folder. </p> + +<p>Also, you should refrain from moving the + location of the SDK directory, since this will break the build scripts (they + will need to be manually updated to reflect the new SDK location before they will + work again).</p> + +<a name="buildingwithant"></a> + +<h2>Building an Android Application</h2> +<p>Use the Ant <code>build.xml</code> file generated by + <code>activityCreator</code> to build your application.</p> +<ol> + <li>If you don't have it, you can obtain Ant from the + <a href="http://ant.apache.org/">Apache Ant home page</a>. Install it and make + sure it is on your executable path. </li> + <li>Before calling Ant, you need to declare the JAVA_HOME environment variable to specify the path to where the JDK is installed. + <p class="note"><strong>Note:</strong> When installing JDK on Windows, the default is to install in the "Program Files" directory. This location will cause <code>ant</code> to fail, because of the space. To fix the problem, you can specify the JAVA_HOME variable like this: <code>set JAVA_HOME=c:\Prora~1\Java\<jdkdir></code>. The easiest solution, however, is to install JDK in a non-space directory, for example: <code>c:\java\jdk1.6.0_02</code>. </p> + </li> + + + <li>If you have not done so already, follow the instructions for Creating a + New Project above to set up the project.</li> + <li>You can now run the Ant build file by simply typing ant in the same folder + as the build.xml file for your project. Each time you change + a source file or resource, you should run ant again and it will package up the + latest version of the application for you to deploy.</li> +</ol> + +<h2>Running an Android Application</h2> +<p>To run a compiled + application, you will upload the .apk file to the <code>/data/app/ </code>directory + in the emulator using the <a href="{@docRoot}reference/adb.html">adb</a> tool as described here:</p> +<ol> + <li>Start the emulator (run <code><em><your_sdk_dir></em>/tools/emulator</code> from the command line)</li> + <li>On the emulator, navigate to the home screen (it is best not to have that + application running when you reinstall it on the emulator; press the <strong>Home</strong> key + to navigate away from that application).</li> + <li>Run <code>adb install <em>myproject</em>/bin/<<em>appname</em>>.apk</code> to upload + the executable. So, for example, to install the Lunar Lander sample, navigate + in the command line to <code><em><your_sdk_dir></em>/sample/LunarLander</code> and type <code>../../tools/adb install bin/LunarLander.apk</code></li> + <li>In the emulator, open the list of available applications, and scroll down to + select and start your application. </li> +</ol> +<p class="note"><strong>Note:</strong> When you install an Activity for the + first time, you might have to restart the emulator before it shows up in the + application launcher, or other applications can call it. This is because + the package manager usually only examines manifests completely on emulator + startup.</p> + +<h2>Attaching a Debugger to Your Application</h2> +<p>This section describes how to display debug information on the screen (such + as CPU usage), as well as how to hook up your IDE to debug running applications + on the emulator. </p> + +<p>Attaching a debugger is automated using the Eclipse plugin, + but you can configure other IDEs to listen on a debugging port to receive debugging + information.</p> +<ol> + <li><strong>Start the <a href="{@docRoot}reference/ddms.html">Dalvik Debug Monitor Server (DDMS) + tool </a>, </strong> which + acts as a port forwarding service between your IDE and the emulator.</li> + <li><strong>Set + optional debugging configurations on + your emulator</strong>, such as blocking application startup for an activity + until a debugger is attached. Note that many of these debugging options + can be used without DDMS, such as displaying CPU usage or screen refresh + rate on the emulator.</li> + <li><strong>Configure your IDE to attach to port 8700 for debugging.</strong> We + include information on <a href="#eclipse">how to set up Eclipse to debug + your project</a>. </li> + +<a name="eclipse" id="eclipse"></a> + +</ol> +<h2>Configuring your IDE to attach to the debugging port</h2> + +<p>DDMS will assign a specific debugging port to every virtual machine that it + finds on the emulator. You must either attach your IDE to that + port (listed on the Info tab for that VM), or you can use a default port 8700 + to connect to whatever application is currently selected on the list of discovered + virtual machines.</p> +<p>Your IDE should attach to your application running on the emulator, showing you + its threads and allowing you to suspend them, inspect their state, and set breakpoints. + If you selected "Wait for debugger" in the Development settings panel + the application will run when Eclipse connects, so you will need to set any breakpoints + you want before connecting.</p> +<p>Changing either the application being debugged or the "Wait for debugger" + option causes the system to kill the selected application if it is currently + running. You can use this to kill your application if it is in a bad state + by simply going to the settings and toggling the checkbox.</p>
\ No newline at end of file diff --git a/docs/html/guide/developing/othertools.jd b/docs/html/guide/developing/othertools.jd new file mode 100755 index 0000000..4ebcf4a --- /dev/null +++ b/docs/html/guide/developing/othertools.jd @@ -0,0 +1,104 @@ +page.title=Other Tools +@jd:body + +<p>The sections below describe other tools that you can use when building Android applications. </p> + +<p>All of the tools are included in the Android SDK and are accessible from the <code>tools/</code> directory.</p> + +<h2>Contents</h2> + +<dl> + <dt><a href="#mksdcard">mksdcard</a></dt> + <dt><a href="#dx">dx</a></dt> + <dt><a href="#activitycreator">activitycreator</a></dd> +</dl> + +<a name="mksdcard"></a> + +<h2>mksdcard</h2> + +<p>The mksdcard tool lets you quickly create a FAT32 disk image that you can load in the emulator, to simulate the presence of an SD card in the device. Here is the usage for mksdcard:</p> + +<pre>mksdcard [-l label] <size>[K|M] <file></pre> + +</p>The table below lists the available options/arguments</p> + +<table> +<tr> + <th>Argument</th> + <th>Description</th> +</tr> + +<tr> + <td><code>-l</code></td> + <td>A volume label for the disk image to create. </td> +</tr> + +<tr> + <td><code>size</code></td> + <td>An integer that specifies the size (in bytes) of disk image to create. +You can also specify size in kilobytes or megabytes, by appending a "K" or "M" to <size>. For example, <code>1048576K</code>, <code>1024M</code>.</td> +</tr> + +<tr> + <td><code>file</code></td> + <td>The path/filename of the disk image to create. </td> +</tr> + +</table> + +<p>Once you have created the disk image file, you can load it in the emulator at startup using the emulator's -sdcard option. For more information, see <a href="{@docRoot}reference/emulator.html">Android Emulator</a>.</p> + +<pre>emulator -sdcard <file></pre> + +<a name="dx"></a> + +<h2>dx</h2> + +<p>The dx tool lets you generate Android bytecode from .class files. The tool converts target files and/or directories to Dalvik executable format (.dex) files, so that they can run in the Android environment. It can also dump the class files in a human-readable format and run a target unit test. You can get the usage and options for this tool by using <code>dx -help</code>.</p> + +<a name="activitycreator"></a> + +<h2>activitycreator</h2> + +<p>If you aren't using the Eclipse IDE and ADT plugin, you can use the the activitycreator script to get started with a new application. When you run the script, it creates the structure of a minimal Android application that you can build on and extend to meet your needs. </p> + +<p>For Linux and Mac, the SDK provides <code>activitycreator.py</code>, a Python script, and for Windows <code>activitycreator.bat</code>, a batch script that runs an executable. Regardless of platform, the usage for the script is the same:</p> + +<pre>activitycreator [--out <folder>] [--ide intellij] your.package.name.ActivityName</pre> + +<table> +<tr> + <th>Option</th> + <th>Description</th> +</tr> + +<tr> + <td><code>--out <folder></code></td> + <td>Specifies where to create the files/folders. </td> +</tr> + +<tr> + <td><code>--ide intellij</code></td> + <td>Creates project files for IntelliJ</td> +</tr> + +</table> + + +<p>When run, the script creates these files: </p> + + <ul> + <li>AndroidManifest.xml -- The application manifest file.</li> + <li>build.xml -- An Ant script to build/package the application.</li> + <li>res -- The resource directory.</li> + <li>src -- The source directory.</li> + <li>src/your/package/name/ActivityName.java -- The Activity class. </li> + <li>bin -- The output folder for the compiled .apk (when built by Ant).</li> +</ul> + +<p>When you are ready, you can use Ant to <a href="{@docRoot}intro/installing.html#buildingwithant">build the project</a> so that you can run it on the emulator.</p> + +<p>If you are using Eclipse with the ADT plugin, you do not need to use activitycreator. You can use the New Project Wizard, provided by the ADT plugin, instead. </p> + + diff --git a/docs/html/guide/developing/tools.jd b/docs/html/guide/developing/tools.jd new file mode 100644 index 0000000..eab005d --- /dev/null +++ b/docs/html/guide/developing/tools.jd @@ -0,0 +1,112 @@ +page.title=Tools Overview +@jd:body + +<img src="{@docRoot}images/android_icon_125.png" alt="android_robot" align="right" width="125" height="137""> + +<p>The Android SDK includes a variety of custom tools that help you develop mobile +applications on the Android platform. The most important of these are the Android +Emulator and the Android Development Tools plugin for Eclipse, but the SDK also +includes a variety of other tools for debugging, packaging, and installing your +applications on the emulator. </p> + +<dl> + <dt><a href="{@docRoot}reference/emulator.html">Android Emulator</a></dt> + <dd>A virtual mobile device that runs on your computer. You use the emulator to design, + debug, and test your applications in an actual Android run-time environment. </dd> + + <dt><a href="{@docRoot}reference/hierarchy-viewer.html">Hierarchy Viewer</a> + <sup class="new">New!</sup></dt></dt> + <dd>The Hierarchy Viewer tool allows you to debug and optimize your user interface. + It provides a visual representation of your layout's hierarchy of Views and a magnified inspector + of the current display with a pixel grid, so you can get your layout just right. + </dd> + + <dt><a href="{@docRoot}reference/draw9patch.html">Draw 9-patch</a> + <sup class="new">New!</sup></dt> + <dd>The Draw 9-patch tool allows you to easily create a + {@link android.graphics.NinePatch} graphic using a WYSIWYG editor. It also previews stretched + versions of the image, and highlights the area in which content is allowed. + </dd> + + <dt><a href="{@docRoot}intro/installing.html#installingplugin">Android + Development Tools Plugin</a> for the Eclipse IDE</dt> + <dd>The ADT plugin adds powerful extensions to the Eclipse integrated environment, + making creating and debugging your Android applications easier and faster. If you + use Eclipse, the ADT plugin gives you an incredible boost in developing Android + applications: + </dd> + + <ul> + <li>It gives you access to other Android development tools from inside + the Eclipse IDE. For example, ADT lets you access the many capabilities of the + DDMS tool — taking screenshots, managing port-forwarding, setting breakpoints, + and viewing thread and process information — directly from Eclipse. + <li>It provides a New Project Wizard, which helps you quickly create and set up + all of the basic files you'll need for a new Android application.</li> + <li>It automates and simplifies the process of building your Android application.</li> + <li>It provides an Android code editor that helps you write valid XML for your + Android manifest and resource files.</li> + </ul> + + <p>For more information about the ADT plugin, including + installation instructions, see <a + href="{@docRoot}intro/installing.html#installingplugin" + title="ADT Plugin for Eclipse">Installing the ADT Plugin for + Eclipse</a>. For a usage example with screenshots, see <a + href="{@docRoot}intro/hello-android.html" title="Hello + Android">Hello Android</a>.</p> + + <dt><a href="{@docRoot}reference/ddms.html" >Dalvik Debug Monitor + Service</a> (ddms)</dt> + <dd>Integrated with Dalvik, the Android platform's custom VM, this tool + lets you manage processes on an emulator or device and assists in debugging. + You can use it to kill processes, select a specific process to debug, + generate trace data, view heap and thread information, take screenshots + of the emulator or device, and more. </dd> + + <dt><a href="{@docRoot}reference/adb.html" >Android Debug Bridge</a> (adb)</dt> + <dd>The adb tool lets you install your application's .apk files on an + emulator or device and access the emulator or device from a command line. + You can also use it to link a standard debugger to application code running + on an Android emulator or device.</dd> + + <dt><a href="{@docRoot}reference/aapt.html" >Android Asset + Packaging Tool</a> (aapt)</dt> + <dd>The aapt tool lets you create .apk files containing the binaries and + resources of Android applications.</dd> + + <dt><a href="{@docRoot}reference/aidl.html" >Android Interface + Description Language</a> (aidl)</dt> + <dd>Lets you generate code for an interprocess interface, such as what + a service might use.</dd> + + <dt><a href="{@docRoot}reference/adb.html#sqlite">sqlite3</a></dt> + <dd>Included as a convenience, this tool lets you access the SQLite data + files created and used by Android applications.</dd> + + <dt><a href="{@docRoot}reference/traceview.html" >Traceview</a></dt> + <dd> This tool produces graphical analysis views of trace log data that you + can generate from your Android application. </dd> + + <dt><a href="{@docRoot}reference/othertools.html#mksdcard">mksdcard</a></dt> + <dd>Helps you create a disk image that you can use with the emulator, + to simulate the presence of an external storage card (such as an SD card).</dd> + + <dt><a href="{@docRoot}reference/othertools.html#dx">dx</a></dt> + <dd>The dx tool rewrites .class bytecode into Android bytecode + (stored in .dex files.)</dd> + + <dt><a href="{@docRoot}reference/monkey.html" >UI/Application + Exerciser Monkey</a></dt> + <dd>The Monkey is a program that runs on your emulator or device and generates pseudo-random + streams of user events such as clicks, touches, or gestures, as well as a number of system- + level events. You can use the Monkey to stress-test applications that you are developing, + in a random yet repeatable manner.</dd> + + <dt><a href="{@docRoot}reference/othertools.html#activitycreator">activitycreator</a></dt> + <dd>A script that generates <a + href="http://ant.apache.org/" title="Ant">Ant</a> build files that + you can use to compile your Android applications. If you are developing + on Eclipse with the ADT plugin, you won't need to use this script. </dd> +</dl> + diff --git a/docs/html/guide/developing/tools/aapt.jd b/docs/html/guide/developing/tools/aapt.jd new file mode 100644 index 0000000..40a209d --- /dev/null +++ b/docs/html/guide/developing/tools/aapt.jd @@ -0,0 +1,20 @@ +page.title=Using aapt +@jd:body + +<p><strong>aapt</strong> stands for Android Asset Packaging Tool and is included in the <code>tools/</code> directory of the SDK. This tool allows you to view, create, and update Zip-compatible archives (zip, jar, apk). It can also compile resources into binary assets. +</p> +<p> +Though you probably won't often use <strong>aapt</strong> directly, build scripts and IDE plugins can utilize this tool to package the apk file that constitutes an Android application. +</p> +<p> +For more usage details, open a terminal, go to the <code>tools/</code> directory, and run the command: +</p> +<ul> + <li><p>Linux or Mac OS X:</p> + <pre>./aapt</pre> + </li> + <li><p>Windows:</p> + <pre>aapt.exe</pre> + </li> +</ul> + diff --git a/docs/html/guide/developing/tools/adb.jd b/docs/html/guide/developing/tools/adb.jd new file mode 100644 index 0000000..25b5e29 --- /dev/null +++ b/docs/html/guide/developing/tools/adb.jd @@ -0,0 +1,668 @@ +page.title=Android Debug Bridge +@jd:body + +<p>Android Debug Bridge (adb) is a versatile tool that lets you manage the state of a device or <a href="{@docRoot}reference/emulator.html">emulator</a>. </p> + +<p>Some of ways you can use adb include:</p> + +<ul> +<li>Run shell commands on a device</li> +<li>Manage port forwarding on an emulator or device</li> +<li>Copy files to/from an emulator or device</li> +</ul> +<p>The sections below introduce adb and describe many of its common uses. </p> + +<h2>Contents</h2> +<dl> +<dt><a href="#overview">Overview</a></dt> +<dt><a href="#issuingcommands">Issuing adb Commands</a></dt> +<dt><a href="#devicestatus">Querying for Emulator/Device Instances</a></dt> +<dt><a href="#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a></dt> +<dt><a href="#move">Installing an Application</a></dt> +<dt><a href="#forwardports">Forwarding Ports</a></dt> +<dt><a href="#copyfiles">Copying Files to or from an Emulator/Device Instance</a></dt> +<dt><a href="#commandsummary">Listing of adb Commands </a></dt> +<dt><a href="#shellcommands">Issuing Shell Commands</a></dt> + <dd><a href="#sqlite">Examining sqlite3 Databases from a Remote Shell</a></dd> + <dd><a href="#monkey">UI/Application Exerciser Monkey</a></dd> + <dd><a href="#othershellcommands">Other Shell Commands</a></dd> +<dt><a href="#logcat">Enabling logcat Logging</a> </dt> + <dd><a href="#usinglogcat">Using logcat Commands</a></dd> + <dd><a href="#filteringoutput">Filtering Log Output</a></dd> + <dd><a href="#outputformat">Controlling Log Output Format</a></dd> + <dd><a href="#alternativebuffers">Viewing Alternative Log Buffers</a></dd> + <dd><a href="#stdout">Viewing stdout and stderr</a></dd> + <dd><a href="#logcatoptions">Listing of logcat Command Options</a></dd> +<dt><a href="#stopping">Stopping the adb Server</a> </dt> +</dl> + +<a name="overview"></a> + +<h2>Overview</h2> + +<p>The adb tool is a client-server program that includes three components: </p> + +<ul> + <li>A client, which runs on your development machine. You can invoke a client from a shell by issuing an adb command. Other Android tools such as the ADT plugin and DDMS also create adb clients. </li> + <li>A server, which runs as a background process on your development machine. The server manages communication between the client and the adb daemon running on an emulator or device. </li> + <li>A daemon, which runs as a background process on each emulator or device instance. </li> +</ul> + +<p>When you start an adb client, the client first checks whether there is an adb server process already running. If there isn't, it starts the server process. When the server starts, it binds to local TCP port 5037 and listens for commands sent from adb clients—all adb clients use port 5037 to communicate with the adb server. </p> + +<p>The server then sets up connections to all running emulator/device instances. It locates emulator/device instances by scanning odd-numbered ports in the range 5555 to 5585, the range used by emulators/devices. Where the server finds an adb daemon, it sets up a connection to that port. Note that each emulator/device instance acquires a pair of sequential ports — an even-numbered port for console connections and an odd-numbered port for adb connections. For example: </p> + +<blockquote> +Emulator 1, console: 5554<br/> +Emulator 1, adb: 5555<br> +Emulator 2, console: 5556<br> +Emulator 2, adb: 5557 ... +</blockquote> + +<p>As shown, the emulator instance connected to adb on port 5555 is the same as the instance whose console listens on port 5554. </p> + +<p>Once the server has set up connections to all emulator instances, you can use adb commands to control and access those instances. Because the server manages connections to emulator/device instances and handles commands from multiple adb clients, you can control any emulator/device instance from any client (or from a script).</p> + +<p>The sections below describe the commands that you can use to access adb capabilities and manage the state of an emulator/device. Note that if you are developing Android applications in Eclipse and have installed the ADT plugin, you do not need to access adb from the command line. The ADT plugin provides a trasparent integration of adb into the Eclipse IDE. However, you can still use adb directly as necessary, such as for debugging.</p> + +<a name="issuingcommands"></a> + +<h2>Issuing adb Commands</h2> + +<p>You can issue adb commands from a command line on your development machine or from a script. The usage is: </p> + + <pre>adb [-d|-e|-s <serialNumber>] <command> </pre> + +<p>When you issue a command, the program invokes an adb client. The client is not specifically associated with any emulator instance, so if multiple emulators/devices are running, you need to use the <code>-d</code> option to specify the target instance to which the command should be directed. For more information about using this option, see <a href"#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a>. </p> + +<a name="devicestatus"></a> + +<h2>Querying for Emulator/Device Instances</h2> + +<p>Before issuing adb commands, it is helpful to know what emulator/device instances are connected to the adb server. You can generate a list of attached emulators/devices using the <code>devices</code> command: </p> + + <pre>adb devices</pre> + +<p>In response, adb prints this status information for each instance:</p> + +<ul> + <li>Serial number — A string created by adb to uniquely identify an emulator/device instance by its + console port number. The format of the serial number is <code><type>-<consolePort></code>. + Here's an example serial number: <code>emulator-5554</code></li> + <li>State — The connection state of the instance. Three states are supported: + <ul> + <li><code>offline</code> — the instance is not connected to adb or is not responding.</li> + <li><code>device</code> — the instance is now connected to the adb server. Note that this state does not + imply that the Android system is fully booted and operational, since the instance connects to adb + while the system is still booting. However, after boot-up, this is the normal operational state of + an emulator/device instance.</li> + </ul> + </li> +</ul> + +<p>The output for each instance is formatted like this: </p> + + <pre>[serialNumber] [state]</pre> + +<p>Here's an example showing the <code>devices</code> command and its output:</p> + + <pre>$ adb devices +List of devices attached +emulator-5554 device +emulator-5556 device +emulator-5558 device</pre> + +<p>If there is no emulator/device running, adb returns <code>no device</code>.</p> + + +<a name="directingcommands"></a> + +<h2>Directing Commands to a Specific Emulator/Device Instance</h2> + +<p>If multiple emulator/device instances are running, you need to specify a target instance when issuing adb commands. To so so, use the <code>-s</code> option in the commands. The usage for the <code>-s</code> option is:</p> + + <pre>adb -s <serialNumber> <command> </pre> + +<p>As shown, you specify the target instance for a command using its adb-assigned serial number. You can use the <code>devices</code> command to obtain the serial numbers of running emulator/device instances. </p> + +<p>Here is an example: </p> + + <pre>adb -s emulator-5556 install helloWorld.apk</pre> + +<p>Note that, if you issue a command without specifying a target emulator/device instance using <code>-s</code>, adb generates an error. + +<a name="move"></a> + +<h2>Installing an Application</h2> +<p>You can use adb to copy an application from your development computer and install it on an emulator/device instance. To do so, use the <code>install</code> command. With the command, you must specify the path to the .apk file that you want to install:</p> + +<pre>adb install <path_to_apk></pre> + +<p>For more information about how to create an .apk file that you can install on an emulator/device instance, see <a href="{@docRoot}reference/aapt.html">Android Asset Packaging Tool</a> (aapt). </p> + +<p>Note that, if you are using the Eclipse IDE and have the ADT plugin installed, you do not need to use adb (or aapt) directly to install your application on the emulator/device. Instead, the ADT plugin handles the packaging and installation of the application for you. </p> + + +<a name="forwardports"></a> + +<h2>Forwarding Ports</h2> + + <p>You can use the <code>forward</code> command to set up arbitrary port forwarding — forwarding of requests on a specific host port to a different port on an emulator/device instance. Here's how you would set up forwarding of host port 6100 to emulator/device port 7100:</p> +<pre>adb forward tcp:6100 tcp:7100</pre> + <p>You can also use adb to set up forwarding to named abstract UNIX domain sockets, as illustrated here:</p> +<pre>adb forward tcp:6100 local:logd </pre> + +<a name="copyfiles"></a> + +<h2>Copying Files to or from an Emulator/Device Instance</h2> + +<p>You can use the adb commands <code>pull</code> and <code>push</code> to copy files to and from an emulator/device instance's data file. Unlike the <code>install</code> command, which only copies an .apk file to a specific location, the <code>pull</code> and <code>push</code> commands let you copy arbitrary directories and files to any location in an emulator/device instance. </p> + +<p>To copy a file or directory (recursively) <em>from</em> the emulator or device, use</p> +<pre>adb pull <remote> <local></pre> + +<p>To copy a file or directory (recursively) <em>to</em> the emulator or device, use</p> + <pre>adb push <local> <remote></pre> + +<p>In the commands, <code><local></code> and <code><remote></code> refer to the paths to the target files/directory on your development machine (local) and on the emulator/device instance (remote).</p> + +<p>Here's an example: </p> +<pre>adb push foo.txt /sdcard/foo.txt</pre> + +<a name="commandsummary"></a> + +<h2>Listing of adb Commands</h2> + +<p>The table below lists all of the supported adb commands and explains their meaning and usage. </p> + + +<table> +<tr> + <th>Category</th> + <th>Command</th> + <th>Description</th> + <th>Comments</th> +</tr> + +<tr> +<td rowspan="3">Options</td> +<td><code>-d</code></td> +<td>Direct an adb command to the only attached USB device.</td> +<td>Returns an error if more than one USB device is attached.</td> +</tr> + +<tr> +<td><code>-e</code></td> +<td>Direct an adb command to the only running emulator instance.</td> +<td>Returns an error if more than one emulator instance is running. </td> +</tr> + +<tr> +<td><code>-s <serialNumber></code></td> +<td>Direct an adb command a specific emulator/device instance, referred to by its adb-assigned serial number (such as "emulator-5556").</td> +<td>If not specified, adb generates an error.</td> +</tr> + +<tr> +<td rowspan="3">General</td> +<td><code>devices</code></td> +<td>Prints a list of all attached emulator/device instances.</td> +<td>See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information.</td> +</tr> + +<tr> +<td><code>help</code></td> +<td>Prints a list of supported adb commands.</td> +<td> </td> +</tr> + +<tr> +<td><code>version</code></td> +<td>Prints the adb version number. </td> +<td> </td> +</tr> + +<tr> +<td rowspan="3">Debug</td> +<td ><code>logcat [<option>] [<filter-specs>]</code></td> +<td>Prints log data to the screen. </td> +<td> </td> +</tr> + +<tr> +<td><code>bugreport</code></td> +<td>Prints <code>dumpsys</code>, <code>dumpstate</code>, and <code>logcat</code> data to the screen, for the purposes of bug reporting. </td> +<td> </td> +</tr> + +<tr> +<td><code>jdwp</code></td> +<td>Prints a list of available JDWP processes on a given device. </td> +<td>You can use the <code>forward jdwp:<pid></code> port-forwarding specification to connect to a specific JDWP process. For example: <br> + <code>adb forward tcp:8000 jdwp:472</code><br> + <code>jdb -attach localhost:8000</code></p> + </td> +</tr> + +<tr> +<td rowspan=3">Data</td> +<td><code>install <path-to-apk></code></td> +<td>Pushes an Android application (specified as a full path to an .apk file) to the data file of an emulator/device. </td> +<td> </td> +</tr> + +<tr> +<td><code>pull <remote> <local></code></td> +<td>Copies a specified file from an emulator/device instance to your development computer. </td> +<td> </td> +</tr> + +<tr> +<td><code>push <local> <remote></code></td> +<td>Copies a specified file from your development computer to an emulator/device instance. </td> +<td> </td> +</tr> + +<tr> +<td rowspan="2">Ports and Networking</td> +<td><code>forward <local> <remote></code></td> +<td>Forwards socket connections from a specified local port to a specified remote port on the emulator/device instance. </td> +<td>Port specifications can use these schemes: +<ul><li><code>tcp:<portnum></code></li> +<li><code>local:<UNIX domain socket name></code></li> +<li><code>dev:<character device name></code></li> +<li><code>jdwp:<pid></code></li></ul> +</td> +</tr> + +<tr> +<td><code>ppp <tty> [parm]...</code></td> +<td>Run PPP over USB. +<ul> +<li><code><tty></code> — the tty for PPP stream. For example <code>dev:/dev/omap_csmi_ttyl</code>. </li> +<li><code>[parm]... </code> &mdash zero or more PPP/PPPD options, such as <code>defaultroute</code>, <code>local</code>, <code>notty</code>, etc.</li></ul> + +<p>Note that you should not automatically start a PDP connection. </p></td> +<td></td> +</tr> + +<tr> +<td rowspan="3">Scripting</td> +<td><code>get-serialno</code></td> +<td>Prints the adb instance serial number string.</td> +<td rowspan="2">See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information. </td> +</tr> + +<tr> +<td><code>get-state</code></td> +<td>Prints the adb state of an emulator/device instance.</td> +</td> +</tr> + +<tr> +<td><code>wait-for-device</code></td> +<td>Blocks execution until the device is online — that is, until the instance state is <code>device</code>.</td> +<td>You can prepend this command to other adb commands, in which case adb will wait until the emulator/device instance is connected before issuing the other commands. Here's an example: +<pre>adb wait-for-device shell getprop</pre> + +Note that this command does <em>not</em> cause adb to wait until the entire system is fully booted. For that reason, you should not prepend it to other commands that require a fully booted system. As an example, the <code>install</code> requires the Android package manager, which is available only after the system is fully booted. A command such as + +<pre>adb wait-for-device install <app>.apk</pre> + +would issue the <code>install</code> command as soon as the emulator or device instance connected to the adb server, but before the Android system was fully booted, so it would result in an error. </td> +</tr> + + + +<tr> +<td rowspan="2">Server</td> +<td><code>start-server</code></td> +<td>Checks whether the adb server process is running and starts it, if not.</td> +<td> </td> +</tr> + +<tr> +<td><code>kill-server</code></td> +<td>Terminates the adb server process.</td> +<td> </td> +</tr> + + + +<tr> +<td rowspan="2">Shell</td> +<td><code>shell</code></td> +<td>Starts a remote shell in the target emulator/device instance.</td> +<td rowspan="2">See <a href="#shellcommands">Issuing Shell Commands</a> for more information. </td> +</tr> + +<tr> +<td><code>shell [<shellCommand>]</code></td> +<td>Issues a shell command in the target emulator/device instance and then exits the remote shell.</td> +</tr> + +</table> + + +<a name="shellcommands"></a> + +<h2>Issuing Shell Commands</h2> + +<p>Adb provides an ash shell that you can use to run a variety of commands on an emulator +or device. The command binaries are stored in the file system of the emulator or device, +in this location: </p> + +<pre>/system/bin/...</pre> + +<p>You can use the <code>shell</code> command to issue commands, with or without entering the adb remote shell on the emulator/device. </p> + +<p>To issue a single command without entering a remote shell, use the <code>shell</code> command like this: </p> + + <pre>adb [-d|-e|-s {<serialNumber>}] shell <shellCommand></pre> + +<p>To drop into a remote shell on a emulator/device instance, use the <code>shell</code> command like this:</p> + + <pre>adb [-d|-e|-s {<serialNumber>}] shell</pre> + +<p>When you are ready to exit the remote shell, use <code>CTRL+D</code> or <code>exit</code> to end the shell session. </p> + +<p>The sections below provide more information about shell commands that you can use.</p> + +<a name="sqlite" id="sqlite"></a> + +<h3>Examining sqlite3 Databases from a Remote Shell</h3> + +<p>From an adb remote shell, you can use the +<a href="http://www.sqlite.org/sqlite.html">sqlite3</a> command-line program to +manage SQLite databases created by Android applications. The +<code>sqlite3</code> tool includes many useful commands, such as +<code>.dump</code> to print out the contents of a table and +<code>.schema</code> to print the SQL CREATE statement for an existing table. +The tool also gives you the ability to execute SQLite commands on the fly.</p> + +<p>To use <code>sqlite3</code>, enter a remote shell on the emulator instance, as described above, then invoke the tool using the <code>sqlite3</code> command. Optionally, when invoking <code>sqlite3</code> you can specify the full path to the database you want to explore. Emulator/device instances store SQLite3 databases in the folder <code><span chatdir="1"><span chatindex="259474B4B070F261">/data/data/<em><package_name></em>/databases</span></span>/</code>. </p> + +<p>Here's an example: </p> + +<pre>$ adb -s emulator-5554 shell +# sqlite3 /data/data/com.example.google.rss.rssexample/databases/rssitems.db +SQLite version 3.3.12 +Enter ".help" for instructions +<em>.... enter commands, then quit...</em> +sqlite> .exit </pre> + +<p>Once you've invoked <code>sqlite3</code>, you can issue <code>sqlite3</code> commands in the shell. To exit and return to the adb remote shell, use <code>exit</code> or <code>CTRL+D</code>. + + +<a name="monkey"></a> + +<h3>UI/Application Exerciser Monkey</h3> + +<p>The Monkey is a program that runs on your emulator or device and generates pseudo-random +streams of user events such as clicks, touches, or gestures, as well as a number of system-level +events. You can use the Monkey to stress-test applications that you are developing, +in a random yet repeatable manner.</p> + +<p>The simplest way to use the monkey is with the following command, which will launch your +application and send 500 pseudo-random events to it.</p> + +<pre>$ adb shell monkey -v -p your.package.name 500</pre> + +<p>For more information about command options for Monkey, see the complete +<a href="{@docRoot}reference/monkey.html" title="monkey">UI/Application Exerciser Monkey</a> documentation page.</p> + + +<a name="othershellcommands"></a> + +<h3>Other Shell Commands</h3> + +<p>The table below lists several of the adb shell commands available. For a complete list of commands and programs, start an emulator instance and use the <code>adb -help</code> command. </p> + +<pre>adb shell ls /system/bin</pre> + +<p>Help is available for most of the commands. </p> + +<table> +<tr> + <th>Shell Command</th> + <th>Description</th> + <th>Comments</th> +</tr> + +<tr> +<td><code>dumpsys</code></td> +<td>Dumps system data to the screen.</td> +<td rowspan=4">The <a href="{@docRoot}reference/ddms.html">Dalvik Debug Monitor Service</a> (DDMS) tool offers integrated debug environment that you may find easier to use.</td> +</tr> + +<tr> +<td><code>dumpstate</code></td> +<td>Dumps state to a file.</td> +</tr> + +<tr> +<td><code>logcat [<option>]... [<filter-spec>]...</code></td> +<td>Enables radio logging and prints output to the screen. </td> +</tr> + +<tr> +<td><code>dmesg</code></td> +<td>Prints kernel debugging messages to the screen. </td> +</tr> + +<tr> +<td><code>start</code></td> +<td>Starts (restarts) an emulator/device instance.</td> +<td> </td> +</tr> + +<tr> +<td><code>stop</code></td> +<td>Stops execution of an emulator/device instance.</td> +<td> </td> +</tr> + +</table> + +<a name="logcat"></a> + +<h2>Enabling logcat Logging</h2> + +<p>The Android logging system provides a mechanism for collecting and viewing system debug output. Logs from various applications and portions of the system are collected in a series of circular buffers, which then can be viewed and filtered by the <code>logcat</code> command.</p> + +<a name="usinglogcat"></a> + +<h3>Using logcat Commands</h3> + +<p>You can use the <code>logcat</code> command to view and follow the contents of the system's log buffers. The general usage is:</p> + +<pre>[adb] logcat [<option>] ... [<filter-spec>] ...</pre> + +<p>The sections below explain filter specifications and the command options. See <a href="#logcatoptions">Listing of logcat Command Options</a> for a summary of options. </p> + +<p>You can use the <code>logcat</code> command from your development computer or from a remote adb shell in an emulator/device instance. To view log output in your development computer, you use</p> + +<pre>$ adb logcat</pre> + +<p>and from a remote adb shell you use</p> + +<pre># logcat</pre> + +<a name="filteringoutput"></a> + +<h3>Filtering Log Output</h3> + +<p>Every Android log message has a <em>tag</em> and a <em>priority</em> associated with it. </p> + +<ul> +<li>The tag of a log message is a short string indicating the system component from which the message originates (for example, "View" for the view system). </li> + +<li>The priority is one of the following character values, ordered from lowest to highest priority:</li> + +<ul> + <li><code>V</code> — Verbose (lowest priority)</li> + <li><code>D</code> — Debug</li> + <li><code>I</code> — Info</li> + <li><code>W</code> — Warning</li> + <li><code>E</code> — Error</li> + <li><code>F</code> — Fatal</li> + <li><code>S</code> — Silent (highest priority, on which nothing is ever printed)</li> +</ul> +</ul> + +<p>You can obtain a list of tags used in the system, together with priorities, by running <code>logcat</code> and observing the first two columns +of each message, given as <code><priority>/<tag></code>. </p> + +<p>Here's an example of logcat output that shows that the message relates to priority level "I" and tag "ActivityManager":</p> + +<pre>I/ActivityManager( 585): Starting activity: Intent { action=android.intent.action...}</pre> + +<p>To reduce the log output to a manageable level, you can restrict log output using <em>filter expressions</em>. Filter expressions let you indicate to the system the tags-priority combinations that you are interested in — the system suppresses other messages for the specified tags. </p> + +<p>A filter expression follows this format <code>tag:priority ...</code>, where <code>tag</code> indicates the tag of interest and <code>priority</code> indicates the <em>minimum</em> level of priority to report for that tag. Messages for that tag at or above the specified priority are written to the log. You can supply any number of <code>tag:priority</code> specifications in a single filter expression. The series of specifications is whitespace-delimited. </p> + +<p>Here's an example of a filter expression that suppresses all log messages except those with the tag "ActivityManager", at priority "Info" or above, and all log messages with tag "MyApp", with priority "Debug" or above:</p> + +<pre>adb logcat ActivityManager:I MyApp:D *:S</pre> + +<p>The final element in the above expression, <code>*:S</code>, sets the priority level for all tags to "silent", thus ensuring only log messages with "View" and "MyApp" are displayed. Using <code>*:S</code> is an excellent way to ensure that log output is restricted to the filters that you have explicitly specified — it lets your filters serve as a "whitelist" for log output.</p> + +<p>The following filter expression displays all log messages with priority level "warning" and higher, on all tags:</p> + +<pre>adb logcat *:W</pre> + +<p>If you're running <code>logcat</code> from your development computer (versus running it on a remote adb shell), you can also set a default filter expression by exporting a value for the environment variable <code>ANDROID_LOG_TAGS</code>:</p> + +<pre>export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"</pre> + +<p>Note that <code>ANDROID_LOG_TAGS</code> filter is not exported to the emulator/device instance, if you are running <code>logcat</code> from a remote shell or using <code>adb shell logcat</code>.</p> + + +<a name="outputformat"></a> + +<h3>Controlling Log Output Format</h3> + +<p>Log messages contain a number of metadata fields, in addition to the tag and priority. You can modify the output format for messages so that they display a specific metadata field. To do so, you use the <code>-v</code> option and specify one of the supported output formats listed below. </p> + +<ul> + <li><code>brief</code> — Display priority/tag and PID of originating process (the default format).</li> + <li><code>process</code> — Display PID only.</li> + <li><code>tag</code> — Display the priority/tag only. </li> + <li><code>thread</code> — Display process:thread and priority/tag only. </li> + <li><code>raw</code> — Display the raw log message, with no other metadata fields.</li> + <li><code>time</code> — Display the date, invocation time, priority/tag, and PID of the originating process.</li> + <li><code>long</code> — Display all metadata fields and separate messages with a blank lines.</li> +</ul> + +<p>When starting <code>logcat</code>, you can specify the output format you want by using the <code>-v</code> option:</p> + +<pre>[adb] logcat [-v <format>]</pre> + +<p>Here's an example that shows how to generate messages in <code>thread</code> output format: </p> + +<pre>adb logcat -v thread</pre> + +<p>Note that you can only specify one output format with the <code>-v</code> option. </p> + +<a name="alternativebuffers"></a> + +<h3>Viewing Alternative Log Buffers </h3> + +<p>The Android logging system keeps multiple circular buffers for log messages, and not all of the log messages are sent to the default circular buffer. To see additional log messages, you can start <code>logcat</code> with the <code>-b</code> option, to request viewing of an alternate circular buffer. You can view any of these alternate buffers: </p> + +<ul> +<li><code>radio</code> — View the buffer that contains radio/telephony related messages.</li> +<li><code>events</code> — View the buffer containing events-related messages.</li> +<li><code>main</code> — View the main log buffer (default)</li> +</ul> + +<p>The usage of the <code>-b</code> option is:</p> + +<pre>[adb] logcat [-b <buffer>]</pre> + +<p>Here's an example of how to view a log buffer containing radio and telephony messages: </p> + +<pre>adb logcat -b radio</b></pre> + +<a name="stdout"></a> + +<h3>Viewing stdout and stderr</h3> + +<p>By default, the Android system sends <code>stdout</code> and <code>stderr</code> (<code>System.out</code> and <code>System.err</code>) output to <code>/dev/null</code>. In +processes that run the Dalvik VM, you can have the system write a copy of the output to the log file. In this case, the system writes the messages to the log using the log tags <code>stdout</code> and <code>stderr</code>, both with priority <code>I</code>. </p> + +<p>To route the output in this way, you stop a running emulator/device instance and then use the shell command <code>setprop</code> to enable the redirection of output. Here's how you do it: </p> + +<pre>$ adb shell stop +$ adb shell setprop log.redirect-stdio true +$ adb shell start</pre> + +<p>The system retains this setting until you terminate the emulator/device instance. To use the setting as a default on the emulator/device instance, you can add an entry to <code>/data/local.prop</code> +on the device.</p> + +<a name="logcatoptions"></a> + +<h3>Listing of logcat Command Options</h3> + +<table> +<tr> + <th>Option</th> + <th>Description</th> +</tr> + +<tr> +<td><code>-b <buffer></code></td> +<td>Loads an alternate log buffer for viewing, such as <code>event</code> or <code>radio</code>. The <code>main</code> buffer is used by default. See <a href="#alternativebuffers">Viewing Alternative Log Buffers</a>.</td> +</tr> + +<tr> +<td><code>-c</code></td> +<td>Clears (flushes) the entire log and exits. </td> +</tr> + +<tr> +<td><code>-d</code></td> +<td>Dumps the log to the screen and exits.</td> +</tr> + +<tr> +<td><code>-f <filename></code></td> +<td>Writes log message output to <code><filename></code>. The default is <code>stdout</code>.</td> +</tr> + +<tr> +<td><code>-g</code></td> +<td>Prints the size of the specified log buffer and exits. </td> +</tr> + +<tr> +<td><code>-n <count></code></td> +<td>Sets the maximum number of rotated logs to <code><count></code>. The default value is 4. Requires the <code>-r</code> option. </td> +</tr> + +<tr> +<td><code>-r <kbytes></code></td> +<td>Rotates the log file every <code><kbytes></code> of output. The default value is 16. Requires the <code>-f</code> option. </td> +</tr> + +<tr> +<td><code>-s</code></td> +<td>Sets the default filter spec to silent. </td> +</tr> + +<tr> +<td><code>-v <format></code></td> +<td>Sets the output format for log messages. The default is <code>brief</code> format. For a list of supported formats, see <a href="#outputformat">Controlling Log Output Format</a>.</td> +</tr> + +</table> + +<a name="stopping"></a> + +<h2>Stopping the adb Server</h2> + +<p>In some cases, you might need to terminate the adb server process and then restart it. For example, if adb does not respond to a command, you can terminate the server and restart it and that may resolve the problem. </p> + +<p>To stop the adb server, use the <code>kill-server</code>. You can then restart the server by issuing any adb command. </p> + + diff --git a/docs/html/guide/developing/tools/aidl.jd b/docs/html/guide/developing/tools/aidl.jd new file mode 100755 index 0000000..145fd93 --- /dev/null +++ b/docs/html/guide/developing/tools/aidl.jd @@ -0,0 +1,301 @@ +page.title=Designing a Remote Interface Using AIDL +@jd:body + +<p>Since each application runs in its own process, and you can write a service that +runs in a different process from your Application's UI, sometimes you need to pass objects +between processes. On the Android platform, one process can not normally access the memory +of another process. So to talk, they need to decompose their objects into primitives that +the operating system can understand, and "marshall" the object across that boundary for you.</p> + +<p>The code to do that marshalling is tedious to write, so we provide the AIDL tool to do it +for you.</p> + +<p> AIDL (Android Interface Definition Language) is an <a +href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</a> +language used to generate code that enables two processes on an Android-powered device +to talk using interprocess communication (IPC). If you have code +in one process (for example, in an Activity) that needs to call methods on an +object in another process (for example, a Service), you would use AIDL to +generate code to marshall the parameters.</p> +<p>The AIDL IPC mechanism + is interface-based, similar to COM or Corba, but lighter weight. It uses a proxy + class to pass values between the client and the implementation. </p> +<p>This page includes the following main topics: </p> +<ul> + <li><a href="#implementing">Implementing IPC Using AIDL</a></li> + <li><a href="#calling">Calling an .aidl (IPC) Class </a></li> +</ul> +<h2>Implementing IPC Using AIDL <a name="implementing"></a></h2> +<p>Follow these steps to implement an IPC service using AIDL.</p> +<ol> + <li><strong><a href="#aidlsyntax">Create your .aidl file</a> </strong>- This + file defines an interface (<em>YourInterface</em>.aidl) that defines the + methods and fields available to a client. </li> + <li><strong>Add the .aidl file to your makefile</strong> - (the <a href="{@docRoot}intro/installing.html#developingwitheclipse">Eclipse + plugin</a> manages this for you). Android includes the compiler, called + AIDL, in the <code>tools/</code> directory. </li> + <li><strong><a href="#implementtheinterface">Implement your interface methods</a></strong> - + The AIDL compiler creates an interface in the Java programming language from your AIDL interface. + This interface has an inner abstract class named Stub that inherits the + interface (and implements a few additional methods necessary for the IPC + call). You must create a class that extends <em>YourInterface</em>.Stub + and implements the methods you declared in your .aidl file. </li> + <li><strong><a href="#exposingtheinterface">Expose your interface to clients</a></strong> - + If you're writing a service, you should extend {@link + android.app.Service Service} and override {@link android.app.Service#onBind + Service.onBind(Intent)} to return an instance of your class that implements your + interface. </li> +</ol> +<h3>Create an .aidl File <a name="aidlsyntax"></a></h3> +<p>AIDL is a simple syntax that lets you declare an interface with one or more + methods, that can take parameters and return values. These parameters and return + values can be of any type, even other AIDL-generated interfaces. <em>However, it + is important to note</em> that you <em>must</em> import all non-built-in types, + <em>even if they are defined in the same package as your interface</em>. + Here are the data types that AIDL can support: </p> +<ul> + <li>Primitive Java programming language types (int, boolean, etc) + — No <code>import</code> statement is needed. </li> + <li>One of the following classes (no <code>import</code> statements needed): + <ul> + <li><strong>String</strong></li> + <li><strong>List</strong> - All elements in the List must be one of the types + in this list, including other AIDL-generated interfaces and + parcelables. List may optionally be used as a "generic" class (e.g. + List<String>). + The actual concrete class that the other side will receive + will always be an ArrayList, although the method will be generated + to use the List interface. </li> + <li><strong>Map</strong> - All elements in the Map must be of one of the + types in this list, including other AIDL-generated interfaces and + parcelables. Generic maps, (e.g. of the form Map<String,Integer> + are not supported. + The actual concrete class that the other side will receive + will always be a HashMap, although the method will be generated + to use the Map interface.</li> + <li><strong>CharSequence</strong> - This is useful for the CharSequence + types used by {@link android.widget.TextView TextView} and other + widget objects. </li> + </ul> + </li> + <li>Other AIDL-generated interfaces, which are always passed by reference. + An <code>import</code> statement is always needed for these.</li> + <li>Custom classes that implement the <a href="#parcelable">Parcelable + protocol</a> and are passed by value. + An <code>import</code> statement is always needed for these.</li> +</ul> +<p>Here is the basic AIDL syntax:</p> +<pre>// My AIDL file, named <em>SomeClass</em>.aidl +// Note that standard comment syntax is respected. +// Comments before the import or package statements are not bubbled up +// to the generated interface, but comments above interface/method/field +// declarations are added to the generated interface. + +// Include your fully-qualified package statement. +package com.android.sample; + +// See the list above for which classes need +// import statements (hint--most of them) +import com.android.sample.IAtmService; + +// Declare the interface. +interface IBankAccountService { + + // Methods can take 0 or more parameters, and + // return a value or void. + int getAccountBalance(); + void setOwnerNames(in List<String> names); + + // Methods can even take other AIDL-defined parameters. + BankAccount createAccount(in String name, int startingDeposit, in IAtmService atmService); + + // All non-Java primitive parameters (e.g., int, bool, etc) require + // a directional tag indicating which way the data will go. Available + // values are in, out, inout. (Primitives are in by default, and cannot be otherwise). + // Limit the direction to what is truly needed, because marshalling parameters + // is expensive. + int getCustomerList(in String branch, out String[] customerList); +}</pre> + +<h3>Implementing the Interface <a name="implementtheinterface"></a></h3> +<p>AIDL generates an interface file for you with the same name as your .aidl + file. If you are using the Eclipse plugin, AIDL will automatically be run as part of + the build process (you don't need to run AIDL first and then build your project). + If you are not using the plugin, you should run AIDL first. </p> +<p>The generated interface + includes an abstract inner class named Stub that declares all the methods + that you declared in your .aidl file. Stub also defines a few helper methods, + most notably asInterface(), which takes an IBinder (passed to a client's onServiceConnected() + implementation when applicationContext.bindService() succeeds), and returns an + instance of the interface used to call the IPC methods. See the section + <a href="#calling">Calling an IPC Method</a> for more details on how to make this cast.</p> +<p>To implement your interface, extend <em>YourInterface</em>.Stub, + and implement the methods. (You can create the .aidl file and implement the stub + methods without building between--the Android build process will process .aidl +files before .java files.) </p> +<p>Here is an example of implementing an interface called IRemoteService, which exposes + a single method, getPid(), using an anonymous instance:</p> +<pre>// No need to import IRemoteService if it's in the same project. +private final IRemoteService.Stub mBinder = new IRemoteService.Stub(){ + public int getPid(){ + return Process.myPid(); + } +}</pre> +<p>A few rules about implementing your interface: </p> +<ul> + <li>No exceptions that you throw will be sent back to the caller.</li> + <li>IPC calls are synchronous. If you know that an IPC service takes more than + a few milliseconds to complete, you should not call it in the Activity/View thread, + because it might hang the application (Android might display an "Application + is Not Responding" dialog). + Try to call them in a separate thread. </li> + <li>Only methods are supported; you cannot declare static fields in an AIDL interface.</li> +</ul> + +<h3>Exposing Your Interface to Clients<a name="exposingtheinterface" id="exposingtheinterface"></a></h3> +<p>Now that you've got your interface implementation, you need to expose it to clients. + This is known as "publishing your service." To publish a service, + inherit {@link android.app.Service Service} and implement {@link android.app.Service#onBind + Service.onBind(Intent)} to return an instance of the class that implements your interface. + Here's a code snippet of a service that exposes the IRemoteService + interface to clients. </p> +<pre>public class RemoteService extends Service { +... +{@include development/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.java exposing_a_service} +}</pre> + +<a name="parcelable"></a> +<h3>Pass by value Parameters using Parcelables</h3> + +<p>If you have a class that you would like to send from one process to another through +an AIDL interface, you can do that. You must ensure that the code for your class is available +to the other side of the IPC. Generally, that means that you're talking to a service that you +started.</p> +<p>There are five parts to making a class support the Parcelable protocol:</b> +<ol> +<li>Make your class implement the {@link android.os.Parcelable} interface.</li> +<li>Implement the method <code>public void writeToParcel(Parcel out)</code> that takes the +current state of the object and writes it to a parcel.</li> +<li>Implement the method <code>public void readFromParcel(Parcel in)</code> that reads the +value in a parcel into your object.</li> +<li>Add a static field called <code>CREATOR</code> to your class which is an object implementing +the {@link android.os.Parcelable.Creator Parcelable.Creator} interface.</li> +<li>Last but not least: +<ul> +<li>If you are developing with Eclipse/ADT, follow these steps: +<ol type="a"> +<li>In the Package Explorer view, right-click on the project.</li> +<li>Choose <strong>Android Tools</strong> > <strong>Create Aidl preprocess file +for Parcelable classes</strong>.</li> +<li>This will create a file called "project.aidl" in the root of the project. +The file will be automatically used when compiling an aidl file that uses the +parcelable classes.</li> +</ol> +</li> +<li>If you are developing with Ant or are using a custom build process, create an aidl file +that declares your parcelable class (as shown below). If you are using a custom build process, +do not add the aidl file to your build. Similar to a header file in C, the aidl file isn't +compiled.</li> +</ul> +</li> +</ul> +<p>AIDL will use these methods and fields in the code it generates to marshall and unmarshall +your objects.</p> +<p>Here is an example of how the {@link android.graphics.Rect} class implements the +Parcelable protocol.</p> + +<pre class="prettyprint"> +import android.os.Parcel; +import android.os.Parcelable; + +public final class Rect implements Parcelable { + public int left; + public int top; + public int right; + public int bottom; + + public static final Parcelable.Creator<Rect> CREATOR = new Parcelable.Creator<Rect>() { + public Rect createFromParcel(Parcel in) { + return new Rect(in); + } + + public Rect[] newArray(int size) { + return new Rect[size]; + } + }; + + public Rect() { + } + + private Rect(Parcel in) { + readFromParcel(in); + } + + public void writeToParcel(Parcel out) { + out.writeInt(left); + out.writeInt(top); + out.writeInt(right); + out.writeInt(bottom); + } + + public void readFromParcel(Parcel in) { + left = in.readInt(); + top = in.readInt(); + right = in.readInt(); + bottom = in.readInt(); + } +} +</pre> + +<p>Here is Rect.aidl for this example</p> + +<pre class="prettyprint"> +package android.graphics; + +// Declare Rect so AIDL can find it and knows that it implements +// the parcelable protocol. +parcelable Rect; +</pre> + +<p>The marshalling in the Rect class is pretty simple. Take a look at the other +methods on {@link android.os.Parcel} to see the other kinds of values you can write +to a Parcel.</p> + +<p class="warning"><b>Warning:</b> Don't forget the security implications of receiving data from +other processes. In this case, the rect will read four numbers from the parcel, +but it is up to you to ensure that these are within the acceptable range of +values for whatever the caller is trying to do. See +<a href="{@docRoot}devel/security.html">Security and Permissions in Android</a> for more +on how to keep your application secure from malware.</p> + +<h2>Calling an IPC Method <a name="calling"></a></h2> +<p>Here are the steps a calling class should make to call your remote interface: </p> +<ol> + <li>Declare a variable of the interface type that your .aidl file defined. </li> + <li>Implement {@link android.content.ServiceConnection ServiceConnection}. </li> + <li>Call {@link android.content.Context#bindService(android.content.Intent,android.content.ServiceConnection,int) + Context.bindService()}, passing in your ServiceConnection implementation. </li> + <li>In your implementation of {@link android.content.ServiceConnection#onServiceConnected(android.content.ComponentName,android.os.IBinder) + ServiceConnection.onServiceConnected()}, you will receive an {@link android.os.IBinder + IBinder} instance (called <em>service</em>). Call <code><em>YourInterfaceName</em>.Stub.asInterface((IBinder)<em>service</em>)</code> to + cast the returned parameter to <em>YourInterface</em> type.</li> + <li>Call the methods that you defined on your interface. You should always trap + {@link android.os.DeadObjectException} exceptions, which are thrown when + the connection has broken; this will be the only exception thrown by remote + methods.</li> + <li>To disconnect, call {@link android.content.Context#unbindService(android.content.ServiceConnection) + Context.unbindService()} with the instance of your interface. </li> +</ol> +<p>A few comments on calling an IPC service:</p> +<ul> + <li>Objects are reference counted across processes. </li> + <li>You can send anonymous objects + as method arguments. </li> +</ul> +<p>Here is some sample code demonstrating calling an AIDL-created service, taken + from the Remote Activity sample in the ApiDemos project.</p> +<p>{@sample development/samples/ApiDemos/src/com/example/android/apis/app/RemoteServiceBinding.java + exposing_a_service}</p> + + + diff --git a/docs/html/guide/developing/tools/ddms.jd b/docs/html/guide/developing/tools/ddms.jd new file mode 100644 index 0000000..79ae66a --- /dev/null +++ b/docs/html/guide/developing/tools/ddms.jd @@ -0,0 +1,250 @@ +page.title=Using Dalvik Debug Monitor Service (DDMS) +@jd:body + +<p>Android ships with a debugging tool called the Dalvik Debug Monitor Service (DDMS), + which provides port-forwarding services, screen capture on the device, thread + and heap information on the device, logcat, process, and radio state information, + incoming call and SMS spoofing, location data spoofing, and more. This page + provides a modest discussion of DDMS features; it is not an exhaustive exploration of + all the features and capabilities.</p> + +<p>DDMS ships in the <code>tools/</code> directory of the SDK. + Enter this directory from a terminal/console and type <code>ddms</code> (or <code>./ddms</code> + on Mac/Linux) to run it. DDMS will work with both the emulator and a connected device. If both are + connected and running simultaneously, DDMS defaults to the emulator.</p> + +<h2 id="how-ddms-works">How DDMS works</h2> +<p>DDMS acts as a middleman to connect the IDE to the applications running on +the device. On Android, every application runs in its own process, +each of which hosts its own virtual machine (VM). And each process +listens for a debugger on a different port.</p> + +<p>When it starts, DDMS connects to <a href="{@docRoot}reference/adb.html">adb</a> and +starts a device monitoring service between the two, which will notify DDMS when a device is +connected or disconnected. When a device is connected, a VM monitoring service is created +between adb and DDMS, which will notify DDMS when a VM on the device is started +or terminated. Once a VM is running, DDMS retrieves the the VM's process ID (pid), via adb, +and opens a connection to the VM's debugger, through the adb daemon (adbd) on the device. +DDMS can now talk to the VM using a custom wire protocol.</p> + +<p>For each VM on the device, DDMS opens a port upon which it will listen for a debugger. For the first VM, DDMS listens for a debugger on port 8600, the next on 8601, and so on. When a debugger connects to one of these ports, all traffic is forwarded between the debugger and the associated VM. Debugging can then process like any remote debugging session.</p> + +<p>DDMS also opens another local port, the DDMS "base port" (8700, by default), upon which it also listens for a debugger. When a debugger connects to this base port, all traffic is forwarded to the VM currently selected in DDMS, so this is typically where you debugger should connect.</p> + +<p>For more information on port-forwarding with DDMS, +read <a href="{@docRoot}intro/installing.html#eclipse">Configuring your IDE to attach +to port 8700 for debugging</a>.</p> + +<p class="note"><strong>Tip:</strong> +You can set a number of DDMS preferences in <strong>File</strong> > <strong>Preferences</strong>. +Preferences are saved to "$HOME/.ddmsrc". </p> + +<p class="warning"><strong>Known debugging issues with Dalvik</strong><br/> +Debugging an application in the Dalvik VM should work the same as it does +in other VMs. However, when single-stepping out of synchronized code, the "current line" +cursor may jump to the last line in the method for one step.</p> + + +<h2 id="left-pane">Left Pane</h2> +<p>The left side of the Debug Monitor shows each emulator/device currently found, with a list of + all the VMs currently running within each. + VMs are identified by the package name of the application it hosts.</p> +<p>Use this list to find and attach to the VM + running the activity(ies) that you want to debug. Next to each VM in the + list is a "debugger pass-through" port (in the right-most column). + If you connect your debugger to one of the the ports listed, you + will be connected to the corresponding VM on the device. However, when using + DDMS, you need only connect to port 8700, as DDMS forwards all traffic here to the + currently selected VM. (Notice, as you select a VM in the list, the listed port includes 8700.) + This way, there's no need to reconfigure the debugger's port each time you switch between VMs.</p> +<p>When an application running on the device calls {@link android.os.Debug#waitForDebugger()} + (or you select this option in the <a href="{@docRoot}intro/installing.html#additionaldebugging">developer + options</a>), a red icon will be shown next to the client name, while it waits for the + debugger to attach to the VM. When a debugger is connected, the icon will turn green. </p> +<p>If you see a crossed-out bug icon, this means that the DDMS was unable to complete a +connection between the debugger and the VM because it was unable to open the VM's local port. +If you see this for all VMs on the device, it is likely because you have another instance of +DDMS running (this includes the Eclipse plugin).</p> +<p>If you see a question mark in place of an application package, this means that, +once DDMS received the application pid from adb, it +somehow failed to make a successful handshake with the VM process. Try restarting DDMS.</p> + + +<h2 id="right-pane">Right pane</h2> +<p>On the right side, the Debug Monitor provides tabs that display useful information +and some pretty cool tools.</p> + +<h3 id="info">Info</h3> +<p>This view shows some general information about the selected VM, including the process + ID, package name, and VM version.</p> + +<h3 id="threads">Threads</h3> +<p> The threads view has a list of threads running in the process of the target VM. + To reduce the amount + of data sent over the wire, the thread updates are only sent when explicitly + enabled by toggling the "threads" button + in the toolbar. This toggle is maintained per VM. This tab includes the following + information: </p> +<ul> + <li> <strong>ID</strong> - a VM-assigned unique thread ID. In Dalvik, these are + odd numbers starting from 3. </li> + <li> <strong>Tid</strong> - the Linux thread ID. For the main thread in a process, + this will match the process ID. </li> + <li> <strong>Status</strong> - the VM thread status. Daemon threads are + shown with an asterisk (*). This will be one of the following: + <ul> + <li> <em>running</em> - executing application code </li> + <li> <em>sleeping</em> - called Thread.sleep() </li> + <li> <em>monitor</em> - waiting to acquire a monitor lock </li> + <li> <em>wait</em> - in Object.wait() </li> + <li> <em>native</em> - executing native code </li> + <li> <em>vmwait</em> - waiting on a VM resource </li> + <li> <em>zombie</em> - thread is in the process of dying </li> + <li> <em>init</em> - thread is initializing (you shouldn't see this) </li> + <li> <em>starting</em> - thread is about to start (you shouldn't see + this either) </li> + </ul> + </li> + <li> <strong>utime</strong> - cumulative time spent executing user code, in "jiffies" (usually + 10ms). Only available under Linux. </li> + <li> <strong>stime</strong> - cumulative time spent executing system code, in "jiffies" (usually + 10ms). </li> + <li> <strong>Name</strong> - the name of the thread</li> +</ul> +<p> "ID" and "Name" are set when the thread is started. The remaining + fields are updated periodically (default is every 4 seconds). </p> + +<h3 id="vm-heap">VM Heap</h3> +<p> Displays some heap stats, updated during garbage collection. If, when a VM is selected, +the VM Heap view says that heap updates are not enabled, click the "Show heap updates" button, +located in the top-left toolbar. Back in the VM Heap view, click <strong>Cause GC</strong> +to perform garbage collection and update the heap stats.</p> + + +<h3 id="allocation-tracker">Allocation Tracker</h3> +<p>In this view, you can track the memory allocation of each virtual machine. +With a VM selected in the left pane, click <strong>Start Tracking</strong>, then +<strong>Get Allocations</strong> to view all allocations since tracking started. +The table below will be filled with all the relevant +data. Click it again to refresh the list.</p> + + +<h3 id="emulator-control">Emulator Control</h3> +<p>With these controls, you can simulate special device states and activities. +Features include:</p> +<ul> +<li><strong>Telephony Status</strong> - change the state of the phone's Voice and Data plans + (home, roaming, searching, etc.), and simulate different kinds of network Speed and Latency + (GPRS, EDGE, UTMS, etc.).</li> +<li><strong>Telephony Actions</strong> - perform simulated phone calls and SMS messages to the emulator.</li> +<li><strong>Location Controls</strong> - send mock location data to the emulator so that you can perform + location-aware operations like GPS mapping. + +<p>To use the Location Controls, launch your application in the Android emulator and open DDMS. +Click the Emulator Controls tab and scroll down to Location Controls. +From here, you can:</p> +<ul class="listhead"> + <li>Manually send individual longitude/latitude coordinates to the device. + <p>Click <strong>Manual</strong>, + select the coordinate format, fill in the fields and click <strong>Send</strong>. + </p> + </li> + <li>Use a GPX file describing a route for playback to the device. + <p>Click <strong>GPX</strong> and load the file. Once loaded, + click the play button to playback the route for your location-aware application.</p> + <p>When performing playback from GPX, you can adjust the speed of + playback from the DDMS panel and control playback with the pause and skip buttons. + DDMS will parse both the waypoints (<code><wpt></code>, in the first table), + and the tracks (<code><trk></code>, + in the second table, with support for multiple segments, <code><trkseg></code>, + although they are simply + concatenated). Only the tracks can be played. Clicking a waypoint in the first list simply + sends its coordinate to the device, while selecting a track lets you play it.</p> + </li> + <li>Use a KML file describing individual placemarks for sequenced playback to the device. + <p>Click <strong>KML</strong> and load the file. Once loaded, + click the play button to send the coordinates to your location-aware application.</p> + <p>When using a KML file, it is parsed for a <code><coordinates></code> + element. The value of which should be a single + set of longitude, latitude and altitude figures. For example:</p> + <pre><coordinates>-122.084143,37.421972,4</coordinates></pre> + <p>In your file, you may include multiple <code><Placemark></code> elements, each containing + a <code><coordinates></code> element. When you do so, the collection of placemarks will + be added as tracks. DDMS will send one placemark per second to the device.</p> + <p>One way to generate a suitable KML file is to find a location in Google Earth. + Right-click the location entry that appears on the left and select "Save place as..." + with the save format set to Kml.</p> +<p class="note"><strong>Note:</strong> DDMS does not support routes created with the +<code><MultiGeometry><LineString>lat1, long1, lat2, long2, ....</LineString></MultiGeometry></code> methods. + There is also currently no support for the <code><TimeStamp></code> node inside + the <code><Placemark></code>. + Future releases may support timed placement and routes within a single coordinate element.</p> + </li> + </ul> + <p>For <em>additional</em> methods of spoofing location-based data, see the + <a href="{@docRoot}toolbox/apis/lbs.html">Location-based Service APIs</a> document.</p> + </li> +</ul> + + +<!-- <h4>Event Log</h4> --> + + +<h2 id="file-explorer">File Explorer</h2> +<p>With the File Explorer, you can view the device file system and perform basic management, +like pushing and pulling files. This circumvents using the <a href="{@docRoot}reference/adb.html">adb</a> +<code>push</code> and <code>pull</code> commands, with a GUI experience.</p> +<p>With DDMS open, select <strong>Device</strong> > <strong>File Explorer...</strong> to open the +File Explorer window. You can drag-and-drop into the device directories, but cannot drag <em>out</em> of them. +To copy files from the device, select the file and click the <strong>Pull File from Device</strong> +button in the toolbar. To delete files, use the <strong>Delete</strong> button in the toolbar.</p> +<p>If you're interested in using an SD card image on the emulator, you're still required to use +the <code>mksdcard</code> command to create an image, and then mount it during emulator bootup. +For example, from the <code>/tools</code> directory, execute:</p> +<pre> +<b>$</b> mksdcard 1024M ./img +<b>$</b> emulator -sdcard ./img +</pre> +<p>Now, when the emulator is running, the DDMS File Explorer will be able to read and write to the +sdcard directory. However, your files may not appear automatically. For example, if you add an +MP3 file to the sdcard, the media player won't see them until you restart the emulator. (When restarting +the emulator from command line, be sure to mount the sdcard again.)</p> +<p>For more information on creating an SD card image, see the +<a href="{@docRoot}/reference/othertools.html#mksdcard">Other Tools</a> document.</p> + +<h2 id="screen-capture">Screen Capture</h2> +<p>You can capture screen images on the device or emulator by selecting <strong>Device</strong> + > <strong>Screen capture...</strong> in the menu bar, or press CTRL-S.</p> + +<h2 id="exploring-processes">Exploring Processes</h2> +<p>You can see the output of <code>ps -x</code> for a specific VM by selecting <strong>Device</strong> + > <strong>Show process status</strong>... in the menu bar.</p> + +<h2 id="cause-a-gc-to-occur">Cause a GC to Occur</h2> +<p>Cause garbage collection to occury by pressing the trash can button on the toolbar. </p> + +<h2 id="running-dumpsys-and-dumpstate">Running Dumpsys and Dumpstate on the Device (logcat)<a name="logcat" id="logcat"></a> </h2> +<ul> + <li>To run <strong>dumpsys</strong> (logcat) from Dalvik, select <strong>Device</strong> > + <strong>Run logcat...</strong> in the menu bar.</li> + <li>To run <strong>dumpstate</strong> from Dalvik, select <strong>Device</strong> > <strong>Dump device + state...</strong> in the menu bar. </li> +</ul> + +<h2 id="examine-radio-state">Examine Radio State</h2> +<p>By default, radio state is not output during a standard logcat (it is a lot of + information). To see radio information, either click <strong>Device</strong> > <strong>Dump radio + state...</strong> or run logcat as described in <a href="{@docRoot}intro/installing.html#logradio">Logging + Radio Information</a>. </p> + +<h2 id="stop-a-vitrual-machine">Stop a Virtual Machine </h2> +<p>You can stop a virtual machine by selecting <strong>Actions</strong> > <strong>Halt +VM</strong>. Pressing this button causes the VM to call <code>System.exit(1)</code>.</p> + +<h2 id="known-issues" style="color:#FF0000">Known issues with DDMS </h2> +<p>DDMS has the following known limitations:</p> +<ul> + <li>If you connect and disconnect a debugger, ddms drops and reconnects the + client so the VM realizes that the debugger has gone away. This will be fixed + eventually. </li> +</ul> diff --git a/docs/html/guide/developing/tools/draw9patch.jd b/docs/html/guide/developing/tools/draw9patch.jd new file mode 100644 index 0000000..25604f8 --- /dev/null +++ b/docs/html/guide/developing/tools/draw9patch.jd @@ -0,0 +1,61 @@ +page.title=Draw 9-patch +@jd:body + +<p>The Draw 9-patch tool allows you to easily create a + {@link android.graphics.NinePatch} graphic using a WYSIWYG editor.</p> +<p>To learn more about what a Nine-patch graphic is, and how they work, please read +the section on Nine-patch in the +<a href="{@docRoot}reference/available-resources.html#ninepatch">Available Resource +Types</a> document.</p> + +<div class="sidebox" style="width:auto"><br/> +<img src="/android/images/draw9patch-norm.png" alt="" height="300" width="341" /> +</div> + +<p>Here's a quick guide to create a Nine-patch graphic using the Draw 9-patch tool. +You'll need the PNG image with which you'd like to create a NinePatch.</p> + +<ol> + <li>From a terminal, launch the <code>draw9patch</code> application from your SDK + <code>/tools</code> directory. + </li> + <li>Drag your PNG image into the Draw 9-patch window + (or <strong>File</strong> > <strong>Open 9-patch...</strong> to locate the file). + Your workspace will now open. + <p>The left pane is your drawing area, in which you can edit the lines for the + stretchable patches and content area. The right + pane is the preview area, where you can preview your graphic when stretched.</p> + </li> + <li>Click within the 1-pixel perimeter to draw the lines that define the stretchable + patches and (optional) content area. Right-click (or hold Shift and click, on Mac) to erase + previously drawn lines. + </li> + <li>When done, select <strong>File</strong> > <strong>Save 9-patch...</strong> + <p>Your image will be saved with the <code>.9.png</code> file name.</p> + </li> +</ol> + <p class="note"><strong>Note:</strong> A normal PNG file (<code>*.png</code>) will be + loaded with an empty one-pixel border added around the image, in which you can draw + the stretchable patches and content area. + A previously saved 9-patch file (<code>*.9.png</code>) will be loaded as-is, + with no drawing area added, because it already exists.</p> + +<div class="sidebox" style="width:auto"><br/> +<img src="/android/images/draw9patch-bad.png" alt="" height="300" width="341" /> +</div> + +<p>Optional controls include:</p> +<ul> + <li><strong>Zoom</strong>: Adjust the zoom level of the graphic in the drawing area.</li> + <li><strong>Patch scale</strong>: Adjust the scale of the images in the preview area.</li> + <li><strong>Show lock</strong>: Visualize the non-drawable area of the graphic on mouse-over.</li> + <li><strong>Show patches</strong>: Preview the stretchable patches in the drawing area (pink is a + stretchable patch).</li> + <li><strong>Show content</strong>: Highlight the content area in the preview images + (purple is the area in which content is allowed).</li> + <li><strong>Show bad patches</strong>: Adds a red border around patch areas that may + produce artifacts in the graphic when stretched. Visual coherence of your stretched + image will be maintained if you eliminate all bad patches.</li> +<ul> + +<p><strong><a href="/android/intro/tools.html">Back to Development Tools</a></strong></p>
\ No newline at end of file diff --git a/docs/html/guide/developing/tools/emulator.jd b/docs/html/guide/developing/tools/emulator.jd new file mode 100755 index 0000000..0516fdd --- /dev/null +++ b/docs/html/guide/developing/tools/emulator.jd @@ -0,0 +1,1724 @@ +page.title=Android Emulator +@jd:body + +<img src="{@docRoot}images/emulator-hvga-p.png" alt="Image of the Android Emulator" width="271" height="524" style="margin-left:0em;float:right;"/> + +<p>The Android SDK includes a mobile device emulator -- a virtual mobile device +that runs on your computer. The emulator lets you prototype, develop, and test +Android applications without using a physical device. </p> + +<p>The Android emulator mimics all of the typical hardware and software features +of a typical mobile device, except that it can not receive or place actual phone +calls. It provides a variety of navigation and control keys, which you can "press" +using your mouse or keyboard to generate events for your application. It also +provides a screen in which your application is displayed, together with any other +Android applications running. </p> + +<p>To help you model and test your application, the emulator lets your application +use the services of the Android platform to invoke other applications, access the +network, play audio and video, store and retrieve data, notify the user, and render +graphical transitions and themes. </p> + +<p>The emulator also includes a variety of debug capabilities, such as a console +from which you can log kernel output, simulate application interrupts (such as +arriving SMS messages or phone calls), and simulate latency effects and dropouts +on the data channel.</p> + + +<h2 style="clear:right;">Contents</h2> + +<div class="g-section g-tpl-50-50"> +<div class="g-unit g-first"> + +<dl> +<dt><a href="#overview">Overview</a></dt> +<dt><a href="#starting">Starting and Stopping the Emulator</a></dt> +<dt><a href="#controlling">Controlling the Emulator</a></dt> +<dt><a href="#startup-options">Emulator Startup Options</a></dt> +<dt><a href="#diskimages">Working with Emulator Disk Images</a></dt> + <dd><a href="#systemimages">System Images</a></dd> + <dd><a href="#runtimeimages">Runtime Images: User Data and SD Card</a></dd> + <dd><a href="#temporaryimages">Temporary Images</a></dd> +<dt><a href="#emulatornetworking">Emulator Networking</a></dt> + <dd><a href="#networkaddresses">Network Address Space</a></dd> + <dd><a href="#networkinglimitations">Local Networking Limitations</a></dd> + <dd><a href="#redirections">Using Network Redirections</a></dd> + <dd><a href="#dns">Configuring the Emulator's DNS Settings</a></dd> + <dd><a href="#proxy">Using the Emulator with a Proxy</a></dd> + <dd><a href="#connecting">Interconnecting Emulator Instances</a></dd> + <dd><a href="#calling">Sending a Voice Call or SMS to Another Emulator Instance</a></dd> +</dl> +</div> + +<div class="g-unit"> +<dl> +<dt><a href="#console">Using the Emulator Console</a></dt> + <dd><a href="#portredirection">Port Redirections</a></dd> + <dd><a href="#geo">Geo Location Provider Emulation</a></dd> + <dd><a href="#events">Sending Events</a></dd> + <dd><a href="#power">Emulating Device Power Characteristics</a></dd> + <dd><a href="#netstatus">Network Status</a></dd> + <dd><a href="#netdelay">Network Delay Emulation</a></dd> + <dd><a href="#netspeed">Network Speed Emulation</a></dd> + <dd><a href="#telephony">Telephony Emulation</a></dd> + <dd><a href="#sms">SMS Emulation</a></dd> + <dd><a href="#vm">VM State</a></dd> + <dd><a href="#window">Emulator Window</a></dd> + <dd><a href="#terminating">Terminating an Emulator Instance</a></dd> +<dt><a href="#skins">Using Emulator Skins</a></dt> +<dt><a href="#multipleinstances">Running Multiple Instances of the Emulator</a></dt> +<dt><a href="#apps">Installing Applications on the Emulator</a></dt> +<dt><a href="#sdcard">SD Card Emulation</a></dt> + <dd><a href="#creating">Creating a Disk Image</a></dd> + <dd><a href="#copying">Copying Files to a Disk Image</a></dd> + <dd><a href="#loading">Loading the Disk Image at Emulator Startup</a></dd> +<dt><a href="#troubleshooting">Troubleshooting Emulator Problems</a></dt> +<dt><a href="#limitations">Emulator Limitations</a></dt> +</dl> +</div> + +</div> + +<a name="overview"></a> + +<h2>Overview</h2> + +<p>The Android emulator is a QEMU-based application that provides a virtual ARM +mobile device on which you can run your Android applications. It provides a full +Android system stack, down to the kernel level, and includes a set of +preinstalled applications (such as the dialer) that you can access from your +applications. It provides a skinnable mobile device UI, customizable key +mappings, and a variety of commands and options for controlling the behaviors of +the emulated environment. </p> + +<p>The Android system image distributed in the SDK contains ARM machine code for +the Android Linux kernel, the native libraries, the Dalvik VM, and the various +Android package files (such as for for the Android framework and preinstalled +applications). The emulator's QEMU layers provide dynamic binary translation of +the ARM machine code to the OS and processor architecture of your development +machine. </p> + +<p>Adding custom capabilities to the underlying QEMU services, the Android +emulator supports many hardware features likely to be found on mobile devices, +including: </p> + +<ul> + <li>An ARMv5 CPU and the corresponding memory-management unit (MMU)</li> + <li>A 16-bit LCD display</li> + <li>One or more keyboards (a Qwerty-based keyboard and associated Dpad/Phone +buttons)</li> + <li>A sound chip with output and input capabilities</li> + <li>Flash memory partitions (emulated through disk image files on the +development machine)</li> + <li>A GSM modem, including a simulated SIM Card</li> +</li> +</ul> + +<p>The sections below provide more information about the emulator and how to use +it for developing Android applications.</p> + +<a name="starting"></a> + +<h2>Starting and Stopping the Emulator</h2> + +<p>During development and testing of your application, you install and run your +application in the Android emulator. You can launch the emulator as a standalone +application, from a command line, or you can use it as part of your Eclipse +development environment. In either case, you can specify the startup options +described in this document to control the emulator. + </p> + +<p>You can run your application on a single instance of the emulator or, +depending on your needs, you can start multiple emulator instances and run your +application in more than one emulated device. You can use the emulator's +built-in commands to simulate GSM phone calling or SMS between emulator +instances, and you can set up network redirections that allow emulators to send +data to one another. For more information, see <a href="#telephony">Telephony +Emulation</a>, <a href="#sms">SMS Emulation</a>, and +<a href="#emulatornetworking">Emulator Networking</a></p> + +<p>To start an instance of the emulator from the command line, change to the +<code>tools/</code> folder of the SDK and enter <code>emulator</code> or +<code>./emulator</code>. This initializes the Android system and you will see +the emulator window appear on your screen. </p> + +<p>If you are working in Eclipse, the ADT plugin for Eclipse installs your +application and starts the emulator automatically, when you run or debug +the application. You can specify emulator startup options in the Run/Debug +dialog, in the Target tab. When the emulator is running, you can issue +console commands as described later in this document.</p> + +<p>If you are not working in Eclipse, see <a href="#apps">Installing Applications +on the Emulator</a> for information about how to install your application.</p> + +<p>To stop an emulator instance, just close the emulator's window.</p> + +<a name="controlling"></a> + +<h2>Controlling the Emulator</h2> + +<p>You can use emulator <a href="#startup-options">startup options</a> and <a +href="#console">console commands</a> to control the behaviors and +characteristics of the emulated environment itself. +</p> + +<p>When the emulator is running, you can interact with the emulated mobile +device just as you would an actual mobile device, except that you use your mouse +pointer to "touch" the touchscreen and your keyboard keys to +"press" the simulated device keys. </p> + +<p>The table below summarizes the mappings between the emulator keys and and +the keys of your keyboard. </p> + +<table border="0" style="clear:left;"> + <tr> + <th>Emulated Device Key </th> + <th>Keyboard Key </th> + </tr> + <tr> + <td>Home</td> + <td>HOME</td> + </tr> + <tr> + <td>Menu (left softkey)</td> + <td>F2 <em>or</em> Page-up button</td> + </tr> + <tr> + <td>Star (right softkey)</td> + <td>Shift-F2 <em>or </em>Page Down</td> + </tr> + <tr> + <td>Back</td> + <td>ESC</td> + </tr> + <tr> + <td>Call/dial button </td> + <td>F3</td> + </tr> + <tr> + <td>Hangup/end call button</td> + <td>F4</td> + </tr> + <tr> + <td>Search</td> + <td>F5 </td> + </tr> + <tr> + <td>Power button</td> + <td>F7 </td> + </tr> + <tr> + <td>Audio volume up button</td> + <td>KEYPAD_PLUS, Ctrl-F5</td> + </tr> + + <tr> + <td>Audio volume down button</td> + <td>KEYPAD_MINUS, Ctrl-F6</td> + </tr> + <tr> + <td>Camera button</td> + <td>Ctrl-KEYPAD_5, Ctrl-F3</td> + </tr> + <tr> + <td>Switch to previous layout orientation (for example, portrait, landscape)</td> + <td>KEYPAD_7, F11</td> + </tr> + <tr> + <td>Switch to next layout orientation (for example, portrait, landscape)</td> + <td>KEYPAD_9, F12</td> + </tr> + <tr> + <td>Toggle cell networking on/off</td> + <td>F8</td> + </tr> + <tr> + <td>Toggle code profiling</td> + <td>F9 (only with <code>-trace</code> startup option)</td> + </tr> + <tr> + <td>Toggle fullscreen mode</td> + <td>Alt-Enter</td> + </tr> + <tr> + <td>Toggle trackball mode</td> + <td>Ctrl-T</td> + </tr> + <tr> + <td>DPad left/up/right/down</td> + <td>KEYPAD_4/8/6/2</td> + </tr> + <tr> + <td>DPad center click</td> + <td>KEYPAD_5</td> + </tr> + <tr> + <td>Onion alpha increase/decrease</td> + <td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td> + </tr> +</table> + +<p>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p> + +<a name="startup-options"></a> + +<h2> Emulator Startup Options</h2> +<p>The emulator supports a variety of options that you can specify +when launching the emulator, to control its appearance or behavior. +Here's the command-line usage for launching the emulator with options: </p> + +<pre>emulator [-<option> [<value>]] ... [-<qemu args>]</pre> + +<p>The table below summarizes the available options.</p> + +<table> +<tr> + <th width="10%" >Category</th> + <th width="20%" >Option</th> + <th width="30%" >Description</th> + <th width="40%" >Comments</th> +</tr> + +<tr> + <td rowspan="8">Help</td> + <td><code>-help</code></td> + <td>Print a list of all emulator options.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-all</code></td> + <td>Print help for all startup options.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-<option></code></td> + <td>Print help for a specific startup option.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-debug-tags</code></td> + <td>Print a list of all tags for <code>-debug <tags></code>.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-disk-images</code></td> + <td>Print help for using emulator disk images.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-environment</code></td> + <td>Print help for emulator environment variables.</td> + <td> </td> +</tr><tr> + <td><code>-help-keys</code></td> + <td>Print the current mapping of keys.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-keyset-file</code></td> + <td>Print help for defining a custom key mappings file.</td> + <td> </td> +</tr> + +<tr> + <td rowspan="10">Disk Images</td> + <td><code>-cache <filepath></code></td> + <td>Use <filepath> as the working cache partition image. </td> + <td>Optionally, you can specify a path relative to the current working directory. + If no cache file is specified, the emulator's default behavior is to use a temporary file instead. + <p>For more information on disk images, use <code>-help-disk-images</code>.</p> +</td></tr> +<tr> + <td><code>-data <filepath></code></td> + <td>Use <filepath> as the working user-data disk image. </td> + <td>Optionally, you can specify a path relative to the current working directory. + If <code>-data</code> is not used, the emulator looks for a file named "userdata-qemu.img" + in the directory specified in <datadir>. ~/.android (on Linux/Mac) or + C:\Documents and Settings\<user>\Local Settings\Application Data\Android (on Windows). + <p> If you use <code>-data <filepath></code> but the file does not exist, the emulator creates + a file at that location using the specified name. </p> + <p>See <a href="#multipleinstances">Running Multiple Emulator Instances</a> for information about how + to use <code>-data</code> to let multiple emulator instances preserve their user data across sessions.</p> + <p>For more information on disk images, use <code>-help-disk-images</code>.</p> +</td></tr> +<!-- +<tr> + <td><code>-datadir <dir></code></td> + <td>Search for the user-data disk image specified in <code>-data</code> in <dir></td> + <td><code><dir></code> is a path relative to the current working directory. + +<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image in the + directory ~/.android (on Linux/Mac) or C:\Documents and Settings\<user>\Local Settings\Application + Data\Android (on Windows). </p><p>For more information on disk images, use <code>-help-disk-images</code>.</p> +</td></tr> +--> +<tr> + <td><code>-image <filepath></code></td> + <td>Use <filepath> as the system image.</td> + <td>Optionally, you can specify a path relative to the current working directory. + Default is <system>/system.img.</td> +</tr> +<tr> + <td><code>-initdata <filepath></code></td> + <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents + of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td> + <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>. <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td> +</tr> +<tr> + <td><code>-kernel <filepath></code></td> + <td>Use <filepath> as the emulated kernel.</td> + <td>Optionally, you can specify a path relative to the current working directory. </td> +</tr> +<tr> + <td><code>-nocache</code></td> + <td>Start the emulator without a cache partition.</td> + <td>See also <code>-cache <file></code>.</td> +</tr> +<tr> + <td><code>-ramdisk <filepath></code></td> + <td>Use <filepath> as the ramdisk image.</td> + <td>Default value is <code><system>/ramdisk.img</code>. + <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p> +</td> +</tr> +<tr> + <td><code>-sdcard <filepath></code></td> + <td>Use <file> as the SD card image.</td> + <td>Default value is <code><system>/sdcard.img</code>. + <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p> +</td> +</tr> +<tr> + <td><code>-system <dirpath></code></td> + <td>Search for system, ramdisk and user data images in <dir>.</td> + <td><code><dir></code> is a directory path relative to the current + working directory.</td> +</tr> +<tr> + <td><code>-wipe-data</code></td> + <td>Reset the current user-data disk image (that is, the file specified by <code>-datadir</code> and + <code>-data</code>, or the default file). The emulator deletes all data from the user data image file, + then copies the contents of the file at <code>-inidata</code> data to the image file before starting. + </td> + <td>See also <code>-initdata</code>. + <p>For more information on disk images, use <code>-help-disk-images</code>.</p> +</td> +</tr> +<tr> + <td rowspan="9">Debug</td> + <td><code>-debug <tags></code></td> + <td>Enable/disable debug messages for the specified debug tags.</td> + <td><code><tags></code> is a space/comma/column-separated list of debug component names. + Use <code>-help-debug-tags</code> to print a list of debug component names that you can use. </td> +</tr> +<tr> + <td><code>-debug-<tag></code></td> + <td>Enable/disable debug messages for the specified debug tag.</td> + <td rowspan="2">Use <code>-help-debug-tags</code> to print a list of debug component names that you can use in <code><tag></code>. </td> +</tr> +<tr> + <td><code>-debug-no-<tag></code></td> + <td>Disable debug messages for the specified debug tag.</td> +</tr> +<tr> + <td><code>-logcat <logtags></code></td> + <td>Enable logcat output with given tags.</td> + <td>If the environment variable ANDROID_LOG_TAGS is defined and not + empty, its value will be used to enable logcat output by default.</td> +</tr> +<tr> + <td><code>-shell</code></td> + <td>Create a root shell console on the current terminal.</td> + <td>You can use this command even if the adb daemon in the emulated system is broken. + Pressing Ctrl-c from the shell stops the emulator instead of the shell.</td> +</tr> +<tr> + <td><code>-shell-serial <device></code></td> + <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character + device to use for communication with the shell.</td> + <td><device> must be a QEMU device type. See the documentation for 'serial -dev' at + <a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a> + for a list of device types.</p> + +<p>Here are some examples: </p> +<ul> + <li><code>-shell-serial stdio</code> is identical to <code>-shell</code></li> + <li><code>-shell-serial tcp::4444,server,nowait</code> lets you communicate with the shell over TCP port 4444</li> + <li><code>-shell-serial fdpair:3:6</code> lets a parent process communicate with the shell using fds 3 (in) and 6 (out)</li> + <li><code>-shell-serial fdpair:0:1</code> uses the normal stdin and stdout fds, except that QEMU won't tty-cook the data.</li> + </ul> +</td> +</tr> +<tr> + <td><code>-show-kernel <name></code></td> + <td>Display kernel messages.</td> + <td> </td> +</tr> +<tr> + <td><code>-trace <name></code></td> + <td>Enable code profiling (press F9 to start), written to a specified file.</td> + <td> </td> +</tr> +<tr> + <td><code>-verbose</code></td> + <td>Enable verbose output.</td> + <td>Equivalent to <code>-debug-init</code>. +<p>You can define the default verbose output options used by emulator instances in the Android environment variable +ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option: +<code>-debug-<tags>.</code> </p> +<p>Here's an example showing ANDROID_VERBOSE defined with the <code>-debug-init</code> and <code>-debug-modem</code> options: +<p><code>ANDROID_VERBOSE=init,modem</code></p> +<p>For more information about debug tags, use <code><-help-debug-tags></code>.</p> +</td> +</tr> +<tr> + <td rowspan="6">Media</td> + <td><code>-audio <backend></code></td> + <td>Use the specified audio backend.</td> + <td> </td> +</tr> +<tr> + <td><code>-audio-in <backend></code></td> + <td>Use the specified audio-input backend.</td> + <td> </td> +</tr> +<tr> + <td><code>-audio-out <backend></code></td> + <td>Use the specified audio-output backend.</td> + <td> </td> +</tr> +<!--<tr> + <td><code>-mic <device or file></code></td> + <td>Use device or WAV file for audio input.</td> + <td> </td> +</tr> +--> +<tr> + <td><code>-noaudio</code></td> + <td>Disable audio support in the current emulator instance.</td> + <td> </td> +</tr> +<tr> + <td><code>-radio <device></code></td> + <td>Redirect radio modem interface to a host character device.</td> + <td> </td></tr> +<tr> + <td><code>-useaudio</code></td> + <td>Enable audio support in the current emulator instance.</td> + <td>Enabled by default. </td> +</tr> + +<tr> + <td rowspan="7">Network</td> + <td><code>-dns-server <servers></code></td> + <td>Use the specified DNS server(s). </td> + <td>The value of <code><servers></code> must be a comma-separated list of up to 4 DNS server names or + IP addresses.</td> +</tr> +<tr> + <td><code>-http-proxy <proxy></code></td> + <td>Make all TCP connections through a specified HTTP/HTTPS proxy</td> + <td>The value of <code><proxy></code> can be one of the following:<br> + <code>http://<server>:<port></code><br> + <code>http://<username>:<password>@<server>:<port></code> + <p>The <code>http://</code> prefix can be omitted. If the <code>-http-proxy <proxy></code> command is not supplied, + the emulator looks up the <code>http_proxy</code> environment variable and automatically uses any value matching + the <code><proxy></code> format described above.</p></td> +</tr> +<tr> + <td><code>-netdelay <delay></code></td> + <td>Set network latency emulation to <delay>.</td> + <td>Default value is <code>none</code>. See the table in <a href="#netdelay">Network Delay Emulation</a> for + supported <code><delay></code> values. </td> +</tr> +<tr> + <td><code>-netfast</code></td> + <td>Shortcut for <code>-netspeed full -netdelay none</code></td> + <td> </td></tr> +<tr> + <td><code>-netspeed <speed></code></td> + <td>Set network speed emulation to <speed>.</td> + <td>Default value is <code>full</code>. See the table in <a href="#netspeed">Network Speed Emulation</a> for + supported <code><speed></code> values. </td> +</tr> +<tr> + <td><code>-port <port></code></td> + <td>Set the console port number for this emulator instance to <code><port></code>.</td> + <td>The console port number must be an even integer between 5554 and 5584, inclusive. <code><port></code>+1 + must also be free and will be reserved for ADB.</td> +</tr> +<tr> + <td><code>-report-console <socket></code></td> + <td>Report the assigned console port for this emulator instance to a remote third party + before starting the emulation. </td> + <td><code><socket></code> must use one of these formats: + +<p><code>tcp:<port>[,server][,max=<seconds>]</code></br> +<code>unix:<port>[,server][,max=<seconds>]</code></p> + +<p>Use <code>-help-report-console</code></p> to view more information about this topic. </td> +</tr> +<tr> + <td rowspan="8">System</td> + <td><code>-cpu-delay <delay></code></td> + <td>Slow down emulated CPU speed by <delay> </td> + <td>Supported values for <delay> are integers between 0 and 1000. + +<p>Note that the <delay> does not correlate to clock speed or other absolute metrics +— it simply represents an abstract, relative delay factor applied non-deterministically +in the emulator. Effective performance does not always +scale in direct relationship with <delay> values.</p> +</td> +</tr> +<tr> + <td><code>-gps <device></code></td> + <td>Redirect NMEA GPS to character device.</td> + <td>Use this command to emulate an NMEA-compatible GPS unit connected to + an external character device or socket. The format of <code><device></code> must be QEMU-specific + serial device specification. See the documentation for 'serial -dev' at + <a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. +</td> +</tr> +<tr> + <td><code>-nojni</code></td> + <td>Disable JNI checks in the Dalvik runtime.</td><td> </td></tr> +<tr> + <td><code>-qemu</code></td> + <td>Pass arguments to qemu.</td> + <td> </td></tr> +<tr> + <td><code>-qemu -h</code></td> + <td>Display qemu help.</td> + <td></td></tr> +<tr> + <td><code>-radio <device></code></td> + <td>Redirect radio mode to the specified character device.</td> + <td>The format of <code><device></code> must be QEMU-specific + serial device specification. See the documentation for 'serial -dev' at +<a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. +</td> +</tr> +<tr> + <td><code>-timezone <timezone></code></td> + <td>Set the timezone for the emulated device to <timezone>, instead of the host's timezone.</td> + <td><code><timezone></code> must be specified in zoneinfo format. For example: +<p>"America/Los_Angeles"<br> +"Europe/Paris"</p> +</td> +</tr> +<tr> + <td><code>-version</code></td> + <td>Display the emulator's version number.</td> + <td> </td> +</tr> +<tr> + <td rowspan="12">UI</td> + <td><code>-dpi-device <dpi></code></td> + <td>Scale the resolution of the emulator to match the screen size + of a physical device.</td> + <td>The default value is 165. See also <code>-scale</code>.</td> +</tr> +<tr> + <td><code>-no-boot-anim</code></td> + <td>Disable the boot animation during emulator startup.</td> + <td>Disabling the boot animation can speed the startup time for the emulator.</td> +</tr> +<tr> + <td><code>-no-window</code></td> + <td>Disable the emulator's graphical window display.</td> + <td> </td> +</tr> +<tr> + <td><code>-scale <scale></code></td> + <td>Scale the emulator window. </td> + <td><code><scale></code> is a number between 0.1 and 3 that represents the desired scaling factor. You can + also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" + tells the emulator to select the best window size.</td> +</tr> +<tr> + <td><code>-raw-keys</code></td> + <td>Disable Unicode keyboard reverse-mapping.</td> + <td> </td></tr> +<tr> + <td><code>-noskin</code></td> + <td>Don't use any emulator skin.</td> + <td> </td></tr> +<tr> + <td><code>-keyset <file></code></td> + <td>Use the specified keyset file instead of the default.</td> + <td>The keyset file defines the list of key bindings between the emulator and the host keyboard. + For more information, use <code>-help-keyset</code> to print information about this topic. +</td> +</tr> +<tr> + <td><code>-onion <image></code></td> + <td>Use overlay image over screen.</td> + <td>No support for JPEG. Only PNG is supported.</td></tr> +<tr> + <td><code>-onion-alpha <percent></code></td> + <td>Specify onion skin translucency value (as percent). + <td>Default is 50.</td> +</tr> +<tr> + <td><code>-onion-rotation <position></code></td> + <td>Specify onion skin rotation. + <td><code><position></code> must be one of the values 0, 1, 2, 3.</td> +</tr> +<tr> + <td><code>-skin <skinID></code></td> + <td>Start the emulator with the specified skin. </td> + <td>The SDK includes a <a href="#skins">choice of four skins</a>:<br /> + <li>HVGA-L (480x320, landscape)</li> + <li>HVGA-P (320x480, portrait) (default) </li> + <li>QVGA-L (320x240, landscape)</li> + <li>QVGA-P (240x320, portrait) </li> +</td> +</tr> +<tr> + <td><code>-skindir <dir></code></td> + <td>Search for emulator skins in <dir>. </td> + <td> </td></tr> +</table> + +<a name="diskimages"></a> + +<h2>Working with Emulator Disk Images</h2> + +<p>The emulator uses mountable disk images stored on your development machine to +simulate flash (or similar) partitions on an actual device. For example, it uses +disk image containing an emulator-specific kernel, the Android system, a +ramdisk image, and writeable images for user data and simulated SD card.</p> + +<p>To run properly, the emulator requires access to a specific set of disk image +files. The Android SDK includes default versions of the required images, stored +in predetermined locations in the SDK directory structure. At startup, the +emulator looks for and reads the image files, using their default names and +storage locations. </p> + +<p>To let you use alternate or custom versions of the image files, the emulator +provides startup options that override the default locations and filenames of +the image files. When you use the options, the emulator searches for the image +file under the image name or location that you specify; if it can not locate the +image, it reverts to using the default names and location.</p> + +<p>The emulator uses three types of image files: system image files, runtime +image files, and temporary image files. The sections below describe how to +override the location/name of each type of file. </p> + +<a name="systemimages"></a> +<h3>System Images</h3> + +<p>System images contain system data and default settings without which the +emulator can not run. The image files are read-only — the emulator reads +the images at startup and does not modify them during the session.</p> + +<p>All of the system image files are stored in a single directory. By default, +the system images are stored in the <code>lib/images</code>' under the +emulator's program location. </p> + +<p>The emulator provides the <code>-system <dir></code> startup option to +let you override the location under which the emulator looks for the system +images files. </p> + +<p>The emulator also provides startup options that let you override the names of +the system images, as described in the table below. When you use one of the +options, the emulator looks in the default directory, or in a custom location +(if you specified <code>-system <dir></code>). Note that, if you provide +alternate system image file, it must contain the same type of data as the +default. For example, your override of the system.img file must point to a disk +image containing an Android system. </p> + + +<table> +<tr> + <th width="10%" >Name</th> + <th width="30%" >Description</th> + <th width="40%" >Comments</th> +</tr> + +<tr> + <td><code>kernel-qemu.img</code></td> + <td>The emulator-specific Linux kernel image</td> + <td>Override using <code>-kernel <file></code></td> +</tr> + +<tr> + <td><code>ramdisk.img</code></td> + <td>The ramdisk image used to boot the system.</td> + <td>Override using <code>-ramdisk <file></code></td> +</tr> + +<tr> + <td><code>system.img</code></td> + <td>The <em>initial</em> Android system image.</td> + <td>Override using <code>-image <file></code></td> +</tr> + +<tr> + <td><code>userdata.img</code></td> + <td>The <em>initial</em> user-data disk image</td> + <td>Override using <code>-initdata <file></code>. Also see +<code>-data <file></code>, below.</td> +</tr> + +</table> + +<a name="runtimeimages"></a> +<h3>Runtime Images: User Data and SD Card</h3> + +<p>At runtime, the emulator reads and writes data on two disk images: a +user-data image and (optionally) an SD card image. This emulates the user-data +partition and removable storage media on actual device. </p> + +<p>The emulator provides a default user-data disk image. At startup, the emulator +creates the default image as a copy of the system user-data image (user-data.img), +described above. The emulator stores the default image in this location on +on your development machine: </p> + +<ul> + <li>Linux and OS X: <code>~/.android</code></li> + <li>Windows: <code>C:\Documents and Settings\<user>\Local Settings\Application Data\Android</code></li> +</ul> + +<!-- +<p>The emulator provides a startup option, <code>-datadir <dir></code>, +that you can use to override the location under which the emulator looks for the runtime +image files. </p> +--> + +<p>The emulator provides startup options to let you override the actual names and storage +locations of the runtime images to load, as described in the table below. When you use one +of these options, the emulator looks for the specified file(s) in the current working directory, +in the default directory, or in a custom location (if you specified a path with the filename. </p> + +<table> +<tr> + <th width="10%" >Name</th> + <th width="30%" >Description</th> + <th width="40%" >Comments</th> +</tr> +<tr> + <td><code>userdata-qemu.img</code></td> + <td>An image to which the emulator writes runtime user-data for a unique user.</td> + <td>Override using <code>-data <;filepath></code>, where <code><filepath></code> is the +path the image, relative to the current working directory. If you supply a filename only, +the emulator looks for the file in the current working directory. If the file at <code><filepath></code> does +not exist, the emulator creates an image from the default userdata.img, stores it under the name you +specified, and persists user data to it at shutdown. </td> +</tr> + +<tr> + <td><code>sdcard.img</code></td> + <td>An image representing an SD card inserted into the emulated device.</td> + <td>Override using <code>-sdcard <filepath></code>, where <code><filepath></code> is the +path the image, relative to the current working directory. If you supply a filename only, +the emulator looks for the file in the current working directory. </td> +</tr> + +</table> + +<h4>User-Data Image</h4> + +<p>Each emulator instance uses a writeable user-data image to store user- and +session-specific data. For example, it uses the image to store a unique user's +installed application data, settings, databases, and files. </p> + +<p>At startup, the emulator attempts to load a user-data image stored during +a previous session. It looks for the file in the current working directory, +at the default location, as described above, and at the custom location/name +that you specified at startup. </p> + +<ul> +<li>If it finds a user-data image, it mounts the image and makes it available to the system +for reading/writing of user data. </li> +<li>If it does not find one, it creates an image by copying the system user-data +image (userdata.img), described above. At device power-off, the system persists +the user data to the image, so that it will be available in the next session. +Note that the emulator stores the new disk image at the location/name that you +specify in <code>-data</code> startup option.</li> +</ul> + +<p>If you are planning to run multiple emulator instances concurrently, note +that only the first emulator instance can persist user-data, if no explicit +user-data image file is specified in the startup command. When running multiple +emulator instances, you must specify a name for the image file to use (or +create), by using the <code>-data <name></code> option with a unique +<code><name></code> value. For more information, see +<a href="#multipleinstances">Running Multiple Emulator Instances</a>.</p> + +<h4>SD Card</h4> + +<P>Optionally, you can create a writeable disk image that the emulator can use +to simulate removeable storage in an actual device. For information about how to create an +emulated SD card and load it in the emulator, see <a href="#sdcard">SD Card Emulation</a></p> + +<a name="temporaryimages"></a> +<h3>Temporary Images</h3> + +<p>The emulator creates two writeable images at startup that it deletes at +device power-off. The images are: </p> + +<ul> + <li>A writable copy of the Android system image</li> + <li>The <code>/cache</code> partition image</li> +</ul> + +<p>The emulator does not permit renaming the temporary system image or +persisting it at device power-off. </p> + +<p>The <code>/cache</code> partition image is initially empty, and is used by +the browser to cache downloaded web pages and images. The emulator provides an +<code>-cache <file></code>, which specifies the name of the file at which +to persist the <code>/cache</code> image at device power-off. If <code><file> +</code> does not exist, the emulator creates it as an empty file. </p> + +<p>You can also disable the use of the cache partition by specifying the +<code>-nocache</code> option at startup. </p> + + +<a name="emulatornetworking"></a> +<h2>Emulator Networking</h2> + +<p>The emulator provides versatile networking capabilities that you can use to +set up complex modeling and testing environments for your application. The +sections below introduce the emulator's network architecture and capabilities. +</p> + +<a name="networkaddresses"></a> +<h3>Network Address Space</h3> + +<p>Each instance of the emulator runs behind a virtual router/firewall service +that isolates it from your development machine's network interfaces and settings +and from the internet. An emulated device can not see your development machine +or other emulator instances on the network. Instead, it sees only that it is +connected through Ethernet to a router/firewall.</p> + +<p>The virtual router for each instance manages the 10.0.2/24 network address +space — all addresses managed by the router are in the form of +10.0.2.<xx>, where <xx> is a number. Addresses within this space are +pre-allocated by the emulator/router as follows:</p> + +<table> + <tr> + <th>Network Address</th> + <th>Description</th> + </tr> + <tr> + <td>10.0.2.1</td> + <td>Router/gateway address </td> + </tr> + <tr> + <td>10.0.2.2</td> + <td>Special alias to your host loopback interface (i.e., 127.0.0.1 on your +development machine)</td> + </tr> + <tr> + <td>10.0.2.3</td> + <td>First DNS server</td> + </tr> + <tr> + <td>10.0.2.4 / 10.0.2.5 / 10.0.2.6</td> + <td>Optional second, third and fourth DNS server (if any) </td> + </tr> + <tr> + <td>10.0.2.15</td> + <td>The emulated device's own network/ethernet interface</td> + </tr> + <tr> + <td>127.0.0.1</td> + <td>The emulated device's own loopback interface </td> + </tr> +</table> + +<p>Note that the same address assignments are used by all running emulator +instances. That means that if you have two instances running concurrently on +your machine, each will have its own router and, behind that, each will have an +IP address of 10.0.2.15. The instances are isolated by a router and can +<em>not</em> see each other on the same network. For information about how to +let emulator instances communicate over TCP/UDP, see <a +href="#connecting">Connecting Emulator Instances</a>.</p> + +<p>Also note that the address 127.0.0.1 on your development machine corresponds +to the emulator's own loopback interface. If you want to access services running +on your development machine's loopback interface (a.k.a. 127.0.0.1 on your +machine), you should use the special address 10.0.2.2 instead.</p> + +<p>Finally, note that each emulated device's pre-allocated addresses are +specific to the Android emulator and will probably be very different on real +devices (which are also very likely to be NAT-ed, i.e., behind a +router/firewall)</p> + +<a name="networkinglimitations"></a> +<h3>Local Networking Limitations</h3> + +<p>Each emulator instance runs behind a virtual router, but unlike an actual +device connected to a physical router, the emulated device doesn't have access +to a physical network. Instead it runs as part of a normal application on your +development machine. This means that it is subject to the same networking +limitations as other applications on your machine:</p> + +<ul> + <li>Communication with the emulated device may be blocked by a firewall +program running on your machine.</li> + <li>Communication with the emulated device may be blocked by another +(physical) firewall/router to which your machine is connected.</li> +</ul> + +<p>The emulator's virtual router should be able to handle all outbound TCP and +UDP connections/messages on behalf of the emulated device, provided your +development machine's network environment allows it to do so. There are no +built-in limitations on port numbers or ranges except the one imposed by your +host operating system and network.</p> + +<p>Depending on the environment, the emulator may not be able to support other +protocols (such as ICMP, used for "ping") might not be supported. Currently, the +emulator does not support IGMP or multicast. </p> + +<a name="redirections"></a> +<h3>Using Network Redirections</h3> + +<p>To communicate with an emulator instance behind its virtual router, you need +to set up network redirections on the virtual router. Clients can then connect +to a specified guest port on the router, while the router directs traffic +to/from that port to the emulated device's host port. </p> + +<p>To set up the network redirections, you create a mapping of host and guest +ports/addresses on the the emulator instance. There are two ways to set up +network redirections: using emulator console commands and using the ADB tool, as +described below. </p> + +<a name="consoleredir"></a> +<h4>Setting up Redirections through the Emulator Console</h4> + +<p>Each emulator instance provides a control console the you can connect to, to +issue commands that are specific to that instance. You can use the +<code>redir</code> console command to set up redirections as needed for an +emulator instance. </p> + +<p>First, determine the console port number for the target emulator instance. +For example, the console port number for the first emulator instance launched is +5554. Next, connect to the console of the target emulator instance, specifying +its console port number, as follows: </p> + +<pre><code>telnet localhost 5554</code></pre> + +<p>Once connected, use the <code>redir</code> command to work with redirections. +To add a redirection, use:</a>. </p> + +<pre><code>add <protocol>:<host-port>:<guest-port></code> +</pre> + +<p>where <code><protocol></code> is either <code>tcp</code> or <code>udp</code>, +and <code><host-port></code> and <code><guest-port></code> sets the +mapping between your own machine and the emulated system, respectively. </p> + +<p>For example, the following command sets up a redirection that will handle all +incoming TCP connections to your host (development) machine on 127.0.0.1:5000 +and will pass them through to the emulated system's 10.0.2.15:6000.:</p> + +<pre>redir add tcp:5000:6000</pre> + +<p>To delete a redirection, you can use the <code>redir del</code> command. To +list all redirections for a specific instance, you can use <code>redir +list</code>. For more information about these and other console commands, see +<a href="#console">Using the Emulator Console</a>. </p> + +<p>Note that port numbers are restricted by your local environment. this typically +means that you cannot use host port numbers under 1024 without special +administrator privileges. Also, you won't be able to set up a redirection for a +host port that is already in use by another process on your machine. In that +case, <code>redir</code> generates an error message to that effect. </p> + +<a name="adbredir"></a> +<h4>Setting Up Redirections through ADB</h4> + +<p>The Android Debug Bridge (ADB) tool provides port forwarding, an alternate +way for you to set up network redirections. For more information, see <a +href="{@docRoot}reference/adb.html#forwardports">Forwarding Ports</a> in the ADB +documentation.</p> + +<p>Note that ADB does not currently offer any way to remove a redirection, +except by killing the ADB server.</p> + +<a name="dns"></a> +<h3>Configuring the Emulator's DNS Settings</h3> + +<p>At startup, the emulator reads the list of DNS servers that your system is +currently using. It then stores the IP addresses of up to four servers on this +list and sets up aliases to them on the emulated addresses 10.0.2.3, 10.0.2.4, +10.0.2.5 and 10.0.2.6 as needed. </p> + +<p>On Linux and OS X, the emulator obtains the DNS server addresses by parsing +the file <code>/etc/resolv.conf</code>. On Windows, the emulator obtains the +addresses by calling the <code>GetNetworkParams()</code> API. Note that this +usually means that the emulator ignores the content of your "hosts" file +(<code>/etc/hosts</code> on Linux/OS X, <code>%WINDOWS%/system32/HOSTS</code> + on Windows).</P> + +<p>When starting the emulator at the command line, you can also use the +<code>-dns-server <serverList></code> option to manually specify the +addresses of DNS servers to use, where <serverList> is a comma-separated +list of server names or IP addresses. You might find this option useful if you +encounter DNS resolution problems in the emulated network (for example, an +"Unknown Host error" message that appears when using the web browser).</p> + +<a name="proxy"></a> +<h3>Using the Emulator with a Proxy</h3> + +<p>If your emulator must access the Internet through a proxy server, you can use +the <code>-http-proxy <proxy></code> option when starting the emulator, to +set up the appropriate redirection. In this case, you specify proxy information +in <code><proxy></code> in one of these formats:</p> + +<pre>http://<machineName>:<port></pre> + +<p>or</p> + +<pre>http://<username>:<password>@<machineName>:<port></pre> + +<p>The <code>-http-proxy</code> option forces the emulator to use the specified +HTTP/HTTPS proxy for all outgoing TCP connections. Redirection for UDP is not +currently supported.</p> + +<p>Alternatively, you can define the environment variable +<code>http_proxy</code> to the value you want to use for +<code><proxy></code>. In this case, you do not need to specify a value for +<code><proxy></code> in the <code>-http-proxy</code> command — the +emulator checks the value of the <code>http_proxy</code> environment variable at +startup and uses its value automatically, if defined. </p> + +<p>You can use the <code>-verbose-proxy</code> option to diagnose proxy +connection problems.</p> + +<a name="connecting"></a> +<h3>Interconnecting Emulator Instances</h3> + +<p>To allow one emulator instance to communicate with another, you must set up +the necessary network redirections as illustrated below. </p> + +<p>Assume that your environment is</p> + +<ul> + <li>A is you development machine</li> + <li>B is your first emulator instance, running on A</li> + <li>C is your second emulator instance, running on A too</li> +</ul> + +<p>and you want to run a server on B, to which C will connect, here is how you +could set it up: </p> + +<ol> + <li>Set up the server on B, listening to +<code>10.0.2.15:<serverPort></code></li> + <li>On B's console, set up a redirection from +<code>A:localhost:<localPort></code> to <code> +B:10.0.2.15:<serverPort></code></li> + <li>On C, have the client connect to 10.0.2.2:<localPort></code></li> +</ol> + +<p>For example, if you wanted to run an HTTP server, you can select +<code><serverPort></code> as 80 and <code><localPort></code> as +8080:</p> + +<ul> + <li>B listens on 10.0.2.15:80</li> + <li>On B's console, issue <code>redir add tcp:8080:80</code></li> + <li>C connects to 10.0.2.2:8080</li> +</ul> + +<a name="calling"></a> +<h3>Sending a Voice Call or SMS to Another Emulator Instance</h3> + +<p>The emulator automatically forwards simulated voice calls and SMS messages from one instance to another. To send a voice call or SMS, you use the dialer application and SMS application (if available) installed on one emulator </p> + +<p>To initiate a simulated voice call to another emulator instance:</p> +<ol> +<li>Launch the dialer application on the originating emulator instance.</li> +<li>As the number to dial, enter the console port number of the instance you'd like to call. You can determine + the console port number of the target instance by checking its window title, where the + console port number is reported as "Android Emulator (<port>). </li> +<li>Press "Dial". A new inbound call appears in the target emulator instance. </li> +</ol> + +<p>To send an SMS message to another emulator instance, launch the SMS application (if available). Specify the console port number of the target emulator instance as as the SMS address, enter the message text, and send the message. The message is delivered to the target emulator instance. </p> + +<p>You can also connect to an emulator instance's console to simulate an incoming voice call or SMS. For more information, see <a href="#telephony">Telephony Emulation</a> and <a href="#sms">SMS Emulation</a>. + +<a name="console"></a> + +<h2>Using the Emulator Console</h2> + +<p>Each running emulator instance includes a console facility that lets you dynamically query and control the simulated device environment. For example, you can use the console to dynamically manage port redirections and network characteristics and simulate telephony events. To access the console and enter commands, you use telnet to connect to the console's port number. </p> +<p>To connect to the console of any running emulator instance at any time, use this command: </p> + +<pre>telnet localhost <console-port></pre> + +<p>An emulator instance occupies a pair of adjacent ports: a console port and an adb port. The port numbers differ by 1, with the adb port having the higher port number. The console of the first emulator instance running on a given machine uses console port 5554 and adb port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557, 5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility. </p> + +<p>To connect to the emulator console, you must specify a valid console port. If multiple emulator instances are running, you need to determine the console port of the emulator instance you want to connect to. You can find the instance's console port listed in the title of the instance window. For example, here's the window title for an instance whose console port is 5554:</p> + +<p><code>Android Emulator (5554)</code></p> + +<p>Alternatively, you can use the <code>adb devices</code> command, which prints a list of running emulator instances and their console port numbers. For more information, see <a href="{@docRoot}reference/adb.html#devicestatus">Querying for Emulator/Device Instances</a> in the adb documentation.</p> + +<p class="note">Note: The emulator listens for connections on ports 5554-5587 and accepts connections only from localhost.</p> + +<p>Once you are connected to the console, you can then enter <code>help [command]</code> to see a list of console commands and learn about specific commands. </p> + +<p>To exit the console session, use <code>quit</code> or <code>exit</code>.</p> + +<p>The sections below describe the major functional areas of the console.</p> + +<a name="portredirection"></a> + +<h3>Port Redirection</h3> +<p>You can use the console to add and remove port redirections while the emulator is running. After connecting to the console, you can manage port redirections in this way:</p> +<pre>redir <list|add|del> </pre> + +<p>The <code>redir</code> command supports the subcommands listed in the table below. </p> + +<table> +<tr> + <th width="25%" >Subcommand + <th width="30%" >Description</th> + <th width="35%">Comments</th> +</tr> + + <tr> + <td><code>list</code></td> + <td>List the current port redirections.</td> + <td> </td> + </tr> + + +<tr> + <td><code>add <protocol>:<host-port>:<guest-port></code></td> + <td>Add a new port redirection.</td> +<td><li><protocol> must be either "tcp" or "udp"</li> +<li><host-port> is the port number to open on the host</li> +<li><guest-port> is the port number to route data to on the emulator/device</li></td> +</tr> +<tr> + <td><code>del <protocol>:<host-port></code></td> + <td>Delete a port redirection.</td> +<td>See above for meanings of <protocol> and <host-port>.</td> +</tr> +</table> + +<a name="geo"></a> +<h3>Geo Location Provider Emulation</h3> + +<p>The console provides commands to let you set the geo position used by an emulator emulated device. You can use the <code>geo</code> command to send a simple GPS fix to the emulator, without needing to use NMEA 1083 formatting. The usage for the command is: </p> + +<pre>geo <fix|nmea></pre> + +<p>The <code>geo</code> command supports the subcommands listed in the table below. </p> + +<table> +<tr> + <th width="25%" >Subcommand + <th width="30%" >Description</th> + <th width="35%">Comments</th> +</tr> + + <tr> + <td><code>fix <longitude> <latitude> [<altitude>]</code></td> + <td>Send a simple GPS fix to the emulator instance.</td> + <td>Specify longitude and latitude in decimal degrees. Specify altitude in meters.</td> + </tr> +<tr> + <td><code>nmea <sentence></code></td> + <td>Send an NMEA 0183 sentence to the emulated device, as if it were sent from an emulated GPS modem.</td> +<td><code><sentence></code> must begin with '$GP'. Only '$GPGGA' and '$GPRCM' sentences are currently supported.</td> +</tr> +</table> + +<p>You can issue the <code>geo</code> command to fix the GPS location as soon as an emulator instance is running. The emulator creates a mock location provider that sends the location to GPS-aware applications as soon as they start and register location listeners. Any application can query the location manager to obtain the current GPS fix for the emulated device by calling: + +<pre>LocationManager.getLastKnownLocation("gps")</pre> + +<p>For more information about the Location Manager, see {@link android.location.LocationManager} and its methods.</p> + +<a name="events"></a> +<h3>Hardware Events Emulation</h3> + +<p>You can use the <code>event</code> command to send various events to the emulator.The usage for the command is: </p> + +<pre>event <send|types|codes|text></pre> + +<p>The <code>event</code> command supports the subcommands listed in the table below. </p> + +<table> +<tr> + <th width="25 %" >Subcommand + <th width="30%" >Description</th> + <th width="35%">Comments</th> +</tr> + + <tr> + <td><code>send <type>:<code>:<value> [...]</code></td> + <td>Send one or more events to the Android kernel. </td> + <td>You can use text names or integers for <code><type></code> and <code><value></code>.</td> + </tr> +<tr> + <td><code>types</code></td> + <td>List all <code><type></code> string aliases supported by the <code>event</code> subcommands.</td> +<td> </td> +</tr> +<tr> + <td><code>codes <type></code></td> + <td>List all <code><codes></code> string aliases supported by the <code>event</code> + subcommands for the specified <code><type></code>.</td> +<td> </td> +</tr> +<tr> + <td><code>event text <message></code></td> + <td>Simulate keypresses to send the specified string of characters as a message,</td> +<td>The message must be a UTF-8 string. Unicode posts will be reverse-mapped according to the current device keyboard. Unsupported characters will be discarded silently.</td> +</tr> +</table> + +<a name="power"></a> +<h3>Device Power Characteristics</h3> + +<p>You can use the <code>power</code> command to control the simulated power state of the emulator instance.The usage for the command is: </p> + +<pre>power <display|ac|status|present|health|capactiy></pre> + +<p>The <code>event</code> command supports the subcommands listed in the table below. </p> + +<table> +<tr> + <th width="25 %" >Subcommand + <th width="30%" >Description</th> + <th width="35%">Comments</th> +</tr> + + <tr> + <td><code>display</code></td> + <td>Display battery and charger state.</td> + <td> </td> + </tr> +<tr> + <td><code>ac <on|off></code></td> + <td>Set AC charging state to on or off. </td> +<td> </td> +</tr> +<tr> + <td><code>status <unknown|charging|discharging|not-charging|full></code></td> + <td>Change battery status as specified.</td> +<td> </td> +</tr> + +<tr> + <td><code>present <true|false></code></td> + <td>Set battery presence state.</td> +<td> </td> +</tr> +<tr> + <td><code>health <unknown|good|overheat|dead|overvoltage|failure></code></td> + <td>Set battery health state.</td> +<td> </td> +</tr> +<tr> + <td><code>power health <percent></code></td> + <td>Set remaining battery capacity state (0-100).</td> +<td> </td> +</tr> +</table> + +<a name="netstatus"></a> +<h3>Network Status</h3> + +<p>You can use the console to check the network status and current delay and speed characteristics. To do so, connect to the console and use the <code>netstatus</code> command. Here's an example of the command and its output. </p> + +<pre>network status +</pre> + +<a name="netdelay"></a> +<h3>Network Delay Emulation</h3> + +<p>The emulator lets you simulate various network latency levels, so that you can test your applicaton in an environment more typical of the actual conditions in which it will run. You can set a latency level or range at emulator startup or you can use the console to change the latency dynamically, while the application is running in the emulator. </p> +<p>To set latency at emulator startup, use the <code>-netdelay</code> emulator option with a supported <code><delay></code> value, as listed in the table below. Here are some examples:</p> +<pre>emulator -netdelay gprs +emulator -netdelay 40 100</pre> + +<p>To make dynamic changes to network delay while the emulator is running, connect to the console and use the <code>netdelay</code> command with a supported <code><delay></code> value from the table below. </p> + +<pre>network delay gprs</pre> + +<p>The format of network <delay> is one of the following (numbers are milliseconds):</p> + +<table style="clear:right;width:100%;"> +<tr> + <th width="30%" >Value</td> + <th width="35%" >Description</th><th width="35%">Comments</th></tr> + + <tr><td><code>gprs</code></td><td>GPRS</td> + <td>(min 150, max 550)</td> + </tr> + +<tr><td><code>edge</code></td><td>EDGE/EGPRS</td> +<td>(min 80, max 400)</td> +</tr> +<tr><td><code>umts</code></td><td>UMTS/3G</td> +<td>(min 35, max 200)</td> +</tr> +<tr><td><code>none</code></td><td>No latency</td><td>(min 0, max 0)</td></tr> +<tr><td><code><num></code></td> +<td>Emulate an exact latency (milliseconds).</td> +<td> </td></tr> +<tr><td><code><min>:<max></code></td> +<td>Emulate an specified latency range (min, max milliseconds).</td> +<td> </td></tr> +</table> + +<a name="netspeed"></a> +<h3>Network Speed Emulation</h3> + +<p>The emulator also lets you simulate various network transfer rates. You can set a transfer rate or range at emulator startup or you can use the console to change the rate dynamically, while the application is running in the emulator. </p> +<p>To set the network speed at emulator startup, use the <code>-netspeed</code> emulator option with a supported <code><speed></code> value, as listed in the table below. Here are some examples:</p> +<pre>emulator -netspeed gsm +emulator -netspeed 14.4 80</pre> + +<p>To make dynamic changes to network speed while the emulator is running, connect to the console and use the <code>netspeed</code> command with a supported <code><speed></code> value from the table below. </p> + +<pre>network speed 14.4 80</pre> + +<p>The format of network <code><speed></code> is one of the following (numbers are +kilobits/sec):</p> +<table style="clear:right;width:100%;"> +<tbody> +<tr> + <th width="30%">Value</td> + <th width="35%">Description</th><th width="35%">Comments</th></tr> + + <tr> + <td><code>gsm</code></td> + <td>GSM/CSD</td><td>(Up: 14.4, down: 14.4)</td></tr> +<tr> + <td><code>hscsd</code></td> + <td>HSCSD</td><td>(Up: 14.4, down: 43.2)</td></tr> +<tr> + <td><code>gprs</code></td> + <td>GPRS</td><td>(Up: 40.0, down: 80.0)</td></tr> +<tr> + <td><code>edge</code></td> + <td>EDGE/EGPRS</td> + <td>(Up: 118.4, down: 236.8)</td> +</tr> +<tr> + <td><code>umts</code></td> + <td>UMTS/3G</td><td>(Up: 128.0, down: 1920.0)</td></tr> +<tr> + <td><code>hsdpa</code></td> + <td>HSDPA</td><td>(Up: 348.0, down: 14400.0)</td></tr> +<tr> + <td><code>full</code></td> + <td>no limit</td><td>(Up: 0.0, down: 0.0)</td></tr> +<tr> + <td><code><num></code></td> + <td>Set an exact rate used for both upload and download.</td><td></td></tr> +<tr> + <td><code><up>:<down></code></td> + <td>Set exact rates for upload and download separately.</td><td></td></tr> +</table> + + +<a name="telephony"></a> + +<h3>Telephony Emulation</h3> + +<p>The Android emulator includes its own GSM emulated modem that lets you simulate telephony functions in the emulator. For example, you can simulate inbound phone calls and establish/terminate data connections. The Android system handles simulated calls exactly as it would actual calls. The emulator does not support call audio in this release. </p> +<p>You can use the console to access the emulator's telephony functions. After connecting to the console, you can use</p> +<pre>gsm <call|accept|busy|cancel|data|hold|list|voice|status> </pre> +<p>to invoke telephony functions. </p> +<p>The <code>gsm</code> command supports the subcommands listed in the table below. </p> +<table> + <tr> + <th >Subcommand </th> + <th width="25%">Description</th> + <th>Comments</th> + </tr> + <tr> + <td><code>call <phonenumber></code></td> + <td>Simulate an inbound phone call from <phonenumber>.</td> + <td>See also <a href="#calling">Sending a Voice Call or SMS to another Emulator Instance</a>.</td> + </tr> + <tr> + <td><code>accept <phonenumber></code></td> + <td>Accept an inbound call from <phonenumber> and change the call's state "active".</td> + <td>You can change a call's state to "active" only if its current state is "waiting" or "held".</td> + </tr> + <tr> + <td><code>busy <phonenumber></code></td> + <td>Close an outbound call to <phonenumber> and change the call's state to "busy".</td> + <td>You can change a call's state to "busy" only if its current state is "waiting".</td> + </tr> + <tr> + <td><code>cancel <phonenumber></code></td> + <td>Terminate an inbound or outbound phone call to/from <phonenumber>.</td> + <td> </td> + </tr> + <tr> + <td><code>data <state></code></td> + <td>Change the state of the GPRS data connection to <state>.</td> + <td>Supported <state> values are:<br /> + <li><code>unregistered</code> -- No network available</li> + <li><code>home</code> -- On local network, non-roaming</li> + <li><code>roaming</code> -- On roaming network</li> + <li><code>searching</code> -- Searching networks</li> + <li><code>denied</code> -- Emergency calls only</li> + <li><code>off</code> -- Same as 'unregistered'</li> + <li><code>on</code> -- same as 'home'</li> </td> + </tr> + <tr> + <td><code>hold</code></td> + <td>Change the state of a call to "held". </td> + <td>You can change a call's state to "held" only if its current state is "active" or "waiting". </td> + </tr> + <tr> + <td><code>list</code></td> + <td>List all inbound and outbound calls and their states.</td> + <td> </td> + </tr> + <tr> + <td><code>voice <state></code></td> + <td>Change the state of the GPRS voice connection to <state>.</td> + <td>Supported <state> values are:<br /> + <li><code>unregistered</code> -- No network available</li> + <li><code>home</code> -- On local network, non-roaming</li> + <li><code>roaming</code> -- On roaming network</li> + <li><code>searching</code> -- Searching networks</li> + <li><code>denied</code> -- Emergency calls only</li> + <li><code>off</code> -- Same as 'unregistered'</li> + <li><code>on</code> -- Same as 'home'</li></td> + </tr> + + <tr> + <td><code>status</code></td> + <td>Report the current GSM voice/data state.</td> + <td>Values are those described for the <code>voice</code> and <code>data</code> commands.</td> + </tr> +</table> + +<a name="sms"></a> + +<h3>SMS Emulation</h3> + +<p>The Android emulator console lets you generate an SMS message and direct it to an emulator instance. Once you connect to an emulator instance, you can generate an emulated incoming SMS using this command:</p> + +<pre>sms send <senderPhoneNumber> <textmessage></pre> + +<p>where <code><senderPhoneNumber></code> contains an arbitrary numeric string. </p> + +<p>The console forwards the SMS message to the Android framework, which passes it through to an application that handles that message type. </p> + +<a name="vm"></a> + +<h3>VM State</h3> + +<p>You can use the <code>vm</code> command to control the VM on an emulator instance.The usage for the command is: </p> + +<pre>vm <start|stop|status></pre> + +<p>The <code>vm</code> command supports the subcommands listed in the table below. </p> + +<table> +<tr> + <th width="25%" >Subcommand + <th width="30%" >Description</th> + <th width="35%">Comments</th> +</tr> +<tr> + <td><code>start</code></td> + <td>Start the VM on the instance. </td> + <td> </td> +</tr> +<tr> + <td><code>stop</code></td> + <td>Stop the VM on the instance. </td> + <td> </td> +</tr> +<tr> + <td><code>start</code></td> + <td>Display the current status of the VM (running or stopped). </td> + <td> </td> +</tr> +</table> + + +<a name="window"></a> + +<h3>Emulator Window</h3> + +<p>You can use the <code>window</code> command to manage the emulator window. The usage for the command is: </p> + +<pre>window <scale></pre> + +<p>The <code>vm</code> command supports the subcommands listed in the table below. </p> + +<table> +<tr> + <th width="25%" >Subcommand + <th width="30%" >Description</th> + <th width="35%">Comments</th> +</tr> +<tr> + <td><code>scale <scale></code></td> + <td>Scale the emulator window.</td> + <td><scale> must be a number between 0.1 and 3 that describes the desired scaling factor. You can + also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" + tells the emulator to select the best window size.</td> +</tr> +</table> + + +<a name="terminating"></a> + +<h3>Terminating an Emulator Instance</h3> + +<p>You can terminate an emulator instance through the console, using the <code>kill</code> command.</p> + + +<a name="skins"></a> + +<h2>Using Emulator Skins</h2> + +<p>You can run the emulator with any of four default skins, as described in the table below. To specify a skin, use <code>-skin <skinID></code> when starting the emulator. </p> + +<p>For example: </p> + +<pre>emulator -skin HVGA-L</pre> + +<p>Note that you must enter the <code><skinID></code> in uppercase letters (if your development computer is case-sensitive).</p> + +<table border="0" style="clear:left;padding:2em;"> + <tr> + <th width="20%">skinID</th> + <th >Description</th> + <th >Skin</th> + </tr> + <tr> + <td><code>HVGA-L</code></td> + <td>480x320, landscape</td> + <td><img src="{@docRoot}images/e-mini-hvga-l.png" width="219" height="113"></td> + </tr> + <tr> + <td><code>HVGA-P</code></td> + <td>320x480, portrait (default)</td> + <td><img src="{@docRoot}images/e-mini-hvga-p.png" width="113" height="219"></td> + </tr> + <tr> + <td><code>QVGA-L</code></td> + <td>320x240, landscape</td> + <td><img src="{@docRoot}images/e-mini-qvga-l.png" width="119" height="197"></td> + </tr> + <tr> + <td><code>QVGA-P</code></td> + <td>240x320, portrait</td> + <td><img src="{@docRoot}images/e-mini-qvga-p.png" width="95" height="173"></td> + </tr> +</table> + +<a name="multipleinstances"></a> + +<h2>Running Multiple Emulator Instances</h2> + +<p>You can run multiple instances of the emulator concurrently, if necessary. Each emulator instance can use a separate user-data image file and a different console port. This lets you manage each instance in isolation. </p> + +<p>However, if you will run multiple emulator instances, note that there are limitations on the capability of each instance to maintain its persistent user data — user settings and installed applications — across sessions. Specifically:</p> + +<ul> + <li>By default, only the first-launched emulator instance can preserve user data across sessions. When a session closes, + the emulator stores the user data to a user-data image file — by default, it stores the data in the file + <code>~/.android/userdata-qemu.img </code>(on Linux and Mac) or <code>C:\Documents and Settings\<user>\Local + Settings\Application Data\Android\userdata-qemu.img</code> (on Windows) in your development computer.</li> + +<li>Emulator instances that you start after the first instance (that are running concurrently) can also store user data during a session, but they <em>do not</em> preserve it for the next session, unless you have specified a unique user-data image file in which the data should be stored. </li> + +</ul> + +<p>To run multiple emulator instances and let each maintain user data across sessions, start the instances with the <code>-data</code> option (see <a href="#startup-options">Startup Options</a>) and supply the path to a user-data file. </p> + +<a name="apps"></a> + +<h2>Installing Applications on the Emulator</h2> + +<p>If you don't have access to Eclipse or the ADT Plugin, you can install +your application on the emulator <a href="{@docRoot}reference/adb.html#move">using +the adb utility</a>. Before installing the application, you need to package it +in a .apk file using the <a href="aapt.html">Android Asset Packaging Tool</a>. +Once the application is installed, you can start the emulator from the command +line, as described in this document, using any startup options necessary. +When the emulator is running, you can also connect to the emulator instance's +console to issue commands as needed.</p> + +<p>As you update your code, you periodically package and install it on the emulator. +The emulator preserves the application and its state data across restarts, +in a user-data disk partition. To ensure that the application runs properly +as you update it, you may need to delete the emulator's user-data partition. +To do so, start the emulator with the <code>-wipe-data</code> option. +For more information about the user-data partition and other emulator storage, +see <a href="#diskimages">Working with Emulator Disk Images</a>.</p> + +<a name="sdcard"></a> + +<h2>SD Card Emulation</h2> +<p>You can create a disk image and then load it to the emulator at startup, to simulate the presence of a user's SD card in the device. The sections below describe how to create the disk image, how to copy files to it, and how to load it in the emulator at startup. </p> + +<p>Note that you can only load disk image at emulator startup. Similarly, you can not remove a simulated SD card from a running emulator. However, you can browse, send files to, and copy/remove files from a simulated SD card either with adb or the emulator. </p> + +<p>The emulator supports emulated SDHC cards, so you can create an SD card image of any size up to 128 gigabytes.</p> + +<a name="creating"></a> + +<h3>Creating a Disk Image</h3> + +<p>You can use the mksdcard tool, included in the SDK, to create a FAT32 disk image that you can load in the emulator at startup. You can access mksdcard in the tools/ directory of the SDK and create a disk image like this: </p> + +<pre>mksdcard <size> <file></pre> + +<p>For example:</p> + +<pre>mksdcard 1024M sdcard1.iso</pre> + +<p>For more information, see <a href="{@docRoot}reference/othertools.html">Other Tools</a>. </p> + +<a name="copying"></a> +<h3>Copying Files to a Disk Image</h3> + +<p>Once you have created the disk image, you can copy files to it prior to loading it in the emulator. To copy files, you can mount the image as a loop device and then copy the files to it, or you can use a utility such as mtools to copy the files directly to the image. The mtools package is available for Linux, Mac, and Windows.</p> + +<a name="loading"></a> +<a name="step3" id="step3"></a> + +<h3>Loading the Disk Image at Emulator Startup</h3> +<p>To load FAT32 disk image in the emulator, start the emulator with the <code>-sdcard</code> flag and specify the name and path of your image (relative to the current working directory): </p> + +<pre>emulator -sdcard <filepath></pre> + +<a name="troubleshooting"></a> + +<h2>Troubleshooting Emulator Problems</h2> + +<p>The adb utility sees the emulator as an actual physical device. For this reason, you might have to use the -d flag with some common adb commands, such as <code>install</code>. The -d flag lets you specify which of several connected devices to use as the target of a command. If you don't specify -d, the emulator will target the first device in its list. For more information about adb, see <a href="{@docRoot}reference/adb.html">Android Debug Bridge</a>.</p> + +<p>For emulators running on Mac OS X, if you see an error "Warning: No DNS servers found" when starting the emulator, check to see whether you have an <code>/etc/resolv.conf</code> file. If not, please run the following line in a command window:</p> + <pre>ln -s /private/var/run/resolv.conf /etc/resolv.conf</pre> + +<p>See <a href="{@docRoot}kb/index.html">Frequently Asked Questions</a> for more troubleshooting information. </p> + +<a name="limitations"></a> + <h2>Emulator Limitations</h2> + <p>In this release, the limitations of the emulator include: </p> + <ul> + <li>No support for placing or receiving actual phone calls. You can simulate phone calls (placed and received) through the emulator console, however. </li> + <li>No support for USB connections</li> + <li>No support for camera/video capture (input).</li> + <li>No support for device-attached headphones</li> + <li>No support for determining connected state</li> + <li>No support for determining battery charge level and AC charging state</li> + <li>No support for determining SD card insert/eject</li> + <li>No support for Bluetooth</li> + </ul> diff --git a/docs/html/guide/developing/tools/hierarchy-viewer.jd b/docs/html/guide/developing/tools/hierarchy-viewer.jd new file mode 100644 index 0000000..065211c --- /dev/null +++ b/docs/html/guide/developing/tools/hierarchy-viewer.jd @@ -0,0 +1,99 @@ +page.title=Hierarchy Viewer +@jd:body + +<p>The Hierarchy Viewer application allows you to debug and optimize your user +interface. It provides a visual representation of the layout's View hierarchy +(the Layout View) and a magnified inspector of the display (the Pixel Perfect View). +</p> + +<p>To get the Hierarchy Viewer started:</p> +<ol> + <li>Connect your device or launch an emulator.</li> + <li>From a terminal, launch <code>hierarchyviewer</code> from your SDK + <code>/tools</code> directory. + </li> + <li>In the window that opens, you'll see a list of <strong>Devices</strong>. When a device is + selected, a list of currently active <strong>Windows</strong> is displayed + on the right. The <em><Focused Window></em> is the window currently in + the foreground, and also the default window loaded if you do not select another. + </li> + <li>Select the window that you'd like to inspect and click + <strong>Load View Hierarchy</strong>. The Layout View will be loaded. + You can then load the Pixel Perfect View by clicking the second + icon at the bottom-left of the window. + </li> +</ol> + +<p>If you've navigated to a different window on the device, press <strong>Refresh Windows</strong> +to refresh the list of available windows on the right.</p> + +<h2>Layout View</h2> +<p>The Layout View offers a look at the View layout and properties. It has three views:</p> +<ul> + <li>Tree View: a hierarchy diagram of the Views, on the left.</li> + <li>Properties View: a list of the selected View's properties, on the top-right.</li> + <li>Wire-frame View: a wire-frame drawing of the layout, on the bottom-right.</li> +</ul> +<br/> +<img src="/android/images/hierarchyviewer-layout.png" alt="" height="509" width="700" /> + +<p>Select a node in the Tree View to display the properties of that element in +the Properties View. When a node is selected, the Wire-frame View +also indicates the bounds of the element with a red rectangle. +Double click a node in the tree (or select it, and click <strong>Display +View</strong>) to open a new window with a rendering of that element.</p> + +<p>The Layout View includes a couple other helpful features for debugging your layout: +<strong>Invalidate</strong> and <strong>Request Layout</strong>. These buttons execute the +respective View calls, {@link android.view.View#invalidate()} and {@link android.view.View#requestLayout()}, +on the View element currently selected in the tree. Calling these methods on any View can +be very useful when simultaneously running a debugger on your application.</p> + +<p>The Tree View can be resized by adjusting the zoom slider, below +the diagram. The number of View elements in the window is also given here. You +should look for ways to minimize the number of Views. The fewer View elements there +are in a window, the faster it will perform.</p> + +<p>If you interact with the device and change the focused View, the diagram will not automatically refresh. +You must reload the Layout View by clicking <strong>Load View Hierarchy</strong>. + + +<h2>Pixel Perfect View</h2> +<p>The Pixel Perfect View provides a magnified look at the current device window. It has three views:</p> +<ul> + <li>Explorer View: shows the View hierarchy as a list, on the left.</li> + <li>Normal View: a normal view of the device window, in the middle.</li> + <li>Loupe View: a magnified, pixel-grid view of the device window, on the right.</li> +</ul> +<br/> +<img src="/android/images/hierarchyviewer-pixelperfect.png" alt="" height="509" width="700" /> + +<p>Click on an element in the Explorer View and a "layout box" will be drawn in the +Normal View to indicate the layout position of that element. The layout box uses multiple rectangles, to indicate the normal bounds, the padding and the margin (as needed). The purple or green rectangle indicates +the normal bounds of the element (the height and width). The inner white or black rectangle indicates +the content bounds, when padding is present. A black or white rectangle outside the normal purple/green +rectangle indicates any present margins. +(There are two colors for each rectangle, in order to provide the best contrast +based on the colors currently in the background.)</p> + +<p>A very handy feature for designing your UI is the ability to overlay an image in the Normal and Loupe +Views. For example, you might have a mock-up image of how you'd like to layout your interface. +By selecting <strong>Load...</strong> from the controls in the Normal View, you can choose the +image from your computer and it will be placed atop the preview. Your chosen image will anchor at the bottom left corner of the screen. You can then adjust the opacity of the overlay and begin fine-tuning your layout to match the mock-up.</p> + +<p>The Normal View and Loupe View refresh at regular intervals (5 seconds by default), but the +Explorer View does not. If you navigate away and focus on a different View, then you should refresh the +Explorer's hierarchy by clicking <strong>Load View Hierarchy</strong>. This is even true +when you're working in a window that holds multiple Views that are not always visible. If you do not, +although the previews will refresh, clicking a View in the Explorer will not provide the proper layout box +in the Normal View, because the hierarchy believes you are still focused on the prior View.</p> + +<p>Optional controls include:</p> +<ul> + <li><strong>Overlay</strong>: Load an overlay image onto the view and adjust its opacity.</li> + <li><strong>Refresh Rate</strong>: Adjust how often the Normal and Loupe View refresh their display.</li> + <li><strong>Zoom</strong>: Adjust the zoom level of the Loupe View.</li> +</ul> + +<p><strong><a href="/android/intro/tools.html">Back to Development Tools</a></strong></p> + diff --git a/docs/html/guide/developing/tools/index.jd b/docs/html/guide/developing/tools/index.jd new file mode 100644 index 0000000..c38f6c5 --- /dev/null +++ b/docs/html/guide/developing/tools/index.jd @@ -0,0 +1,110 @@ +page.title=Tools Overview +@jd:body + +<img src="{@docRoot}images/android_icon_125.png" alt="android_robot" align="right" width="125" height="137""> + +<p>The Android SDK includes a variety of custom tools that help you develop mobile +applications on the Android platform. The most important of these are the Android +Emulator and the Android Development Tools plugin for Eclipse, but the SDK also +includes a variety of other tools for debugging, packaging, and installing your +applications on the emulator. </p> + +<dl> + <dt><a href="{@docRoot}emulator.html">Android Emulator</a></dt> + <dd>A virtual mobile device that runs on your computer. You use the emulator to design, + debug, and test your applications in an actual Android run-time environment. </dd> + + <dt><a href="{@docRoot}hierarchy-viewer.html">Hierarchy Viewer</a> + <sup class="new">New!</sup></dt></dt> + <dd>The Hierarchy Viewer tool allows you to debug and optimize your user interface. + It provides a visual representation of your layout's hierarchy of Views and a magnified inspector + of the current display with a pixel grid, so you can get your layout just right. + </dd> + + <dt><a href="{@docRoot}draw9patch.html">Draw 9-patch</a> + <sup class="new">New!</sup></dt> + <dd>The Draw 9-patch tool allows you to easily create a + {@link android.graphics.NinePatch} graphic using a WYSIWYG editor. It also previews stretched + versions of the image, and highlights the area in which content is allowed. + </dd> + + <dt>Android + Development Tools Plugin</a> for the Eclipse IDE</dt> + <dd>The ADT plugin adds powerful extensions to the Eclipse integrated environment, + making creating and debugging your Android applications easier and faster. If you + use Eclipse, the ADT plugin gives you an incredible boost in developing Android + applications: + </dd> + + <ul> + <li>It gives you access to other Android development tools from inside + the Eclipse IDE. For example, ADT lets you access the many capabilities of the + DDMS tool — taking screenshots, managing port-forwarding, setting breakpoints, + and viewing thread and process information — directly from Eclipse. + <li>It provides a New Project Wizard, which helps you quickly create and set up + all of the basic files you'll need for a new Android application.</li> + <li>It automates and simplifies the process of building your Android application.</li> + <li>It provides an Android code editor that helps you write valid XML for your + Android manifest and resource files.</li> + </ul> + + <p>For more information about the ADT plugin, including + installation instructions, see <em>Installing the ADT Plugin for + Eclipse</em> in your SDK package. For a usage example with screenshots, see the <a + href="{@docRoot}tutorials/hello-android.html" title="Hello + Android">Hello Android</a> tutorial.</p> + + <dt><a href="{@docRoot}ddms.html" >Dalvik Debug Monitor + Service</a> (ddms)</dt> + <dd>Integrated with Dalvik, the Android platform's custom VM, this tool + lets you manage processes on an emulator or device and assists in debugging. + You can use it to kill processes, select a specific process to debug, + generate trace data, view heap and thread information, take screenshots + of the emulator or device, and more. </dd> + + <dt><a href="{@docRoot}adb.html" >Android Debug Bridge</a> (adb)</dt> + <dd>The adb tool lets you install your application's .apk files on an + emulator or device and access the emulator or device from a command line. + You can also use it to link a standard debugger to application code running + on an Android emulator or device.</dd> + + <dt><a href="{@docRoot}aapt.html" >Android Asset + Packaging Tool</a> (aapt)</dt> + <dd>The aapt tool lets you create .apk files containing the binaries and + resources of Android applications.</dd> + + <dt><a href="{@docRoot}aidl.html" >Android Interface + Description Language</a> (aidl)</dt> + <dd>Lets you generate code for an interprocess interface, such as what + a service might use.</dd> + + <dt><a href="{@docRoot}adb.html#sqlite">sqlite3</a></dt> + <dd>Included as a convenience, this tool lets you access the SQLite data + files created and used by Android applications.</dd> + + <dt><a href="{@docRoot}traceview.html" >Traceview</a></dt> + <dd> This tool produces graphical analysis views of trace log data that you + can generate from your Android application. </dd> + + <dt><a href="{@docRoot}othertools.html#mksdcard">mksdcard</a></dt> + <dd>Helps you create a disk image that you can use with the emulator, + to simulate the presence of an external storage card (such as an SD card).</dd> + + <dt><a href="{@docRoot}othertools.html#dx">dx</a></dt> + <dd>The dx tool rewrites .class bytecode into Android bytecode + (stored in .dex files.)</dd> + + <dt><a href="{@docRoot}monkey.html" >UI/Application + Exerciser Monkey</a></dt> + <dd>The Monkey is a program that runs on your emulator or device and generates pseudo-random + streams of user events such as clicks, touches, or gestures, as well as a number of system- + level events. You can use the Monkey to stress-test applications that you are developing, + in a random yet repeatable manner.</dd> + + <dt><a href="{@docRoot}othertools.html#activitycreator">activitycreator</a></dt> + <dd>A script that generates <a + href="http://ant.apache.org/" title="Ant">Ant</a> build files that + you can use to compile your Android applications. If you are developing + on Eclipse with the ADT plugin, you won't need to use this script. </dd> +</dl> + diff --git a/docs/html/guide/developing/tools/monkey.jd b/docs/html/guide/developing/tools/monkey.jd new file mode 100644 index 0000000..d829f5b --- /dev/null +++ b/docs/html/guide/developing/tools/monkey.jd @@ -0,0 +1,240 @@ +page.title=UI/Application Exerciser Monkey +@jd:body + +<p>The Monkey is a program that runs on your +<a href="{@docRoot}reference/emulator.html">emulator</a> or device and generates pseudo-random +streams of user events such as clicks, touches, or gestures, as well as a number of system-level +events. You can use the Monkey to stress-test applications that you are developing, in a random +yet repeatable manner.</p> + +<a name="overview"></a> +<h2>Overview</h2> + +<p>The Monkey is a command-line tool that that you can run on any emulator +instance or on a device. It sends a pseudo-random stream of +user events into the system, which acts as a stress test on the application software you are +developing.</p> + +<p>The Monkey includes a number of options, but they break down into four primary +categories:</p> + +<ul> + <li>Basic configuration options, such as setting the number of events to attempt.</li> + <li>Operational constraints, such as restricting the test to a single package.</li> + <li>Event types and frequencies.</li> + <li>Debugging options.</li> +</ul> + +<p>When the Monkey runs, it generates events and sends them to the system. It also <i>watches</i> +the system under test and looks for three conditions, which it treats specially:</p> + +<ul> + <li>If you have constrained the Monkey to run in one or more specific packages, it + watches for attempts to navigate to any other packages, and blocks them.</li> + <li>If your application crashes or receives any sort of unhandled exception, the Monkey + will stop and report the error.</li> + <li>If your application generates an <i>application not responding</i> error, the Monkey + will stop and report the error.</li> +</ul> + +<p>Depending on the verbosity level you have selected, you will also see reports on the progress +of the Monkey and the events being generated.</p> + +<a name="basics"></a> +<h2>Basic Use of the Monkey</h2> + +<p>You can launch the Monkey using a command line on your development machine or from a script. +Because the Monkey runs in the emulator/device environment, you must launch it from a shell in +that environment. You can do this by prefacing <code>adb shell</code> to each command, +or by entering the shell and entering Monkey commands directly.</p> +<p>The basic syntax is: </p> + +<pre>$ adb shell monkey [options] <event-count></pre> + +<p>With no options specified, the Monkey will launch in a quiet (non-verbose) mode, and will send +events to any (and all) packages installed on your target. Here is a more typical command line, +which will launch your application and send 500 pseudo-random events to it:</p> + +<pre>$ adb shell monkey -p your.package.name -v 500</pre> + +<a name="reference"></a> +<h2>Command Options Reference</h2> + +<p>The table below lists all options you can include on the Monkey command line.</p> + +<table> +<tr> + <th>Category</th> + <th>Option</th> + <th>Description</th> +</tr> + +<tr> +<td rowspan="2">General</td> +<td><code>--help</code></td> +<td>Prints a simple usage guide.</td> +</tr> + +<tr> +<td><code>-v</code></td> +<td>Each -v on the command line will increment the verbosity level. +Level 0 (the default) provides little information beyond startup notification, test completion, and +final results. +Level 1 provides more details about the test as it runs, such as individual events being sent to +your activities. +Level 2 provides more detailed setup information such as activities selected or not selected for +testing.</td> +</tr> + +<tr> +<td rowspan="10">Events</td> +<td><code>-s <seed></code></td> +<td>Seed value for pseudo-random number generator. If you re-run the Monkey with the same seed +value, it will generate the same sequence of events.</td> +</tr> + +<tr> +<td><code>--throttle <milliseconds></code></td> +<td>Inserts a fixed delay between events. You can use this option to slow down the Monkey. +If not specified, there is no delay and the events are generated as rapidly as possible.</td> +</tr> + +<tr> +<td><code>--pct-touch <percent></code></td> +<td>Adjust percentage of touch events. +(Touch events are a down-up event in a single place on the screen.)</td> +</tr> + +<tr> +<td><code>--pct-motion <percent></code></td> +<td>Adjust percentage of motion events. +(Motion events consist of a down event somewhere on the screen, a series of pseudo-random +movements, and an up event.)</td> +</tr> + +<tr> +<td><code>--pct-trackball <percent></code></td> +<td>Adjust percentage of trackball events. +(Trackball events consist of one or more random movements, sometimes followed by a click.)</td> +</tr> + +<tr> +<td><code>--pct-nav <percent></code></td> +<td>Adjust percentage of "basic" navigation events. +(Navigation events consist of up/down/left/right, as input from a directional input device.)</td> +</tr> + +<tr> +<td><code>--pct-majornav <percent></code></td> +<td>Adjust percentage of "major" navigation events. +(These are navigation events that will typically cause actions within your UI, such as +the center button in a 5-way pad, the back key, or the menu key.)</td> +</tr> + +<tr> +<td><code>--pct-syskeys <percent></code></td> +<td>Adjust percentage of "system" key events. +(These are keys that are generally reserved for use by the system, such as Home, Back, Start Call, +End Call, or Volume controls.)</td> +</tr> + +<tr> +<td><code>--pct-appswitch <percent></code></td> +<td>Adjust percentage of activity launches. At random intervals, the Monkey will issue a startActivity() call, as a way of maximizing +coverage of all activities within your package.</td> +</tr> + +<tr> +<td><code>--pct-anyevent <percent></code></td> +<td>Adjust percentage of other types of events. This is a catch-all for all other types of events such as keypresses, other less-used +buttons on the device, and so forth.</td> +</tr> + +<tr> +<td rowspan="2">Constraints</td> +<td><code>-p <allowed-package-name></code></td> +<td>If you specify one or more packages this way, the Monkey will <i>only</i> allow the system +to visit activities within those packages. If your application requires access to activities in +other packages (e.g. to select a contact) you'll need to specify those packages as well. +If you don't specify any packages, the Monkey will allow the system to launch activities +in all packages. To specify multiple packages, use the -p option multiple times — one -p +option per package.</td> +</tr> + +<tr> +<td><code>-c <main-category></code></td> +<td>If you specify one or more categories this way, the Monkey will <i>only</i> allow the +system to visit activities that are listed with one of the specified categories. +If you don't specify any categories, the Monkey will select activities listed with the category +Intent.CATEGORY_LAUNCHER or Intent.CATEGORY_MONKEY. To specify multiple categories, use the -c +option multiple times — one -c option per category.</td> +</tr> + +<tr> +<td rowspan="8">Debugging</td> +<td><code>--dbg-no-events</code></td> +<td>When specified, the Monkey will perform the initial launch into a test activity, but +will not generate any further events. +For best results, combine with -v, one or more package constraints, and a non-zero throttle to keep the Monkey +running for 30 seconds or more. This provides an environment in which you can monitor package +transitions invoked by your application.</td> +</tr> + +<tr> +<td><code>--hprof</code></td> +<td>If set, this option will generate profiling reports immediately before and after +the Monkey event sequence. +This will generate large (~5Mb) files in data/misc, so use with care. See +<a href="{@docRoot}reference/traceview.html" title="traceview">Traceview</a> for more information +on trace files.</td> +</tr> + +<tr> +<td><code>--ignore-crashes</code></td> +<td>Normally, the Monkey will stop when the application crashes or experiences any type of +unhandled exception. If you specify this option, the Monkey will continue to send events to +the system, until the count is completed.</td> +</tr> + +<tr> +<td><code>--ignore-timeouts</code></td> +<td>Normally, the Monkey will stop when the application experiences any type of timeout error such +as a "Application Not Responding" dialog. If you specify this option, the Monkey will continue to +send events to the system, until the count is completed.</td> +</tr> + +<tr> +<td><code>--ignore-security-exceptions</code></td> +<td>Normally, the Monkey will stop when the application experiences any type of permissions error, +for example if it attempts to launch an activity that requires certain permissions. If you specify +this option, the Monkey will continue to send events to the system, until the count is +completed.</td> +</tr> + +<tr> +<td><code>--kill-process-after-error</code></td> +<td>Normally, when the Monkey stops due to an error, the application that failed will be left +running. When this option is set, it will signal the system to stop the process in which the error +occurred. +Note, under a normal (successful) completion, the launched process(es) are not stopped, and +the device is simply left in the last state after the final event.</td> +</tr> + +<tr> +<td><code>--monitor-native-crashes</code></td> +<td>Watches for and reports crashes occurring in the Android system native code. If --kill-process-after-error is set, the system will stop.</td> +</tr> + +<tr> +<td><code>--wait-dbg</code></td> +<td>Stops the Monkey from executing until a debugger is attached to it.</td> +</tr> + +</table> + +<!-- TODO: add a section called "debugging" that covers ways to use it, +need to clear data, use of the seed, etc. --> + +<!-- TODO: add a section that lays down a contract for Monkey output so it can be +scripted safely. --> + diff --git a/docs/html/guide/developing/tools/othertools.jd b/docs/html/guide/developing/tools/othertools.jd new file mode 100755 index 0000000..4ebcf4a --- /dev/null +++ b/docs/html/guide/developing/tools/othertools.jd @@ -0,0 +1,104 @@ +page.title=Other Tools +@jd:body + +<p>The sections below describe other tools that you can use when building Android applications. </p> + +<p>All of the tools are included in the Android SDK and are accessible from the <code>tools/</code> directory.</p> + +<h2>Contents</h2> + +<dl> + <dt><a href="#mksdcard">mksdcard</a></dt> + <dt><a href="#dx">dx</a></dt> + <dt><a href="#activitycreator">activitycreator</a></dd> +</dl> + +<a name="mksdcard"></a> + +<h2>mksdcard</h2> + +<p>The mksdcard tool lets you quickly create a FAT32 disk image that you can load in the emulator, to simulate the presence of an SD card in the device. Here is the usage for mksdcard:</p> + +<pre>mksdcard [-l label] <size>[K|M] <file></pre> + +</p>The table below lists the available options/arguments</p> + +<table> +<tr> + <th>Argument</th> + <th>Description</th> +</tr> + +<tr> + <td><code>-l</code></td> + <td>A volume label for the disk image to create. </td> +</tr> + +<tr> + <td><code>size</code></td> + <td>An integer that specifies the size (in bytes) of disk image to create. +You can also specify size in kilobytes or megabytes, by appending a "K" or "M" to <size>. For example, <code>1048576K</code>, <code>1024M</code>.</td> +</tr> + +<tr> + <td><code>file</code></td> + <td>The path/filename of the disk image to create. </td> +</tr> + +</table> + +<p>Once you have created the disk image file, you can load it in the emulator at startup using the emulator's -sdcard option. For more information, see <a href="{@docRoot}reference/emulator.html">Android Emulator</a>.</p> + +<pre>emulator -sdcard <file></pre> + +<a name="dx"></a> + +<h2>dx</h2> + +<p>The dx tool lets you generate Android bytecode from .class files. The tool converts target files and/or directories to Dalvik executable format (.dex) files, so that they can run in the Android environment. It can also dump the class files in a human-readable format and run a target unit test. You can get the usage and options for this tool by using <code>dx -help</code>.</p> + +<a name="activitycreator"></a> + +<h2>activitycreator</h2> + +<p>If you aren't using the Eclipse IDE and ADT plugin, you can use the the activitycreator script to get started with a new application. When you run the script, it creates the structure of a minimal Android application that you can build on and extend to meet your needs. </p> + +<p>For Linux and Mac, the SDK provides <code>activitycreator.py</code>, a Python script, and for Windows <code>activitycreator.bat</code>, a batch script that runs an executable. Regardless of platform, the usage for the script is the same:</p> + +<pre>activitycreator [--out <folder>] [--ide intellij] your.package.name.ActivityName</pre> + +<table> +<tr> + <th>Option</th> + <th>Description</th> +</tr> + +<tr> + <td><code>--out <folder></code></td> + <td>Specifies where to create the files/folders. </td> +</tr> + +<tr> + <td><code>--ide intellij</code></td> + <td>Creates project files for IntelliJ</td> +</tr> + +</table> + + +<p>When run, the script creates these files: </p> + + <ul> + <li>AndroidManifest.xml -- The application manifest file.</li> + <li>build.xml -- An Ant script to build/package the application.</li> + <li>res -- The resource directory.</li> + <li>src -- The source directory.</li> + <li>src/your/package/name/ActivityName.java -- The Activity class. </li> + <li>bin -- The output folder for the compiled .apk (when built by Ant).</li> +</ul> + +<p>When you are ready, you can use Ant to <a href="{@docRoot}intro/installing.html#buildingwithant">build the project</a> so that you can run it on the emulator.</p> + +<p>If you are using Eclipse with the ADT plugin, you do not need to use activitycreator. You can use the New Project Wizard, provided by the ADT plugin, instead. </p> + + diff --git a/docs/html/guide/developing/tools/traceview.jd b/docs/html/guide/developing/tools/traceview.jd new file mode 100644 index 0000000..8c87eed --- /dev/null +++ b/docs/html/guide/developing/tools/traceview.jd @@ -0,0 +1,310 @@ +page.title=Traceview: A Graphical Log Viewer +@jd:body + +<p>Traceview is a graphical viewer for execution logs +saved by your application. The sections below describe how to use the program. </p> + +<h2>Contents</h2> + +<dl> + <dt><a href="#creatingtracefiles">Creating Trace Files</a></dt> + <dt><a href="#copyingfiles">Copying Trace Files to a Host Machine</a></dt> + <dt><a href="#runningtraceview">Viewing Trace Files in Traceview</a></dt> + <dd><a href="#timelinepanel">Timeline Panel</a></dd> + <dd><a href="#profilepanel">Profile Panel</a></dd> + <dt><a href="#format">Traceview File Format</a></dd> + <dd><a href="#datafileformat">Data File Format</a><dd> + <dd><a href="#keyfileformat">Key File Format</a></dd> + <dt><a href="#knownissues">Traceview Known Issues</a></dd> + <dt><a href="#dmtracedump">Using dmtracedump</a></dt> +</dl> + +<a name="creatingtracefiles"></a> + +<h2>Creating Trace Files</h2> + +<p>To use Traceview, you need to generate log files containing the trace information you want to analyze. To do that, you include the {@link android.os.Debug} + class in your code and call its methods to start and stop logging of trace information + to disk. When your application quits, you can then use Traceview to examine the log files + for useful run-time information such + as method calls and run times. </p> +<p>To create the trace files, include the {@link android.os.Debug} class and call one + of the {@link android.os.Debug#startMethodTracing() startMethodTracing()} methods. + In the call, you specify a base name for the trace files that the system generates. + To stop tracing, call {@link android.os.Debug#stopMethodTracing() stopMethodTracing()}. + These methods start and stop method tracing across the entire virtual machine. For + example, you could call startMethodTracing() in your activity's onCreate() + method, and call stopMethodTracing() in that activity's onDestroy() method.</p> + +<pre> + // start tracing to "/sdcard/calc.trace" + Debug.startMethodTracing("calc"); + // ... + // stop tracing + Debug.stopMethodTracing(); +</pre> + +<p>When your application calls startMethodTracing(), the system creates a +file called <code><trace-base-name>.trace</code>. This contains the +binary method trace data and a mapping table with thread and method names.</p> + +<p>The system then begins buffering the generated trace data, until your application calls + stopMethodTracing(), at which time it writes the buffered data to the + output file. + If the system reaches the maximum buffer size before stopMethodTracing() + is called, the system stops tracing and sends a notification + to the console. </p> + +<p>Interpreted code will run more slowly when profiling is enabled. Don't +try to generate absolute timings from the profiler results (i.e. "function +X takes 2.5 seconds to run"). The times are only +useful in relation to other profile output, so you can see if changes +have made the code faster or slower. </p> + +<p>When using the Android emulator, you must create an SD card image upon which +the trace files will be written. For example, from the <code>/tools</code> directory, you +can create an SD card image and mount it when launching the emulator like so:</p> +<pre> +<b>$</b> mksdcard 1024M ./imgcd +<b>$</b> emulator -sdcard ./img +</pre> +<p>For more information, read about the +<a href="{@docRoot}reference/othertools.html#mksdcard">mksdcard tool</a>.</p> + +<p>The format of the trace files is described <a href="#format">later + in this document</a>. </p> + +<a name="copyingfiles"></a> + +<h2>Copying Trace Files to a Host Machine</h2> +<p>After your application has run and the system has created your trace files <code><trace-base-name>.trace</code> + on a device or emulator, you must copy those files to your development computer. You can use <code>adb pull</code> to copy + the files. Here's an example that shows how to copy an example file, + calc.trace, from the default location on the emulator to the /tmp directory on +the emulator host machine:</p> +<pre>adb pull /sdcard/calc.trace /tmp</pre> + + +<a name="runningtraceview"></a> + +<h2>Viewing Trace Files in Traceview</h2> +<p>To run traceview and view the trace files, enter <code>traceview <trace-base-name></code>. + For example, to run Traceview on the example files copied in the previous section, + you would use: </p> + <pre>traceview /tmp/calc</pre> + + <p>Traceview loads the log files and displays their data in a window that has two panels:</p> + <ul> + <li>A <a href="#timelinepanel">timeline panel</a> -- describes when each thread + and method started and stopped</li> + <li>A <a href="#timelinepanel">profile panel</a> -- provides a summary of what happened inside a method</li> + </ul> + <p>The sections below provide addition information about the traceview output panes. </p> + +<a name="timelinepanel"></a> + +<h3>Timeline Panel </h3> +<p>The image below shows a close up of the timeline panel. Each thread’s + execution is shown in its own row, with time increasing to the right. Each method + is shown in another color (colors are reused in a round-robin fashion starting + with the methods that have the most inclusive time). The thin lines underneath + the first row show the extent (entry to exit) of all the calls to the selected + method. The method in this case is LoadListener.nativeFinished() and it was + selected in the profile view. </p> +<p><img src="../images/traceview_timeline.png" alt="Traceview timeline panel" width="893" height="284"></p> +<a name="profilepanel"></a> +<h3>Profile Panel</h3> +<p>The image below shows the profile pane. The profile pane shows a + summary of all the time spent in a method. The table shows + both the inclusive and exclusive times (as well as the percentage of the total + time). Exclusive time is the time spent in the method. Inclusive time is the + time spent in the method plus the time spent in any called functions. We refer + to calling methods as "parents" and called methods as "children." + When a method is selected (by clicking on it), it expands to show the parents + and children. Parents are shown with a purple background and children + with a yellow background. The last column in the table shows the number of calls + to this method plus the number of recursive calls. The last column shows the + number of calls out of the total number of calls made to that method. In this + view, we can see that there were 14 calls to LoadListener.nativeFinished(); looking + at the timeline panel shows that one of those calls took an unusually + long time.</p> +<p><img src="../images/traceview_profile.png" alt="Traceview profile panel." width="892" height="630"></p> + +<a name="format"></a> +<h2>Traceview File Format</h2> +<p>Tracing creates two distinct pieces of output: a <em>data</em> file, + which holds the trace data, and a <em>key</em> file, which + provides a mapping from binary identifiers to thread and method names. + The files are concatenated when tracing completes, into a + single <em>.trace</em> file. </p> + +<p class="note"><strong>Note:</strong> The previous version of Traceview did not concatenate +these files for you. If you have old key and data files that you'd still like to trace, you +can concatenate them yourself with <code>cat mytrace.key mytrace.data > mytrace.trace</code>.</p> + +<a name="datafileformat"></a> + +<h3>Data File Format</h3> +<p>The data file is binary, structured as + follows (all values are stored in little-endian order):</p> +<pre>* File format: +* header +* record 0 +* record 1 +* ... +* +* Header format: +* u4 magic 0x574f4c53 ('SLOW') +* u2 version +* u2 offset to data +* u8 start date/time in usec +* +* Record format: +* u1 thread ID +* u4 method ID | method action +* u4 time delta since start, in usec +</pre> +<p>The application is expected to parse all of the header fields, then seek + to "offset to data" from the start of the file. From there it just + reads + 9-byte records until EOF is reached.</p> +<p><em>u8 start date/time in usec</em> is the output from gettimeofday(). + It's mainly there so that you can tell if the output was generated yesterday + or three months ago.</p> +<p><em>method action</em> sits in the two least-significant bits of the + <em>method</em> word. The currently defined meanings are: </p> +<ul> + <li>0 - method entry </li> + <li>1 - method exit </li> + <li>2 - method "exited" when unrolled by exception handling </li> + <li>3 - (reserved)</li> +</ul> +<p>An unsigned 32-bit integer can hold about 70 minutes of time in microseconds. +</p> + +<a name="keyfileformat"></a> + +<h3>Key File Format</h3> +<p>The key file is a plain text file divided into three sections. Each + section starts with a keyword that begins with '*'. If you see a '*' at the start + of a line, you have found the start of a new section.</p> +<p>An example file might look like this:</p> +<pre>*version +1 +clock=global +*threads +1 main +6 JDWP Handler +5 Async GC +4 Reference Handler +3 Finalizer +2 Signal Handler +*methods +0x080f23f8 java/io/PrintStream write ([BII)V +0x080f25d4 java/io/PrintStream print (Ljava/lang/String;)V +0x080f27f4 java/io/PrintStream println (Ljava/lang/String;)V +0x080da620 java/lang/RuntimeException <init> ()V +[...] +0x080f630c android/os/Debug startMethodTracing ()V +0x080f6350 android/os/Debug startMethodTracing (Ljava/lang/String;Ljava/lang/String;I)V +*end</pre> +<dl> + <dt><em>version section</em></dt> + <dd>The first line is the file version number, currently + 1. + The second line, <code>clock=global</code>, indicates that we use a common + clock across all threads. A future version may use per-thread CPU time counters + that are independent for every thread.</dd> + <dt><em>threads section</em></dt> + <dd>One line per thread. Each line consists of two parts: the thread ID, followed + by a tab, followed by the thread name. There are few restrictions on what + a valid thread name is, so include everything to the end of the line.</dd> + <dt><em>methods section </em></dt> + <dd>One line per method entry or exit. A line consists of four pieces, + separated by tab marks: <em>method-ID</em> [TAB] <em>class-name</em> [TAB] + <em>method-name</em> [TAB] + <em>signature</em> . Only + the methods that were actually entered or exited are included in the list. + Note that all three identifiers are required to uniquely identify a + method.</dd> +</dl> +<p>Neither the threads nor methods sections are sorted.</p> + +<a name="knownissues"></a> +<h2>Traceview Known Issues</h2> +<dl> + <dt>Threads</dt> + <dd>Traceview logging does not handle threads well, resulting in these two problems: +<ol> + <li> If a thread exits during profiling, the thread name is not emitted; </li> + <li>The VM reuses thread IDs. If a thread stops and another starts, they + may get the same ID. </li> +</ol> +</dd> + +<a name="dmtracedump"></a> + +<h2>Using dmtracedump</h2> + +<p>The Android SDK includes dmtracedump, a tool that gives you an alternate way + of generating graphical call-stack diagrams from trace log files. The tool + uses the Graphviz Dot utility to create the graphical output, so you need to + install Graphviz before running dmtracedump.</p> + +<p>The dmtracedump tool generates the call stack data as a tree diagram, with each call + represented as a node. It shows call flow (from parent node to child nodes) using + arrows. The diagram below shows an example of dmtracedump output.</p> + +<img src="{@docRoot}images/tracedump.png" width="485" height="401" style="margin-top:1em;"/> + +<p style="margin-top:1em;">For each node, dmtracedump shows <code><ref> <em>callname</em> (<inc-ms>, + <exc-ms>,<numcalls>)</code>, where</p> + +<ul> + <li><code><ref></code> -- Call reference number, as used in trace logs</li> + <li><code><inc-ms></code> -- Inclusive elapsed time (milliseconds spent in method, including all child methods)</li> + <li><code><exc-ms></code> -- Exclusive elapsed time (milliseconds spent in method, not including any child methods)</li> + <li><code><numcalls></code> -- Number of calls</li> +</ul> + +<p>The usage for dmtracedump is: </p> + +<pre>dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name></pre> + +<p>The tool then loads trace log data from <trace-base-name>.data and <trace-base-name>.key. + The table below lists the options for dmtracedump.</p> + +<table> +<tr> + <th>Option</td> + <th>Description</th> +</tr> + + <tr> + <td><code>-d <trace-base-name> </code></td> + <td>Diff with this trace name</td> + </tr> + <tr> + <td><code>-g <outfile> </code></td> + <td>Generate output to <outfile></td> + </tr> + <tr> + <td><code>-h </code></td> + <td>Turn on HTML output</td> + </tr> + <tr> + <td><code>-o </code></td> + <td>Dump the trace file instead of profiling</td> + </tr> + <tr> + <td><code>-d <trace-base-name> </code></td> + <td>URL base to the location of the sortable javascript file</td> + </tr> + <tr> + <td><code>-t <percent> </code></td> + <td>Minimum threshold for including child nodes in the graph (child's inclusive + time as a percentage of parent inclusive time). If this option is not used, + the default threshold is 20%. </td> + </tr> + +</table> diff --git a/docs/html/guide/developing/traceview.jd b/docs/html/guide/developing/traceview.jd new file mode 100644 index 0000000..8c87eed --- /dev/null +++ b/docs/html/guide/developing/traceview.jd @@ -0,0 +1,310 @@ +page.title=Traceview: A Graphical Log Viewer +@jd:body + +<p>Traceview is a graphical viewer for execution logs +saved by your application. The sections below describe how to use the program. </p> + +<h2>Contents</h2> + +<dl> + <dt><a href="#creatingtracefiles">Creating Trace Files</a></dt> + <dt><a href="#copyingfiles">Copying Trace Files to a Host Machine</a></dt> + <dt><a href="#runningtraceview">Viewing Trace Files in Traceview</a></dt> + <dd><a href="#timelinepanel">Timeline Panel</a></dd> + <dd><a href="#profilepanel">Profile Panel</a></dd> + <dt><a href="#format">Traceview File Format</a></dd> + <dd><a href="#datafileformat">Data File Format</a><dd> + <dd><a href="#keyfileformat">Key File Format</a></dd> + <dt><a href="#knownissues">Traceview Known Issues</a></dd> + <dt><a href="#dmtracedump">Using dmtracedump</a></dt> +</dl> + +<a name="creatingtracefiles"></a> + +<h2>Creating Trace Files</h2> + +<p>To use Traceview, you need to generate log files containing the trace information you want to analyze. To do that, you include the {@link android.os.Debug} + class in your code and call its methods to start and stop logging of trace information + to disk. When your application quits, you can then use Traceview to examine the log files + for useful run-time information such + as method calls and run times. </p> +<p>To create the trace files, include the {@link android.os.Debug} class and call one + of the {@link android.os.Debug#startMethodTracing() startMethodTracing()} methods. + In the call, you specify a base name for the trace files that the system generates. + To stop tracing, call {@link android.os.Debug#stopMethodTracing() stopMethodTracing()}. + These methods start and stop method tracing across the entire virtual machine. For + example, you could call startMethodTracing() in your activity's onCreate() + method, and call stopMethodTracing() in that activity's onDestroy() method.</p> + +<pre> + // start tracing to "/sdcard/calc.trace" + Debug.startMethodTracing("calc"); + // ... + // stop tracing + Debug.stopMethodTracing(); +</pre> + +<p>When your application calls startMethodTracing(), the system creates a +file called <code><trace-base-name>.trace</code>. This contains the +binary method trace data and a mapping table with thread and method names.</p> + +<p>The system then begins buffering the generated trace data, until your application calls + stopMethodTracing(), at which time it writes the buffered data to the + output file. + If the system reaches the maximum buffer size before stopMethodTracing() + is called, the system stops tracing and sends a notification + to the console. </p> + +<p>Interpreted code will run more slowly when profiling is enabled. Don't +try to generate absolute timings from the profiler results (i.e. "function +X takes 2.5 seconds to run"). The times are only +useful in relation to other profile output, so you can see if changes +have made the code faster or slower. </p> + +<p>When using the Android emulator, you must create an SD card image upon which +the trace files will be written. For example, from the <code>/tools</code> directory, you +can create an SD card image and mount it when launching the emulator like so:</p> +<pre> +<b>$</b> mksdcard 1024M ./imgcd +<b>$</b> emulator -sdcard ./img +</pre> +<p>For more information, read about the +<a href="{@docRoot}reference/othertools.html#mksdcard">mksdcard tool</a>.</p> + +<p>The format of the trace files is described <a href="#format">later + in this document</a>. </p> + +<a name="copyingfiles"></a> + +<h2>Copying Trace Files to a Host Machine</h2> +<p>After your application has run and the system has created your trace files <code><trace-base-name>.trace</code> + on a device or emulator, you must copy those files to your development computer. You can use <code>adb pull</code> to copy + the files. Here's an example that shows how to copy an example file, + calc.trace, from the default location on the emulator to the /tmp directory on +the emulator host machine:</p> +<pre>adb pull /sdcard/calc.trace /tmp</pre> + + +<a name="runningtraceview"></a> + +<h2>Viewing Trace Files in Traceview</h2> +<p>To run traceview and view the trace files, enter <code>traceview <trace-base-name></code>. + For example, to run Traceview on the example files copied in the previous section, + you would use: </p> + <pre>traceview /tmp/calc</pre> + + <p>Traceview loads the log files and displays their data in a window that has two panels:</p> + <ul> + <li>A <a href="#timelinepanel">timeline panel</a> -- describes when each thread + and method started and stopped</li> + <li>A <a href="#timelinepanel">profile panel</a> -- provides a summary of what happened inside a method</li> + </ul> + <p>The sections below provide addition information about the traceview output panes. </p> + +<a name="timelinepanel"></a> + +<h3>Timeline Panel </h3> +<p>The image below shows a close up of the timeline panel. Each thread’s + execution is shown in its own row, with time increasing to the right. Each method + is shown in another color (colors are reused in a round-robin fashion starting + with the methods that have the most inclusive time). The thin lines underneath + the first row show the extent (entry to exit) of all the calls to the selected + method. The method in this case is LoadListener.nativeFinished() and it was + selected in the profile view. </p> +<p><img src="../images/traceview_timeline.png" alt="Traceview timeline panel" width="893" height="284"></p> +<a name="profilepanel"></a> +<h3>Profile Panel</h3> +<p>The image below shows the profile pane. The profile pane shows a + summary of all the time spent in a method. The table shows + both the inclusive and exclusive times (as well as the percentage of the total + time). Exclusive time is the time spent in the method. Inclusive time is the + time spent in the method plus the time spent in any called functions. We refer + to calling methods as "parents" and called methods as "children." + When a method is selected (by clicking on it), it expands to show the parents + and children. Parents are shown with a purple background and children + with a yellow background. The last column in the table shows the number of calls + to this method plus the number of recursive calls. The last column shows the + number of calls out of the total number of calls made to that method. In this + view, we can see that there were 14 calls to LoadListener.nativeFinished(); looking + at the timeline panel shows that one of those calls took an unusually + long time.</p> +<p><img src="../images/traceview_profile.png" alt="Traceview profile panel." width="892" height="630"></p> + +<a name="format"></a> +<h2>Traceview File Format</h2> +<p>Tracing creates two distinct pieces of output: a <em>data</em> file, + which holds the trace data, and a <em>key</em> file, which + provides a mapping from binary identifiers to thread and method names. + The files are concatenated when tracing completes, into a + single <em>.trace</em> file. </p> + +<p class="note"><strong>Note:</strong> The previous version of Traceview did not concatenate +these files for you. If you have old key and data files that you'd still like to trace, you +can concatenate them yourself with <code>cat mytrace.key mytrace.data > mytrace.trace</code>.</p> + +<a name="datafileformat"></a> + +<h3>Data File Format</h3> +<p>The data file is binary, structured as + follows (all values are stored in little-endian order):</p> +<pre>* File format: +* header +* record 0 +* record 1 +* ... +* +* Header format: +* u4 magic 0x574f4c53 ('SLOW') +* u2 version +* u2 offset to data +* u8 start date/time in usec +* +* Record format: +* u1 thread ID +* u4 method ID | method action +* u4 time delta since start, in usec +</pre> +<p>The application is expected to parse all of the header fields, then seek + to "offset to data" from the start of the file. From there it just + reads + 9-byte records until EOF is reached.</p> +<p><em>u8 start date/time in usec</em> is the output from gettimeofday(). + It's mainly there so that you can tell if the output was generated yesterday + or three months ago.</p> +<p><em>method action</em> sits in the two least-significant bits of the + <em>method</em> word. The currently defined meanings are: </p> +<ul> + <li>0 - method entry </li> + <li>1 - method exit </li> + <li>2 - method "exited" when unrolled by exception handling </li> + <li>3 - (reserved)</li> +</ul> +<p>An unsigned 32-bit integer can hold about 70 minutes of time in microseconds. +</p> + +<a name="keyfileformat"></a> + +<h3>Key File Format</h3> +<p>The key file is a plain text file divided into three sections. Each + section starts with a keyword that begins with '*'. If you see a '*' at the start + of a line, you have found the start of a new section.</p> +<p>An example file might look like this:</p> +<pre>*version +1 +clock=global +*threads +1 main +6 JDWP Handler +5 Async GC +4 Reference Handler +3 Finalizer +2 Signal Handler +*methods +0x080f23f8 java/io/PrintStream write ([BII)V +0x080f25d4 java/io/PrintStream print (Ljava/lang/String;)V +0x080f27f4 java/io/PrintStream println (Ljava/lang/String;)V +0x080da620 java/lang/RuntimeException <init> ()V +[...] +0x080f630c android/os/Debug startMethodTracing ()V +0x080f6350 android/os/Debug startMethodTracing (Ljava/lang/String;Ljava/lang/String;I)V +*end</pre> +<dl> + <dt><em>version section</em></dt> + <dd>The first line is the file version number, currently + 1. + The second line, <code>clock=global</code>, indicates that we use a common + clock across all threads. A future version may use per-thread CPU time counters + that are independent for every thread.</dd> + <dt><em>threads section</em></dt> + <dd>One line per thread. Each line consists of two parts: the thread ID, followed + by a tab, followed by the thread name. There are few restrictions on what + a valid thread name is, so include everything to the end of the line.</dd> + <dt><em>methods section </em></dt> + <dd>One line per method entry or exit. A line consists of four pieces, + separated by tab marks: <em>method-ID</em> [TAB] <em>class-name</em> [TAB] + <em>method-name</em> [TAB] + <em>signature</em> . Only + the methods that were actually entered or exited are included in the list. + Note that all three identifiers are required to uniquely identify a + method.</dd> +</dl> +<p>Neither the threads nor methods sections are sorted.</p> + +<a name="knownissues"></a> +<h2>Traceview Known Issues</h2> +<dl> + <dt>Threads</dt> + <dd>Traceview logging does not handle threads well, resulting in these two problems: +<ol> + <li> If a thread exits during profiling, the thread name is not emitted; </li> + <li>The VM reuses thread IDs. If a thread stops and another starts, they + may get the same ID. </li> +</ol> +</dd> + +<a name="dmtracedump"></a> + +<h2>Using dmtracedump</h2> + +<p>The Android SDK includes dmtracedump, a tool that gives you an alternate way + of generating graphical call-stack diagrams from trace log files. The tool + uses the Graphviz Dot utility to create the graphical output, so you need to + install Graphviz before running dmtracedump.</p> + +<p>The dmtracedump tool generates the call stack data as a tree diagram, with each call + represented as a node. It shows call flow (from parent node to child nodes) using + arrows. The diagram below shows an example of dmtracedump output.</p> + +<img src="{@docRoot}images/tracedump.png" width="485" height="401" style="margin-top:1em;"/> + +<p style="margin-top:1em;">For each node, dmtracedump shows <code><ref> <em>callname</em> (<inc-ms>, + <exc-ms>,<numcalls>)</code>, where</p> + +<ul> + <li><code><ref></code> -- Call reference number, as used in trace logs</li> + <li><code><inc-ms></code> -- Inclusive elapsed time (milliseconds spent in method, including all child methods)</li> + <li><code><exc-ms></code> -- Exclusive elapsed time (milliseconds spent in method, not including any child methods)</li> + <li><code><numcalls></code> -- Number of calls</li> +</ul> + +<p>The usage for dmtracedump is: </p> + +<pre>dmtracedump [-ho] [-s sortable] [-d trace-base-name] [-g outfile] <trace-base-name></pre> + +<p>The tool then loads trace log data from <trace-base-name>.data and <trace-base-name>.key. + The table below lists the options for dmtracedump.</p> + +<table> +<tr> + <th>Option</td> + <th>Description</th> +</tr> + + <tr> + <td><code>-d <trace-base-name> </code></td> + <td>Diff with this trace name</td> + </tr> + <tr> + <td><code>-g <outfile> </code></td> + <td>Generate output to <outfile></td> + </tr> + <tr> + <td><code>-h </code></td> + <td>Turn on HTML output</td> + </tr> + <tr> + <td><code>-o </code></td> + <td>Dump the trace file instead of profiling</td> + </tr> + <tr> + <td><code>-d <trace-base-name> </code></td> + <td>URL base to the location of the sortable javascript file</td> + </tr> + <tr> + <td><code>-t <percent> </code></td> + <td>Minimum threshold for including child nodes in the graph (child's inclusive + time as a percentage of parent inclusive time). If this option is not used, + the default threshold is 20%. </td> + </tr> + +</table> diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs new file mode 100644 index 0000000..70aaba4 --- /dev/null +++ b/docs/html/guide/guide_toc.cs @@ -0,0 +1,85 @@ +<ul> + +<li><h2>Android Basics</h2> + <ul> + <li><a href="<?cs var:toroot ?>guide/basics/what-is-android.html">What Is Android?</a></li> + <li><a href="<?cs var:toroot ?>guide/basics/">The Application Framework</a></li> + <li><a style="color:gray;">The Android SDK</a></li> + <li><a style="color:gray;">Developing for Android</a></li> +<!-- signing, upgrading, selecting a package name, select device profile, touch, trackball, dpad available, etc. --> + </ul> +</li> + +<li><h2>Framework Topics</h2> + <ul> + <li><a href="<?cs var:toroot ?>guide/topics/views/">Views and Layout</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/resources/">Resources and Assests</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/intents/">Intents and Intent Filtering</a></li> + <li><a style="color:gray;">Processes and Threads</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/data/">Data Storage</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/contentproviders/">Content Providers</a></li> + <li><a style="color:gray;">Notifications</a></li> + <li><a style="color:gray;">Drawing</a></li> + <li><a style="color:gray;">Localization</a></li> + <li><a style="color:gray;">IPC</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/security/">Security</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/">The Manifest File</a></li> + </ul> +</li> + +<li><h2>Developing</h2> + <ul> + <li><a href="<?cs var:toroot ?>guide/developing/eclipse.html">In Eclipse, with ADT</a></li> + <li><a href="<?cs var:toroot ?>guide/developing/other-ide.html">In Other IDEs</a></li> + <li><a href="<?cs var:toroot ?>guide/developing/tools/">Debugging Tools</a></li> + <li><a href="<?cs var:toroot ?>guide/developing/debug-tasks.html">Debugging Tasks</a></li> + <li><a href="<?cs var:toroot ?>guide/developing/app-signing.html">Signing</a></li> + <li><a style="color:gray;">Instrumentation</a></li> + <li><a style="color:gray;">JUnit</a></li> + </ul> +</li> + +<li><h2>Publishing</h2> + <ul> + <li><a style="color:gray;">Preparing to Publish</a></li> + <li><a style="color:gray;">Signing Your Application</a></li> + <li><a style="color:gray;">Publishing on Android Market</a></li> + <li><a style="color:gray;">Publishing on a Web Server</a></li> + </ul> +</li> + +<li><h2>Best Practices</h2> + <ul> + <li><a href="<?cs var:toroot ?>guide/practices/design/performance.html">Designing for Performance</a></li> + <li><a href="<?cs var:toroot ?>guide/practices/design/responsiveness.html">Designing for Responsiveness</a></li> + <li><a href="<?cs var:toroot ?>guide/practices/design/seamlessness.html">Designing for Seamlessness</a></li> + <li><a style="color:gray;">User Interface Guidelines</a></li> + </ul> +</li> +<!-- +<li><h2>Best Practices (alt)</h2> + <ul> + <li><a href="<?cs var:toroot ?>guide/practices/design/">Design Goals</a></li> + <li><a style="color:gray;">User Interface Guidelines</a></li> + </ul> +</li> +--> +<li><h2>Tutorials</h2> + <ul> + <li><a href="<?cs var:toroot ?>guide/tutorials/hello-world.html">Hello World</a></li> + <li><a href="<?cs var:toroot ?>guide/tutorials/views/hello-views-index.html">Hello Views</a></li> + <li><a href="<?cs var:toroot ?>guide/tutorials/notepad/notepad-index.html">Notepad</a></li> + <li><a href="<?cs var:toroot ?>samples/">Sample Code</a></li> + </ul> +</li> + +<li><h2>Appendix</h2> + <ul> + <li><a href="<?cs var:toroot ?>guide/appendix/media-formats.html">Supported Media Formats</a></li> + <li><a href="<?cs var:toroot ?>guide/appendix/g-app-intents.html">Intents List: Google Apps</a></li> + <li><a href="<?cs var:toroot ?>guide/appendix/glossary.html">Glossary</a></li> + <li><a href="<?cs var:toroot ?>guide/appendix/faq/">FAQ</a></li> + </ul> +</li> + +</ul> diff --git a/docs/html/guide/index.jd b/docs/html/guide/index.jd new file mode 100644 index 0000000..280ab85 --- /dev/null +++ b/docs/html/guide/index.jd @@ -0,0 +1,4 @@ +page.title=Android Developer Guide +@jd:body + +FIXME
\ No newline at end of file diff --git a/docs/html/guide/practices/design/index.jd b/docs/html/guide/practices/design/index.jd new file mode 100644 index 0000000..a818831 --- /dev/null +++ b/docs/html/guide/practices/design/index.jd @@ -0,0 +1,21 @@ +page.title=Application Design Goals +@jd:body + +<p>When learning how to build applications on a new platform, you first learn what APIs are available and how to use them. Later, you learn the nuances of the platform. Put another way: first you learn how you <em>can</em> build applications; later, you learn how you <em>should</em> build them, to ensure that your applications offer outstanding performance and a great user experience. </p> + +<p>The documents below help you learn the nuances of Android and get started building great applications more quickly, They discuss important aspects of application design that directly influence the user experience of your application, when in the hands of a mobile device user. You should read and consider these design goals as you plan your application and throughout its development, especially if you are new to developing for mobile devices.</p> + +<p>Successful mobile applications offer an outstanding user experience, in addition to a compelling technical feature set. The user experience is more than just its visual design or UI flow. It is also influenced by how well the application responds to the user's keypresses and other actions, how it well it interacts with other applications, and how fully and efficiently it uses device and system capabilities.</p> + +<p>An outstanding user experience has three key characteristics: it is +<em>fast</em>; it is <em>responsive</em>; and it is <em>seamless</em>. Of course +every platform since the dawn of computing has probably cited those same three +qualities at one time or another. However, each platform achieves them in +different ways; the documents below explain how you can build Android +applications that are fast, responsive, and seamless. </p> + +<ul> +<li><a href="performance.html">Designing for Performance</a> (writing efficient Android code)</a></li> +<li><a href="responsiveness.html">Designing for Responsiveness</a> (avoiding ANR)</a></li> +<li><a href="seamlessness.html">Designing for Seamlessness</a> (coexisting with other applications)</a></li> +</ul> diff --git a/docs/html/guide/practices/design/performance.jd b/docs/html/guide/practices/design/performance.jd new file mode 100644 index 0000000..1eef342 --- /dev/null +++ b/docs/html/guide/practices/design/performance.jd @@ -0,0 +1,549 @@ +page.title=Designing for Performance +@jd:body + +<p>An Android application should be fast. Well, it's probably more accurate to +say that it should be <em>efficient</em>. That is, it should execute as +efficiently as possible in the mobile device environment, with its limited +computing power and data storage, smaller screen, and constrained battery life. + +<p>As you develop your application, keep in mind that, while the application may +perform well enough in your emulator, running on your dual-core development +computer, it will not perform that well when run a mobile device — even +the most powerful mobile device can't match the capabilities of a typical +desktop system. For that reason, you should strive to write efficient code, to +ensure the best possible performance on a variety of mobile devices.</p> + +<p>Generally speaking, writing fast or efficient code means keeping memory +allocations to a minimum, writing tight code, and avoiding certain language and +programming idioms that can subtly cripple performance. In object-oriented +terms, most of this work takes place at the <em>method</em> level, on the order of +actual lines of code, loops, and so on.</p> + +<p>This document covers these topics: </p> +<ul> + <li><a href="#intro">Introduction</a></li> + <li><a href="#object_creation">Avoid Creating Objects</a></li> + <li><a href="#native_methods">Use Native Methods</a></li> + <li><a href="#prefer_virtual">Prefer Virtual Over Interface</a></li> + <li><a href="#prefer_static">Prefer Static Over Virtual</a></li> + <li><a href="#internal_get_set">Avoid Internal Getters/Setters</a></li> + <li><a href="#cache_fields">Cache Field Lookups</a></li> + <li><a href="#use_final">Declare Constants Final</a></li> + <li><a href="#foreach">Use Enhanced For Loop Syntax With Caution</a></li> + <li><a href="#avoid_enums">Avoid Enums</a></li> + <li><a href="#package_inner">Use Package Scope with Inner Classes</a></li> + <li><a href="#avoidfloat">Avoid Float</a> </li> + <li><a href="#samples">Some Sample Performance Numbers</a> </li> + <li><a href="#closing_notes">Closing Notes</a></li> +</ul> + +<a name="intro" id="intro"></a> +<h2>Introduction</h2> + +<p>There are two basic rules for resource-constrained systems:</p> + +<ul> + <li>Don't do work that you don't need to do.</li> + <li>Don't allocate memory if you can avoid it.</li> +</ul> + +<p>All the tips below follow from these two basic tenets.</p> + +<p>Some would argue that much of the advice on this page amounts to "premature +optimization." While it's true that micro-optimizations sometimes make it +harder to develop efficient data structures and algorithms, on embedded +devices like handsets you often simply have no choice. For instance, if you +bring your assumptions about VM performance on desktop machines to Android, +you're quite likely to write code that exhausts system memory. This will bring +your application to a crawl — let alone what it will do to other programs +running on the system!</p> + +<p>That's why these guidelines are important. Android's success depends on +the user experience that your applications provide, and that user experience +depends in part on whether your code is responsive and snappy, or slow and +aggravating. Since all our applications will run on the same devices, we're +all in this together, in a way. Think of this document as like the rules of +the road you had to learn when you got your driver's license: things run +smoothly when everybody follows them, but when you don't, you get your car +smashed up.</p> + +<p>Before we get down to brass tacks, a brief observation: nearly all issues +described below are valid whether or not the VM features a JIT compiler. If I +have two methods that accomplish the same thing, and the interpreted execution +of foo() is faster than bar(), then the compiled version of foo() will +probably be as fast or faster than compiled bar(). It is unwise to rely on a +compiler to "save" you and make your code fast enough.</p> + +<a name="object_creation"></a> +<h2>Avoid Creating Objects</h2> + +<p>Object creation is never free. A generational GC with per-thread allocation +pools for temporary objects can make allocation cheaper, but allocating memory +is always more expensive than not allocating memory.</p> + +<p>If you allocate objects in a user interface loop, you will force a periodic +garbage collection, creating little "hiccups" in the user experience.</p> + +<p>Thus, you should avoid creating object instances you don't need to. Some +examples of things that can help:</p> + +<ul> + <li>When extracting strings from a set of input data, try + to return a substring of the original data, instead of creating a copy. + You will create a new String object, but it will share the char[] + with the data.</li> + <li>If you have a method returning a string, and you know that its result + will always be appended to a StringBuffer anyway, change your signature + and implementation so that the function does the append directly, + instead of creating a short-lived temporary object.</li> +</ul> + +<p>A somewhat more radical idea is to slice up multidimensional arrays into parallel +single one-dimension arrays:</p> + +<ul> + <li>An array of ints is a much better than an array of Integers, + but this also generalizes to the fact that two parallel arrays of ints + are also a <strong>lot</strong> more efficient than an array of (int,int) + objects. The same goes for any combination of primitive types.</li> + <li>If you need to implement a container that stores tuples of (Foo,Bar) + objects, try to remember that two parallel Foo[] and Bar[] arrays are + generally much better than a single array of custom (Foo,Bar) objects. + (The exception to this, of course, is when you're designing an API for + other code to access; in those cases, it's usually better to trade + correct API design for a small hit in speed. But in your own internal + code, you should try and be as efficient as possible.)</li> +</ul> + +<p>Generally speaking, avoid creating short-term temporary objects if you +can. Fewer objects created mean less-frequent garbage collection, which has +a direct impact on user experience.</p> + +<a name="native_methods" id="native_methods"></a> +<h2>Use Native Methods</h2> + +<p>When processing strings, don't hesitate to use specialty methods like +String.indexOf(), String.lastIndexOf(), and their cousins. These are typically +implemented in C/C++ code that easily runs 10-100x faster than doing the same +thing in a Java loop.</p> + +<p>The flip side of that advice is that punching through to a native +method is more expensive than calling an interpreted method. Don't use native +methods for trivial computation, if you can avoid it.</p> + +<a name="prefer_virtual" id="prefer_virtual"></a> +<h2>Prefer Virtual Over Interface</h2> + +<p>Suppose you have a HashMap object. You can declare it as a HashMap or as +a generic Map:</p> + +<pre>Map myMap1 = new HashMap(); +HashMap myMap2 = new HashMap();</pre> + +<p>Which is better?</p> + +<p>Conventional wisdom says that you should prefer Map, because it +allows you to change the underlying implementation to anything that +implements the Map interface. Conventional wisdom is correct for +conventional programming, but isn't so great for embedded systems. Calling +through an interface reference can take 2x longer than a virtual +method call through a concrete reference.</p> + +<p>If you have chosen a HashMap because it fits what you're doing, there +is little value in calling it a Map. Given the availability of +IDEs that refactor your code for you, there's not much value in calling +it a Map even if you're not sure where the code is headed. (Again, though, +public APIs are an exception: a good API usually trumps small performance +concerns.)</p> + +<a name="prefer_static" id="prefer_static"></a> +<h2>Prefer Static Over Virtual</h2> + +<p>If you don't need to access an object's fields, make your method static. It can +be called faster, because it doesn't require a virtual method table +indirection. It's also good practice, because you can tell from the method +signature that calling the method can't alter the object's state.</p> + +<a name="internal_get_set" id="internal_get_set"></a> +<h2>Avoid Internal Getters/Setters</h2> + +<p>In native languages like C++ it's common practice to use getters (e.g. +<code>i = getCount()</code>) instead of accessing the field directly (<code>i += mCount</code>). This is an excellent habit for C++, because the compiler can +usually inline the access, and if you need to restrict or debug field access +you can add the code at any time.</p> + +<p>On Android, this is a bad idea. Virtual method calls are expensive, +much more so than instance field lookups. It's reasonable to follow +common object-oriented programming practices and have getters and setters +in the public interface, but within a class you should always access +fields directly.</p> + +<a name="cache_fields" id="cache_fields"></a> +<h2>Cache Field Lookups</h2> + +<p>Accessing object fields is much slower than accessing local variables. +Instead of writing:</p> +<pre>for (int i = 0; i < this.mCount; i++) + dumpItem(this.mItems[i]);</pre> + +<p>You should write:</p> +<pre> int count = this.mCount; + Item[] items = this.mItems; + + for (int i = 0; i < count; i++) + dumpItems(items[i]); +</pre> + +<p>(We're using an explicit "this" to make it clear that these are +member variables.)</p> + +<p>A similar guideline is never call a method in the second clause of a "for" +statement. For example, the following code will execute the getCount() method +once per iteration, which is a huge waste when you could have simply cached +the value as an int:</p> + +<pre>for (int i = 0; i < this.getCount(); i++) + dumpItems(this.getItem(i)); +</pre> + +<p>It's also usually a good idea to create a local variable if you're going to be +accessing an instance field more than once. For example:</p> + +<pre> + protected void drawHorizontalScrollBar(Canvas canvas, int width, int height) { + if (isHorizontalScrollBarEnabled()) { + int size = <strong>mScrollBar</strong>.getSize(<em>false</em>); + if (size <= 0) { + size = mScrollBarSize; + } + <strong>mScrollBar</strong>.setBounds(0, <em>height</em> - size, width, height); + <strong>mScrollBar</strong>.setParams( + computeHorizontalScrollRange(), + computeHorizontalScrollOffset(), + computeHorizontalScrollExtent(), <em>false</em>); + <strong>mScrollBar</strong>.draw(canvas); + } + }</pre> + +<p>That's four separate lookups of the member field <code>mScrollBar</code>. +By caching mScrollBar in a local stack variable, the four member field lookups +become four stack variable references, which are much more efficient.</p> + +<p>Incidentally, method arguments have the same performance characteristics +as local variables.</p> + +<a name="use_final" id="use_final"></a> +<h2>Declare Constants Final</h2> + +<p>Consider the following declaration at the top of a class:</p> + +<pre>static int intVal = 42; +static String strVal = "Hello, world!";</pre> + +<p>The compiler generates a class initializer method, called +<code><clinit></code>, that is executed when the class is first used. +The method stores the value 42 into <code>intVal</code>, and extracts a +reference from the classfile string constant table for <code>strVal</code>. +When these values are referenced later on, they are accessed with field +lookups.</p> + +<p>We can improve matters with the "final" keyword:</p> + +<pre>static final int intVal = 42; +static final String strVal = "Hello, world!";</pre> + +<p>The class no longer requires a <code><clinit></code> method, +because the constants go into classfile static field initializers, which are +handled directly by the VM. Code accessing <code>intVal</code> will use +the integer value 42 directly, and accesses to <code>strVal</code> will +use a relatively inexpensive "string constant" instruction instead of a +field lookup.</p> + +<p>Declaring a method or class "final" does not confer any immediate +performance benefits, but it does allow certain optimizations. For example, if +the compiler knows that a "getter" method can't be overridden by a sub-class, +it can inline the method call.</p> + +<p>You can also declare local variables final. However, this has no definitive +performance benefits. For local variables, only use "final" if it makes the +code clearer (or you have to, e.g. for use in an anonymous inner class).</p> + +<a name="foreach" id="foreach"></a> +<h2>Use Enhanced For Loop Syntax With Caution</h2> + +<p>The enhanced for loop (also sometimes known as "for-each" loop) can be used for collections that implement the Iterable interface. +With these objects, an iterator is allocated to make interface calls +to hasNext() and next(). With an ArrayList, you're better off walking through +it directly, but for other collections the enhanced for loop syntax will be equivalent +to explicit iterator usage.</p> + +<p>Nevertheless, the following code shows an acceptable use of the enhanced for loop:</p> + +<pre>public class Foo { + int mSplat; + static Foo mArray[] = new Foo[27]; + + public static void zero() { + int sum = 0; + for (int i = 0; i < mArray.length; i++) { + sum += mArray[i].mSplat; + } + } + + public static void one() { + int sum = 0; + Foo[] localArray = mArray; + int len = localArray.length; + + for (int i = 0; i < len; i++) { + sum += localArray[i].mSplat; + } + } + + public static void two() { + int sum = 0; + for (Foo a: mArray) { + sum += a.mSplat; + } + } +}</pre> + +<p><strong>zero()</strong> retrieves the static field twice and gets the array +length once for every iteration through the loop.</p> + +<p><strong>one()</strong> pulls everything out into local variables, avoiding +the lookups.</p> + +<p><strong>two()</strong> uses the enhanced for loop syntax introduced in version 1.5 of +the Java programming language. The code generated by the compiler takes care +of copying the array reference and the array length to local variables, making +it a good choice for walking through all elements of an array. It does +generate an extra local load/store in the main loop (apparently preserving +"a"), making it a teensy bit slower and 4 bytes longer than one().</p> + +<p>To summarize all that a bit more clearly: enhanced for loop syntax performs well +with arrays, but be cautious when using it with Iterable objects since there is +additional object creation.</p> + +<a name="avoid_enums" id="avoid_enums"></a> +<h2>Avoid Enums</h2> + +<p>Enums are very convenient, but unfortunately can be painful when size +and speed matter. For example, this:</p> + +<pre>public class Foo { + public enum Shrubbery { GROUND, CRAWLING, HANGING } +}</pre> + +<p>turns into a 900 byte .class file (Foo$Shrubbery.class). On first use, the +class initializer invokes the <init> method on objects representing each +of the enumerated values. Each object gets its own static field, and the full +set is stored in an array (a static field called "$VALUES"). That's a lot of +code and data, just for three integers.</p> + +<p>This:</p> + +<pre>Shrubbery shrub = Shrubbery.GROUND;</pre> + +<p>causes a static field lookup. If "GROUND" were a static final int, +the compiler would treat it as a known constant and inline it.</p> + +<p>The flip side, of course, is that with enums you get nicer APIs and +some compile-time value checking. So, the usual trade-off applies: you should +by all means use enums for public APIs, but try to avoid them when performance +matters.</p> + +<p>In some circumstances it can be helpful to get enum integer values +through the <code>ordinal()</code> method. For example, replace:</p> + +<pre>for (int n = 0; n < list.size(); n++) { + if (list.items[n].e == MyEnum.VAL_X) + // do stuff 1 + else if (list.items[n].e == MyEnum.VAL_Y) + // do stuff 2 +}</pre> + +<p>with:</p> + +<pre> int valX = MyEnum.VAL_X.ordinal(); + int valY = MyEnum.VAL_Y.ordinal(); + int count = list.size(); + MyItem items = list.items(); + + for (int n = 0; n < count; n++) + { + int valItem = items[n].e.ordinal(); + + if (valItem == valX) + // do stuff 1 + else if (valItem == valY) + // do stuff 2 + }</pre> + +<p>In some cases, this will be faster, though this is not guaranteed.</p> + +<a name="package_inner" id="package_inner"></a> +<h2>Use Package Scope with Inner Classes</h2> + +<p>Consider the following class definition:</p> + +<pre>public class Foo { + private int mValue; + + public void run() { + Inner in = new Inner(); + mValue = 27; + in.stuff(); + } + + private void doStuff(int value) { + System.out.println("Value is " + value); + } + + private class Inner { + void stuff() { + Foo.this.doStuff(Foo.this.mValue); + } + } +}</pre> + +<p>The key things to note here are that we define an inner class (Foo$Inner) +that directly accesses a private method and a private instance field +in the outer class. This is legal, and the code prints "Value is 27" as +expected.</p> + +<p>The problem is that Foo$Inner is technically (behind the scenes) a totally +separate class, which makes direct access to Foo's private +members illegal. To bridge that gap, the compiler generates a +couple of synthetic methods:</p> + +<pre>/*package*/ static int Foo.access$100(Foo foo) { + return foo.mValue; +} +/*package*/ static void Foo.access$200(Foo foo, int value) { + foo.doStuff(value); +}</pre> + +<p>The inner-class code calls these static methods whenever it needs to +access the "mValue" field or invoke the "doStuff" method in the outer +class. What this means is that the code above really boils down to a case +where you're accessing member fields through accessor methods instead of +directly. Earlier we talked about how accessors are slower than direct field +accesses, so this is an example of a certain language idiom resulting in an +"invisible" performance hit.</p> + +<p>We can avoid this problem by declaring fields and methods accessed +by inner classes to have package scope, rather than private scope. +This runs faster and removes the overhead of the generated methods. +(Unfortunately it also means the fields could be accessed directly by other +classes in the same package, which runs counter to the standard OO +practice of making all fields private. Once again, if you're +designing a public API you might want to carefully consider using this +optimization.)</p> + +<a name="avoidfloat" id="avoidfloat"></a> +<h2>Avoid Float</h2> + +<p>Before the release of the Pentium CPU, it was common for game authors to do +as much as possible with integer math. With the Pentium, the floating point +math co-processor became a built-in feature, and by interleaving integer and +floating-point operations your game would actually go faster than it would +with purely integer math. The common practice on desktop systems is to use +floating point freely.</p> + +<p>Unfortunately, embedded processors frequently do not have hardware floating +point support, so all operations on "float" and "double" are performed in +software. Some basic floating point operations can take on the order of a +millisecond to complete.</p> + +<p>Also, even for integers, some chips have hardware multiply but lack +hardware divide. In such cases, integer division and modulus operations are +performed in software — something to think about if you're designing a +hash table or doing lots of math.</p> + +<a name="samples" id="samples"></a> +<h2>Some Sample Performance Numbers</h2> + +<p>To illustrate some of our ideas, here is a table listing the approximate +run times for a few basic actions. Note that these values should NOT be taken +as absolute numbers: they are a combination of CPU and wall clock time, and +will change as improvements are made to the system. However, it is worth +noting how these values apply relative to each other — for example, +adding a member variable currently takes about four times as long as adding a +local variable.</p> + +<table> + <tr> + <th>Action</th> + <th>Time</th> + </tr> + <tr> + <td>Add a local variable </td> + <td>1</td> + </tr> + <tr class="alt"> + <td>Add a member variable </td> + <td>4</td> + </tr> + <tr> + <td>Call String.length()</td> + <td>5</td> + </tr> + <tr class="alt"> + <td>Call empty static native method</td> + <td>5</td> + </tr> + <tr> + <td>Call empty static method </td> + <td>12</td> + </tr> + <tr class="alt"> + <td>Call empty virtual method </td> + <td>12.5</td> + </tr> + <tr> + <td>Call empty interface method </td> + <td>15</td> + </tr> + <tr class="alt"> + <td>Call Iterator:next() on a HashMap </td> + <td>165</td> + </tr> + <tr> + <td>Call put() on a HashMap</td> + <td>600</td> + </tr> + <tr class="alt"> + <td>Inflate 1 View from XML </td> + <td>22,000</td> + </tr> + <tr> + <td>Inflate 1 LinearLayout containing 1 TextView </td> + <td>25,000</td> + </tr> + <tr class="alt"> + <td>Inflate 1 LinearLayout containing 6 View objects </td> + <td>100,000</td> + </tr> + <tr> + <td>Inflate 1 LinearLayout containing 6 TextView objects </td> + <td>135,000</td> + </tr> + <tr class="alt"> + <td>Launch an empty activity </td> + <td>3,000,000</td> + </tr> +</table> + +<a name="closing_notes" id="closing_notes"></a> +<h2>Closing Notes</h2> + +<p>The best way to write good, efficient code for embedded systems is to +understand what the code you write really does. If you really want to allocate +an iterator, by all means use enhanced for loop syntax on a List; just make it a +deliberate choice, not an inadvertent side effect.</p> + +<p>Forewarned is forearmed! Know what you're getting into! Insert your +favorite maxim here, but always think carefully about what your code is doing, +and be on the lookout for ways to speed it up.</p> diff --git a/docs/html/guide/practices/design/responsiveness.jd b/docs/html/guide/practices/design/responsiveness.jd new file mode 100644 index 0000000..e0d1864 --- /dev/null +++ b/docs/html/guide/practices/design/responsiveness.jd @@ -0,0 +1,117 @@ +page.title=Designing for Responsiveness +@jd:body + +<p>It's possible to write code that wins every performance test in the world, but still sends users in a fiery rage when they try to use the application. These are the applications that aren't <em>responsive</em> enough — the ones that feel +sluggish, hang or freeze for significant periods, or take too long to process +input. </p> + +<p>In Android, the system guards against applications that are insufficiently responsive for a period of time by displaying a dialog to the user, called the Application Not Responding (ANR) dialog. The user can choose to let the application continue, but the user won't appreciate having to act on this dialog every time he or she uses your application. So it's important to design responsiveness into your application, so that the system never has cause to display an ANR to the user. </p> + +<p>Generally, the system displays an ANR if an application cannot respond to user input. For example, if an application blocks on some I/O operation (frequently a network access), then the main application thread won't be able to process incoming user input events. After a time, the system concludes that the application has hung, and displays the ANR to give the user the option to kill it. + +<p>Similarly, if your application spends too much time building an elaborate in-memory +structure, or perhaps computing the next move in a game, the system will +conclude that your application has hung. It's always important to make +sure these computations are efficient using the techniques above, but even the +most efficient code still takes time to run.</p> + +<p>In both of these cases, the fix is usually to create a child thread, and do +most of your work there. This keeps the main thread (which drives the user +interface event loop) running, and prevents the system from concluding your code +has frozen. Since such threading usually is accomplished at the class +level, you can think of responsiveness as a <em>class</em> problem. (Compare +this with basic performance, which was described above as a <em>method</em>-level +concern.)</p> + +<div class="sidebox" style="margin-top:1em;border:0;"> +<div style="border:0;background-color:#fff;padding:15px;padding-right:2em;margin:0;"> +<img src="/android/images/anr.png" width="240" height="320" alt="Screenshot of ANR dialog box"> +<p style="margin-top:.5em;padding:.5em;">An ANR dialog displayed to the user.</p> +</div> +</div> + +<p>This document discusses how the Android system determines whether an application is +not responding and provides guidelines for +ensuring that your application is responsive. </p> + +<p>This document covers these topics: </p> +<ul> + <li><a href="#anr">What Triggers ANR?</a></li> + <li><a href="#avoiding">How to Avoid ANR</a></li> + <li><a href="#reinforcing">Reinforcing Responsiveness</a></li> +</ul> + +<h2 id="anr">What Triggers ANR?</h2> + +<p>In Android, application responsiveness is monitored by the Activity Manager +and Window Manager system services. Android will display the ANR dialog +for a particular application when it detects one of the following +conditions:</p> +<ul> + <li>No response to an input event (e.g. key press, screen touch) within 5 seconds</li> + <li>A {@link android.content.BroadcastReceiver BroadcastReceiver} hasn't finished executing within 10 seconds</li> +</ul> + +<h2 id="avoiding">How to Avoid ANR</h2> + +<p>Given the above definition for ANR, let's examine why this can occur in +Android applications and how best to structure your application to avoid ANR.</p> + +<p>Android applications normally run entirely on a single (i.e. main) thread. +This means that anything your application is doing in the main thread that +takes a long time to complete can trigger the ANR dialog because your +application is not giving itself a chance to handle the input event or Intent +broadcast.</p> + +<p>Therefore any method that runs in the main thread should do as little work +as possible. In particular, Activities should do as little as possible to set +up in key life-cycle methods such as <code>onCreate()</code> and +<code>onResume()</code>. Potentially long running operations such as network +or database operations, or computationally expensive calculations such as +resizing bitmaps should be done in a child thread (or in the case of databases +operations, via an asynchronous request). However, this does not mean that +your main thread should block while waiting for the child thread to +complete — nor should you call <code>Thread.wait()</code> or +<code>Thread.sleep()</code>. Instead of blocking while waiting for a child +thread to complete, your main thread should provide a {@link +android.os.Handler Handler} for child threads to post back to upon completion. +Designing your application in this way will allow your main thread to remain +responsive to input and thus avoid ANR dialogs caused by the 5 second input +event timeout. These same practices should be followed for any other threads +that display UI, as they are also subject to the same timeouts.</p> + +<p>The specific constraint on IntentReciever execution time emphasizes what +they were meant to do: small, discrete amounts of work in the background such +as saving a setting or registering a Notification. So as with other methods +called in the main thread, applications should avoid potentially long-running +operations or calculations in BroadcastReceivers. But instead of doing intensive +tasks via child threads (as the life of a BroadcastReceiver is short), your +application should start a {@link android.app.Service Service} if a +potentially long running action needs to be taken in response to an Intent +broadcast. As a side note, you should also avoid starting an Activity from an +Intent Receiver, as it will spawn a new screen that will steal focus from +whatever application the user is currently has running. If your application +has something to show the user in response to an Intent broadcast, it should +do so using the {@link android.app.NotificationManager Notification +Manager}.</p> + +<h2 id="reinforcing">Reinforcing Responsiveness</h2> + +<p>Generally, 100 to 200ms is the threshold beyond which users will perceive +lag (or lack of "snappiness," if you will) in an application. As such, here +are some additional tips beyond what you should do to avoid ANR that will help +make your application seem responsive to users.</p> + +<ul> + <li>If your application is doing work in the background in response to + user input, show that progress is being made ({@link + android.widget.ProgressBar ProgressBar} and {@link + android.app.ProgressDialog ProgressDialog} are useful for this).</li> + <li>For games specifically, do calculations for moves in a child + thread.</li> + <li>If your application has a time-consuming initial setup phase, consider + showing a splash screen or rendering the main view as quickly as possible + and filling in the information asynchronously. In either case, you should + indicate somehow that progress is being made, lest the user perceive that + the application is frozen.</li> +</ul> diff --git a/docs/html/guide/practices/design/seamlessness.jd b/docs/html/guide/practices/design/seamlessness.jd new file mode 100644 index 0000000..4d1dab0 --- /dev/null +++ b/docs/html/guide/practices/design/seamlessness.jd @@ -0,0 +1,245 @@ +page.title=Designing for Seamlessness +@jd:body + +<p>Even if your application is fast and responsive, certain design decisions can +still cause problems for users — because of unplanned interactions with +other applications or dialogs, inadvertent loss of data, unintended blocking, +and so on. To avoid these problems, it helps to understand the context in which +your applications run and the system interactions that can affect your +application. In short, you should strive to develop an application that +interacts seamlessly with the system and with other applications. </p> + +<p>A common seamlessness problem is when an application's background process +— for example, a service or broadcast receiver — pops up a dialog in +response to some event. This may seem like harmless behavior, especially when +you are building and testing your application in isolation, on the emulator. +However, when your application is run on an actual device, your application may +not have user focus at the time your background process displays the dialog. So +it could end up that your application would display it's dialog behind the +active application, or it could take focus from the current application and +display the dialog in front of whatever the user was doing (such as dialing a +phone call, for example). That behavior would not work for your application or +for the user. </p> + +<p>To avoid these problems, your application should use the proper system +facility for notifying the user — the +{@link android.app.Notification Notification} classes. Using +notifications, your application can signal the user that an event has +taken place, by displaying an icon in the status bar rather than taking +focus and interrupting the user.</p> + +<p>Another example of a seamlessness problem is when an activity inadvertently +loses state or user data because it doesn't correctly implement the onPause() +and other lifecycle methods. Or, if your application exposes data intended to be +used by other applications, you should expose it via a ContentProvider, rather +than (for example) doing so through a world-readable raw file or database.</p> + +<p>What those examples have in common is that they involve cooperating nicely +with the system and other applications. The Android system is designed to treat +applications as a sort of federation of loosely-coupled components, rather than +chunks of black-box code. This allows you as the developer to view the entire +system as just an even-larger federation of these components. This benefits you +by allowing you to integrate cleanly and seamlessly with other applications, and +so you should design your own code to return the favor.</p> + +<p>This document discusses common seamlessness problems and how to avoid them. +It covers these topics: </p> +<ul> + <li><a href="#drop">Don't Drop Data</a></li> + <li><a href="#expose">Don't Expose Raw Data</a></li> + <li><a href="#interrupt">Don't Interrupt the User</a></li> + <li><a href="#threads">Got a Lot to Do? Do it in a Thread</a></li> + <li><a href="#multiple-activities">Don't Overload a Single Activity Screen</a></li> + <li><a href="#themes">Extend System Themes</a></li> + <li><a href="#flexui">Design Your UI to Work with Multiple Screen Resolutions</a></li> + <li><a href="#network">Assume the Network is Slow</a></li> + <li><a href="#keyboard">Don't Assume Touchscreen or Keyboard</a></li> + <li><a href="#battery">Do Conserve the Device Battery</a></li> +</ul> + +<h2 id="drop">Don't Drop Data</h2> + +<p>Always keep in mind that Android is a mobile platform. It may seem obvious to +say it, but it's important to remember that another Activity (such as the +"Incoming Phone Call" app) can pop up over your own Activity at any moment. +This will fire the onSaveInstanceState() and onPause() methods, and will likely result in +your application being killed.</p> + +<p>If the user was editing data in your application when the other Activity +appeared, your application will likely lose that data when your application is +killed. Unless, of course, you save the work in progress first. The "Android +Way" is to do just that: Android applications that accept or edit input should +override the onSaveInstanceState() method and save their state in some appropriate +fashion. When the user revisits the application, she should be able to +retrieve her data.</p> + +<p>A classic example of a good use of this behavior is a mail application. If the +user was composing an email when another Activity started up, the application +should save the in-process email as a draft.</p> + +<h2 id="expose">Don't Expose Raw Data</h2> + +<p>If you wouldn't walk down the street in your underwear, neither should your +data. While it's possible to expose certain kinds of application to the world +to read, this is usually not the best idea. Exposing raw data requires other +applications to understand your data format; if you change that format, you'll +break any other applications that aren't similarly updated.</p> + +<p>The "Android Way" is to create a ContentProvider to expose your data to other +applications via a clean, well-thought-out, and maintainable API. Using a +ContentProvider is much like inserting a Java language interface to split up and +componentize two tightly-coupled pieces of code. This means you'll be able to +modify the internal format of your data without changing the interface exposed +by the ContentProvider, and this without affecting other applications.</p> + +<h2 id="interrupt">Don't Interrupt the User</h2> + +<p>If the user is running an application (such as the Phone application during a +call) it's a pretty safe bet he did it on purpose. That's why you should avoid +spawning activities except in direct response to user input from the current +Activity.</p> + +<p>That is, don't call startActivity() from BroadcastReceivers or Services running in +the background. Doing so will interrupt whatever application is currently +running, and result in an annoyed user. Perhaps even worse, your Activity may +become a "keystroke bandit" and receive some of the input the user was in the +middle of providing to the previous Activity. Depending on what your +application does, this could be bad news.</p> + +<p>Instead of spawning Activity UIs directly from the background, you should +instead use the NotificationManager to set Notifications. These will appear in +the status bar, and the user can then click on them at his leisure, to see +what your application has to show him.</p> + +<p>(Note that all this doesn't apply to cases where your own Activity is already +in the foreground: in that case, the user expects to see your next Activity in +response to input.)</p> + +<h2 id="threads">Got a Lot to Do? Do it in a Thread</h2> + +<p>If your application needs to perform some expensive or long-running +computation, you should probably move it to a thread. This will prevent the +dreaded "Application Not Responding" dialog from being displayed to the user, +with the ultimate result being the fiery demise of your application.</p> + +<p>By default, all code in an Activity as well as all its Views run in the same +thread. This is the same thread that also handles UI events. For example, when +the user presses a key, a key-down event is added to the Activity's main +thread's queue. The event handler system needs to dequeue and handle that +event quickly; if it doesn't, the system concludes after a few seconds that +the application is hung and offers to kill it for the user.</p> + +<p>If you have long-running code, running it inline in your Activity will run it +on the event handler thread, effectively blocking the event handler. This will +delay input processing, and result in the ANR dialogs. To avoid this, move +your computations to a thread. This <a +href="responsiveness.html">Design for Responsiveness</a> document +discusses how to do that..</p> + +<h2 id="multiple-activities">Don't Overload a Single Activity Screen</h2> + +<p>Any application worth using will probably have several different screens. +When designing the screens of your UI, be sure to make use of multiple Activity +object instances.</p> + +<p>Depending on your development background, you may interpret an Activity as +similar to something like a Java Applet, in that it is the entry point for +your application. However, that's not quite accurate: where an Applet subclass +is the single entry point for a Java Applet, an Activity should be thought of +as one of potentially several entry points to your application. The only +difference between your "main" Activity and any others you might have is that +the "main" one just happens to be the only one that expressed an interest in +the "android.intent.action.MAIN" action in your AndroidManifest..xml file.</p> + +<p>So, when designing your application, think of your application as a federation +of Activity objects. This will make your code a lot more maintainable in the long +run, and as a nice side effect also plays nicely with Android's application +history and "backstack" model.</p> + +<h2 id="themes">Extend System Themes</h2> + +<p>When it comes to the look-and-feel of the user interface, it's important to +blend in nicely. Users are jarred by applications which contrast with the user +interface they've come to expect. When designing your UIs, you should try and +avoid rolling your own as much as possible. Instead, use a Theme. You +can override or extend those parts of the theme that you need to, but at least +you're starting from the same UI base as all the other applications. For all +the details, <a href="{@docRoot}devel/ui/applying-themes.html">click here</a>.</p> + +<h2 id="flexui">Design Your UI to Work with Multiple Screen Resolutions</h2> + +<p>Different Android-powered devices will support different screen resolutions. +Some will even be able to change resolutions on the fly, such as by switching +to landscape mode. It's important to make sure your layouts and drawables +are flexible enough to display properly on a variety of device screens.</p> + +<p>Fortunately, this is very easy to do. In brief, what you must do is +provide different versions of your artwork (if you use any) for the key +resolutions, and then design your layout to accommodate various dimensions. +(For example, avoid using hard-coded positions and instead use relative +layouts.) If you do that much, the system handles the rest, and your +application looks great on any device.</p> + +<h2 id="network">Assume the Network is Slow</h2> + +<p>Android devices will come with a variety of network-connectivity options. All +will have some data-access provision, though some will be faster than others. +The lowest common denominator, however, is GPRS, the non-3G data service for +GSM networks. Even 3G-capable devices will spend lots of time on non-3G +networks, so slow networks will remain a reality for quite a long time to +come.</p> + +<p>That's why you should always code your applications to minimize network +accesses and bandwidth. You can't assume the network is fast, so you should +always plan for it to be slow. If your users happen to be on faster networks, +then that's great — their experience will only improve. You want to avoid the +inverse case though: applications that are usable some of the time, but +frustratingly slow the rest based on where the user is at any given moment are +likely to be unpopular.</p> + +<p>One potential gotcha here is that it's very easy to fall into this trap if +you're using the emulator, since the emulator uses your desktop computer's +network connection. That's almost guaranteed to be much faster than a cell +network, so you'll want to change the settings on the emulator that simulate +slower network speeds. You can do this in Eclipse, in the "Emulator Settings" +tab of your launch configuration or via a <a +href="{@docRoot}guide/developing/tools/emulator.html#netspeed">command-line +option</a> when starting the emulator.</p> + +<h2 id="keyboard">Don't Assume Touchscreen or Keyboard</h2> + +Keyboad Different Keystrokes for Different Folks</h2> +<p> +Android will support a variety of handset form-factors. That's a fancy way of +saying that some Android devices will have full "QWERTY" keyboards, while +others will have 40-key, 12-key, or even other key configurations. Similarly, +some devices will have touch-screens, but many won't. +</p><p> +When building your applications, keep that in mind. Don't make assumptions +about specific keyboard layouts -- unless, of course, you're really interested +in restricting your application so that it can only be used on those devices. +</p> + +<h2 id="network">Assume the Network is Slow</h2> +<h2 id="keyboard">Don't Assume Touchscreen or Keyboard</h2> +<h2 id="battery">Do Conserve the Device Battery</h2> +<p> +A mobile device isn't very mobile if it's constantly plugged into the +wall. Mobile devices are battery-powered, and the longer we can make that +battery last on a charge, the happier everyone is — especially the user. +Two of the biggest consumers of battery power are the processor, and the +radio; that's why it's important to write your applications to do as little +work as possible, and use the network as infrequently as possible. +</p><p> +Minimizing the amount of processor time your application uses really comes +down to <a href="performance.html">writing efficient +code</a>. To minimize the power drain from using the radio, be sure to handle +error conditions gracefully, and only fetch what you need. For example, don't +constantly retry a network operation if one failed. If it failed once, it's +likely because the user has no reception, so it's probably going to fail again +if you try right away; all you'll do is waste battery power. +</p><p> +Users are pretty smart: if your program is power-hungry, you can count on +them noticing. The only thing you can be sure of at that point is that your +program won't stay installed very long. +</p> diff --git a/docs/html/guide/practices/index.html b/docs/html/guide/practices/index.html new file mode 100644 index 0000000..4881acf --- /dev/null +++ b/docs/html/guide/practices/index.html @@ -0,0 +1,8 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=../index.html"> +</head> +<body> +<a href="../index.html">click here</a> if you are not redirected. +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/samples/index.jd b/docs/html/guide/samples/index.jd new file mode 100644 index 0000000..0224a56 --- /dev/null +++ b/docs/html/guide/samples/index.jd @@ -0,0 +1,17 @@ +guide=true +page.title=Android Samples +@jd:body + + +<p>Sometimes, the best way to learn how things are done is to just look at some code. +So here we've provided the source code for some simple Android applications.</p> + +<dl> + <dt><a href="ApiDemos/">API Demos</a></dt> + <dd>A variety of small applications that demonstrate simple views and widgets.</dd> + <dt><a href="LunarLander/">Lunar Lander</a></dt> + <dd>A classic Lunar Lander game.</dd> + <dt><a href="NotePad/">Notepad</a></dt> + <dd>An application for saving notes. Similar (but not identical) to the + <a href="{@docRoot}guide/tutorials/notepad/notepad-index.html">Notepad tutorial</a>.</dd> +</dl>
\ No newline at end of file diff --git a/docs/html/guide/topics/data/contentproviders.jd b/docs/html/guide/topics/data/contentproviders.jd new file mode 100644 index 0000000..343ed84 --- /dev/null +++ b/docs/html/guide/topics/data/contentproviders.jd @@ -0,0 +1,608 @@ +page.title=Accessing Content Providers +@jd:body + +<p>If you want to make your data public, you can create (or call) a content +provider. This is an object that can store and retrieve data accessible by all +applications. This is the only way to share data across packages; there is no +common storage area that all packages can share. Android ships with a number +of content providers for common data types (audio, video, images, personal +contact information, and so on). You can see some of +Android's native content providers in the {@link android.provider provider} package.</p> + +<p>How a content provider actually stores its data under the covers is up to +the implementation of the content provider, but all content providers must +implement a common convention to query for data, and a common convention to +return results. However, a content provider can implement custom helper +functions to make data storage/retrieval simpler for the specific data that it +exposes.</p> + +<p>This document covers two topics related to Content Providers:</p> +<ul> + <li><a href="#usingacp">Using a Content Provider</a></li> + <li><a href="#creatingacontentprovider">Creating a Content Provider</a></li> +</ul> + +<h2>Using a Content Provider to Store and Retrieve Data <a name="usingacp" +id="usingacp"></a></h2> + +<p>This section describes how to store and retrieve data using a content +provider implemented by you or anyone else. Android exposes a number of +content providers for a wide range of data types, from music and image files +to phone numbers. You can see a list of content providers exposed through the +convenience classes in the {@link android.provider android.provider} package.</p> + +<p>Android's content providers are loosely linked to their clients. Each +content provider exposes a unique string (a URI) identifying the type of data +that it will handle, and the client must use that string to store or retrieve +data of that type. We'll explain this more in <a href="#querying">Querying for +Data</a>.</p> + +<p>This section describes the following activities:</p> + +<ul> + <li> + <a href="#querying">Querying for Data</a> + + <ul> + <li>Making the query</li> + + <li>What the query returns</li> + + <li>Querying for files</li> + + <li>Reading retrieved data</li> + </ul> + </li> + + <li><a href="#modifyingdata">Modifying Data</a></li> + + <li><a href="#addingrecord">Adding a Record</a></li> + + <li><a href="#deletingrecord">Deleting a Record</a></li> +</ul> + +<a name="querying" id="querying"></a> +<h4>Querying for Data</h4> + +<p>Each contact provider exposes a unique public URI (wrapped by {@link android.net.Uri}) +that is used by a client to query/add/update/delete data on that content +provider. This URI has two forms: one to indicate all values of that type +(e.g., all personal contacts), and one form to indicate a specific record of +that type (e.g., Joe Smith's contact information).</p> + +<ul> + <li><strong>content://contacts/people/</strong> is the URI that would return a list of all contact names on the device.</li> + + <li><strong>content://contacts/people/23</strong> is the URI string that would return a single result row, the contact with ID = 23. .</li> +</ul> + +<p>An application sends a query to the device that specifies a general type of +item (all phone numbers), or a specific item (Bob's phone number), to +retrieve. Android then returns a Cursor over a recordset of results, with a +specific set of columns. Let's look at a hypothetical query string and a +result set (the results have been trimmed a bit for clarity):</p> + +<p>query = <code>content://contacts/people/</code></p> + +<p>Results:</p> + +<table border="1"> + <tbody> + <tr> + <th scope="col">_ID</th> + + <th scope="col">_COUNT</th> + + <th scope="col">NUMBER</th> + + <th scope="col">NUMBER_KEY</th> + + <th scope="col">LABEL</th> + + <th scope="col">NAME</th> + + <th scope="col">TYPE</th> + </tr> + + <tr> + <td>13</td> + + <td>4</td> + + <td>(425) 555 6677</td> + + <td>425 555 6677</td> + + <td>Kirkland office</td> + + <td>Bully Pulpit</td> + + <td>Work</td> + </tr> + + <tr> + <td>44</td> + + <td>4</td> + + <td>(212) 555-1234</td> + + <td>212 555 1234</td> + + <td>NY apartment</td> + + <td>Alan Vain</td> + + <td>Home</td> + </tr> + + <tr> + <td>45</td> + + <td>4</td> + + <td>(212) 555-6657</td> + + <td>212 555 6657</td> + + <td>Downtown office</td> + + <td>Alan Vain</td> + + <td>Work</td> + </tr> + + <tr> + <td>53</td> + + <td>4</td> + + <td>201.555.4433</td> + + <td>201 555 4433</td> + + <td>Love Nest</td> + + <td>Rex Cars</td> + + <td>Home</td> + </tr> + </tbody> +</table> + +<p>Note that the query string isn't a standard SQL query string, but instead a +URI string that describes the type of data to return. This URI consists of +three parts: the string "content://"; a segment that describes what kind of +data to retrieve; and finally an optional ID of a specific item of the +specified content type. Here are a few more example query strings:</p> + +<ul> + <li><strong>content://media/internal/images</strong> is the URI string that would return a list of all + the internal images on the device.</li> + + <li><strong>content://media/external/images</strong> is the URI string that would return a list of all + the images on the "primary" external storage (e.g., the SD card).</li> + + <li><strong>content://contacts/people/</strong> is the URI that would return a list of all contact names on the device.</li> + + <li><strong>content://contacts/people/23</strong> is the URI string that would return a single result row, the contact with ID = 23.</li> +</ul> + +<p>Although there is a general form, these query URIs are somewhat arbitrary and +confusing. Therefore, Android provides a list of helper classes in the {@link +android.provider} package that +define these query strings so you should not need to know the actual URI value +for different data types. These helper classes define a string (actually, +a {@link android.net.Uri Uri} object) +called CONTENT_URI for a specific data type.</p> + +<p>Typically you will use the defined CONTENT_URI object to make a query, +instead of writing the full URI yourself. +So, each of the example query strings listed above (except for the last one that specifies the record ID) + can be acquired with the following Uri references:</p> + +<ul> + <li>{@link android.provider.MediaStore.Images.Media#INTERNAL_CONTENT_URI + MediaStore.Images.Media.INTERNAL_CONTENT_URI}</li> + + <li>{@link android.provider.MediaStore.Images.Media#EXTERNAL_CONTENT_URI + MediaStore.Images.Media.EXTERNAL_CONTENT_URI}</li> + + <li>{@link android.provider.Contacts.People#CONTENT_URI + Contacts.People.CONTENT_URI}</li> +</ul> + +<p>To query a specific record ID (e.g., content://contacts/people/23), +you'll use the same CONTENT_URI, but must append the specific ID value that you want. +This is one of the few times you should need to examine or modify the URI string. +So, for example, if you were looking for record 23 in the people contacts, you might run a query +as shown here:</p> +<pre> +// Get the base URI for contact with _ID=23. +// This is same as Uri.parse("content://contacts/people/23"); +Uri myPerson = ContentUris.withAppendedId(People.CONTENT_URI, 23); +// Query for this record. +Cursor cur = managedQuery(myPerson, null, null, null); +</pre> +<p class="note"><strong>Tip:</strong> You can also append a string to a Uri, using +{@link android.net.Uri#withAppendedPath(Uri,String)}.</p> + +<p>This query returns a cursor over a database query result set. What columns +are returned, what they're called, and what they are named are discussed next. +For now, though, know that you can specify that only certain columns be +returned, the sort order, and a SQL WHERE clause.</p> + +<p>You should use the {@link +android.app.Activity#managedQuery(android.net.Uri,java.lang.String[],java.lang.String,java.lang.String[],java.lang.String) Activity.managedQuery()} +method to retrieve a managed cursor. A managed cursor handles all the niceties +such as unloading itself when the application pauses, and requerying itself +when the application restarts. You can ask Android to manage an unmanaged +cursor for you by calling {@link +android.app.Activity#startManagingCursor(android.database.Cursor) Activity.startManagingCursor()}.</p> + +<p>Let's look at an example query to retrieve a list of contact names and their primary phone +numbers.</p> +<pre> +// An array specifying which columns to return. +string[] projection = new string[] { + People._ID, + People.NAME, + People.NUMBER, +}; + +// Get the base URI for People table in Contacts content provider. +// ie. content://contacts/people/ +Uri mContacts = People.CONTENT_URI; + +// Best way to retrieve a query; returns a managed query. +Cursor managedCursor = managedQuery( mContacts, + projection, //Which columns to return. + null, // WHERE clause--we won't specify. + People.NAME + " ASC"); // Order-by clause. +</pre> + +<p>This query will retrieve data from the people table of +the Contacts content provider. It will retrieve the name, primary phone number, and unique record ID for +each contact. </p> + +<p><strong>What the query returns</strong></p> + +<p>A query returns a set of zero or more database records. The column names, +order, and type are specific to the content provider, but every query includes +a column called _id, which is the ID of the item in that row. If a query can +return binary data, such as a bitmap or audio file, it will have a column with +any name that holds a content:// URI that you can use to get this data (more +information on how to get the file will be given later). Here is a tiresome +example result set for the previous query:</p> + +<table border="1"> + <tbody> + <tr> + <th scope="col">_id</th> + + <th scope="col">name</th> + + <th scope="col">number</th> + + + </tr> + + <tr> + <td>44</td> + + <td>Alan Vain</td> + + <td>212 555 1234</td> + + + </tr> + + <tr> + <td>13</td> + + <td>Bully Pulpit</td> + + <td>425 555 6677</td> + + + </tr> + + <tr> + <td>53</td> + + <td>Rex Cars</td> + + <td>201 555 4433</td> + + + </tr> + </tbody> +</table> + +<p>This result set demonstrates what is returned when we specified a subset of +columns to return. The optional subset list is passed in the +<em>projection</em> parameter of the query. A content manager should list +which columns it supports either by implementing a set of interfaces +describing each column (see {@link +android.provider.Contacts.People.Phones Contacts.People.Phones}, +which extends {@link android.provider.BaseColumns BaseColumns}, {@link +android.provider.Contacts.PhonesColumns PhonesColumns}, and {@link +android.provider.Contacts.PeopleColumns PeopleColumns}), or by +listing the column names as constants. Note that you need to +know the data type of a column exposed by a content provider in order to be +able to read it; the field reading method is specific to the data type, and a +column's data type is not exposed programmatically.</p> + +<p>The retrieved data is exposed by a {@link +android.database.Cursor Cursor} object that can be used to +iterate backward or forward through the result set. You can use this cursor to +read, modify, or delete rows. Adding new rows requires a different object +described later.</p> + +<p>Note that by convention, every recordset includes a field named _id, which +is the ID of a specific record, and a _count field, which is a count of +records in the current result set. These field names are defined by {@link +android.provider.BaseColumns BaseColumns}.</p> + +<p><strong>Querying for Files</strong></p> + +<p>The previous query result demonstrates how a file is returned in a data +set. The file field is typically (but not required to be) a string path to the +file. However, the caller should never try to read and open the file directly +(permissions problems for one thing can make this fail). Instead, you should +call {@link +android.content.ContentResolver#openInputStream(android.net.Uri) ContentResolver.openInputStream()} +/ {@link +android.content.ContentResolver#openOutputStream(android.net.Uri) +ContentResolver.openOutputStream()}, +or one of the helper functions from a content provider.</p> + +<p><strong>Reading Retrieved Data</strong></p> + +<p>The Cursor object retrieved by the query provides access to a recordset of +results. If you have queried for a specific record by ID, this set will +contain only one value; otherwise, it can contain multiple values. You can +read data from specific fields in the record, but you must know the data type +of the field, because reading data requires a specialized method for each type +of data. (If you call the string reading method on most types of columns, +Android will give you the String representation of the data.) The Cursor lets +you request the column name from the index, or the index number from the +column name.</p> + +<p>If you are reading binary data, such as an image file, you should call +{@link +android.content.ContentResolver#openOutputStream(android.net.Uri) ContentResolver.openOutputStream()} +on the string content:// URI stored in a column name.</p> + +<p>The following snippet demonstrates reading the name and phone number from +our phone number query:</p> +<pre> +private void getColumnData(Cursor cur){ + if (cur.moveToFirst()) { + + String name; + String phoneNumber; + int nameColumn = cur.getColumnIndex(People.NAME); + int phoneColumn = cur.getColumnIndex(People.NUMBER); + String imagePath; + + do { + // Get the field values + name = cur.getString(nameColumn); + phoneNumber = cur.getString(phoneColumn); + + // Do something with the values. + ... + + } while (cur.moveToNext()); + + } +} +</pre> + +<h3>Modifying Data<a name="modifyingdata" id="modifyingdata"></a></h3> + +<p>To batch update a group of records (for example, to change "NY" to "New +York" in all contact fields), call the {@link +android.content.ContentResolver#update(android.net.Uri,android.content.ContentValues,java.lang.String,java.lang.String[]) ContentResolver.update()} +method with the columns and values to change.</p> + +<h3>Adding a New Record <a name="addingrecord" id="addingrecord"></a></h3> + +<p>To add a new record, call ContentResolver.insert() with the URI of the type +of item to add, and a Map of any values you want to set immediately on the new +record. This will return the full URI of the new record, including record +number, which you can then use to query and get a Cursor over the new +record.</p> + +<pre> +ContentValues values = new ContentValues(); +Uri phoneUri = null; +Uri emailUri = null; + +values.put(Contacts.People.NAME, "New Contact"); +//1 = the new contact is added to favorites +//0 = the new contact is not added to favorites +values.put(Contacts.People.STARRED,1); + +//Add Phone Numbers +Uri uri = getContentResolver().insert(Contacts.People.CONTENT_URI, values); + +//The best way to add Contacts data like Phone, email, IM is to +//get the CONTENT_URI of the contact just inserted from People's table, +//and use withAppendedPath to construct the new Uri to insert into. +phoneUri = Uri.withAppendedPath(uri, Contacts.People.Phones.CONTENT_DIRECTORY); + +values.clear(); +values.put(Contacts.Phones.TYPE, Phones.TYPE_MOBILE); +values.put(Contacts.Phones.NUMBER, "1233214567"); +getContentResolver().insert(phoneUri, values); + +//Add Email +emailUri = Uri.withAppendedPath(uri, ContactMethods.CONTENT_DIRECTORY); + +values.clear(); +//ContactMethods.KIND is used to distinguish different kinds of +//contact data like email, im, etc. +values.put(ContactMethods.KIND, Contacts.KIND_EMAIL); +values.put(ContactMethods.DATA, "test@example.com"); +values.put(ContactMethods.TYPE, ContactMethods.TYPE_HOME); +getContentResolver().insert(emailUri, values); + +</pre> + +<p>To save a file, you can call ContentResolver().openOutputStream() with the +URI as shown in the following snippet: +</p> +<pre> +// Save the name and description in a map. Key is the content provider's +// column name, value is the value to save in that record field. +ContentValues values = new ContentValues(3); +values.put(MediaStore.Images.Media.DISPLAY_NAME, "road_trip_1"); +values.put(MediaStore.Images.Media.DESCRIPTION, "Day 1, trip to Los Angeles"); +values.put(MediaStore.Images.Media.MIME_TYPE, "image/jpeg"); + +// Add a new record without the bitmap, but with the values. +// It returns the URI of the new record. +Uri uri = getContentResolver().insert(MediaStore.Images.Media.EXTERNAL_CONTENT_URI, values); + +try { + // Now get a handle to the file for that record, and save the data into it. + // sourceBitmap is a Bitmap object representing the file to save to the database. + OutputStream outStream = getContentResolver().openOutputStream(uri); + sourceBitmap.compress(Bitmap.CompressFormat.JPEG, 50, outStream); + outStream.close(); +} catch (Exception e) { + Log.e(TAG, "exception while writing image", e); +} +</pre> + +<h3>Deleting a Record <a name="deletingrecord" id="deletingrecord"></a></h3> + +<p>To delete a single record, call {@link +android.content.ContentResolver#delete(android.net.Uri,java.lang.String,java.lang.String[]) ContentResolver.delete()} +with the URI of a specific row.</p> + +<p>To delete multiple rows, call ContentResolver.delete() with the URI of the +type of record to delete (for example, +android.provider.Contacts.People.CONTENT_URI) and a SQL WHERE clause defining +which rows to delete (<em>Warning</em>: be sure to include a valid WHERE +clause if deleting a general type using ContentResolver.delete(), or else you +risk deleting more records than you intended!).</p> + +<h2>Creating a Content Provider<a name="creatingacontentprovider" +id="creatingacontentprovider"></a> </h2> <p>Here is how to create your own +content provider to act as a public source for reading and writing a new data +type:</p> +<ol> + <li>Extend + {@link android.content.ContentProvider ContentProvider}.</li> + <li>Define a <code>public static final {@link android.net.Uri Uri} </code>named + CONTENT_URI. This is the string that represents the full "content://" URI + that your content provider handles. You must define a unique string for this + value; the best solution is to use the fully-qualified class name of your + content provider (lowercase). So, for example: <br> + + <code>public static final Uri CONTENT_URI = Uri.parse( + "content://com.google.codelab.rssprovider");</code></li> + <li>Create your system for storing data. Most content providers store their + data using Android's file storage methods or SQLite databases, but you can + store your data any way you want, so long as you follow the calling and return + value conventions.</li> + <li>Define the column names that you will return to your clients. If you are + using an underlying database, these column names are typically identical + to the SQL database column names they represent. In any case, you should include + an integer column named <code>_id</code> to + define a specific record number. If using the SQLite database, this should + be type <code>INTEGER + PRIMARY KEY AUTOINCREMENT</code>. + The <code>AUTOINCREMENT</code> descriptor + is optional, but by default, SQLite + autoincrements an ID counter field to the next number above the largest + existing number in the table. If you delete the last row, the next row added + will have the same ID as the deleted row. To avoid this by having SQLite + increment to the next largest value whether deleted or not, then assign your + ID column the following type: INTEGER PRIMARY KEY AUTOINCREMENT. (<strong>Note</strong> You + should have a unique _id field whether or not you have another field (such + as a URL) that is also unique among all records.) Android provides the + {@link android.database.sqlite.SQLiteOpenHelper SQLiteOpenHelper} + + class to help you create and manage versions of your database. </li> + <li>If you are exposing byte data, such as a bitmap file, the field that stores + this data should actually be a string field with a content:// URI for that + specific file. This is the field that clients will call to retrieve this + data. The content provider for that content type (it can be the same content + provider or another content provider — for example, if you're storing a photo + you would use the media content provider) should implement a field named + _data for that record. The _data field lists the exact file path on the device + for that file. This field is not intended to be read by the client, but by + the ContentResolver. The client will call {@link + android.content.ContentResolver#openOutputStream(android.net.Uri) ContentResolver.openOutputStream()} on the user-facing field holding the URI + for the item (for example, the column named photo might have a value content://media/images/4453). + The ContentResolver will request the _data field for that record, and because + it has higher permissions than a client, it should be able to access + that file directly and return a read wrapper for that file to the client. </li> + <li>Declare public static + Strings that clients can use to specify which columns to return, or to specify + field values from the cursor. Carefully document the data type of each + field. Remember that file fields, such as audio or bitmap fields, are typically + returned as string path values </li> + <li>Return a {@link android.database.Cursor Cursor} object over a recordset in + reply to a query. This means implementing the query(), update(), insert(), + and delete() methods. As a courtesy, you might want to call {@link android.content.ContentResolver#notifyChange(android.net.Uri,android.database.ContentObserver) ContentResolver.notifyChange()} to notify + listeners about updated information. </li> + + <li>Add a <code><provider></code> tag to AndroidManifest.xml, and use its + <em>authorities</em> attribute to define the authority part of the content type it should + handle. For example, if your content type is content://com.example.autos/auto + to request a list of all autos, then <em>authorities</em> would be <code>com.example.autos</code>. + Set the <em>multiprocess</em> attribute to true if data does not need to + be synchronized between multiple running versions of the content provider. </li> + + <li>If you are handling a new data type, you must define a new MIME type to return + for your implementation of {@link android.content.ContentProvider#getType(android.net.Uri) android.ContentProvider.getType(url)}. This type corresponds to the <code>content://</code> URI + submitted to getType(), which will be one of the content types handled by + the provider. The MIME type for each content type has two forms: one for + a specific record, and one for multiple records. Use the {@link android.net.Uri Uri} methods to help determine what is being requested. Here is + the general format for each: +<ul> +<li><code>vnd.android.cursor.item/vnd.<em>yourcompanyname.contenttype</em></code> +for a single row. For example, a request for train record 122 using +<pre>content://com.example.transportationprovider/trains/122</pre> +might return the MIME type +<code>vnd.android.cursor.item/vnd.example.rail</code> +</li> +<li><code>vnd.android.cursor.dir/vnd.<em>yourcompanyname.contenttype</em></code> +for multiple rows. For example, a request for all train records using +<pre>content://com.example.transportationprovider/trains</pre> +might return the MIME type +<code>vnd.android.cursor.dir/vnd.example.rail</code> +</li> +</ul> + + </li> +</ol> +<p>For an example of a private content provider implementation, see the NodePadProvider + class in the notepad sample application that ships with the SDK. </p> +<p>Here is a recap of the important parts of a content URI:</p> +<p><img src="../../images/content_uri.png" alt="Elements of a content URI" height="80" width="528"> </p> +<ol type="A"> + <li>Standard required prefix. Never modified. </li> + <li>Authority part. For third-party applications, this should be a fully-qualified + class to ensure uniqueness. This corresponds to the value in + the <code><provider></code> element's <em>authorities</em> attribute: + <code><provider class="TransportationProvider" + authorities="com.example.transportationprovider" + /></code> </li> + + <li>The path that the content provider uses to determine what kind of data is + being requested. This can be zero or more segments: if the content provider + exposes only one type of data (only trains, for example), this can be absent. + If it provides several types, including subtypes, this can be several elements + long: e.g., "<code>land/bus</code>, <code>land/train</code>, <code>sea/ship</code>, + and <code>sea/submarine</code>" to give four possibilities.</li> + <li>A specific record being requested, if any. This is the _id value of a specific + record being requested. If all records of a specific type are being requested, + omit this and the trailing slash: <code>content://com.example.transportationprovider/trains</code> </li> +</ol> + diff --git a/docs/html/guide/topics/data/data-storage.jd b/docs/html/guide/topics/data/data-storage.jd new file mode 100644 index 0000000..2b3491c --- /dev/null +++ b/docs/html/guide/topics/data/data-storage.jd @@ -0,0 +1,166 @@ +page.title=Data Storage +@jd:body + +<p> +A typical desktop operating system provides a common file system that any +application can use to store files that can be read by other +applications (perhaps with some access control settings). Android uses a +different system: On Android, all application data (including files) are +private to that application. + +<p> +However, Android also provides a standard way for an application to expose +its private data to other applications — through a content providers. +A content provider is an +optional component of an application that exposes read/write access to the +application's data, subject to whatever restrictions it might impose. +Content providers implement a standard syntax for requesting and modifying +data, and a standard mechanism for reading the returned data. Android supplies +a number of content providers for standard data types, such as image, audio, +and video files and personal contact information. For more information on +using content providers, see a separate document, +<a href="{@docRoot}devel/data/contentproviders.html">Content Providers</a>. + +<p> +Whether or not you want to export your application's data to others, +you need a way to store it. Android provides the following four mechanisms +for storing and retrieving data: + +<dl> +<dd><a href="#pref">Preferences</a> +<dd><a href="#files">Files</a> +<dd><a href="#db">Databases</a> +<dd><a href="#netw">Network</a> +</dl> + +<dl> +<dt><a name="pref"></a><b>Preferences</b></dt> +<dd>A lightweight mechanism to store and retrieve key-value pairs of primitive +data types. It is typically used to store application preferences, such as a +default greeting or a text font to be loaded whenever the application is started. Call +<code>{@link android.content.Context#getSharedPreferences(java.lang.String,int) +Context.getSharedPreferences()}</code> to read and write values. Assign a name to +your set of preferences if you want to share them with other components in the same +application, or use <code>{@link android.app.Activity#getPreferences(int) +Activity.getPreferences()}</code> with no name to keep them private to the calling +activity. You cannot share preferences across applications (except by using a +content provider). + +<p> +Here is an example of setting user preferences for silent keypress mode for a +calculator: + +<pre> +import android.app.Activity; +import android.content.SharedPreferences; + +public class Calc extends Activity { +public static final String PREFS_NAME = "MyPrefsFile"; + . . . + + @Override + protected void onCreate(Bundle state){ + super.onCreate(state); + + . . . + + // Restore preferences + SharedPreferences settings = getSharedPreferences(PREFS_NAME, 0); + boolean silent = settings.getBoolean("silentMode", false); + setSilent(silent); + } + + @Override + protected void onStop(){ + super.onStop(); + + // Save user preferences. We need an Editor object to + // make changes. All objects are from android.context.Context + SharedPreferences settings = getSharedPreferences(PREFS_NAME, 0); + SharedPreferences.Editor editor = settings.edit(); + editor.putBoolean("silentMode", mSilentMode); + + // Don't forget to commit your edits!!! + editor.commit(); + } +} +</pre></dd> + +<p> +<dt><a name="files"></a><b>Files</b></dt> +<dd>You can store files directly on the mobile device or on a removable +storage medium. By default, other applications cannot access these files. + +<p> +To read data from a file, call {@link android.content.Context#openFileInput +Context.openFileInput()} and pass it the local name and path of the file. +It returns a standard Java {@link java.io.FileInputStream} object. To write +to a file, call {@link android.content.Context#openFileOutput +Context.openFileOutput()} with the name and path. It returns a {@link +java.io.FileOutputStream} object. Calling these methods with name and path +strings from another application will not work; you can only access local +files. + +<p> +If you have a static file to package with your application at compile time, +you can save the file in your project in <code>res/raw/<em>myDataFile</em></code>, +and then open it with {@link +android.content.res.Resources#openRawResource(int) Resources.openRawResource +(R.raw.<em>myDataFile</em>)}. It returns an {@link java.io.InputStream} +object that you can use to read from the file. +</dd> + +<dt><a name="db"></a><b>Databases</b></dt> +<dd>The Android API contains support for creating and using SQLite databases. +Each database is private to the application that creates it. + +<p> +The {@link android.database.sqlite.SQLiteDatabase} object represents a database +and has methods for interacting with it — making queries and managing the +data. To create the database, call <code>{@link +android.database.sqlite.SQLiteDatabase#create SQLiteDatabase.create()}</code> +and also subclass {@link android.database.sqlite.SQLiteOpenHelper}. + +<p> +As part of its support for the SQLite database system, Android exposes +database management functions that let you store complex collections of data +wrapped into useful objects. For example, Android defines a data type +for contact information; it consists of many fields including a first and last +name (strings), an address and phone numbers (also strings), a photo (bitmap +image), and much other information describing a person. + +<p> +Android ships with the sqlite3 database tool, which enables you to browse +table contents, run SQL commands, and perform other useful functions on SQLite +databases. See <a href="{@docRoot}reference/adb.html#sqlite">Examine databases +(sqlite3)</a> to learn how to run this program. + +<p> +All databases, SQLite and others, are stored on the device in +<code>/data/data/<em>package_name</em>/databases</code>. + +<p> +Discussion of how many tables to create, what fields they contain, and how +they are linked, is beyond the scope of this note, but Android does not +impose any limitations beyond the standard SQLite concepts. We do recommend +including an autoincrement value key field that can be used as a unique ID to +quickly find a record. This is not required for private data, but if you +implement a content provider, you must include such a unique ID field. See the +<a href="{@docRoot}devel/data/contentproviders.html">Content Providers</a> +document for more information on this field and the NotePadProvider class +in the NotePad sample code for an example of creating and populating a +new database. Any databases you create will be accessible by name to any other +class in the application, but not outside the application.</p> +</dd> + +<dt><a name="netw"></a><b>Network</b></dt> +<dd>You can also use the network to store and retrieve data (when it's available). +To do network operations, use the classes in the following packages: +<dl> + <dd><code>{@link java.net java.net.*}</code></dd> + <dd><code>{@link android.net android.net.*}</code></dd> +</dl> +</dd> + +</dl> + diff --git a/docs/html/guide/topics/drawing/opengl.jd b/docs/html/guide/topics/drawing/opengl.jd new file mode 100644 index 0000000..e22a251 --- /dev/null +++ b/docs/html/guide/topics/drawing/opengl.jd @@ -0,0 +1,53 @@ +page.title=OpenGL +@jd:body + +<p>Android includes support for 3D hardware acceleration. This functionality is +accessed via the OpenGL API — specifically, the OpenGL ES API.</p> + +<p>OpenGL ES is a flavor of the OpenGL specification intended for embedded +devices. Versions of OpenGL ES are loosely peered to versions of the primary +OpenGL standard. Android currently supports OpenGL ES 1.0, which corresponds +to OpenGL 1.3. So, if the application you have in mind is possible with OpenGL +1.3 on a desktop system, it should be possible on Android.</p> + +<p>The specific API provided by Android is similar to the J2ME JSR239 OpenGL +ES API. However, it may not be identical, so watch out for deviations.</p> + +<h2>Using the API</h2> + +<p>Here's how to use the API at an extremely high level:</p> + +<ol> +<li>Write a custom View subclass.</li> +<li>Obtain a handle to an OpenGLContext, which provides access to the OpenGL functionality.</li> +<li>In your View's onDraw() method, get a handle to a GL object, and use its methods to perform GL operations.</li> +</ol> + +<p>For an example of this usage model (based on the classic GL ColorCube), +see +<a href="{@docRoot}samples/ApiDemos/src/com/example/android/apis/graphics/GLView1.html">com.android.samples.graphics.GLView1.java</a> +in the ApiDemos sample code project. A slightly more sophisticated version showing how to use +it with threads can be found in +<a href="{@docRoot}samples/ApiDemos/src/com/example/android/apis/graphics/GLSurfaceViewActivity.html">com.android.samples.graphics.GLSurfaceViewActivity.java</a>. +</p> + +<p>Writing a summary of how to actually write 3D applications using OpenGL is +beyond the scope of this text and is left as an exercise for the reader.</p> + +<h2>Links to Additional Information</h2> + +<p>Information about OpenGL ES can be +found at <a title="http://www.khronos.org/opengles/" +href="http://www.khronos.org/opengles/">http://www.khronos.org/opengles/</a>.</p> + +<p>Information specifically +about OpenGL ES 1.0 (including a detailed specification) can be found +at <a title="http://www.khronos.org/opengles/1_X/" +href="http://www.khronos.org/opengles/1_X/">http://www.khronos.org/opengles/1_X/</a>.</p> + +<p>The documentation for the Android {@link javax.microedition.khronos.opengles.GL +OpenGL ES implementations} are also available.</p> + +<p>Finally, note that though Android does include some basic support for +OpenGL ES 1.1, the support is <strong>not complete</strong>, and should not be relied +upon at this time.</p> diff --git a/docs/html/guide/topics/geo/lbs.jd b/docs/html/guide/topics/geo/lbs.jd new file mode 100644 index 0000000..981f6fe --- /dev/null +++ b/docs/html/guide/topics/geo/lbs.jd @@ -0,0 +1,73 @@ +page.title=Location-based Service APIs +@jd:body + +<p>The Android SDK includes two packages that provide Android's primary support +for building location-based services: +{@link android.location} and com.google.android.maps. +Please read on below for a brief introduction to each package.</p> + +<h2>android.location</h2> + +<p>This package contains several classes related to +location services in the Android platform. Most importantly, it introduces the +{@link android.location.LocationManager} +service, which provides an API to determine location and bearing if the +underlying device (if it supports the service). The LocationManager +should <strong>not</strong> be +instantiated directly; rather, a handle to it should be retrieved via +{@link android.content.Context#getSystemService(String) +getSystemService(Context.LOCATION_SERVICE)}.</p> + +<p>Once your application has a handle to the LocationManager, your application +will be able to do three things:</p> + +<ul> + <li>Query for the list of all LocationProviders known to the + LocationManager for its last known location.</li> + <li>Register/unregister for periodic updates of current location from a + LocationProvider (specified either by Criteria or name).</li> + <li>Register/unregister for a given Intent to be fired if the device comes + within a given proximity (specified by radius in meters) of a given + lat/long.</li> +</ul> + +<p>However, during initial development, you may not have access to real +data from a real location provider (Network or GPS). So it may be necessary to +spoof some data for your application, with some mock location data.</p> + +<p class="note"><strong>Note:</strong> If you've used mock LocationProviders in +previous versions of the SDK (m3/m5), you can no longer provide canned LocationProviders +in the /system/etc/location directory. These directories will be wiped during boot-up. +Please follow the new procedures below.</p> + + +<h3>Providing Mock Location Data</h3> + +<p>When testing your application on the Android emulator, there are a couple different +ways to send it some spoof location data: with the DDMS tool or the "geo" command.</p> + +<h4 id="ddms">Using DDMS</h4> +<p>With the DDMS tool, you can simulate location data a few different ways:</p> +<ul> + <li>Manually send individual longitude/latitude coordinates to the device.</li> + <li>Use a GPX file describing a route for playback to the device.</li> + <li>Use a KML file describing individual placemarks for sequenced playback to the device.</li> +</ul> +<p>For more information on using DDMS to spoof location data, see the +<a href="{@docRoot}reference/ddms.html#emulator-control">Using DDMS guide</a>. + +<h4 id="geo">Using the "geo" command</h4> +<p>Launch your application in the Android emulator and open a terminal/console in +your SDK's <code>/tools</code> directory. Now you can use:</p> +<ul><li><code>geo fix</code> to send a fixed geo-location. + <p>This command accepts a longitude and latitude in decimal degrees, and + an optional altitude in meters. For example:</p> + <pre>geo fix -121.45356 46.51119 4392</pre> + </li> + <li><code>geo nmea</code> to send an NMEA 0183 sentence. + <p>This command accepts a single NMEA sentence of type '$GPGGA' (fix data) or '$GPRMC' (transit data). + For example:</p> + <pre>geo nmea $GPRMC,081836,A,3751.65,S,14507.36,E,000.0,360.0,130998,011.3,E*62</pre> + </li> +</ul> + diff --git a/docs/html/guide/topics/geo/mapkey.jd b/docs/html/guide/topics/geo/mapkey.jd new file mode 100644 index 0000000..6442940 --- /dev/null +++ b/docs/html/guide/topics/geo/mapkey.jd @@ -0,0 +1,28 @@ +page.title=Obtaining a MapView API Key +@jd:body + +<p>MapView is a very useful class that lets you easily integrate Google Maps into your application. It provides built-in map downloading, rendering, and caching, as well as a variety of display options and controls. It provides a wrapper around the Google Maps API that lets your application request and manipulate Google Maps data through class methods, and it lets you work with Maps data as you would other types of Views. </p> + +<p>Because MapView gives you access to Google Maps data, you need to register your application with the Google Maps service and agree to the applicable Terms of Service, before your MapView will be able to obtain data from Google Maps. This will apply whether you are developing your application on the emulator or preparing your application for deployment to mobile devices. </p> + +<p>Registering your application is simple, and has two parts: </p> + +<ol> +<li>Registering a public key fingerprint from the certificate that you will use to sign the .apk. The registration service then provides you a Maps API Key that is associated with your application's signer certificate. </li> +<li>Adding the Maps API Key to a special attribute of the MapView element — <code>android:apiKey</code>. You can use the same Maps API Key for any MapView in any application, provided that the application's .apk is signed with the certificate whose fingerprint you registered with the service. </li> +</ol> + +<p>Once you have registered your application as described above, your MapView will be able to retrieve data from the Google Maps servers. </p> + +<div class="special"> +<p>The MapView registration service is not yet active and Google Maps is not yet enforcing the Maps API Key requirement. The registration service will be activated soon, so that MapViews in any application deployed to a mobile device will require registration and a valid Maps API Key.</p> + +<p>As soon as the registration service becomes available, this page (<a href="http://code.google.com/android/toolbox/apis/mapkey.html">http://code.google.com/android/toolbox/apis/mapkey.html</a>) will be updated with details about how and where to register and how to add your Maps API Key to your application. </p> + +<p>In the meantime, you can continue developing your MapView without registration, provided that you:</p> +<ol type="a"> +<li>Add the attribute "android:apiKey" to the MapView element in your layout XML, with any value. Or</li> +<li>Include an arbitrary string in the <code>apikey</code> parameter of the MapView constructor, if creating the MapView programmatically. </li> +</ol> + +<p>When the Maps API Key checking is activated in the service, any MapViews that do not have a properly registered apiKey will stop working. The map data (tile images) of the MapView will never load (even if the device is on the network). In this case, go to the page linked above and read about how to register your certificate fingerprint and obtain a Maps API Key. </p> diff --git a/docs/html/guide/topics/index.html b/docs/html/guide/topics/index.html new file mode 100644 index 0000000..4881acf --- /dev/null +++ b/docs/html/guide/topics/index.html @@ -0,0 +1,8 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=../index.html"> +</head> +<body> +<a href="../index.html">click here</a> if you are not redirected. +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/topics/intents/intents-filters.jd b/docs/html/guide/topics/intents/intents-filters.jd new file mode 100644 index 0000000..39ca589 --- /dev/null +++ b/docs/html/guide/topics/intents/intents-filters.jd @@ -0,0 +1,459 @@ +page.title=Intents and Intent Filters +@jd:body + +<p> +Three of the core components of an application — activities, services, and +broadcast receivers — are activated through messages, called <i>intents</i>. +Intent messaging is a facility for late run-time binding between components in the same +or different applications. The intent itself, an {@link android.content.Intent} +object, is a passive data structure holding an abstract description of an operation +to be performed — or, in the case of broadcasts, a description of something +that has happened and is being announced. There are separate mechanisms for +delivering intents to each type of component: + +<ul> + +<p><li>An Intent object is passed to <code>{@link android.content.Context#startActivity +Context.startActivity()}</code> or <code>{@link android.app.Activity#startActivityForResult +Activity.startActivityForResult()}</code> to launch an activity or get an existing +activity to do something new. + +<p><li>An Intent object is passed to <code>{@link android.content.Context#startService +Context.startService()}</code> to initiate a service or deliver new instructions to an +ongoing service. Similarly, an intent can be passed to <code>{@link +android.content.Context#bindService Context.bindService()}</code> to establish a +connection between the calling component and a target service. It initiates the +service if it's not already running. + +<p><li>Intent objects passed to any of the broadcast methods (such as <code>{@link +android.content.Context#sendBroadcast(Intent) Context.sendBroadcast()}</code>, +<code>{@link android.content.Context#sendOrderedBroadcast(Intent, String) +Context.sendOrderedBroadcast()}</code>, or <code>{@link +android.content.Context#sendStickyBroadcast Context.sendStickyBroadcast()}</code>) +are delivered to all interested broadcast receivers. Many kinds of broadcasts +originate in system code. + +</ul> + +<p> +In each case, the Android system finds the appropriate activity, service, or set +of broadcast receivers to respond to the intent, instantiating them if necessary. +There is no overlap within these messaging systems: Broadcast intents are delivered +only to broadcast receivers, never to activities or services. An intent passed to +{@code startActivity()} is delivered only to an activity, never to a service or +broadcast receiver, and so on. + +<p> +Intents can be divided into two groups: + +<ul> + +<p><li><i>Explicit intents</i> designate the target component by its class name. +They're typically used for application-internal messages — such as +an activity starting a subordinate service or launching a sister activity +— since component names would generally not be known to developers +of other applications. + +<p><li><i>Implicit intents</i> do not name the target. Instead, the +Android system determines the best component (or components) to respond +to the message. It compares the contents of the Intent object with +<i>intent filters</i>, structures associated with components that can +potentially receive intents. Filters advertise the capabilities of a +component and delimit the intents it can handle. + + +</ul> + +<p> +This document describes the rules Android uses to map intents to components — +how it determines which component should receive an intent message. +It begins with a description of Intent objects, and then describes intent filters +and how intents are tested against the filters. + + +<h2>Intent Objects</h2> + +<p> +An {@link android.content.Intent} object is a bundle of information. It contains +information of interest to the component that receives the intent (such as the action +to be taken and the data to act on) plus information +of interest to the Android system (such as the category of component that should handle +the intent and instructions on how to launch a target activity). Principally, it can contain +the following: + +<dl> + +<p><dt><b>Component class name</b></dt> +<dd>The fully qualified class name of the component that should handle the intent +— for example "{@code com.example.project.FreneticActivity}". +This field is optional (and it would not normally be set for broadcast intents, since +broadcasts are intended for more than a single receiver). However, if a class name +is specified, nothing else in the Intent +object matters for determining which component should get the intent; it will be +delivered to the named component. (Of course, the other contents of the intent will +matter to the component that receives it.) + +<p> +The component class is set by <code>{@link android.content.Intent#setComponent +setComponent()}</code>, <code>{@link android.content.Intent#setClass +setClass()}</code>, or <code>{@link android.content.Intent#setClassName(String, String) +setClassName()}</code> and read by <code>{@link android.content.Intent#getComponent +getComponent()}</code>. + +<p><dt><b>Action</b></dt> +<dd>A string naming the action to be performed — or, in the case of broadcast +intents, the action that took place and is being reported. This is the only field +in the object that must be set. The Intent class defines a number of action constants, +including these: + +<p><table> +<tr> + <th>Constant</th> + <th>Target component</th> + <th>Action</th> +</tr><tr> + <td>{@code ACTION_CALL} + <td>activity + <td>Initiate a phone call. +</tr><tr> + <td>{@code ACTION_EDIT} + <td>activity + <td>Display data for the user to edit. +</tr><tr> + <td>{@code ACTION_MAIN} + <td>activity + <td>Start up as the initial activity of a task. +</tr><tr> + <td>{@code ACTION_SYNC} + <td>activity + <td>Synchronize data on a server with data on the mobile device. +</tr><tr> + <td>{@code ACTION_BATTERY_LOW} + <td>broadcast receiver + <td>A warning that the battery is low. +</tr><tr> + <td>{@code ACTION_HEADSET_PLUG} + <td>broadcast receiver + <td>A headset has been plugged into the device, or unplugged from it. +</tr><tr> + <td>{@code ACTION_SCREEN_ON} + <td>broadcast receiver + <td>The screen has been turned on. +</tr><tr> + <td>{@code ACTION_TIMEZONE_CHANGED} + <td>broadcast receiver + <td>The setting for the time zone has changed. +</tr> +</table> + +<p> +See the {@link android.content.Intent} class description for a full list of pre-defined action constants. + +<p> +You can define action strings of your own. Those you define should include the +application package as a prefix — for example: +"<code>com.example.project.DEBIT_ACCT</code>". The action in an Intent object +is set by the <code>{@link android.content.Intent#setAction setAction()}</code> +method and read by <code>{@link android.content.Intent#getAction getAction()}</code>. + +<p><dt><b>Data</b></dt> +<dd>The data to be acted on. Different actions are paired with different kinds +of data specifications. For example, if the action field is {@code ACTION_EDIT}, +the data field would contain the URI of the document to be displayed for editing. +If the action is {@code ACTION_CALL}, the data field would be a {@code tel:} URI +with the number to call. Similarly, if the action is {@code ACTION_VIEW} and the +data field is a {@code mailto:} URI, the receiving activity would be called upon +to display a screen for composing an e-mail message, with the address filled in +from the URI. + +<p> +It's often important to know the type of data (its MIME type) in addition to its URI. +Typically, the type is inferred from the URI. But it can also be explicitly set. +The <code>{@link android.content.Intent#setData setData()}</code> method specifies +data only as a URI, <code>{@link android.content.Intent#setType setType()}</code> +specifies it only as a MIME type, and <code>{@link +android.content.Intent#setDataAndType setDataAndType()}</code> specifies it as both +a URI and a MIME type. The data and type are read by <code>{@link +android.content.Intent#getData getData()}</code> and <code>{@link +android.content.Intent#getType getType()}</code>. + + +<p><dt><b>Category</b></dt> +<dd>A string containing additional information about the kind of component +that should handle the intent. Categories generally apply only to activities. + +<p> +Any number of category descriptions can be placed in an Intent object. As it does for actions, the Intent class defines a number of category constants, including these: + +<p><table> +<tr> + <th>Constant</th> + <th>Meaning</th> +</tr><tr> + <td>{@code CATEGORY_BROWSABLE} + <td>The target activity can be safely invoked by the browser to display data + referenced by a link — for example, an image or an e-mail message. +</tr><tr> + <td>{@code CATEGORY_GADGET} + <td>The activity can be embedded inside of another activity that hosts gadgets. +</tr><tr> + <td>{@code CATEGORY_HOME} + <td>The activity displays the home screen, the first screen the user sees when + the device is turned on or when the HOME key is pressed. +</tr><tr> + <td>{@code CATEGORY_LAUNCHER} + <td>The activity can be the initial activity of a task and is listed in + the top-level application launcher. +</tr><tr> + <td>{@code CATEGORY_PREFERENCE} + <td>The target activity is a preference panel. +</tr> +</table> + +<p> +In addition to the role categories play in Intent objects, they have an +independent function in intent filters. As the examples above suggest, they +instruct the Android system how to treat the activity that owns the filter. For +example, {@code CATEGORY_HOME} defines the home activity. + +<p> +See the {@link android.content.Intent} class description for the full list of +categories. + +<p> +The <code>{@link android.content.Intent#addCategory addCategory()}</code> method +places a category in an Intent object, <code>{@link android.content.Intent#removeCategory +removeCategory()}</code> deletes a category previously added, and <code>{@link android.content.Intent#getCategories getCategories()}</code> gets the set of all +categories currently in the object. + +<p><dt><b>Extras</b></dt> +<dd>Key-value pairs for additional information that should be delivered to the +component handling the intent. Just as some actions are paired with particular +kinds of data URIs, some are paired with particular extras. For example, an +{@code ACTION_TIMEZONE_CHANGED} intent has a "{@code time-zone}" extra that +identifies the new time zone, and {@code ACTION_HEADSET_PLUG} has a +"{@code state}" extra indicating whether the headset is now plugged in or +unplugged, as well as a "{@code name}" extra for the type of headset. + +<p> +The Intent object has a series of {@code put...()} methods for inserting various +types of extra data and a similar set of {@code get...()} methods for reading +the data. These methods parallel those for {@link android.os.Bundle} objects. +In fact, the extras can be installed and read as a Bundle using the <code>{@link +android.content.Intent#putExtras putExtras()}</code> and <code>{@link +android.content.Intent#getExtras getExtras()}</code> methods. + +<p><dt><b>Launch instructions</b></dt> +<dd>Flags that instruct the Android system how to launch an activity (for +example, which task the activity should belong to) and how to treat it after +it's launched (for example, whether it belongs in the list of recent activities). +All these flags are defined in the Intent class. + +</dl> + +<p> +The Android system and the applications that come with the platform employ +Intent objects both to send out system-originated broadcasts and to activate +system-defined components. To see how to structure an intent to activate a +system component, consult the +<a href="{@docRoot}../reference/available-intents.html">list of intents</a> +in the reference. +For example, the component that initiates phone calls can be activated by an +{@code ACTION_CALL} intent with a {@code tel:} URI specifying the phone number. + + +<h2>Intent Filters</h2> + +<p> +If an intent explicitly names a component class, Android delivers the intent to +an instance of that class, creating the instance if necessary. However, if the +intent does not designate a target by name, Android must find the appropriate +component to handle the request — a single activity or service to perform +the requested action or the set of broadcast receivers to respond to the +broadcast announcement. It does so by comparing the Intent object against +components' intent filters. + +<p> +To inform the system which intents they can handle, activities, services, and +broadcast receivers can have one or more intent filters. +Each filter describes a capability of the component, a set of intents that +the component is willing to receive. It, in effect, filters out unwanted +intents. An implicit intent (one that doesn't name a target class) is delivered +to a component only if it can pass through one of the component's filters. +If a component lacks any intent filters, it can be activated only by explicit +intents (those that specifically name its class). + +<p> +A component has separate filters for each job it can do, each face it can +present to the user. For example, if an activity can either display +a list of items that the user can select or display the full details of one of +the items, it would have a separate filter for each of these possibilities. + +<p> +An intent filter is an instance of the {@link android.content.IntentFilter} class. +However, since the Android system must know about the capabilities of a component +before it can launch that component, intent filters are generally not set up in +Java code, but in the application's manifest file (AndroidManifest.xml) as +{@code <intent-filter>} elements. (The one exception would be filters for +broadcast receivers that are registered dynamically by calling <code>{@link android.content.Context#registerReceiver(BroadcastReceiver, IntentFilter, String, +Handler) Context.registerReceiver()}</code>; they are directly created as +IntentFilter objects.) + +<p> +A filter has fields that parallel the action, data, and category fields of an +Intent object. A new intent is tested against the filter in all three areas. +To be delivered to the component that owns the filter, it must pass all three tests. +If it fails even one of them, the Android system won't deliver it to the +component — at least not on the basis of that filter. However, since a +component can have multiple intent filters, an arriving intent that does not pass +through one of a component's filters might make it through on another. + +<p> +Each of the three tests is described in detail below: + +<dl> + +<p> +<dt><b>Action test</b></dt> +<dd>An {@code <intent-filter>} element in the manifest file lists actions +as {@code <action>} subelements. For example: + +<pre><intent-filter . . . > + <action android:name="com.example.project.SHOW_CURRENT" /> + <action android:name="com.example.project.SHOW_RECENT" /> + <action android:name="com.example.project.SHOW_PENDING" /> + . . . +</intent-filter></pre> + +<p> +As the example shows, while an Intent object names just a single action, +a filter may list more than one — or it may not list any at all. + +<p> +To pass this test, the action specified in the {@link android.content.Intent} +object must match one of the actions listed in the filter. However, if the +filter doesn't list any actions, all actions are accepted, so all intents pass +the test. + +<p> +<dt><b>Category test</b></dt> +<dd>An {@code <intent-filter>} element also lists categories as subelements. +For example: + +<pre><intent-filter . . . > + <category android:name="android.intent.category.DEFAULT" /> + <category android:name="android.intent.category.BROWSABLE" /> + . . . +</intent-filter></pre> + +<p>Note that the constants described earlier for actions and categories are not +used in the manifest file. The full string values are used instead. For +instance, the "{@code android.intent.category.BROWSABLE}" string in the example +above corresponds to the {@code CATEGORY_BROWSABLE} constant mentioned earlier +in this document. Similarly, the string "{@code android.intent.action.EDIT}" +corresponds to the {@code ACTION_EDIT} constant. + +<p> +Many categories tell the Android system how to treat the component. For example, +"{@code android.intent.category.LAUNCHER}" (the {@code CATEGORY_LAUNCHER} constant +in code) instructs the system to include the activity in the screen showing +applications the user can launch. Some categories — like "{@code +android.intent.category.DEFAULT}" in the example above &mdash typically appear +only in filters, not in Intent objects. + +<p> +For an intent to pass the category test, every category in the Intent object +must match a category in the filter. The filter can list additional categories, +but it cannot omit any in the intent. An intent with no +categories always passes this test, regardless of what's in the filter. + +<p> +<dt><b>Data test</b></dt> +<dd>Like the action and categories, the data specification for an intent filter +is contained in a subelement. And, as in those cases, the subelement can appear +multiple times, or not at all. For example: + +<pre><intent-filter . . . > + <data android:scheme="content" + android:host="com.example" + android:path="folder/*" . . . /> + <data android:scheme="content" + android:type="image/jpeg" . . . /> + . . . +</intent-filter></pre> + +<p> +Each {@code <data>} element can specify a URI and a data type (MIME type). +There are separate attributes — {@code scheme}, {@code host}, {@code port}, +and {@code path} — for each part of the URI: + +<dl><dd>{@code scheme://host:port/path}</dd></dl> + +<p> +For example, in the following URI, + +<dl><dd>{@code content://com.example.project:200/folder/subfolder/etc}</dd></dl> + +<p> the scheme is "{@code content}", the host is "{@code com.example.project}", +the port is "{@code 200}", and the path is "{@code folder/subfolder/etc}". +The host and port together constitute the URI <i>authority</i>; if a host is +not specified, the port is ignored. + +<p> +Each of these attributes is optional, but they are not independent of each other: +For an authority to be meaningful, a scheme must also be specified. +For a path to be meaningful, both a scheme and an authority must be specified. + +<p> +When the URI in an Intent object is compared to a URI specification in a filter, +it's compared only to the parts of the URI actually specified in the filter. +For example, if a filter specifies only a scheme, all URIs with that scheme match +the filter. If a filter specifies a scheme and an authority but no path, all URIs +with the same scheme and authority match, regardless of their paths. If a filter +specifies a scheme, an authority, and a path, only URIs with the same scheme, +authority, and path match. However, a path specification in the filter can +contain wildcards to require only a partial match of the path. + +<p> +A {@code <data>} element specifies a MIME type with the {@code type} attribute. +Both the Intent object and the filter can use the '*" wildcard for the subtype field +— for example, "{@code text/*}" or "{@code image/*}" — indicating any +subtype matches. + +<p> +The data test compares both the URI and the data type in the Intent object to a URI +and data type specified in the filter. The rules are as follows: + +<ul> + +<p><li>An Intent object that contains neither a URI nor a data type passes the +test only if the filter likewise does not specify any URIs or data types. + +<p><li>An Intent object that contains a URI but no data type (and a type cannot +be inferred from the URI) passes the test only if its URI matches a URI in the +filter and the filter likewise does not specify a type. This will be the case +only for URIs like {@code mailto:} and {@code tel:} that do not refer to actual data. + +<p><li>An Intent object that contains a data type but not a URI passes the test +only if the filter lists the same data type and similarly does not specify a URI. + +<p><li>An Intent object that contains both a URI and a data type (or a data type +can be inferred from the URI) passes the data type part of the test only if its +type matches a type listed in the filter. It passes the URI part of the test +either if its URI matches a URI in the filter or if it has a {@code content:} +or {@code file:} URI and the filter does not specify a URI. In other words, +a component is presumed to support {@code content:} and {@code file:} data if +its filter list only a data type. + +</ul> + +<p> +If an intent can pass through the filters of more than one component, the user +may be asked which component to activate. + + + + + + + diff --git a/docs/html/guide/topics/manifest/manifest.jd b/docs/html/guide/topics/manifest/manifest.jd new file mode 100644 index 0000000..2cf1976 --- /dev/null +++ b/docs/html/guide/topics/manifest/manifest.jd @@ -0,0 +1,183 @@ +page.title=The Manifest File (AndroidManifest.xml) +@jd:body + +<p>Every Android application has a <em>manifest file</em> that declares global values for the application. +For example, the manifest file declares the appliication's fully qualified package name, as well as the application components (activities, services, etc) it exposes, the implementation classes for each, the kinds of data each can handle, +and where they can be launched. </p> + +<p>The manifest is an XML file that is always stored under the name <code>AndroidManifest.xml</code> in the root folder of the application. Only one manifest file is allowed per application package. As part of developing your android application, you will be creating the application's manifest file using the XML vocabulary described in this document. </p> + +<p>An important aspect of this file is the <em>intent filters</em> that it includes. + These filters describe where and when that activity can be started. When an activity + (or the operating system) wants to perform an action such as open a Web page + or open a contact picker screen, it creates an {@link android.content.Intent + Intent} object. This object can hold several descriptors describing what you + want to do, what data you want to do it to, the type of data, and other bits + of information. Android compares the information in an Intent object with the + intent filter exposed by every application and finds the activity most appropriate + to handle the data or action specified by the caller. More details + on intents is given in the {@link android.content.Intent + Intent} reference page.</p> + +<p>Besides declaring your application's activities, content providers, services, +and intent receivers, you can also specify permissions and instrumentation +(security control and testing) in AndroidManifest.xml. For a reference of the tags and +their attributes, please see {@link android.R.styleable#AndroidManifest}.</p> + +<p>A simple AndroidManifest.xml looks like this:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> + +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.my_domain.app.helloactivity"> + + <application android:label="@string/app_name"> + + <activity android:name=".HelloActivity"> + <intent-filter> + <action android:name="android.intent.action.MAIN"/> + <category android:name="android.intent.category.LAUNCHER"/> + </intent-filter> + </activity> + + </application> + +</manifest> +</pre> + +<p>Some general items to note:</p> + +<ul> +<li> <p>Almost every AndroidManifest.xml (as well as many other Android +XML files) will include the namespace declaration +<code>xmlns:android="http://schemas.android.com/apk/res/android"</code> in +its first element. This makes a variety of standard Android attributes +available in the file, which will be used to supply most of the data for +elements in that file.</code> +<li> <p>Most manifests include a single <code><application></code> +element, which defines all of the application-level components and +properties that are available in the package.</p> +<li> <p>Any package that will be presented to the user as a top-level +application available from the program launcher will need to include at +least one {@link android.app.Activity} component that supports the +{@link android.content.Intent#ACTION_MAIN MAIN} action and +{@link android.content.Intent#CATEGORY_LAUNCHER LAUNCHER} category as +shown here.</p> +</ul> + +<p>Here is a detailed outline of the structure of an AndroidManifest.xml file, +describing all tags that are available.</p> + +<dl> + <dt>{@link android.R.styleable#AndroidManifest <manifest>}</dt> + <dd>The root node of the file, describing the complete contents of + the package. Under it you can place: + <dl> + <dt>{@link android.R.styleable#AndroidManifestUsesPermission <uses-permission>}</dt> + <dd>Requests a security permission that your package must be granted in + order for it to operate correctly. See the + <a href="{@docRoot}devel/security.html">Security Model</a> + document for more information on permissions. A manifest can + contain zero or more of these elements.</dd> + <dt>{@link android.R.styleable#AndroidManifestPermission <permission>}</dt> + <dd>Declares a security permission that can be used to restrict which + applications can access components or features in your (or + another) package. See the + <a href="{@docRoot}devel/security.html">Security Model</a> + document for more information on permissions. A manifest can + contain zero or more of these elements.</dd> + <dt>{@link android.R.styleable#AndroidManifestInstrumentation <instrumentation>}</dt> + <dd>Declares the code of an instrumentation component that is available + to test the functionality of this <em>or another</em> package. + See {@link android.app.Instrumentation} for more details. A manifest can + contain zero or more of these elements.</dd> + <dt>{@link android.R.styleable#AndroidManifestApplication <application>}</dt> + <dd>Root element containing declarations of the application-level + components contained in the package. This element can also + include global and/or default attributes for the application, + such as a label, icon, theme, required permission, etc. A manifest + can contain zero or one of these elements (more than one application + tag is not allowed). Under it you can place zero or more of + each of the following component declarations: + <dl> + <dt>{@link android.R.styleable#AndroidManifestActivity <activity>}</dt> + <dd>An {@link android.app.Activity} is the primary facility for + an application to interact with the user. The initial screen + the user sees when launching an application is an activity, + and most other screens they use will be implemented as + separate activities declared with additional activity tags. + + <p><em><strong>Note:</strong></em> Every + Activity must have an <activity> tag in the manifest whether it is exposed + to the world or intended for use only within its own package. If an Activity + has no matching tag in the manifest, you won't be able to launch it. + + <p>Optionally, to support late runtime lookup of your + activity, you can include one or more <intent-filter> + elements to describe the actions the activity supports. + <dl> + <dt><a name="intent-filter"> + {@link android.R.styleable#AndroidManifestIntentFilter <intent-filter>}</a></dt> + <dd>Declares a specific set of {@link android.content.Intent} values + that a component supports, in the form of an + {@link android.content.IntentFilter}. In addition to the + various kinds of values + that can be specified under this element, attributes + can be given here to supply a unique label, icon, and + other information for the action being described. + <dl> + <dt>{@link android.R.styleable#AndroidManifestAction <action>}</dt> + <dd>An {@link android.content.IntentFilter#addAction Intent action} + that the component supports.</dd> + <dt>{@link android.R.styleable#AndroidManifestCategory <category>}</dt> + <dd>An {@link android.content.IntentFilter#addCategory Intent category} + that the component supports.</dd> + <dt>{@link android.R.styleable#AndroidManifestData <data>}</dt> + <dd>An {@link android.content.IntentFilter#addDataType Intent data MIME type}, + {@link android.content.IntentFilter#addDataScheme Intent data URI scheme}, + {@link android.content.IntentFilter#addDataAuthority Intent data URI authority}, or + {@link android.content.IntentFilter#addDataPath Intent data URI path} + that the component supports.</dd> + </dl> + </dl> + + <p>You can also optionally associate one or more pieces of meta-data + with your activity that other clients can retrieve to find + additional arbitrary information about it:</p> + <dl> + <dt><a name="meta-data"> + {@link android.R.styleable#AndroidManifestMetaData <meta-data>}</a></dt> + <dd>Adds a new piece of meta data to the activity, which clients + can retrieve through + {@link android.content.pm.ComponentInfo#metaData + ComponentInfo.metaData}. + </dl> + <dt>{@link android.R.styleable#AndroidManifestReceiver <receiver>}</dt> + <dd>An {@link android.content.BroadcastReceiver} allows an application + to be told about changes to data or actions that happen, + even if it is not currently running. As with the activity + tag, you can optionally include one or more <intent-filter> + elements that the receiver supports or <meta-data> values; + see the activity's + <a href="#intent-filter"><intent-filter></a> and + <a href="#meta-data"><meta-data></a> descriptions + for more information.</dd> + <dt>{@link android.R.styleable#AndroidManifestService <service>}</dt> + <dd>A {@link android.app.Service} is a component that can run in + the background for an arbitrary amount of time. As with the activity + tag, you can optionally include one or more <intent-filter> + elements that the service supports or <meta-data> values; + see the activity's + <a href="#intent-filter"><intent-filter></a> and + <a href="#meta-data"><meta-data></a> descriptions + for more information.</dd> + <dt>{@link android.R.styleable#AndroidManifestProvider <provider>}</dt> + <dd>A {@link android.content.ContentProvider} is a component that + manages persistent data and publishes it for access by other + applications. You can also optionally attach one or more + <meta-data> values, as described in the activity's + <a href="#meta-data"><meta-data></a> description.</dd> + </dl> + </dl> +</dl> diff --git a/docs/html/guide/topics/media/media.jd b/docs/html/guide/topics/media/media.jd new file mode 100644 index 0000000..16ad2b7 --- /dev/null +++ b/docs/html/guide/topics/media/media.jd @@ -0,0 +1,171 @@ +page.title=Media Capabilities +@jd:body + +<div class="sidebox"> + +<h3>Media Quickview</h3> + +<h4>Built-in capabilities</h4> +<ul> +<li>Audio playback and record</li> +<li>Video playback</li> +</ul> + +<h4>Data sources</h4> +<ul> +<li>Raw resources</li> +<li>Data files</li> +<li>Streams</li> +</ul> + +<h4>Media Formats</h4> +<ul> +<li>See appendix <a href="{@docRoot}devguide/appendix/media_formats.html">Android 1.0 Media Formats</a></li> +</ul> + +<h4>Key APIs</h4> +<ul> +<li>{@link android.media.MediaPlayer} (playback, all audio and video formats)</li> +<li>{@link android.media.MediaRecorder} (record, all audio formats)</li> +</ul> + +<p>The Android platform offers built-in encoding/decoding for a variety of common media types, +so that you can easily integrate audio, video, and images into your applications. Accessing the platform's media +capabilities is fairly straightforward &mdash you do so using the same intents and +activities mechanism that the rest of Android uses.</p> + +<p>Android lets you play audio and video from several types of data sources. You can play audio or video from media files stored in the application's resources (raw resources), from standalone files in the filesystem, or from a data stream arriving over a network connection. To play audio or video from your application, use the {@link android.media.MediaPlayer} class.</p> + +<p>The platform also lets you record audio, where supported by the mobile device hardware. Recording of video is not currently supported, but is planned for a future release. To record audio, use the +{@link android.media.MediaRecorder} class. Note that the emulator doesn't have hardware to capture audio, but actual mobile devices are likely to provide these capabilities that you can access through MediaRecorder. </p> + +<p>For a list of the media formats for which Android offers built-in support, see the <a href="{@docRoot}devguide/appendix/media_formats.html">Android Media Formats</a> appendix. </p> + +<h2>Playing Audio and Video</h2> +<p>Media can be played from anywhere: from a raw resource, from a file from the system, +or from an available network (URL).</p> + +<p>You can play back the audio data only to the standard +output device; currently, that is the mobile device speaker or Bluetooth headset. You +cannot play sound files in the conversation audio. </p> + +<h3>Playing from a Raw Resource</h3> +<p>Perhaps the most common thing to want to do is play back media (notably sound) +within your own applications. Doing this is easy:</p> +<ol> + <li>Put the sound (or other media resource) file into the <code>res/raw</code> + folder of your project, where the Eclipse plugin (or aapt) will find it and + make it into a resource that can be referenced from your R class</li> + <li>Create an instance of <code>MediaPlayer</code>, referencing that resource using + {@link android.media.MediaPlayer#create MediaPlayer.create}, and then call + {@link android.media.MediaPlayer#start() start()} on the instance:<br><br></li> +</ol> +<pre> + MediaPlayer mp = MediaPlayer.create(context, R.raw.sound_file_1); + mp.start(); +</pre> +<p>To stop playback, call {@link android.media.MediaPlayer#stop() stop()}. If +you wish to later replay the media, then you must +{@link android.media.MediaPlayer#reset() reset()} and +{@link android.media.MediaPlayer#prepare() prepare()} the MediaPlayer object +before calling {@link android.media.MediaPlayer#start() start()} again. +(<code>create()</code> calls <code>prepare()</code> the first time.)</p> +<p>To pause playback, call {@link android.media.MediaPlayer#pause() pause()}. +Resume playback from where you paused with +{@link android.media.MediaPlayer#start() start()}.</p> + +<h3>Playing from a File or Stream</h3> +<p>You can play back media files from the filesystem or a web URL:</p> +<ol> + <li>Create an instance of the <code>MediaPlayer</code> using <code>new</code></li> + <li>Call {@link android.media.MediaPlayer#setDataSource setDataSource()} + with a String containing the path (local filesystem or URL) + to the file you want to play</li> + <li>First {@link android.media.MediaPlayer#prepare prepare()} then + {@link android.media.MediaPlayer#start() start()} on the instance:<br><br></li> +</ol> +<pre> + MediaPlayer mp = new MediaPlayer(); + mp.setDataSource(PATH_TO_FILE); + mp.prepare(); + mp.start(); +</pre> +<p>{@link android.media.MediaPlayer#stop() stop()} and +{@link android.media.MediaPlayer#pause() pause()} work the same as discussed +above.</p> + <p class="note"><strong>Note:</strong> It is possible that <code>mp</code> could be + null, so good code should <code>null</code> check after the <code>new</code>. + Also, <code>IllegalArgumentException</code> and <code>IOException</code> either + need to be caught or passed on when using <code>setDataSource()</code>, since + the file you are referencing may not exist.</p> +<p class="note"><strong>Note:</strong> +If you're passing a URL to an online media file, the file must be capable of +progressive download.</p> + +<h2>Recording Media Resources</h2> +<p>Recording media is a little more involved than playing it back, as you would +probably expect, but it is still fairly simple. There is just a little more set +up to do</p> +<ol> + <li>Create a new instance of {@link android.media.MediaRecorder + android.media.MediaRecorder} using <code>new</code></li> + <li>Create a new instance of {@link android.content.ContentValues + android.content.ContentValues} and put in some standard properties like + <code>TITLE</code>, <code>TIMESTAMP</code>, and the all important + <code>MIME_TYPE</code></li> + <li>Create a file path for the data to go to (you can use {@link + android.content.ContentResolver android.content.ContentResolver} to + create an entry in the Content database and get it to assign a path + automatically which you can then use)</li> + <li>Set the audio source using {@link android.media.MediaRecorder#setAudioSource + MediaRecorder.setAudioSource()}. You will probably want to use + <code>MediaRecorder.AudioSource.MIC</code></li> + <li>Set output file format using {@link + android.media.MediaRecorder#setOutputFormat MediaRecorder.setOutputFormat()} + </li> + <li>Set the audio encoder using + {@link android.media.MediaRecorder#setAudioEncoder MediaRecorder.setAudioEncoder()} + </li> + <li>Finally, {@link android.media.MediaRecorder#prepare prepare()} and + {@link android.media.MediaRecorder#start start()} the recording. + {@link android.media.MediaRecorder#stop stop()} and + {@link android.media.MediaRecorder#release release()} when you are done</li> +</ol> +<p>Here is a code example that will hopefully help fill in the gaps:</p> +<p><strong>Start Recording</strong></p> +<pre> + recorder = new MediaRecorder(); + ContentValues values = new ContentValues(3); + + values.put(MediaStore.MediaColumns.TITLE, SOME_NAME_HERE); + values.put(MediaStore.MediaColumns.TIMESTAMP, System.currentTimeMillis()); + values.put(MediaStore.MediaColumns.MIME_TYPE, recorder.getMimeContentType()); + + ContentResolver contentResolver = new ContentResolver(); + + Uri base = MediaStore.Audio.INTERNAL_CONTENT_URI; + Uri newUri = contentResolver.insert(base, values); + + if (newUri == null) { + // need to handle exception here - we were not able to create a new + // content entry + } + + String path = contentResolver.getDataFilePath(newUri); + + // could use setPreviewDisplay() to display a preview to suitable View here + + recorder.setAudioSource(MediaRecorder.AudioSource.MIC); + recorder.setOutputFormat(MediaRecorder.OutputFormat.THREE_GPP); + recorder.setAudioEncoder(MediaRecorder.AudioEncoder.AMR_NB); + recorder.setOutputFile(path); + + recorder.prepare(); + recorder.start(); +</pre> +<p><strong>Stop Recording</strong></p> +<pre> + recorder.stop(); + recorder.release(); +</pre> + diff --git a/docs/html/guide/topics/processes/process-lifecycle.jd b/docs/html/guide/topics/processes/process-lifecycle.jd new file mode 100644 index 0000000..0380f94 --- /dev/null +++ b/docs/html/guide/topics/processes/process-lifecycle.jd @@ -0,0 +1,120 @@ +page.title=Processes and Application Life Cycle +@jd:body + +<p>In most cases, every Android application runs in its own Linux process. +This process is created for the application when some of its code needs to +be run, and will remain running until it is no longer needed <em>and</em> +the system needs to reclaim its memory for use by other applications.</p> + +<p>An unusual and fundamental feature of Android is that an application process's +lifetime is <em>not</em> directly controlled by the application itself. +Instead, it is determined by the system through a combination of the parts of the application +that the system knows are running, how important these things are to the user, +and how much overall memory is available in the system.</p> + +<p>It is important that +application developers understand how different application components +(in particular {@link android.app.Activity}, {@link android.app.Service}, +and {@link android.content.BroadcastReceiver}) impact the lifetime +of the application's process. <strong>Not using these components correctly can +result in the system killing the application's process while it is doing +important work.</strong></p> + +<p>A common example of a process life-cycle bug is a +{@link android.content.BroadcastReceiver} that starts a thread when it +receives an Intent in its {@link android.content.BroadcastReceiver#onReceive +BroadcastReceiver.onReceive()} +method, and then returns from the function. Once it returns, the system +considers the BroadcastReceiver to be no longer active, and thus, its hosting +process no longer needed (unless other application components are active in +it). So, the system may kill the process at any time to reclaim memory, and in doing so, +it terminates the spawned thread running in the process. The solution to this problem +is to start a {@link android.app.Service} from the BroadcastReceiver, so the +system knows that there is still active work being done in the process.</p> + +<p>To determine which processes should be killed when low on memory, Android +places each process into an "importance hierarchy" based on the components running in +them and the state of those components. These process types are (in order of importance):</p> + +<ol> + +<li>A <strong>foreground process</strong> is one that is required for +what the user is currently doing. Various application components can +cause its containing process to be considered foreground in different +ways. A process is considered to be in the foreground if any of the +following conditions hold: + <ul> + <li> It is running an {@link android.app.Activity} + at the top of the screen that the user is interacting with (its + {@link android.app.Activity#onResume} method has been called).</li> + <li> It has a {@link android.content.BroadcastReceiver} that is currently running + (its {@link android.content.BroadcastReceiver#onReceive + BroadcastReceiver.onReceive()} method is executing).</li> + <li>It has a {@link android.app.Service} that is currently executing code + in one of its callbacks ({@link android.app.Service#onCreate Service.onCreate()}, + {@link android.app.Service#onStart Service.onStart()}, or + {@link android.app.Service#onDestroy Service.onDestroy()}).</li> + </ul> +</li> +<p>There will only ever be a few such processes in the system, and these will only +be killed as a last resort if memory is so low that not even these processes +can continue to run. Generally, at this point, the device has +reached a memory paging state, so this action is required in order to keep the user +interface responsive.</p> +</li> + +<li>A <strong>visible process</strong> is one holding an {@link android.app.Activity} +that is visible to the user on-screen but not in the foreground (its +{@link android.app.Activity#onPause} method has been called). This may +occur, for example, if the foreground Activity is displayed as a dialog +that allows the previous Activity to be seen behind it. Such a +process is considered extremely important and will not be killed unless doing so is +required to keep all foreground processes running. +</li> + +<li>A <strong>service process</strong> is one holding a {@link android.app.Service} +that has been started with the +{@link android.content.Context#startService startService()} method. Though these +processes are not directly visible to the user, they are generally doing things +that the user cares about (such as background mp3 playback or background +network data upload or download), so the system will always keep such processes +running unless there is not enough memory to retain all foreground and visible process. +</li> + +<li>A <strong>background process</strong> is one holding an {@link android.app.Activity} +that is not currently visible to the user (its +{@link android.app.Activity#onStop} method has been called). These processes +have no direct impact on the user experience. Provided they implement +their Activity life-cycle correctly +(see {@link android.app.Activity} for more details), the system +can kill such processes at any time to reclaim memory for one of the three +previous processes types. Usually there are many of these processes running, +so they are kept in an LRU list to ensure the process that was most recently seen +by the user is the last to be killed when running low on memory. +</li> + +<li>An <strong>empty process</strong> is one that doesn't hold any active application +components. The only reason to keep such a process around is as a cache to +improve startup time the next time a component of its application needs to +run. As such, the system will often kill these processes in order to +balance overall system resources between these empty cached processes and the +underlying kernel caches. +</li> + +</ol> + +<p>When deciding how to classify a process, the system will base its decision on the most +important level found among all the components currently active in the process. +See the {@link android.app.Activity}, {@link android.app.Service}, and +{@link android.content.BroadcastReceiver} documentation for more detail on how +each of these components contribute to the overall life-cycle of a process. +The documentation for each of these classes describes in more detail how +they impact the overall life-cycle of their application.</p> + +<p>A process's priority may also be increased based on other dependencies +a process has to it. For example, if process A has bound to a +{@link android.app.Service} with +the {@link android.content.Context#BIND_AUTO_CREATE Context.BIND_AUTO_CREATE} +flag or is using a +{@link android.content.ContentProvider} in process B, then process B's +classification will always be at least as important as process A's.</p> diff --git a/docs/html/guide/topics/providers/content-providers.jd b/docs/html/guide/topics/providers/content-providers.jd new file mode 100644 index 0000000..93b379e --- /dev/null +++ b/docs/html/guide/topics/providers/content-providers.jd @@ -0,0 +1,847 @@ +page.title=Content Providers +@jd:body + +<h1>Content Providers</h1> + +<p> +Content providers store and retrieve data and make it accessible to all +applications. They're the only way to share data across applications; there's +no common storage area that all Android packages can access. + +<p> +Android ships with a number of content providers for common data types +(audio, video, images, personal contact information, and so on). You can +see some of them listed in the {@link android.provider android.provider} +package. You can query these providers for the data they contain (although, +for some, you must acquire the proper permission to read the data). + +<p> +If you want to make your own data public, you have two options: You can +create your own content provider (a {@link android.content.ContentProvider} +subclass) or you can add the data to an existing provider — if there's +one that controls the same type of data and you have permission to write to it. + +<p> +This document is an introduction to using content providers. It explores +the following topics: + +<dl><dd><a href="#basics">Content provider basics</a> +<br/><a href="#querying">Querying a content provider</a> +<br/><a href="#modifying">Modifying data in a provider</a> +<br/><a href="#creating">Creating a content provider</a></dd></dl> + + +<h2>Content Provider Basics<a href="#basics"></a></h2> + +<p> +How a content provider actually stores its data under the covers is +up to its designer. But all content providers implement a common interface +for querying the provider and returning results — as well as for +adding, altering, and deleting data. + +<p> +It's an interface that clients use indirectly, most generally through +{@link android.content.ContentResolver} objects. You get a ContentResolver +by calling <code>{@link android.content.Context#getContentResolver +getContentResolver()}</code> from within the implementation of an Activity +or other application component: + +<pre>ContentResolver cr = getContentResolver();</pre> + +<p> +You can then use the ContentResolver's methods to interact with whatever +content providers you're interested in. + +<p> +When a query is initiated, the Android system identifies the content provider +that's the target of the query and makes sure that it is up and running. +The system instantiates all ContentProvider objects; you never need to do it +on your own. In fact, you never deal directly with ContentProvider objects +at all. Typically, there's just a single instance of each type of +ContentProvider. But it can communicate with multiple ContentResolver objects +in different applications and processes. The interaction between processes is +handled by the ContentResolver and ContentProvider classes. + + +<h3>The data model</h3> + +<p> +Content providers expose their data as a simple table on a database model, +where each row is a record and each column is data of a particular type +and meaning. For example, information about people and their phone numbers +might be exposed as follows: + +<table> + <tr> + <th scope="col">_ID</th> + <th scope="col">NUMBER</th> + <th scope="col">NUMBER_KEY</th> + <th scope="col">LABEL</th> + <th scope="col">NAME</th> + <th scope="col">TYPE</th> + </tr> + <tr> + <td>13</td> + <td>(425) 555 6677</td> + <td>425 555 6677</td> + <td>Kirkland office</td> + <td>Bully Pulpit</td> + <td>{@code TYPE_WORK}</td> + </tr> + <tr> + <td>44</td> + <td>(212) 555-1234</td> + <td>212 555 1234</td> + <td>NY apartment</td> + <td>Alan Vain</td> + <td>{@code TYPE_HOME}</td> + </tr> + <tr> + <td>45</td> + <td>(212) 555-6657</td> + <td>212 555 6657</td> + <td>Downtown office</td> + <td>Alan Vain</td> + <td>{@code TYPE_MOBILE}</td> + </tr> + <tr> + <td>53</td> + <td>201.555.4433</td> + <td>201 555 4433</td> + <td>Love Nest</td> + <td>Rex Cars</td> + <td>{@code TYPE_HOME}</td> + </tr> +</table> + +<p> +Every record includes a numeric {@code _ID} field that uniquely identifies +the record within the table. IDs can be used to match records in related +tables — for example, to find a person's phone number in one table +and pictures of that person in another. + +<p> +A query returns a {@link android.database.Cursor} object that can move from +record to record and column to column to read the contents of each field. +It has specialized methods for reading each type of data. So, to read a field, +you must know what type of data the field contains. (There's more on query +results and Cursor objects later.) + + +<h3>URIs</h3><a name="uri"></a> + +<p> +Each content provider exposes a public URI (wrapped as a {@link android.net.Uri} +object) that uniquely identifies its data set. A content provider that controls +multiple data sets (multiple tables) exposes a separate URI for each one. All +URIs for providers begin with the string "{@code content://}". The {@code content:} +scheme identifies the data as being controlled by a content provider. + +<p> +If you're defining a content provider, it's a good idea to also define a +constant for its URI, to simplify client code and make future updates cleaner. +Android defines {@code CONTENT_URI} constants for all the providers that come +with the platform. For example, the URI for the table that matches +phone numbers to people and the URI for the table that holds pictures of +people (both controlled by the Contacts content provider) are: + +<p> +<dl><dd>{@code android.provider.Contacts.Phones.CONTENT_URI} +<br/>{@code android.provider.Contacts.Photos.CONTENT_URI}</dd></dl> + +<p> +Similarly, the URIs for the table of recent phone calls and the table +of calendar entries are: + +<p> +<dl><dd>{@code android.provider.CallLog.Calls.CONTENT_URI} +<br/>{@code android.provider.Calendar.CONTENT_URI}</dd></dl> + +<p> +The URI constant is used in all interactions with the content provider. +Every {@link android.content.ContentResolver} method takes the URI +as its first argument. It's what identifies which provider the ContentResolver +should talk to and which table of the provider is being targeted. + + +<h2>Querying a Content Provider<a name="querying"></a></h2> + +<p> +You need three pieces of information to query a content provider: +<ul> +<li>The URI that identifies the provider +<li>The names of the data fields you want to receive +<li>The data types for those fields +</ul> + +<p> +If you're querying a particular record, you also need the ID for that record. + + +<h3>Making the query</h3> + +<p> +To query a content provider, you can use either the +<code>{@link android.content.ContentResolver#query ContentResolver.query()}</code> +method or the <code>{@link android.app.Activity#managedQuery +Activity.managedQuery()}</code> method. +Both methods take the same set of arguments, and both return a +Cursor object. However, {@code managedQuery()} +causes the activity to manage the life cycle of the Cursor. A managed Cursor +handles all of the niceties, such as unloading itself when the activity pauses, +and requerying itself when the activity restarts. You can ask an Activity to +begin managing an unmanaged Cursor object for you by calling +<code>{@link android.app.Activity#startManagingCursor +Activity.startManagingCursor()}</code>. + +<p> +The first argument to either <code>{@link android.content.ContentResolver#query query()}</code> +or <code>{@link android.app.Activity#managedQuery managedQuery()}</code> is the provider URI +— the {@code CONTENT_URI} constant that identifies a particular +ContentProvider and data set (see <a href="#uri">URIs</a> earlier). + +<p> +To restrict a query to just one record, you can append the {@code _ID} value for +that record to the URI — that is, place a string matching the ID as the +last segment of the path part of the URI. For example, if the ID is 23, +the URI would be: + +<dl><dd>{@code content://. . . ./23}</dd></dl> + +<p> +There are some helper methods, particularly +<code>{@link android.content.ContentUris#withAppendedId +ContentUris.withAppendedId()}</code> and <code>{@link +android.net.Uri#withAppendedPath Uri.withAppendedPath()}</code>, +that make it easy to append an ID to a URI. Both are static methods that return +a Uri object with the ID added. So, for example, if you were looking for record +23 in the database of people contacts, you might construct a query as follows: + +<pre> +import android.provider.Contacts.People; +import android.content.ContentUris; +import android.net.Uri; +import android.database.Cursor; + +// Use the ContentUris method to produce the base URI for the contact with _ID == 23. +Uri myPerson = ContentUris.withAppendedId(People.CONTENT_URI, 23); + +// Alternatively, use the Uri method to produce the base URI. +// It takes a string rather than an integer. +Uri myPerson = Uri.withAppendedPath(People.CONTENT_URI, "23"); + +// Then query for this specific record: +Cursor cur = managedQuery(myPerson, null, null, null, null); +</pre> + +<p> +The other arguments to the <code>{@link android.content.ContentResolver#query query()}</code> +and <code>{@link android.app.Activity#managedQuery managedQuery()}</code> methods delimit +the query in more detail. They are: + +<ul> +<p><li>The names of the data columns that should be returned. A {@code null} +value returns all columns. Otherwise, only columns that are listed by name +are returned. All the content providers that come with the platform define +constants for their columns. For example, the +{@link android.provider.Contacts.Phones android.provider.Contacts.Phones} class +defines constants for the names of the columns in the phone table illustrated +earlier &mdash {@code _ID}, {@code NUMBER}, {@code NUMBER_KEY}, {@code NAME}, +and so on. + +<p><li>A filter detailing which rows to return, formatted as an SQL {@code WHERE} +clause (excluding the {@code WHERE} itself). A {@code null} value returns +all rows (unless the URI limits the query to a single record). + +<p><li>Selection arguments. + +<p><li>A sorting order for the rows that are returned, formatted as an SQL +{@code ORDER BY} clause (excluding the {@code ORDER BY} itself). A {@code null} value +returns the records in the default order for the table, which may be +unordered. +</ul> + +<p> +Let's look at an example query to retrieve a list of contact names and their +primary phone numbers: + +<pre> +import android.provider.Contacts.People; +import android.database.Cursor; + +// Form an array specifying which columns to return. +String[] projection = new String[] { + People._ID, + People._COUNT, + People.NAME, + People.NUMBER + }; + +// Get the base URI for the People table in the Contacts content provider. +Uri contacts = People.CONTENT_URI; + +// Make the query. +Cursor managedCursor = managedQuery(contacts, + projection, // Which columns to return + null, // Which rows to return (all rows) + null, // Selection arguments (none) + // Put the results in ascending order by name + People.NAME + " ASC"); +</pre> + +<p> +This query retrieves data from the People table of the Contacts content +provider. It gets the name, primary phone number, and unique record ID for +each contact. It also reports the number of records that are returned as +the {@code _COUNT} field of each record. + +<p> +The constants for the names of the columns are defined in various interfaces +— {@code _ID} and {@code _COUNT} in +{@link android.provider.BaseColumns BaseColumns}, {@code NAME} in {@link android.provider.Contacts.PeopleColumns PeopleColumns}, and {@code NUMBER} +in {@link android.provider.Contacts.PhonesColumns PhoneColumns}. The +{@link android.provider.Contacts.People Contacts.People} class implements +each of these interfaces, which is why the code example above could refer +to them using just the class name. + + +<h3>What a query returns</h3> + +<p> +A query returns a set of zero or more database records. The names of the +columns, their default order, and their data types are specific to each +content provider. +But every provider has an {@code _ID} column, which holds a unique numeric +ID for each record. Every provider can also report the number +of records returned as the {@code _COUNT} column; its value +is the same for all rows. + +<p> +Here is an example result set for the query in the previous section: + +<table border="1"> + <tbody> + <tr> + <th scope="col">_ID</th> + <th scope="col">_COUNT</th> + <th scope="col">NAME</th> + <th scope="col">NUMBER</th> + </tr> + <tr> + <td>44</td> + <td>3</td> + <td>Alan Vain</td> + <td>212 555 1234</td> + </tr> + <tr> + <td>13</td> + <td>3</td> + <td>Bully Pulpit</td> + <td>425 555 6677</td> + </tr> + <tr> + <td>53</td> + <td>3</td> + <td>Rex Cars</td> + <td>201 555 4433</td> + </tr> + </tbody> +</table> + +<p> +The retrieved data is exposed by a {@link android.database.Cursor Cursor} +object that can be used to iterate backward or forward through the result +set. You can use this object only to read the data. To add, modify, or +delete data, you must use a ContentResolver object. + + +<h3>Reading retrieved data</h3> + +<p> +The Cursor object returned by a query provides access to a recordset of +results. If you have queried for a specific record by ID, this set will +contain only one value. Otherwise, it can contain multiple values. +(If there are no matches, it can also be empty.) You +can read data from specific fields in the record, but you must know the +data type of the field, because the Cursor object has a separate method +for reading each type of data — such as <code>{@link +android.database.Cursor#getString getString()}</code>, <code>{@link +android.database.Cursor#getInt getInt()}</code>, and <code>{@link +android.database.Cursor#getFloat getFloat()}</code>. +(However, for most types, if you call the method for reading strings, +the Cursor object will give you the String representation of the data.) +The Cursor lets you request the column name from the index of the column, +or the index number from the column name. + +<p> +The following snippet demonstrates reading names and phone numbers from +the query illustrated earlier: + +<pre> +import android.provider.Contacts.People; + +private void getColumnData(Cursor cur){ + if (cur.moveToFirst()) { + + String name; + String phoneNumber; + int nameColumn = cur.getColumnIndex(People.NAME); + int phoneColumn = cur.getColumnIndex(People.NUMBER); + String imagePath; + + do { + // Get the field values + name = cur.getString(nameColumn); + phoneNumber = cur.getString(phoneColumn); + + // Do something with the values. + ... + + } while (cur.moveToNext()); + + } +} +</pre> + +<p> +If a query can return binary data, such as an image or sound, the data +may be directly entered in the table or the table entry for that data may be +a string specifying a {@code content:} URI that you can use to get the data. +In general, smaller amounts of data (say, from 20 to 50K or less) are most often +directly entered in the table and can be read by calling +<code>{@link android.database.Cursor#getBlob Cursor.getBlob()}</code>. +It returns a byte array. + +<p> +If the table entry is a {@code content:} URI, you should never try to open +and read the file directly (for one thing, permissions problems can make this +fail). Instead, you should call +<code>{@link android.content.ContentResolver#openInputStream +ContentResolver.openInputStream()}</code> to get an +{@link java.io.InputStream} object that you can use to read the data. + + +<h2>Modifying Data<a name="modifying"></a></h2> + +<p> +Data kept by a content provider can be modified by: + +<ul> +<p><li>Adding new records +<li>Adding new values to existing records +<li>Batch updating existing records +<li>Deleting records +</ul> + +<p> +All data modification is accomplished using {@link android.content.ContentResolver} +methods. Some content providers require a more restrictive permission for writing +data than they do for reading it. If you don't have permission to write to a +content provider, the ContentResolver methods will fail. + + +<h3>Adding records</h3> + +<p> +To add a new record to a content provider, first set up a map of key-value pairs +in a {@link android.content.ContentValues} object, where each key matches +the name of a column in the content provider and the value is the desired +value for the new record in that column. Then call <code>{@link +android.content.ContentResolver#insert ContentResolver.insert()}</code> and pass +it the URI of the provider and the ContentValues map. This method returns +the full URI of the new record — that is, the provider's URI with +the appended ID for the new record. You can then use this URI to query and +get a Cursor over the new record, and to further modify the record. +Here's an example: + +<pre> +import android.provider.Contacts.People; +import android.content.ContentResolver; +import android.content.ContentValues; + +ContentValues values = new ContentValues(); + +// Add Abraham Lincoln to contacts and make him a favorite. +values.put(People.NAME, "Abraham Lincoln"); +// 1 = the new contact is added to favorites +// 0 = the new contact is not added to favorites +values.put(People.STARRED, 1); + +Uri uri = getContentResolver().insert(People.CONTENT_URI, values); +</pre> + + +<h3>Adding new values</h3> + +<p> +Once a record exists, you can add new information to it or modify +existing information. For example, the next step in the example above would +be to add contact information — like a phone number or an IM or e-mail +address — to the new entry. + +<p> +The best way to add to a record in the Contacts database is to append +the name of the table where the new data goes to the URI for the +record, then use the amended URI to add the new data values. Each +Contacts table exposes a name for this purpose as a {@code +CONTENT_DIRECTORY} constant. The following code continues the previous +example by adding a phone number and e-mail address for the record +just created: + +<pre> +Uri phoneUri = null; +Uri emailUri = null; + +// Add a phone number for Abraham Lincoln. Begin with the URI for +// the new record just returned by insert(); it ends with the _ID +// of the new record, so we don't have to add the ID ourselves. +// Then append the designation for the phone table to this URI, +// and use the resulting URI to insert the phone number. +phoneUri = Uri.withAppendedPath(uri, People.Phones.CONTENT_DIRECTORY); + +values.clear(); +values.put(People.Phones.TYPE, People.Phones.TYPE_MOBILE); +values.put(People.Phones.NUMBER, "1233214567"); +getContentResolver().insert(phoneUri, values); + +// Now add an email address in the same way. +emailUri = Uri.withAppendedPath(uri, People.ContactMethods.CONTENT_DIRECTORY); + +values.clear(); +// ContactMethods.KIND is used to distinguish different kinds of +// contact methods, such as email, IM, etc. +values.put(People.ContactMethods.KIND, Contacts.KIND_EMAIL); +values.put(People.ContactMethods.DATA, "test@example.com"); +values.put(People.ContactMethods.TYPE, People.ContactMethods.TYPE_HOME); +getContentResolver().insert(emailUri, values); +</pre> + +<p> +You can place small amounts of binary data into a table by calling +the version of <code>{@link android.content.ContentValues#put +ContentValues.put()}</code> that takes a byte array. +That would work for a small icon-like image or a short audio clip, for example. +However, if you have a large amount of binary data to add, such as a photograph +or a complete song, put a {@code content:} URI for the data in the table and call +<code>{@link android.content.ContentResolver#openOutputStream +ContentResolver.openOutputStream()}</code> +with the file's URI. (That causes the content provider to store the data +in a file and record the file path in a hidden field of the record.) + +<p> +In this regard, the {@link android.provider.MediaStore} content +provider, the main provider that dispenses image, audio, and video +data, employs a special convention: The same URI that is used with +{@code query()} or {@code managedQuery()} to get meta-information +about the binary data (such as, the caption of a photograph or the +date it was taken) is used with {@code openInputStream()} +to get the data itself. Similarly, the same URI that is used with +{@code insert()} to put meta-information into a MediaStore record +is used with {@code openOutputStream()} to place the binary data there. +The following code snippet illustrates this convention: + +<pre> +import android.provider.MediaStore.Images.Media; +import android.content.ContentValues; +import java.io.OutputStream; + +// Save the name and description of an image in a ContentValues map. +ContentValues values = new ContentValues(3); +values.put(Media.DISPLAY_NAME, "road_trip_1"); +values.put(Media.DESCRIPTION, "Day 1, trip to Los Angeles"); +values.put(Media.MIME_TYPE, "image/jpeg"); + +// Add a new record without the bitmap, but with the values just set. +// insert() returns the URI of the new record. +Uri uri = getContentResolver().insert(Media.EXTERNAL_CONTENT_URI, values); + +// Now get a handle to the file for that record, and save the data into it. +// Here, sourceBitmap is a Bitmap object representing the file to save to the database. +try { + OutputStream outStream = getContentResolver().openOutputStream(uri); + sourceBitmap.compress(Bitmap.CompressFormat.JPEG, 50, outStream); + outStream.close(); +} catch (Exception e) { + Log.e(TAG, "exception while writing image", e); +} +</pre> + + +<h3>Batch updating records</h3> + +<p> +To batch update a group of records (for example, to change "NY" to "New York" +in all fields), call the <code>{@link +android.content.ContentResolver#update ContentResolver.update()}</code> +method with the columns and values to change. + + +<h3>Deleting a record <a name="deletingrecord"></a></h3> + +<p> +To delete a single record, call {<code>{@link +android.content.ContentResolver#delete ContentResolver.delete()}</code> +with the URI of a specific row. + +<p> +To delete multiple rows, call <code>{@link +android.content.ContentResolver#delete ContentResolver.delete()}</code> +with the URI of the type of record to delete (for example, {@code android.provider.Contacts.People.CONTENT_URI}) and an SQL {@code WHERE} +clause defining which rows to delete. (<i><b>Caution</b>: +Be sure to include a valid {@code WHERE} clause if you're deleting a general +type, or you risk deleting more records than you intended!</i>). + + +<h2>Creating a Content Provider<a name="creating"></a></h2> + +<p> +To create a content provider, you must: + +<ul> +<p><li>Set up a system for storing the data. Most content providers +store their data using Android's file storage methods or SQLite databases, +but you can store your data any way you want. Android provides the +{@link android.database.sqlite.SQLiteOpenHelper SQLiteOpenHelper} +class to help you create a database and {@link +android.database.sqlite.SQLiteDatabase SQLiteDatabase} to manage it. + +<p><li>Extend the {@link android.content.ContentProvider} class to provide +access to the data. + +<p><li>Declare the content provider in the manifest file for your +application (AndroidManifest.xml). +</ul> + +<p> +The following sections have notes on the last two of these tasks. + + +<h3>Extending the ContentProvider class</h3> + +<p> +You define a {@link android.content.ContentProvider} subclass to +expose your data to others using the conventions expected by +ContentResolver and Cursor objects. Principally, this means +implementing six abstract methods declared in the ContentProvider class: + +<dl><dd>{@code query()} +<br/>{@code insert()} +<br/>{@code update()} +<br/>{@code delete()} +<br/>{@code getType()} +<br/>{@code onCreate()}</dd></dl> + +<p> +The {@code query()} method must return a {@link android.database.Cursor} object +that can iterate over the requested data. Cursor itself is an interface, but +Android provides some ready-made Cursor objects that you can use. For example, +{@link android.database.sqlite.SQLiteCursor} can iterate over data stored in +an SQLite database. You get the Cursor object by calling any of the {@link +android.database.sqlite.SQLiteDatabase SQLiteDatabase} class's {@code query()} +methods. There are other Cursor implementations — such as {@link +android.database.MatrixCursor} — for data not stored in a database. + +<p> +As a courtesy, you might also want to call <code>{@link android.content.ContentResolver#notifyChange(android.net.Uri,android.database.ContentObserver) +ContentResolver.notifyChange()}</code> to notify listeners when there are +modifications to the data. + +<p> +Beyond defining the subclass itself, there are other steps you should take +to simplify the work of clients and make the class more accessible: + +<ul> +<p> +<li>Define a {@code public static final} {@link android.net.Uri} +named {@code CONTENT_URI}. This is the string that represents the full +{@code content:} URI that your content provider handles. You must define a +unique string for this value. The best solution is to use the fully-qualified +class name of the content provider (made lowercase). So, for example, the +URI for a TransportationProvider class could be defined as follows: + +<pre>public static final Uri CONTENT_URI = + Uri.parse("content://com.example.codelab.transporationprovider");</pre> + +<p> +If the provider has subtables, also define {@code CONTENT_URI} constants for +each of the subtables. These URIs should all have the same authority (since +that identifies the content provider), and be distinguished only by their paths. +For example: + +<dl><dd>{@code content://com.example.codelab.transporationprovider/train} +<br/>{@code content://com.example.codelab.transporationprovider/air/domestic} +<br/>{@code content://com.example.codelab.transporationprovider/air/international}</dd></dl> + +<p> +For an overview of {@code content:} URIs, see the <a href="#urisum">Content URI +Summary</a> at the end of this document. + +<p> +<li>Define the column names that the content provider will return to clients. +If you are using an underlying database, these column names are typically +identical to the SQL database column names they represent. Also define +{@code public static} String constants that clients can use to specify +the columns in queries and other instructions. + +<p> +Be sure to include an integer column named "{@code _id}" +(with the constant {@code _ID}) for +the IDs of the records. You should have this field whether or not you have +another field (such as a URL) that is also unique among all records. If +you're using the SQLite database, the {@code _ID} field should be the +following type: + +<dl><dd>{@code INTEGER PRIMARY KEY AUTOINCREMENT}</dd></dl> + +<p> +The {@code AUTOINCREMENT} descriptor is optional. But without it, SQLite +increments an ID counter field to the next number above the largest +existing number in the column. If you delete the last row, the next row added +will have the same ID as the deleted row. {@code AUTOINCREMENT} avoids this +by having SQLite increment to the next largest value whether deleted or not. + +<p> +<li>Carefully document the data type of each column. Clients need this +information to read the data. + +<p> +<li>If you are handling a new data type, you must define a new MIME type +to return in your implementation of <code>{@link +android.content.ContentProvider#getType ContentProvider.getType()}</code>. +The type depends in part on whether or not the {@code content:} URI submitted +to {@code getType()} limits the request to a specific record. There's one +form of the MIME type for a single record and another for multiple records. +Use the {@link android.net.Uri Uri} methods to help determine what is being +requested. Here is the general format for each type: + +<ul> +<p><li>For a single record: + +<dl><dd>{@code vnd.android.cursor.item/vnd.<em>yourcompanyname.contenttype</em}</dd></dl> + +<p>For example, a request for train record 122 such as the following URI, + +<dl><dd>{@code content://com.example.transportationprovider/trains/122}</dd></dl> + +<p>might return this MIME type: + +<dl><dd>{@code vnd.android.cursor.item/vnd.example.rail}</dd></dl>. + +<p> +<li>For multiple records: + +<dl><dd>{@code vnd.android.cursor.dir/vnd.<em>yourcompanyname.contenttype</em>}</dd></dl> + +<p>For example, a request for all train records like the following URI, + +<dl><dd>{@code content://com.example.transportationprovider/trains}</dd></dl> + +<p>might return this MIME type + +<dl><dd>{@code vnd.android.cursor.dir/vnd.example.rail}</dd></dl> +</ul> + +<p> +<li>If you are exposing byte data that's too big to put in the table itself +— such as a large bitmap file — the field that exposes the +data to clients should actually contain a {@code content:} URI string. +This is the field that gives clients access to the data file. The record +should also have another field, named "{@code _data}" that lists the exact file +path on the device for that file. This field is not intended to be read by +the client, but by the ContentResolver. The client will call <code>{@link +android.content.ContentResolver#openInputStream ContentResolver.openInputStream()}</code> +on the user-facing field holding the URI for the item. The ContentResolver +will request the "{@code _data}" field for that record, and because +it has higher permissions than a client, it should be able to access +that file directly and return a read wrapper for the file to the client. + +</ul> + +<p> +For an example of a private content provider implementation, see the +NodePadProvider class in the notepad sample application that ships with the SDK. + + +<h3>Declaring the content provider</h3> + +<p> +To let the Android system know about the content provider you've developed, +declare it with a {@code <provider>} element in the application's +AndroidManifest.xml file. Content providers that are not declared in the +manifest are not visible to the Android system + +<p> +The {@code name} attribute is the fully qualified name of the ContentProvider +subclass. The {@code authorities} attribute is the authority part of the +{@code content:} URI that identifies the provider. +For example if the ContentProvider subclass is AutoInfoProvider, the +{@code <provider>} element might look like this: + +<pre> +<provider name="com.example.autos.AutoInfoProvider" + authorities="com.example.autos.autoinfoprovider" + . . . /> +</provider> +</pre> + +<p> +Note that the {@code authorities} attribute omits the path part of a +{@code content:} URI. For example, if AutoInfoProvider controlled subtables +for different types of autos or different manufacturers, + +<dl><dd>{@code content://com.example.autos.autoinfoprovider/honda} +<br/>{@code content://com.example.autos.autoinfoprovider/gm/compact} +<br/>{@code content://com.example.autos.autoinfoprovider/gm/suv}</dd></dl> + +<p> +those paths would not be declared in the manifest. The authority +identifies the provider; your provider can interpret the path part of the +URI in any way you choose. + +<p> +Other {@code <provider>} attributes can set permissions to read and +write data, provide for an icon and text that can be displayed to users, +enable and disable the provider, and so on. Set the {@code multiprocess} +attribute to "{@code true}" if data does not need to be synchronized between +multiple running versions of the content provider. This permits an instance +of the provider to be created in each client process, eliminating the need +to perform IPC. + + +<h2>Content URI Summary</h2><a name="urisum"></a> + +<p> +Here is a recap of the important parts of a content URI: + +<p> +<img src="../../images/content_uri.png" alt="Elements of a content URI" +height="80" width="528"> + +<ol type="A"> +<p><li>Standard prefix indicating that the data is controlled by a +content provider. It's never modified. </li> + +<p><li>The authority part of the URI; it identifies the content provider. +For third-party applications, this should be a fully-qualified class name +(reduced to lowercase) to ensure uniqueness. The authority is declared in +the {@code <provider>} element's {@code authorities} attribute: + +<pre><provider name=".TransportationProvider" + authorities="com.example.transportationprovider" + . . . ></pre> + +<p><li>The path that the content provider uses to determine what kind of data is +being requested. This can be zero or more segments long. If the content provider +exposes only one type of data (only trains, for example), it can be absent. +If the provider exposes several types, including subtypes, it can be several +segments long — for example, "{@code land/bus}", "{@code land/train}", +"{@code sea/ship}", and "{@code sea/submarine}" to give four possibilities. + +<p><li>The ID of the specific record being requested, if any. This is the +{@code _ID} value of the requested record. If the request is not limited to +a single record, this segment and the trailing slash are omitted: + +<dl><dd>{@code content://com.example.transportationprovider/trains}</dd></dl> +</ol> + + diff --git a/docs/html/guide/topics/resources/available-resources.jd b/docs/html/guide/topics/resources/available-resources.jd new file mode 100644 index 0000000..bfe360e --- /dev/null +++ b/docs/html/guide/topics/resources/available-resources.jd @@ -0,0 +1,1211 @@ +page.title=Available Resource Types +@jd:body + +<p>This page describes the different types of resources that you can +externalize from your code and package with your application. They fall into +the following groups:</p> +<ul> + <li><a href="#simplevalues">Simple Values</a></li> + <li><a href="#drawables">Drawables</a></li> + <li><a href="#animation">Animation</a></li> + <li><a href="#layoutresources">Layout</a></li> + <li><a href="#stylesandthemes">Styles and Themes</a></li> +</ul> + +<p>For more details on how to use resources in your application, please see the + <a href="{@docRoot}devel/resources-i18n.html">Resources and i18n</a> + documentation.</p> + +<a name="simplevalues" id="simplevalues"></a> +<h2>Simple Values</h2> + +<p>All simple resource values can be expressed as a string, using various +formats to unambiguously indicate the type of resource being created. For +this reason, these values can be defined both as standard resources +(under res/values), as well as direct values supplied for +mappings in <a href="#stylesandthemes">styles and themes</a>, and attributes in +XML files such as <a href="#layoutresources">layouts</a>.</p> + +<ul> + <li><a href="#colorvals">Colors</a></li> + <li><a href="#stringresources">Strings and Styled Text</a></li> + <li><a href="#dimension">Dimensions</a></li> +</ul> + + +<a name="colorvals" id="colorvals"></a> +<h3>Color Values</h3> +<p> + A color value specifies an RGB value with an alpha channel, which can + be used in various places such as specifying a solid color for a Drawable + or the color to use for text. A color value always begins with + a '#' character and then is followed by the alpha-red-green-blue information + in one of the following formats: +</p> +<ul> +<li> #RGB +<li> #ARGB +<li> #RRGGBB +<li> #AARRGGBB +</ul> +<p> + If you want to retrieve the color represented by a resource ID, you can call + the {@link android.content.res.Resources#getColor(int) Resources.getColor()} method. +</p> +<p> + <strong>Source file format:</strong> XML file requiring a + <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and + a root <code><resources></code> element containing one or more + <code><color></code> tags. +</p> +<p> + <strong>Resource source file location</strong>: res/values/<em>colors</em>.xml (file name is arbitrary) +</p> +<p> + <strong>Compiled resource datatype:</strong> Resource pointer to a Java int. +</p> +<p> + <strong>Resource reference name:</strong> +</p> +<ul> + <li> + <strong>Java</strong> <code>R.color.<em>some_name</em></code> + </li> + <li> + <strong>XML</strong> <code>@[<em>package</em>:]color/some_name</code> (where <em>some_name</em> is the <em>name</em> of a specific color) + </li> +</ul> +<p> + <strong>Syntax</strong> +</p> +<pre> +<color name=<em>color_name</em>><em>#color_value</em></color> +</pre> +<dl> + <dt> + <color> + </dt> + <dd> + Value is a color, using web-style syntax, as describe above. Has only one attribute: + <ul> + <li> + <em>name</em> - The name used in referring to this color. + </li> + </ul> + </dd> +</dl> +<p> + <strong>Example XML Declaration</strong> +</p> +<p> + The following code declares two colors, the first fully opaque, and the + second translucent. +</p> +<pre> +<resources> + <color name="opaque_red">#f00</color> + <color name="translucent_red">#80ff0000</color> +</resources> +</pre> +<p> + <strong>Example Code Use</strong> +</p> +<p> + Example Java code +</p> +<pre> +// Retrieve a color value. +int color = getResources.getColor(R.color.opaque_red); +</pre> +<p> + Example XML code +</p> +<pre> +<TextView android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:textAlign="center" + android:textColor="@color/translucent_red" + android:text="Some Text"/> +</pre> + +<a name="stringresources" id="stringresources"></a> +<h3>Strings and Styled Text</h3> +<p> + Strings, with optional <a href="#styledtext">simple formatting</a>, can be +stored and retrieved as resources. You can add formatting to your string by +using three standard HTML tags: <b>, <i>, and <u>. To +guarantee getting an unstyled string only (the raw text) call the +<code>toString()</code> method of the retrieved CharSequence object. +Methods that accept string resources should be able to process these styling +tags. +</p> +<p> + If you want to retrieve the String represented by a resource ID, you can call the {@link android.content.Context#getString(int) Context.getString()} method. +</p> +<p> + <strong>Note:</strong> If you use an apostrophe or a quote in your string, you must either escape it or enclose the whole string in the other kind of enclosing quotes: +</p> +<pre> +<string name="good_example">"This'll work"</string> +<string name="good_example_2">This\'ll also work</string> +<string name="bad_example">This won't work!</string> +<string name="bad_example_2">XML encodings won&apos;t work either!</string> +</pre> +<p> + <strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><string></code> tags. +</p> +<p> + <strong>Resource source file location</strong>: res/values/<em>strings</em>.xml (file name is arbitrary) +</p> +<p> + <strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence. +</p> +<p> + <strong>Resource reference name:</strong> +</p> +<ul> + <li> + <strong>Java</strong> <code>R.string.<em>some_name</em></code> + </li> + <li> + <strong>XML</strong> <code>@[<em>package</em>:]string/some_name</code> (where <em>some_name</em> is the <em>name</em> of a specific string) + </li> +</ul> +<p> + <strong>Syntax</strong> +</p> +<pre> +<string name=<em>string_name</em>><em>string_value</em></string> +</pre> +<dl> + <dt> + <string> + </dt> + <dd> + Value is a string, with optional styling tags. Has only one attribute: + <ul> + <li> + <em>name</em> - The name used in referring to this string. + </li> + </ul> + </dd> +</dl> +<p> + <strong>Example XML Declaration</strong> +</p> +<p> + The following declares two strings: the first — simple text with no + formatting (resulting in a CharSequence that is simply a String object) — the second includes formatting information in the string (resulting + in a CharSequence that is a complex data structure). If you are using the custom editor for string files in Eclipse, the HTML formatting tags will automatically be escaped and you will need to use {@link android.content.Context#getString(int) Context.getString()} and {@link android.text.Html#fromHtml} to retreive the resource and then convert it to formatted text. +</p> +<pre> +<resources> + <string name="simple_welcome_message">Welcome!</string> + <string name="styled_welcome_message">We are <b><i>so</i></b> glad to see you.</string> +</resources> +</pre> +<p> + <strong>Example Code Use</strong> +</p> +<p> + Example Java code +</p> +<pre> +// Assign a styled string resource to a TextView +// on the current screen. +CharSequence str = getString(R.string.styled_welcome_message); +TextView tv = (TextView)findViewByID(R.id.text); +tv.setText(str); +</pre> +<p> + Example XML code +</p> +<pre> +<TextView android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:textAlign="center" + android:text="@string/simple_welcome_message"/> +</pre> + +<a name="styledtext" id="styledtext"></a> +<h4>Using Styled Text as a Format String</h4> +<p> +Sometimes you may want to create a styled text resource that is also used as a +format string. This cannot be done directly because there is no way of passing +the styled text as the format string argument of String.format() +without stripping out the style information. The workaround is to store the +style tags as escaped HTML tags, and then convert the escaped HTML string into +a styled text after formatting has taken place. +</p> +<p> +To use styled text as a format string, do the following. +</p> +<ol> + <li>Store your styled text resource as an escaped string, so that the HTML tags in your text resource are not interpreted as if they were XML tags: +<pre> +<resources> + <string name="search_results_resultsTextFormat">%1$d results for &lt;b>&amp;quot;%2$s&amp;quot;&lt;/b></string> +</resources> +</pre> +<p> +In this example the format string has two arguments: <code>%1$d</code> is a decimal number, <code>%2$s</code> is a string. +</p> +</li> +<li> + Make sure any String arguments are properly escaped if they might contain '<' or '&' characters. +The {@link android.text.TextUtils#htmlEncode} method will do this: +<pre> +String escapedTitle = TextUtil.htmlEncode(title); +</pre> +</li> +<li> + Use String.format() to format the HTML text, then use {@link android.text.Html#fromHtml} to convert the HTML text into styled text: +<pre> +String resultsTextFormat = getContext().getResources().getString(R.string.search_results_resultsTextFormat); +String resultsText = String.format(resultsTextFormat, count, escapedTitle); +CharSequence styledResults = Html.fromHtml(resultsText); +</pre> +</li> +</ol> + +<a name="dimension" id="dimension"></a> +<h3>Dimension Values</h3> +<p>You can create common dimensions to use for various screen elements by +defining dimension values in XML. A dimension resource is a number followed by +a unit of measurement. For example: 10px, 2in, 5sp. Here are the units of +measurement supported by Android:</p> +<dl> + <dt>px</dt> + <dd>Pixels - corresponds to actual pixels on the screen.</dd> + + <dt>in</dt> + <dd>Inches - based on the physical size of the screen.</dd> + + <dt>mm</dt> + <dd>Millimeters - based on the physical size of the screen.</dd> + + <dt>pt</dt> + <dd>Points - 1/72 of an inch based on the physical size of the screen.</dd> + + <dt>dp</dt> + <dd>Density-independent Pixels - an abstract unit that is based on the + physical density of the screen. These units are relative to a 160 dpi + screen, so one dp is one pixel on a 160 dpi screen. The ratio of + dp-to-pixel will change with the screen density, but not necessarily + in direct proportion. <strong>Note:</strong> The compiler accepts both "dip" and "dp", though "dp" is more consistent with "sp".</dd> + + <dt>sp</dt> + <dd>Scale-independent Pixels - this is like the dp unit, but it is also + scaled by the user's font size preference. It is recommend you use this + unit when specifying font sizes, so they will be adjusted for both the + screen density and user's preference.</dd> +</dl> + +<p>Dimension values are not normally used as raw resources, but rather as +attribute values in XML files. You can, however, create plain resources +containing this data type.</p> + +<p><strong>Source file format:</strong> XML file requiring a <code><?xml +version="1.0" encoding="utf-8"?></code> declaration, and a root +<code><resources></code> element containing one or more +<code><dimen></code> tags.</p> + +<p><strong>Resource source file location</strong>: res/values/dimens.xml (File +name is arbitrary; standard practice is to put all dimensions in one file +devoted to dimensions.)</p> +<p><strong>Compiled resource datatype:</strong> Resource pointer to a +dimension.</p> +<p> + <strong>Resource reference name:</strong> +</p> +<ul> + <li> + <strong>Java</strong> <code>R.dimen.<em>some_name</em></code> + </li> + <li> + <strong>XML</strong> <code>@[<em>package</em>:]dimen/<em>some_name</em></code> (where <em>some_name</em> is the <em>name</em> of a specific <code><dimen></code> element) + </li> +</ul> +<p> + <strong>Syntax</strong> +</p> +<pre> +<dimen name=<em>dimen_name</em>><em>dimen_value</em></dimen> +</pre> +<dl> + <dt> + <dimen> + </dt> + <dd> + A valid dimension value. + <ul> + <li> + <em>name</em> - The name used in referring to this dimension. + </li> + </ul> + </dd> +</dl> +<p> + <strong>Example XML Declaration</strong> +</p> +<p> + The following code declares several dimension values. +</p> +<pre> +<resources> + <dimen name="one_pixel">1px</dimen> + <dimen name="double_density">2dp</dimen> + <dimen name="sixteen_sp">16sp</dimen> +</resources> +</pre> +<p> + <strong>Example Code Use</strong> +</p> +<p> + Example Java code: +</p> +<pre> +float dimen = Resources.getDimen(R.dimen.one_pixel); +</pre> +<p> + Example XML code: +</p> +<pre> +<TextView android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:textSize="@dimen/sixteen_sp"/> +</pre> + +<a name="drawables" id="drawables"></a> +<h2>Drawables</h2> + +<p>A {@link android.graphics.drawable.Drawable} is a type of resource that +you retrieve with {@link android.content.res.Resources#getDrawable +Resources.getDrawable()} and use to draw to the screen. There are a +number of drawable resources that can be created.</p> + +<ul> + <li><a href="#imagefileresources">Bitmap Drawables</a></li> + <li><a href="#colordrawableresources">Color Drawables</a></li> + <li><a href="#ninepatch">Nine Patch (Stretchable) Drawables</a></li> +</ul> + +<a name="imagefileresources" id="imagefileresources"></a> +<h3>Bitmap files</h3> +<p>Android supports bitmap resource files in a few different formats: png +(preferred), jpg (acceptable), gif (discouraged). The bitmap file itself is +compiled and referenced by the file name without the extension (so +res/drawable/my_picture.png would be referenced as R.drawable.my_picture).</p> + +<p> + <strong>Source file formats:</strong> png (preferred), jpg (acceptable), gif (discouraged). One resource per file. +</p> +<p> + <strong>Resource file location</strong>: res/drawable/<em>some_file</em>.png or <em>some_file</em>.jpg or <em>some_file</em>.gif. +</p> +<p> + <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.BitmapDrawable BitmapDrawable}. +</p> +<p> + <strong>Resource reference name:</strong> +</p> +<ul> + <li> + <strong>Java</strong> <code>R.drawable.<em>some_file</em></code> + </li> + <li> + <strong>XML</strong> <code>@[<em>package</em>:]drawable/<em>some_file</em></code> + </li> +</ul> +<p> + <strong>Example Code Use</strong> +</p> +<p> + The following Java snippet demonstrates loading an {@link android.widget.ImageView ImageView} object with a single bitmap from a list of bitmap resources. ImageView is a basic display rectangle for graphics (animations or still images). +</p> +<pre> +// Load an array with BitmapDrawable resources. +private Integer[] mThumbIds = { + R.drawable.sample_thumb_0, + R.drawable.sample_thumb_1, + R.drawable.sample_thumb_2, + R.drawable.sample_thumb_3, + R.drawable.sample_thumb_4 +}; + +// Load and return a view with an image. +public View getView(int position, ViewGroup parent) +{ + ImageView i = new ImageView(mContext); + i.setImageResource(mThumbIds[position]); + i.setAdjustViewBounds(true); + i.setLayoutParams(new Gallery.LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT)); + i.setBackground(android.R.drawable.picture_frame); + return i; +} +</pre> +<p> + This XML example demonstrates loading a bitmap file (chat_icon.png) in an ImageView. +</p> +<pre> +<ImageView id="@+id/icon" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:tint="#FF000000" + android:src="@drawable/chat_icon"/> +</pre> + +<a name="colordrawableresources" id="colordrawableresources"></a> +<h3>Color Drawables</h3> +<p>You can create a {@link android.graphics.drawable.PaintDrawable} object that is a rectangle of color, +with optionally rounded corners. This element can be defined in any of the +files inside res/values/.</p> +<p><strong>Source file format:</strong> XML file requiring a <code><?xml +version="1.0" encoding="utf-8"?></code> declaration, and a root +<code><resources></code> element containing one or more +<code><drawable></code> tags.</p> +<p> + <strong>Resource source file location</strong>: res/values/colors.xml (File name is arbitrary; standard practice is to put the PaintDrawable items in the file along with the <a href="{@docRoot}devel/resources-i18n.html#numericcolorresources">numeric color values</a>.) +</p> +<p> + <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.PaintDrawable}. +</p> +<p> + <strong>Resource reference name:</strong> +</p> +<ul> + <li> + <strong>Java</strong> <code>R.drawable.<em>some_name</em></code> + </li> + <li> + <strong>XML</strong> <code>@[<em>package</em>:]drawable/<em>some_name</em></code> (where <em>some_name</em> is the name of a specific resource) + </li> +</ul> +<p> + <strong>Syntax</strong> +</p> +<pre> +<drawable name=<em>color_name</em>><em>color_value</em></drawable> +</pre> +<dl> + <dt> + <drawable> + </dt> + <dd> + A valid <a href="#colorvals">color value</a>. + <ul> + <li> + <em>name</em> - The name used in referring to this drawable. + </li> + </ul> + </dd> +</dl> +<p> + <strong>Example XML Declaration</strong> +</p> +<p> + The following code declares several color drawables. +</p> +<pre> +<resources> + <drawable name="solid_red">#f00</drawable> + <drawable name="solid_blue">#0000ff</drawable> + <drawable name="solid_green">#f0f0</drawable> +</resources> +</pre> +<p> + <strong>Example Code Use</strong> +</p> +<p> + Example Java code +</p> +<pre> +// Assign a PaintDrawable as the background to +// a TextView on the current screen. +Drawable redDrawable = Resources.getDrawable(R.drawable.solid_red); +TextView tv = (TextView)findViewByID(R.id.text); +tv.setBackground(redDrawable); +</pre> +<p> + Example XML code +</p> +<pre> +<TextView android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:textAlign="center" + android:background="@drawable/solid_red"/> +</pre> + +<a name="ninepatch" id="ninepatch"></a> +<h3>Nine-Patch Stretchable Image</h3> +<p> + Android supports a stretchable bitmap image, called a + {@link android.graphics.NinePatch} graphic. This is a PNG image in which + you define stretchable sections that Android will resize to fit the object + at display time to accommodate variable sized sections, such as text strings. + You typically assign this resource to the View's background. An example use + of a stretchable image is the button backgrounds that Android uses; buttons + must stretch to accommodate strings of various lengths. +</p> +<p> + A NinePatch drawing is a standard PNG image that includes a 1 pixel wide + border. This border is used to define the stretchable and static areas of + the screen. You indicate a stretchable section by drawing one or more 1 pixel + wide black lines in the left or top part of this border. You can have as + many stretchable sections as you want. The relative size of the stretchable + sections stays the same, so the largest sections always remain the largest. +</p> +<p> + You can also define an optional drawable section of the image (effectively, + the padding lines) by drawing a line on the right and bottom lines. If you + do not draw these lines, the first top and left lines will be used. +</p> +<p> + If a View object sets this graphic as a background and then specifies the + View object's text, it will stretch itself so that all the text fits inside + the area designated by the right and bottom lines (if included). If the + padding lines are not included, Android uses the left and top lines to + define the writeable area. +</p> +<p>The <a href="{@docRoot}reference/draw9patch.html">Draw 9-patch</a> tool offers + an extremely handy way to create your NinePatch images, using a + WYSIWYG graphics editor. +</p> +<p> + Here is a sample NinePatch file used to define a button. +</p> +<p> + <img src="{@docRoot}images/ninepatch_raw.png" alt="Raw ninepatch file + showing the definition lines"> +</p> +<p> + This ninepatch uses one single stretchable area, and it also defines a drawable area. +</p> +<p> + <strong>Source file format:</strong> PNG — one resource per file +</p> +<p> + <strong>Resource source file location</strong>: res/drawable/<em>some_name</em>.9.png (must end in .9.png) +</p> +<p> + <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.NinePatchDrawable NinePatchDrawable}. +</p> +<p> + <strong>Resource reference name:</strong> +</p> +<ul> + <li> + <strong>Java</strong> <code>R.drawable.<em>some_file</em></code> + </li> + <li> + <strong>XML</strong> <code>@[<em>package</em>:]drawable.<em>some_file</em></code> + </li> +</ul> +<p> + <strong>Example XML Code</strong> +</p> +<p> + Note that the width and height are set to "wrap_content" to make the button fit neatly around the text. +</p> +<pre> +<Button id="@+id/tiny" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:layout_alignParentTop="true" + android:layout_centerInParent="true" + android:text="Tiny" + android:textSize="8sp" + android:background="@drawable/my_button_background"/> + +<Button id="@+id/big" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:layout_alignParentBottom="true" + android:layout_centerInParent="true" + android:text="Biiiiiiig text!" + android:textSize="30sp" + android:background="@drawable/my_button_background"/> +</pre> +<p> + Here are the two buttons based on this XML and the NinePatch graphic shown above. Notice how the width and height of the button varies with the text, and the background image stretches to accommodate it. +</p> +<p> + <img src="{@docRoot}images/ninepatch_examples.png" alt="Two buttons based on the NinePatch button background"> +</p> + +<a name="animation" id="animation"></a> +<h2>Animation</h2> +<a name="tweenedanimation" id="tweenedanimation"></a> +<h3> + Tweened Animation +</h3> +<p> + Android can perform simple animation on a graphic, or a series of graphics. These include rotations, fading, moving, and stretching. +</p> +<p> + <strong>Source file format:</strong> XML file, one resource per file, one root tag with no <code><?xml></code> declaration +</p> +<p> + <strong>Resource file location</strong>: res/anim/<em>some_file</em>.xml +</p> +<p> + <strong>Compiled resource datatype:</strong> Resource pointer to an {@link android.view.animation.Animation}. +</p> +<p> + <strong>Resource reference name:</strong> +</p> +<ul> + <li> + <strong>Java</strong> <code>R.anim.<em>some_file</em></code> + </li> + <li> + <strong>XML</strong> <code>@[<em>package</em>:]anim/<em>some_file</em></code> + </li> +</ul> +<p> + <strong>Syntax</strong> +</p> +<p> + The file must have a single root element: this will be either a single <code><alpha></code>, <code><scale></code>, <code><translate></code>, <code><rotate></code>, interpolator element, or <code><set></code> element that holds groups of these elements (which may include another <code><set></code>). By default, all elements are applied simultaneously. To have them occur sequentially, you must specify the <code>startOffset</code> attribute, as shown in the example code. +</p> +<pre> +<set android:shareInterpolator=boolean> // Only required if multiple tags are used. + <alpha android:fromAlpha=float + android:toAlpha=float > | + <scale android:fromXScale=float + android:toXScale=float + android:fromYScale=float + android:toYScale=float + android:pivotX=string + android:pivotY=string> | + <translate android:fromX=string + android:toX=string + android:fromY=string + android:toY=string> | + <rotate android:fromDegrees=float + android:toDegrees=float + android:pivotX=string + android:pivotY=string /> | + <<em>interpolator tag</em>> + <set> +</set> +</pre> +<p> + <strong>Elements and Attributes</strong> +</p> +<dl> + <dt> + <set> + </dt> + <dd> + The outermost tag, which can recursively hold itself or other animations. You can include as many child elements of the same or different types as you like. Supports the following attribute: + <ul> + <li> + <em>shareInterpolator</em> - Whether to share the same Interpolator among all immediate child elements. + </li> + </ul> + </dd> + <dt> + <alpha> + </dt> + <dd> + A fading animation, compiled to {@link android.view.animation.AlphaAnimation}. Supports the following attributes: + <ul> + <li> + <em>fromAlpha</em> - 0.0 to 1.0, where 0.0 is transparent. + </li> + <li> + <em>toAlpha</em> - 0.0 to 1.0, where 0.0 is transparent. + </li> + </ul> + </dd> + <dt> + <scale> + </dt> + <dd> + A resizing animation, compiled to {@link android.view.animation.ScaleAnimation}. You can specify what is the center point of the image (the pinned center), from which it grows outward (or inward), by specifying pivotX and pivotY. So, for example, if these were 0, 0 (top left corner), all growth would be down and to the right. <code>scale</code> supports the following attributes: + <ul> + <li> + <em>fromXScale</em> - Starting X size, where 1.0 is no change. + </li> + <li> + <em>toXScale</em> - Ending X size, where 1.0 is no change. + </li> + <li> + <em>fromYScale</em> - Starting Y size, where 1.0 is no change. + </li> + <li> + <em>toYScale</em> - Ending Y size, where 1.0 is no change. + </li> + <li> + <em>pivotX</em> - The X coordinate of the pinned center. + </li> + <li> + <em>pivotY</em> - The Y coordinate of the pinned center. + </li> + </ul> + </dd> + <dt> + <translate> + </dt> + <dd> + A motion animation that moves a visual element within its parent element. It is equivalent to {@link android.view.animation.TranslateAnimation}. +Supports the following attributes in any of the following three formats: values from -100 to 100, ending with "%", indicating a percentage relative to itself; values from -100 to 100, ending in "%p", indicating a percentage relative to its parent; a float with no suffix, indicating an absolute value. + <ul> + <li> + <em>fromXDelta</em> - Starting X location. + </li> + <li> + <em>toXDelta</em> - Ending X location. + </li> + <li> + <em>fromYDelta</em> - Starting Y location. + </li> + <li> + <em>toYDelta</em> - Ending Y location. + </li> + </ul> + </dd> + <dt> + <rotate> + </dt> + <dd> + A rotation animation, compiled to {@link android.view.animation.RotateAnimation}. Supports the following attributes: + <ul> + <li> + <em>fromDegrees</em> - Starting rotation, in degrees. + </li> + <li> + <em>toDegrees</em> - Ending rotation, in degrees. + </li> + <li> + <em>pivotX</em> - The X coordinate of the center of rotation, in pixels, where (0,0) is the top left corner. + </li> + <li> + <em>pivotY</em> - The Y coordinate of the center of rotation, in pixels, where (0,0) is the top left corner. + </li> + </ul> + </dd> + <dt> + <em><interpolator tag></em> + </dt> + <dd> + You can also use any of the interpolator subclass elements defined in {@link android.R.styleable}. Examples include <CycleInterpolator>, <EaseInInterpolator>, and <EaseOutInterpolator>. These objects define a velocity curve that describes how quickly a visual action takes place on a timeline (fast at first and slow later, slow at first and gradually faster, and so on). + </dd> +</dl> +<p> + Note that alpha, scale, rotate, translate all support the following attributes from the base animation class, BaseAnimation: +</p> +<dl> + <dt> + <em>duration</em> + </dt> + <dd> + Duration, in milliseconds, for this effect. + </dd> + <dt> + <em>startOffset</em> + </dt> + <dd> + Offset start time for this effect, in milliseconds. + </dd> + <dt> + <em>fillBefore</em> + </dt> + <dd> + Equivalent to {@link android.view.animation.Animation#setFillBefore animation.Animation.setFillBefore()}. + </dd> + <dt> + <em>fillAfter</em> + </dt> + <dd> + Equivalent to {@link android.view.animation.Animation#setFillAfter animation.Animation.setFillAfter()}. + </dd> + <dt> + <em>interpolator</em> + </dt> + <dd> + You can optionally set an interpolator for each element to determine how quickly or slowly it performs its effect over time. For example, slow at the beginning and faster at the end for EaseInInterpolator, and the reverse for EaseOutInterpolator. A list of interpolators is given in {@link android.R.anim}. To specify these, use the syntax @android:anim/<em>interpolatorName</em>. + </dd> +</dl> +<p> + <strong>Example XML Declaration</strong> +</p> +<p> + The following XML from the ApiDemos application is used to stretch, then simultaneously spin and rotate a block of text. +</p> +<pre> +<set android:shareInterpolator="false"> + <scale + android:interpolator="@android:anim/ease_in_out_interpolator" + android:fromXScale="1.0" + android:toXScale="1.4" + android:fromYScale="1.0" + android:toYScale="0.6" + android:pivotX="50%" + android:pivotY="50%" + android:fillAfter="false" + android:duration="700" /> + <set android:interpolator="@android:anim/ease_in_interpolator"> + <scale + android:fromXScale="1.4" + android:toXScale="0.0" + android:fromYScale="0.6" + android:toYScale="0.0" + android:pivotX="50%" + android:pivotY="50%" + android:startOffset="700" + android:duration="400" + android:fillBefore="false" /> + <rotate + android:fromDegrees="0" + android:toDegrees="-45" + android:toYScale="0.0" + android:pivotX="50%" + android:pivotY="50%" + android:startOffset="700" + android:duration="400" /> + </set> +</set> +</pre> +<p> + The following Java code loads animations called res/anim/hyperspace_in.xml and res/anim/hyperspace_out.xml into a {@link android.widget.ViewFlipper}. +</p> +<pre> +mFlipper.setInAnimation(AnimationUtils.loadAnimation(this, R.anim.hyperspace_in)); +mFlipper.setOutAnimation(AnimationUtils.loadAnimation(this, R.anim.hyperspace_out)); +</pre> + +<a name="layoutresources" id="layoutresources"></a> +<h2>Layout</h2> +<p> + Android lets you specify screen layouts using XML elements inside an XML file, similar to designing screen layout for a webpage in an HTML file. Each file contains a whole screen or a part of a screen, and is compiled into a View resource that can be passed in to {@link android.app.Activity#setContentView(int) Activity.setContentView} or used as a reference by other layout resource elements. Files are saved in the res/layout/ folder of your project, and compiled by the Android resource compiler aapt. +</p> +<p> + Every layout XML file must evaluate to a single root element. First we'll describe how to use the standard XML tags understood by Android as it is shipped, and then we'll give a little information on how you can define your own custom XML elements for custom View objects. See <a href="{@docRoot}devel/implementing-ui.html">Implementing a User Interface</a> for details about the visual elements that make up a screen. +</p> +<p> + The root element must have the Android namespace "http://schemas.android.com/apk/res/android" defined in the root element +</p> +<p> + <strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and a root element of one of the supported XML layout elements. +</p> +<p> + <strong>Resource file location</strong>: res/layout/<em>some_file</em>.xml. +</p> +<p> + <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.View} (or subclass) resource. +</p> +<p> + <strong>Resource reference name:</strong> +</p> +<ul> + <li> + <strong>Java</strong> <code>R.drawable.<em>some_file</em></code> + </li> + <li> + <strong>XML</strong> <code>@[<em>package</em>:]layout/<em>some_file</em></code> + </li> +</ul> +<p> + <strong>Syntax</strong> +</p> +<pre> +<<em>ViewGroupClass</em> xmlns:android="http://schemas.android.com/apk/res/android" + id="@+id/<em>string_name</em>" (attributes)> + <<em>widget</em> or other nested <em>ViewGroupClass</em>>+ + <requestFocus/>(0 or 1 per layout file, assigned to any element) +</<em>ViewGroupClass</em>> +</pre> +<dl> + <dt> + <<em>ViewGroupClass</em>> + </dt> + <dd> + <p>The file must have a single root element. This can be a ViewGroup class that contains other elements, or a widget (or custom item) if it's only one object. By default, you can use any (case-sensitive) Android {@link android.widget widget} or {@link android.view.ViewGroup ViewGroup} class name as an element. These elements support attributes that apply to the underlying class, but the naming is not as clear. How to discover what attributes are supported for what tags is discussed below. You should not assume that any nesting is valid (for example you cannot enclose <code><TextView></code> elements inside a <code><ListLayout></code>).</p> + <p>If a class derives from another class, the XML element inherits all the attributes from the element that it "derives" from. So, for example, <code><EditText></code> is the corresponding XML element for the EditText class. It exposes its own unique attributes (<code>EditText_numeric</code>), as well as all attributes supported by <code><TextView></code> and <code><View></code>. For the <em>id</em> attribute of a tag in XML, you should use a special syntax: "@+id/<em>somestringvalue</em>". The "@+" syntax creates a resource number in the R.id class, if one doesn't exist, or uses it, if it does exist. When declaring an ID value for an XML tag, use this syntax. Example: <code><TextView id="@+id/nameTextbox"/></code>, and refer to it this way in Java: <code>findViewById(R.id.nameTextbox)</code>. All elements support the following values:</p> + <ul> + <li> + <em>id</em> - An ID value used to access this element in Java. Typically you will use the syntax @+id/<em>string_name</em> to generate an ID for you in the id.xml file if you haven't created one yourself. + </li> + <li> + <code>xmlns:android="http://schemas.android.com/apk/res/android"</code> - <em><strong>Required for the root element only.</strong></em> + </li> + </ul> + </dd> + <dt> + <requestFocus> + </dt> + <dd> + Any element representing a View object can include this empty element, which gives it's parent tag initial focus on the screen. You can have only one of these elements per file. + </dd> +</dl> +<p> + <strong>What Attributes Are Supported for What Elements?</strong> +</p> +<p> + Android uses the {@link android.view.LayoutInflater} class at run time to load an XML layout resource and translate it into visual elements. By default, all widget class names are supported directly as tags, but a full list of supported tags and attributes is listed in the {@link android.R.styleable} reference page. However, the attribute names are somewhat obscure. If an underscore appears in the name, this indicates that it is an attribute — typically of the element before the underscore. So, for example, <code>EditText_autoText</code> means that the <code><EditText></code> tag supports an attribute <em>autoText</em>. When you actually use the attribute in that element, use only the portion after the last underscore, and prefix the attribute with the prefix "<code>android:</code>". So, for example, if {@link android.R.styleable} lists the following values: +</p> +<ul> + <li> + <code>TextView</code> + </li> + <li> + <code>TextView_lines</code> + </li> + <li> + <code>TextView_maxlines</code> + </li> +</ul> +<p> + You could create an element like this: +</p> +<pre> +<TextView android:lines="10" android:maxlines="20"/> +</pre> +<p> + This would create a {@link android.widget.TextView} object and set its lines and maxlines properties. +</p> +<p> + Attributes come from three sources: +</p> +<ul> + <li> + <strong>Attributes exposed directly by the element.</strong> For example, <code>TextView</code> supports <code>TextView_text</code>, as discussed above. + </li> + <li> + <strong>Attributes exposed by all the superclasses of that element.</strong> For example, the TextView class extends the View class, so the <code><TextView></code> element supports all the attributes that the <code><View></code> element exposes — a long list, including <code>View_paddingBottom</code> and <code>View_scrollbars</code>. These too are used without the class name: <code><TextView android:paddingBottom="20" android:scrollbars="horizontal" /></code>. + </li> + <li> + <strong>Attributes of the object's {@link android.view.ViewGroup.LayoutParams} subclass.</strong> All View objects support a LayoutParams member (see <a href="{@docRoot}devel/ui/layout.html">LayoutParams in Implementing a UI</a>). To set properties on an element's LayoutParams member, the attribute to use is "android:layout_<em>layoutParamsProperty</em>". For example: <code>android:layout_gravity</code> for an object wrapped by a <code><LinearLayout></code> element. Remember that each LayoutParams subclass also supports inherited attributes. Attributes exposed by each subclass are given in the format <em>someLayoutParamsSubclass</em>_Layout_layout_<em>someproperty</em>. This defines an attribute "android:layout_<em>someproperty</em>". Here is an example of how Android documentation lists the properties of the {@link android.widget.LinearLayout.LayoutParams LinearLayout.LayoutParams} class: + </li> +</ul> +<ul> + <li>LinearLayout_Layout // The actual object — not used. + </li> + <li>LinearLayout_Layout_layout_gravity // Exposes a <code>gravity</code> attribute + </li> + <li>LinearLayout_Layout_layout_height // Exposes a <code>height</code> attribute + </li> + <li>LinearLayout_Layout_layout_weight // Exposes a <code>weight</code> attribute + </li> + <li>LinearLayout_Layout_layout_width // Exposes a <code>width</code> attribute + </li> +</ul> +<p> + Here is an example that sets some of these values on a few objects, including direct attributes, inherited attributes, and LayoutParams attributes: +</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<!-- res/main_screen.xml --> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:orientation="vertical" // The object's own orientation property + android:padding="4" // Inherited View property + android:gravity="center" // The object's own property + android:layout_width="fill_parent" // Parent object's LinearLayout.LayoutParams.width + android:layout_height="fill_parent"> // Parent object's LinearLayout.LayoutParams.height + + <TextView android:layout_width="fill_parent" // TextView.LayoutParams.width + android:layout_height="wrap_content" // TextView.LayoutParams.height + android:layout_weight="0" // TextView.LayoutParams.weight + android:paddingBottom="4" // TextView.paddingBottom + android:text="@string/redirect_getter"/> // TextView.text + + <EditText id="@+id/text" + android:layout_width="fill_parent" // EditText.LayoutParams.width + android:layout_height="wrap_content" // EditText.LayoutParams.height + android:layout_weight="0" // EditText.LinearLayoutParams.weight + android:paddingBottom="4"> // EditText.paddingBottom + <requestFocus /> + </EditText> + + <Button id="@+id/apply" + android:layout_width="wrap_content" // Button.LayoutParams.width + android:layout_height="wrap_content" // Button.LayoutParams.height + android:text="@string/apply" /> // TextView.text +</LinearLayout> +</pre> +<p> + <strong>Example Code Use</strong> +</p> +<p> + The most common use is to load the XML file (located at <em>res/main_screen.xml</em>) and use it as the current screen, as shown here with the preceding file: +</p> +<pre> +setContentView(R.layout.main_screen); +</pre> +<p> + However, layout elements can also represent repeating elements used as templates. +</p> +<a name="customresources" id="customresources"></a> +<h3>Custom Layout Resources</h3> +<p> + You can define custom elements to use in layout resources. These custom elements can then be used the same as any Android layout elements: that is, you can use them and specify their attributes in other resources. The ApiDemos sample application has an example of creating a custom layout XML tag, LabelView. To create a custom element, you will need the following files: +</p> +<ul> + <li> + <strong>Java implementation file</strong> - The implementation file. The class must extend {@link android.view.View View} or a subclass. See LabelView.java in ApiDemos. + </li> + <li> + <strong>res/values/attrs.xml</strong> - Defines the XML element, and the attributes that it supports, for clients to use to instantiate your object in their layout XML file. Define your element in a <code><declare-styleable id=<em>your_java_class_name</em>></code>. See res/layout/attrs.xml in ApiDemos. + </li> + <li> + <strong>res/layout/<em>your_class</em>.xml</strong> [<em>optional</em>] - An optional XML file to describe the layout of your object. This could also be done in Java. See custom_view_1.xml in ApiDemos. + </li> +</ul> +<p> + <strong>Source file format:</strong> XML file without an <code><?xml></code> declaration, and a <code><resources></code> root element containing one or more custom element tags. +</p> +<p> + <strong>Resource file location</strong>: res/values/<em>attrs</em>.xml (file name is arbitrary). +</p> +<p> + <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.View} (or subclass) resource. +</p> +<p> + <strong>Resource reference name:</strong> R.styleable.<em>some_file</em> (Java). +</p> + +<a name="stylesandthemes" id="stylesandthemes"></a> +<h2>Styles and Themes</h2> +<p> + A <em>style</em> is one or more attributes applied to a single element (for example, 10 point red Arial font, applied to a TextView). A style is applied as an attribute to an element in a layout XML file. +</p> +<p> + A <em>theme</em> is one or more attributes applied to a whole screen — for example, you might apply the stock Android Theme.dialog theme to an activity designed to be a floating dialog box. A theme is assigned as an attribute to an Activity in the manifest file. +</p> +<p> + Both styles and themes are defined in a <style> block containing one or more string or numerical values (typically color values), or references to other resources (drawables and so on). These elements support inheritance, so you could have MyBaseTheme, MyBaseTheme.Fancy, MyBaseTheme.Small, and so on. +</p> +<p> + <strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><style></code> tags. +</p> +<p> + <strong>Resource source file location</strong>: res/values/styles.xml (file name is arbitrary). The file name is arbitrary, but standard practice is to put all styles into a file named styles.xml. +</p> +<p> + <strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence. +</p> +<p> + <strong>Resource reference name:</strong> +</p> +<ul> + <li> + <strong>Java</strong> <code>R.style.<em>styleID</em></code> for the whole style, <code>R.style.<em>styleID</em>.<em>itemID</em></code> for an individual setting + </li> + <li> + <strong>XML</strong> <code>@[<em>package</em>:]style/<em>styleID</em></code> for a whole style, <code>@[<em>package</em>:]style/<em>styleID</em>/<em>itemID</em></code> for an individual item. <strong>Note</strong>: to refer to a value in the <em>currently</em> applied theme, use "?" instead of "@" as described below (XML). + </li> +</ul> +<p> + <strong>Syntax</strong> +</p> +<pre> +<style name=<em>string</em> [parent=<em>string</em>] > + <item name=<em>string</em>><em>Hex value | string value | reference</em></item>+<em> +</em></style> +</pre> +<dl> + <dt> + <style> + </dt> + <dd> + Holds one or more <item> elements, each describing one value. This style, which is a bundle of values, can be referred to as a <em>theme</em>. + <ul> + <li> + <em>name</em> - The name used in referring to this theme. + </li> + <li> + <em>parent</em> - An optional parent theme. All values from the specified theme will be inherited into this theme. Any values with identical names that you specify will override inherited values. The name must be qualified by the package, but you don't need the /style directive (for example, <code>android:Theme</code> for the base Android theme, or <code>MyTheme</code> for a theme defined in your package). + </li> + </ul> + </dd> + <dt> + <item> + </dt> + <dd> + A value to use in this theme. It can be a standard string, a hex color value, or a reference to any other resource type. + </dd> +</dl> +<p> + <strong>Example: Declaring a Style in XML</strong> +</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <style name="SpecialText"> + <item name="android:textSize">18sp</item> + <item name="android:textColor">#008</item> + </style> +</resources> +</pre> +<p> + <strong>Example: Referencing a Declared Style from an XML Resource</strong> +</p> +<p> + The following layout XML file applies the previously defined style to a single text box. +</p> +<pre> +<!-- MainPageLayout.xml --> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_height="fill_parent" + android:layout_width="fill_parent" + android:orientation="vertical" + android:scrollbars="vertical" + id="main_frame"> + <EditText id="@+id/text1" + style="@style/SpecialText" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:text="Hello, World!" /> +</LinearLayout> +</pre> + + +<p> + <strong>Example XML Declaration of a Theme</strong> +</p> +<p> + The following example defines a theme, "ThemeNew," which creates new theme items, + refers to some previously defined theme items (values beginning with '@'), + and refers to package resources (values beginning with '?'). +</p> +<pre> +<style name="ThemeNew"> + <item name="windowFrame">@drawable/screen_frame</item> + <item name="windowBackground">@drawable/screen_background_white</item> + <item name="panelForegroundColor">#FF000000</item> + <item name="panelBackgroundColor">#FFFFFFFF</item> + <item name="panelTextColor">?panelForegroundColor</item> + <item name="panelTextSize">14</item> + <item name="menuItemTextColor">?panelTextColor</item> + <item name="menuItemTextSize">?panelTextSize</item> +</style> +</pre> +<p> + Notice that, to reference a value from the currently loaded theme, we use + a question-mark (?) instead of the at-symbol (@), in the reference string. + You must refer to such a specific <code><item></code> by its name in + the currently loaded theme. This can be used in XML resources only. +</p> + +<p> + <strong>Example Code Use of a Theme</strong> +</p> +<p> + The following Java snippet demonstrates loading a style set (i.e., a theme). +</p> +<pre> +setTheme(R.style.ThemeNew); +</pre> +<p> + The following XML applies an Android theme to a whole file (in this case, the Android dialog theme, to make the screen a floating dialog screen). +</p> +<pre> +<!-- AndroidManifest.xml --> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.example.codelab.rssexample"> + <activity class="AddRssItem" android:label="@string/add_item_label" android:theme="@android:style/Theme.Dialog"/> +</manifest> +</pre> diff --git a/docs/html/guide/topics/resources/resources-i18n.jd b/docs/html/guide/topics/resources/resources-i18n.jd new file mode 100755 index 0000000..d3ddd23 --- /dev/null +++ b/docs/html/guide/topics/resources/resources-i18n.jd @@ -0,0 +1,699 @@ +page.title=Resources and i18n +@jd:body +<h1>Resources and Internationalization</h1> + +<p>Resources are external files (that is, non-code files) that are used by +your code and compiled into your application at build time. Android +supports a number of different kinds of resource files, including XML, +PNG, and JPEG files. The XML files have very different formats depending +on what they describe. This document describes what kinds of files are +supported, and the syntax or format of each.</p> +<p>Resources are externalized from source code, and XML files are compiled into +a binary, fast loading format for efficiency reasons. Strings, likewise are compressed +into a more efficient storage form. It is for these reasons that we have these +different resource types in the Android platform.</p> + +<p>This document contains the following sections:</p> + +<ul> + <li> <a href="#Resources">Resources</a> + <ul> + <li> <a href="#CreatingResources">Creating Resources</a></li> + <li> <a href="#UsingResources">Using Resources</a> + <ul> + <li><a href="#ResourcesInCode">Using Resources in Code</a></li> + <li> <a href="#ReferencesToResources">References to Resources</a></li> + <li> <a href="#ReferencesToThemeAttributes">References to Theme Attributes</a></li> + <li> <a href="#UsingSystemResources">Using System Resources</a></li> + </ul> + </li> + <li><a href="#AlternateResources">Alternate Resources</a></li> + <li><a href="{@docRoot}reference/available-resources.html"> + Resource Reference</a></li> + <li> <a href="#ResourcesTerminology">Terminology</a></li> + </ul> + </li> + <li><a href="#i18n">Internationalization (I18N)</a></li> +</ul> +<p>This is a fairly technically dense document, and together with the +<a href="{@docRoot}reference/available-resources.html">Resource Reference</a> +document, they cover a lot of information about resources. It is not necessary +to know this document by heart to use Android, but rather to know that the +information is here when you need it.</p> + +<a name="Resources"></a> +<h2>Resources</h2> + +<p>This topic includes a terminology list associated with resources, and a series + of examples of using resources in code. For a complete guide to the supported + Android resource types, see + <a href="{@docRoot}reference/available-resources.html">Resources</a>. + </p> +<p>The Android resource system keeps track of all non-code + assets associated with an application. You use the + {@link android.content.res.Resources Resources} class to access your + application's resources; the Resources instance associated with your + application can generally be found through + {@link android.content.Context#getResources Context.getResources()}.</p> +<p>An application's resources are compiled into the application +binary at build time for you by the build system. To use a resource, +you must install it correctly in the source tree and build your +application. As part of the build process, symbols for each +of the resources are generated that you can use in your source +code -- this allows the compiler to verify that your application code matches +up with the resources you defined.</p> + +<p>The rest of this section is organized as a tutorial on how to +use resources in an application.</p> + +<a name="CreatingResources" id="CreatingResources"></a> +<h2>Creating Resources</h2> + +<p>Android supports string, bitmap, and many other types of resource. The syntax and format +of each, and where they're stored, depends upon the type of object. In +general, though, you create resources from three types of files: XML files +(everything but bitmaps and raw), bitmap files(for images) and Raw files (anything +else, for example sound files, etc.). In fact, there are two different types of +XML file as well, those that get compiled as-is into the package, and those that +are used to generate resources by aapt. Here is a list of each +resource type, the format of the file, a description of the file, and details +of any XML files. </p> + +<p>You will create and store your resource files under the appropriate +subdirectory under the <code>res/</code> directory in your project. Android +has a resource compiler (aapt) that compiles resources according to which +subfolder they are in, and the format of the file. Here is a list of the file +types for each resource. See the +<a href="{@docRoot}reference/available-resources.html">resource reference</a> for +descriptions of each type of object, the syntax, and the format or syntax of +the containing file.</p> + +<table width="100%" border="1"> + <tr> + <th scope="col">Directory</th> + <th scope="col">Resource Types </th> + </tr> + <tr> + <td><code>res/anim/</code></td> + <td>XML files that are compiled into + <a href="{@docRoot}reference/available-resources.html#animationdrawable">frame by + frame animation</a> or + <a href="{@docRoot}reference/available-resources.html#tweenedanimation">tweened + animation</a> objects </td> + </tr> + <tr> + <td><code>res/drawable/</code></td> + <td><p>.png, .9.png, .jpg files that are compiled into the following + Drawable resource subtypes:</p> + <p>To get a resource of this type, use <code>Resource.getDrawable(<em>id</em>)</code> + <ul> + <li><a href="{@docRoot}reference/available-resources.html#imagefileresources">bitmap files</a></li> + <li><a href="{@docRoot}reference/available-resources.html#ninepatch">9-patches (resizable bitmaps)</a></li> + </ul></td> + </tr> + <tr> + <td><code>res/layout/</code></td> + <td>XML files that are compiled into screen layouts (or part of a screen). + See <a href="{@docRoot}devel/ui/xml.html">layouts</a></td> + </tr> + <tr> + <td><code>res/values/</code></td> + <td><p>XML files that can be compiled into many kinds of resource.</p> + <p class="note"><strong>Note:</strong> unlike the other res/ folders, this one + can hold any number of files that hold descriptions of resources to create + rather than the resources themselves. The XML element types control + where these resources are placed under the R class.</p> + <p>While the files can be named anything, these are + the typical files in this folder (the convention is to name + the file after the type of elements defined within):</p> + <ul> + <li><strong>arrays.xml</strong> to define arrays </li> + <!-- TODO: add section on arrays --> + <li><strong>colors.xml</strong> to define <a href="{@docRoot}reference/available-resources.html#colordrawableresources">color + drawables</a> and <a href="#colorvals">color string values</a>. + Use <code>Resources.getDrawable()</code> and + <code>Resources.getColor(), respectively,</code> + to get these resources.</li> + <li><strong>dimens.xml</strong> to define <a href="{@docRoot}reference/available-resources.html#dimension">dimension value</a>. Use <code>Resources.getDimension()</code> to get + these resources.</li> + <li><strong>strings.xml</strong> to define <a href="{@docRoot}reference/available-resources.html#stringresources">string</a> values (use either + <code>Resources.getString</code> or preferably <code>Resources.getText()</code> + to get + these resources. <code>getText()</code> will retain any rich text styling + which is usually desirable for UI strings.</li> + <li><strong>styles.xml</strong> to define <a href="{@docRoot}reference/available-resources.html#stylesandthemes">style</a> objects.</li> + </ul></td> + </tr> + <tr> + <td><code>res/xml/</code></td> + <td>Arbitrary XML files that are compiled and can be read at run time by + calling {@link android.content.res.Resources#getXml(int) Resources.getXML()}.</td> + </tr> + <tr> + <td><code>res/raw/</code></td> + <td>Arbitrary files to copy directly to the device. They are added uncompiled + to the compressed file that your application build produces. To use these + resources in your application, call {@link android.content.res.Resources#openRawResource(int) + Resources.openRawResource()} with the resource ID, which is R.raw.<em>somefilename</em>.</td> + </tr> +</table> +<p>Resources are compiled into the final APK file. Android creates a wrapper class, + called R, that you can use to refer to these resources in your code. R contains subclasses + named according to the path and file name of the source file</p> +<a name="colorvals" id="colorvals"></a> +<h3>Global Resource Notes</h3> +<ul> + <li>Several resources allow you to define colors. Android accepts color values + written in various web-style formats -- a hexadecimal constant in any of the + following forms: #RGB, #ARGB, #RRGGBB, #AARRGGBB. </li> + <li>All color values support setting an alpha channel value, where the first + two hexadecimal numbers specify the transparency. Zero in the alpha channel + means transparent. The default value is opaque. </li> +</ul> +<a name="UsingResources" id="UsingResources"></a> +<h2>Using Resources </h2> +<p>This section describes how to use the resources you've created. It includes the + following topics:</p> +<ul> + <li><a href="#ResourcesInCode">Using resources in code</a> - How to call + resources in your code to instantiate them. </li> + <li><a href="#ReferencesToResources">Referring to resources from other resources</a> - + You can reference resources from other resources. This lets you reuse common + resource values inside resources. </li> + <li><a href="#AlternateResources">Supporting Alternate Resources for Alternate + Configurations</a> - You can specify different resources + to load, depending on the language or display configuration of the host + hardware. </li> +</ul> +<p>At compile time, Android generates a class named R that contains resource identifiers + to all the resources in your program. This class contains several subclasses, + one for each type of resource supported by Android, and for which you provided + a resource file. Each class contains one or more identifiers for the compiled resources, + that you use in your code to load the resource. Here is a small resource file + that contains string, layout (screens or parts of screens), and image resources.</p> +<p class="note"><strong>Note:</strong> the R class is an auto-generated file and is not +designed to be edited by hand. It will be automatically re-created as needed when +the resources are updated.</p> +<pre class="prettyprint">package com.android.samples; +public final class R { + public static final class string { + public static final int greeting=0x0204000e; + public static final int start_button_text=0x02040001; + public static final int submit_button_text=0x02040008; + public static final int main_screen_title=0x0204000a; + }; + public static final class layout { + public static final int start_screen=0x02070000; + public static final int new_user_pane=0x02070001; + public static final int select_user_list=0x02070002; + + }; + public static final class drawable { + public static final int company_logo=0x02020005; + public static final int smiling_cat=0x02020006; + public static final int yellow_fade_background=0x02020007; + public static final int stretch_button_1=0x02020008; + + }; +}; +</pre> +<a name="ResourcesInCode" id="ResourcesInCode"></a> +<h3>Using Resources in Code </h3> + +<p>Using resources in code is just a matter of knowing the full resource ID +and what type of object your resource has been compiled into. Here is the +syntax for referring to a resource:</p> +<p><code>R.<em>resource_type</em>.<em>resource_name</em></code></p> +<p>or</p> +<p><code>android.R.<em>resource_type</em>.<em>resource_name</em></code></p> + +<p>Where <code>resource_type</code> is the R subclass that holds a specific type +of resource. <code>resource_name</code> is the <em>name</em> attribute for resources +defined in XML files, or the file name (without the extension) for resources +defined by other file types. Each type of resource will be added to a specific +R subclass, depending on the type of resource it is; to learn which R subclass +hosts your compiled resource type, consult the +<a href="{@docRoot}reference/available-resources.html">resource +reference</a> document. Resources compiled by your own application can +be referred to without a package name (simply as +<code>R.<em>resource_type</em>.<em>resource_name</em></code>). Android contains +a number of standard resources, such as screen styles and button backgrounds. To +refer to these in code, you must qualify them with <code>android</code>, as in +<code>android.R.drawable.button_background</code>.</p> + +<p>Here are some good and bad examples of using compiled resources in code:</p> + +<pre class="prettyprint">// Load a background for the current screen from a drawable resource. +this.getWindow().setBackgroundDrawableResource(R.drawable.my_background_image); + +// WRONG Sending a string resource reference into a +// method that expects a string. +this.getWindow().setTitle(R.string.main_title); + +// RIGHT Need to get the title from the Resources wrapper. +this.getWindow().setTitle(Resources.getText(R.string.main_title)); + +// Load a custom layout for the current screen. +setContentView(R.layout.main_screen); + +// Set a slide in animation for a ViewFlipper object. +mFlipper.setInAnimation(AnimationUtils.loadAnimation(this, + R.anim.hyperspace_in)); + +// Set the text on a TextView object. +TextView msgTextView = (TextView)findViewByID(R.id.msg); +msgTextView.setText(R.string.hello_message); </pre> + +<a name="ReferencesToResources" id="ReferencesToResources"></a> +<h3>References to Resources</h3> + +<p>A value supplied in an attribute (or resource) can also be a reference to +a resource. This is often used in layout files to supply strings (so they +can be localized) and images (which exist in another file), though a reference +can be any resource type including colors and integers.</p> + +<p>For example, if we have +<a href="{@docRoot}reference/available-resources.html#colordrawableresources">color +resources</a>, we can write a layout file that sets the text color size to be +the value contained in one of those resources:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<EditText id="text" + xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" android:layout_height="fill_parent" + <strong>android:textColor="@color/opaque_red"</strong> + android:text="Hello, World!" /> +</pre> + +<p>Note here the use of the '@' prefix to introduce a resource reference -- the +text following that is the name of a resource in the form +of <code>@[package:]type/name</code>. In this case we didn't need to specify +the package because we are referencing a resource in our own package. To +reference a system resource, you would need to write:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<EditText id="text" + xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" android:layout_height="fill_parent" + android:textColor="@<strong>android:</strong>color/opaque_red" + android:text="Hello, World!" /> +</pre> + +<p>As another example, you should always use resource references when supplying +strings in a layout file so that they can be localized:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<EditText id="text" + xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" android:layout_height="fill_parent" + android:textColor="@android:color/opaque_red" + android:text="@string/hello_world" /> +</pre> + +<p>This facility can also be used to create references between resources. +For example, we can create new drawable resources that are aliases for +existing images:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <drawable id="my_background">@android:drawable/theme2_background</drawable> +</resources> +</pre> + +<a name="ReferencesToThemeAttributes"></a> +<h3>References to Theme Attributes</h3> + +<p>Another kind of resource value allows you to reference the value of an +attribute in the current theme. This attribute reference can <em>only</em> +be used in style resources and XML attributes; it allows you to customize the +look of UI elements by changing them to standard variations supplied by the +current theme, instead of supplying more concrete values.</p> + +<p>As an example, we can use this in our layout to set the text color to +one of the standard colors defined in the base system theme:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<EditText id="text" + xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" android:layout_height="fill_parent" + <strong>android:textColor="?android:textDisabledColor"</strong> + android:text="@string/hello_world" /> +</pre> + +<p>Note that this is very similar to a resource reference, except we are using +an '?' prefix instead of '@'. When you use this markup, you are supplying +the name of an attribute resource that will be looked up in the theme -- +because the resource tool knows that an attribute resource is expected, +you do not need to explicitly state the type (which would be +<code>?android:attr/android:textDisabledColor</code>).</p> + +<p>Other than using this resource identifier to find the value in the +theme instead of raw resources, the name syntax is identical to the '@' format: +<code>?[namespace:]type/name</code> with the type here being optional.</p> + +<a name="UsingSystemResources"></a> +<h3>Using System Resources</h3> + +<p>Many resources included with the system are available to applications. +All such resources are defined under the class "android.R". For example, +you can display the standard application icon in a screen with the following +code:</p> + +<pre class="prettyprint"> +public class MyActivity extends Activity +{ + public void onStart() + { + requestScreenFeatures(FEATURE_BADGE_IMAGE); + + super.onStart(); + + setBadgeResource(android.R.drawable.sym_def_app_icon); + } +} +</pre> + +<p>In a similar way, this code will apply to your screen the standard +"green background" visual treatment defined by the system:</p> + +<pre class="prettyprint"> +public class MyActivity extends Activity +{ + public void onStart() + { + super.onStart(); + + setTheme(android.R.style.Theme_Black); + } +} +</pre> + +<a name="AlternateResources" id="AlternateResources"></a> +<h2>Supporting Alternate Resources for Alternate Languages and Configurations</h2> + +<p>You can supply different resources for your product according to the UI +language or hardware configuration on the device. Note that although you can +include different string, layout, and other resources, the SDK does not expose +methods to let you specify which alternate resource set to load. Android +detects the proper set for the hardware and location, and loads them as +appropriate. Users can select alternate language settings using the settings +panel on the device. </p> +<p>To include alternate resources, create parallel resource folders with +qualifiers appended to the folder names, indicating the configuration it +applies to (language, screen orientation, and so on). For example, here is a +project that holds one string resource file for English, and another for +French:</p> + +<pre> +MyApp/ + res/ + values-en/ + strings.xml + values-fr/ + strings.xml +</pre> + +<p>Android supports several types of qualifiers, with various values for each. +Append these to the end of the resource folder name, separated by dashes. You +can add multiple qualifiers to each folder name, but they must appear in the +order they are listed here. For example, a folder containing drawable +resources for a fully specified configuration would look like:</p> + +<pre> +MyApp/ + res/ + drawable-en-rUS-port-160dpi-finger-keysexposed-qwerty-dpad-480x320/ +</pre> + +<p>More typically, you will only specify a few specific configuration options +that a resource is defined for. You may drop any of the values from the +complete list, as long as the remaining values are still in the same +order:</p> + +<pre> +MyApp/ + res/ + drawable-en-rUS-finger/ + drawable-port/ + drawable-port-160dpi/ + drawable-qwerty/ +</pre> + +<table border="1"> + <tr> + <th> Qualifier </th> + <th> Values </th> + </tr> + <tr> + <td>Language</td> + <td>The two letter <a href="http://www.loc.gov/standards/iso639-2/php/code_list.php">ISO + 639-1</a> language code in lowercase. For example: + <code>en</code>, <code>fr</code>, <code>es</code> </td> + </tr> + <tr> + <td>Region</td> + <td>The two letter + <a href="http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html">ISO + 3166-1-alpha-2</a> language code in uppercase preceded by a lowercase + "r". For example: <code>rUS</code>, <code>rFR</code>, <code>rES</code></td> + </tr> + <tr> + <td>Screen orientation</td> + <td><code>port</code>, <code>land</code>, <code>square</code> </td> + </tr> + <tr> + <td>Screen pixel density</td> + <td><code>92dpi</code>, <code>108dpi</code>, etc. </td> + </tr> + <tr> + <td>Touchscreen type</td> + <td><code>notouch</code>, <code>stylus</code>, <code>finger</code></td> + </tr> + <tr> + <td>Whether the keyboard is available to the user</td> + <td><code>keysexposed</code>, <code>keyshidden</code> </td> + </tr> + <tr> + <td>Primary text input method</td> + <td><code>nokeys</code>, <code>qwerty</code>, <code>12key</code> </td> + </tr> + <tr> + <td>Primary non-touchscreen<br /> + navigation method</td> + <td><code>notouch</code>, <code>dpad</code>, <code>trackball</code>, <code>wheel</code> </td> + </tr> + <tr> + <td>Screen dimensions</td> + <td><code>320x240</code>, <code>640x480</code>, etc. The larger dimension + must be specified first. </td> + </tr> +</table> + +<p>This list does not include device-specific parameters such as carrier, +branding, device/hardware, or manufacturer. Everything that an application +needs to know about the device that it is running on is encoded via the +resource qualifiers in the table above.</p> + +<p>Here are some general guidelines on qualified resource directory names:</p> + +<ul> + <li>Values are separated by a dash (as well as a dash after the base directory + name) </li> + <li>Values are case-sensitive (even though they must be unique across all folder + names in a case-insensitive way)<br />For example,</li> + <ul> + <li>A portrait-specific <code>drawable</code> directory must be named + <code>drawable-port</code>, not <code>drawable-PORT</code>.</li> + <li>You may not have two directories named <code>drawable-port</code> + and <code>drawable-PORT</code>, even if you had intended "port" and + "PORT" to refer to different parameter values.</li> + </ul> + <li>Only one value for each qualifier type is supported (that is, you cannot + specify <code>drawable-rEN-rFR/</code>)</li> + <li>You can specify multiple parameters to define specific configurations, + but they must always be in the order listed above. + For example, <code>drawable-en-rUS-land</code> will apply to landscape view, + US-English devices. </li> + <li>Android will try to find the most specific matching directory for the current + configuration, as described below</li> + <li>The order of parameters listed in this table is used to break a tie in case + of multiple qualified directories (see the example given below) </li> + <li>All directories, both qualified and unqualified, live under the <code>res/</code> folder. + Qualified directories cannot be nested (you cannot have <code>res/drawable/drawable-en</code>) </li> + <li>All resources will be referenced in code or resource reference syntax by + their simple, undecorated name. So if a resource is named this:<br /> + <code>MyApp/res/drawable-port-92dp/myimage.png</code><br /> + It would be referenced as this:<br /> + <code>R.drawable.myimage</code> (code)<br /> + <code>@drawable/myimage</code> (XML)</li> +</ul> + +<h3>How Android finds the best matching directory </h3> + +<p>Android will pick which of the various underlying resource files should be +used at runtime, depending on the current configuration. The selection process +is as follows:</p> + +<ol> + <li> + Eliminate any resources whose configuration does not match the current + device configuration. For example, if the screen pixel density is 108dpi, + this would eliminate only <code>MyApp/res/drawable-port-92dpi/</code>. + <blockquote> + <pre> +MyApp/res/drawable/myimage.png +MyApp/res/drawable-en/myimage.png +MyApp/res/drawable-port/myimage.png +<strike>MyApp/res/drawable-port-92dpi/myimage.png</strike> +</pre> + </blockquote> + </li> + <li> + Pick the resources with the highest number of matching configurations. + For example, if our locale is en-GB and orientation is port, then we + have two candidates with one matching configuration each: + <code>MyApp/res/drawable-en/</code> and <code>MyApp/res/drawable-port/</code>. + The directory <code>MyApp/res/drawable/</code> is eliminated because + it has zero matching configurations, while the others have one matching + configuration. + <blockquote> + <pre> +<strike>MyApp/res/drawable/myimage.png</strike> +MyApp/res/drawable-en/myimage.png +MyApp/res/drawable-port/myimage.png +</pre> + </blockquote> + </li> + <li> + Pick the final matching file based on configuration precedence, which + is the order of parameters listed in the table above. That is, it is + more important to match the language than the orientation, so we break + the tie by picking the language-specific file, <code>MyApp/res/drawable-en/</code>. + <blockquote> + <pre>MyApp/res/drawable-en/myimage.png +<strike>MyApp/res/drawable-port/myimage.png</strike> +</pre> + </blockquote> + </li> +</ol> + +<a name="ResourcesTerminology"></a> +<h2>Terminology</h2> + +<p>The resource system brings a number of different pieces together to +form the final complete resource functionality. To help understand the +overall system, here are some brief definitions of the core concepts and +components you will encounter in using it:</p> + +<p><strong>Asset</strong>: A single blob of data associated with an application. This +includes object files compiled from the Java source code, graphics (such as PNG +images), XML files, etc. These files are organized in a directory hierarchy +that, during final packaging of the application, is bundled together into a +single ZIP file.</p> + +<p><strong>aapt</strong>: Android Asset Packaging Tool. The tool that generates the +final ZIP file of application assets. In addition to collecting raw assets +together, it also parses resource definitions into binary asset data.</p> + +<p><strong>Resource Table</strong>: A special asset that aapt generates for you, +describing all of the resources contained in an application/package. +This file is accessed for you by the Resources class; it is not touched +directly by applications.</p> + +<p><strong>Resource</strong>: An entry in the Resource Table describing a single +named value. Broadly, there are two types of resources: primitives and +bags.</p> + +<p><strong>Resource Identifier</strong>: In the Resource Table all resources are +identified by a unique integer number. In source code (resource descriptions, +XML files, Java source code) you can use symbolic names that stand as constants for +the actual resource identifier integer.</p> + +<p><strong>Primitive Resource</strong>: All primitive resources can be written as a +simple string, using formatting to describe a variety of primitive types +included in the resource system: integers, colors, strings, references to +other resources, etc. Complex resources, such as bitmaps and XML +describes, are stored as a primitive string resource whose value is the path +of the underlying Asset holding its actual data.</p> + +<p><strong>Bag Resource</strong>: A special kind of resource entry that, instead of a +simple string, holds an arbitrary list of name/value pairs. Each name is +itself a resource identifier, and each value can hold +the same kinds of string formatted data as a normal resource. Bags also +support inheritance: a bag can inherit the values from another bag, selectively +replacing or extending them to generate its own contents.</p> + +<p><strong>Kind</strong>: The resource kind is a way to organize resource identifiers +for various purposes. For example, drawable resources are used to +instantiate Drawable objects, so their data is a primitive resource containing +either a color constant or string path to a bitmap or XML asset. Other +common resource kinds are string (localized string primitives), color +(color primitives), layout (a string path to an XML asset describing a view +layout), and style (a bag resource describing user interface attributes). +There is also a standard "attr" resource kind, which defines the resource +identifiers to be used for naming bag items and XML attributes</p> + +<p><strong>Style</strong>: The name of the resource kind containing bags that are used +to supply a set of user interface attributes. For example, a TextView class may +be given a style resource that defines its text size, color, and alignment. +In a layout XML file, you associate a style with a bag using the "style" +attribute, whose value is the name of the style resource.</p> + +<p><strong>Style Class</strong>: Specifies a related set of attribute resources. +This data is not placed in the resource table itself, but used to generate +constants in the source code that make it easier for you to retrieve values out of +a style resource and/or XML tag's attributes. For example, the +Android platform defines a "View" style class that +contains all of the standard view attributes: padding, visibility, +background, etc.; when View is inflated it uses this style class to +retrieve those values from the XML file (at which point style and theme +information is applied as approriate) and load them into its instance.</p> + +<p><strong>Configuration</strong>: For any particular resource identifier, there may be +multiple different available values depending on the current configuration. +The configuration includes the locale (language and country), screen +orientation, screen density, etc. The current configuration is used to +select which resource values are in effect when the resource table is +loaded.</p> + +<p><strong>Theme</strong>: A standard style resource that supplies global +attribute values for a particular context. For example, when writing an +Activity the application developer can select a standard theme to use, such +as the Theme.White or Theme.Black styles; this style supplies information +such as the screen background image/color, default text color, button style, +text editor style, text size, etc. When inflating a layout resource, most +values for widgets (the text color, selector, background) if not explicitly +set will come from the current theme; style and attribute +values supplied in the layout can also assign their value from explicitly +named values in the theme attributes if desired.</p> + +<p><strong>Overlay</strong>: A resource table that does not define a new set of resources, +but instead replaces the values of resources that are in another resource table. +Like a configuration, this is applied at load time +to the resource data; it can add new configuration values (for example +strings in a new locale), replace existing values (for example change +the standard white background image to a "Hello Kitty" background image), +and modify resource bags (for example change the font size of the Theme.White +style to have an 18 pt font size). This is the facility that allows the +user to select between different global appearances of their device, or +download files with new appearances.</p> + +<h2>Resource Reference</h2> +<p>The <a href="{@docRoot}reference/available-resources.html">Resource Reference</a> +document provides a detailed list of the various types of resource and how to use them +from within the Java source code, or from other references.</p> + +<a name="i18n" id="i18n"></a> +<h2>Internationalization and Localization</h2> +<p class="note"><strong>Coming Soon:</strong> Internationalization and Localization are +critical, but are also not quite ready yet in the current SDK. As the +SDK matures, this section will contain information on the Internationalization +and Localization features of the Android platform. In the meantime, it is a good +idea to start by externalizing all strings, and practicing good structure in +creating and using resources.</p> + diff --git a/docs/html/guide/topics/security/security.jd b/docs/html/guide/topics/security/security.jd new file mode 100644 index 0000000..4b258e0 --- /dev/null +++ b/docs/html/guide/topics/security/security.jd @@ -0,0 +1,394 @@ +page.title=Security and Permissions +@jd:body + +<p>Android is a multi-process system, where each application (and parts of the +system) runs in its own process. Most security between applications and +the system is enforced at the process level through standard Linux facilities, +such as user and group IDs that are assigned to applications. +Additional finer-grained security features are provided +through a "permission" mechanism that enforces restrictions on the specific +operations that a particular process can perform, and per-URI permissions +for granting ad-hoc access to specific pieces of data.</p> + +<p>This document covers these topics: </p> + +<ul> +<li><a href="#arch">Security Architecture</a></li> +<li><a href="#signing">Application Signing</a></li> +<li><a href="#userid">User IDs and File Access</a></li> +<li><a href="#permissions">Using Permissions</a></li> +<li><a href="#declaring">Declaring and Enforcing Permissions</a> + <ul> + <li><a href="#manifest">Enforcing Permissions in AndroidManifest.xml</a></li> + <li><a href="#broadcasts">Enforcing Permissions when Sending Broadcasts</a></li> + <li><a href="#enforcement">Other Permission Enforcement</a></li> + </ul></li> +<li>><a href="#uri">URI Permissions</a></li> +</ul> + + +<a name="arch"></a> +<h2>Security Architecture</h2> + +<p>A central design point of the Android security architecture is that no +application, by default, has permission to perform any operations that would +adversely impact other applications, the operating system, or the user. This +includes reading or writing the user's private data (such as contacts or +e-mails), reading or writing another application's files, performing +network access, keeping the device awake, etc.<p> + +<p>An application's process is a secure sandbox. It can't disrupt other +applications, except by explicitly declaring the <em>permissions</em> it needs +for additional capabilities not provided by the basic sandbox. These +permissions it requests can be handled by the operating in various ways, +typically by automatically allowing or disallowing based on certificates or +by prompting the user. The permissions required by an application are declared +statically in that application, so they can be known up-front at install time +and will not change after that.</p> + + +<a name="signing"></a> +<h2>Application Signing</h2> + +<p>All Android applications (.apk files) must be signed with a certificate whose +private key is held by their developer. This certificate identifies the author +of the application. The certificate does <em>not</em> need to be signed by +a certificate authority: it is perfectly allowable, and typical, for Android +applications to use self-signed certificates. The certificate is used only +to establish trust relationships between applications, not for wholesale +control over whether an application can be installed. The most significant +ways that signatures impact security is by determining who can access +signature-based permissions and who can share user IDs.</p> + + +<a name="userid"></a> +<h2>User IDs and File Access</h2> + +<p>Each Android package (.apk) file installed on the device is given its +own unique Linux user ID, creating a sandbox for it and preventing it from touching +other applications (or other applications from touching it). This user ID is +assigned to it when the application is installed on the device, and +remains constant for the duration of its life on that device.</p> + +<p>Because security enforcement happens at the +process level, the code of any two packages can not normally +run in the same process, since they need to run as different Linux users. +You can use the {@link android.R.attr#sharedUserId} attribute in the +<code>AndroidManifest.xml</code>'s +{@link android.R.styleable#AndroidManifest manifest} tag of each package to +have them assigned the same user ID. By doing this, for purposes of security +the two packages are then treated as being the same application, with the same +user ID and file permissions. Note that in order to retain security, only two applications +signed with the same signature (and requesting the same sharedUserId) will +be given the same user ID.</p> + +<p>Any data stored by an application will be assigned that application's user +ID, and not normally accessible to other packages. When creating a new file +with {@link android.content.Context#getSharedPreferences}, +{@link android.content.Context#openFileOutput}, or +{@link android.content.Context#openOrCreateDatabase}, +you can use the +{@link android.content.Context#MODE_WORLD_READABLE} and/or +{@link android.content.Context#MODE_WORLD_WRITEABLE} flags to allow any other +package to read/write the file. When setting these flags, the file is still +owned by your application, but its global read and/or write permissions have +been set appropriately so any other application can see it.</p> + + +<a name="permissions"></a> +<h2>Using Permissions</h2> + +<p>A basic Android application has no permissions associated with it, +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 +<code>{@link android.R.styleable#AndroidManifestUsesPermission <uses-permission>}</code> +tags declaring the permissions that your application needs.</p> + +<p>For example, an application that needs to monitor incoming SMS messages would +specify:</p> + +<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.android.app.myapp" > + + <uses-permission android:name="android.permission.RECEIVE_SMS" /> + +</manifest></pre> + +<p>At application install time, permissions requested by the application are +granted to it by the package installer, based on checks against the +signatures of the applications declaring those permissions and/or interaction +with the user. <em>No</em> checks with the user +are done while an application is running: it either was granted a particular +permission when installed, and can use that feature as desired, or the +permission was not granted and any attempt to use the feature will fail +without prompting the user.</p> + +<p>Often times a permission failure will result in a {@link +java.lang.SecurityException} being thrown back to the application. However, +this is not guaranteed to occur everywhere. For example, the {@link +android.content.Context#sendBroadcast} method checks permissions as data is +being delivered to each receiver, after the method call has returned, so you +will not receive an exception if there are permission failures. In almost all +cases, however, a permission failure will be printed to the system log.</p> + +<p>The permissions provided by the Android system can be found at {@link +android.Manifest.permission}. Any application may also define and enforce its +own permissions, so this is not a comprehensive list of all possible +permissions.</p> + +<p>A particular permission may be enforced at a number of places during your +program's operation:</p> + +<ul> +<li>At the time of a call into the system, to prevent an application from +executing certain functions.</li> +<li>When starting an activity, to prevent applications from launching +activities of other applications.</li> +<li>Both sending and receiving broadcasts, to control who can receive +your broadcast or who can send a broadcast to you.</li> +<li>When accessing and operating on a content provider.</li> +<li>Binding or starting a service.</li> +</ul> + + +<a name="declaring"></a> +<h2>Declaring and Enforcing Permissions</h2> + +<p>To enforce your own permissions, you must first declare them in your +<code>AndroidManifest.xml</code> using one or more +<code>{@link android.R.styleable#AndroidManifestPermission <permission>}</code> +tags.</p> + +<p>For example, an application that wants to control who can start one +of its activities could declare a permission for this operation as follows:</p> + +<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.me.app.myapp" > + + <permission android:name="com.me.app.myapp.permission.DEADLY_ACTIVITY" + android:label="@string/permlab_deadlyActivity" + android:description="@string/permdesc_deadlyActivity" + android:permissionGroup="android.permission-group.COST_MONEY" + android:protectionLevel="dangerous" /> + +</manifest></pre> + +<p>The {@link android.R.styleable#AndroidManifestPermission_protectionLevel +<protectionLevel>} attribute is required, telling the system how the +user is to be informed of applications requiring the permission, or who is +allowed to hold that permission, as described in the linked documentation.</p> + +<p>The {@link android.R.styleable#AndroidManifestPermission_permissionGroup +<permissionGroup>} attribute is optional, and only used to help the system display +permissions to the user. You will usually want to set this to either a standard +system group (listed in {@link android.Manifest.permission_group +android.Manifest.permission_group}) or in more rare cases to one defined by +yourself. It is preferred to use an existing group, as this simplifies the +permission UI shown to the user.</p> + +<p>Note that both a label and description should be supplied for the +permission. These are string resources that can be displayed to the user when +they are viewing a list of permissions +(<code>{@link android.R.styleable#AndroidManifestPermission_label android:label}</code>) +or details on a single permission ( +<code>{@link android.R.styleable#AndroidManifestPermission_description android:description}</code>). +The label should be short, a few words +describing the key piece of functionality the permission is protecting. The +description should be a couple sentences describing what the permission allows +a holder to do. Our convention for the description is two sentences, the first +describing the permission, the second warning the user of what bad things +can happen if an application is granted the permission.</p> + +<p>Here is an example of a label and description for the CALL_PHONE +permission:</p> + +<pre> + <string name="permlab_callPhone">directly call phone numbers</string> + <string name="permdesc_callPhone">Allows the application to call + phone numbers without your intervention. Malicious applications may + cause unexpected calls on your phone bill. Note that this does not + allow the application to call emergency numbers.</string> +</pre> + +<p>You can look at the permissions currently defined in the system with the +shell command <code>adb shell pm list permissions</code>. In particular, +the '-s' option displays the permissions in a form roughly similar to how the +user will see them:</p> + +<pre> +$ adb shell pm list permissions -s +All Permissions: + +Network communication: view Wi-Fi state, create Bluetooth connections, full +Internet access, view network state + +Your location: access extra location provider commands, fine (GPS) location, +mock location sources for testing, coarse (network-based) location + +Services that cost you money: send SMS messages, directly call phone numbers + +...</pre> + +<a name="manifest"></a> +<h3>Enforcing Permissions in AndroidManifest.xml</h3> + +<p>High-level permissions restricting access to entire components of the +system or application can be applied through your +<code>AndroidManifest.xml</code>. All that this requires is including an {@link +android.R.attr#permission android:permission} attribute on the desired +component, naming the permission that will be used to control access to +it.</p> + +<p><strong>{@link android.app.Activity}</strong> permissions +(applied to the +{@link android.R.styleable#AndroidManifestActivity <activity>} tag) +restrict who can start the associated +activity. The permission is checked during +{@link android.content.Context#startActivity Context.startActivity()} and +{@link android.app.Activity#startActivityForResult Activity.startActivityForResult()}; +if the caller does not have +the required permission then {@link java.lang.SecurityException} is thrown +from the call.</p> + +<p><strong>{@link android.app.Service}</strong> permissions +(applied to the +{@link android.R.styleable#AndroidManifestService <service>} tag) +restrict who can start or bind to the +associated service. The permission is checked during +{@link android.content.Context#startService Context.startService()}, +{@link android.content.Context#stopService Context.stopService()} and +{@link android.content.Context#bindService Context.bindService()}; +if the caller does not have +the required permission then {@link java.lang.SecurityException} is thrown +from the call.</p> + +<p><strong>{@link android.content.BroadcastReceiver}</strong> permissions +(applied to the +{@link android.R.styleable#AndroidManifestReceiver <receiver>} tag) +restrict who can send broadcasts to the associated receiver. +The permission is checked <em>after</em> +{@link android.content.Context#sendBroadcast Context.sendBroadcast()} returns, +as the system tries +to deliver the submitted broadcast to the given receiver. As a result, a +permission failure will not result in an exception being thrown back to the +caller; it will just not deliver the intent. In the same way, a permission +can be supplied to +{@link android.content.Context#registerReceiver(android.content.BroadcastReceiver, android.content.IntentFilter, String, android.os.Handler) +Context.registerReceiver()} +to control who can broadcast to a programmatically registered receiver. +Going the other way, a permission can be supplied when calling +{@link android.content.Context#sendBroadcast(Intent, String) Context.sendBroadcast()} +to restrict which BroadcastReceiver objects are allowed to receive the broadcast (see +below).</p> + +<p><strong>{@link android.content.ContentProvider}</strong> permissions +(applied to the +{@link android.R.styleable#AndroidManifestProvider <provider>} tag) +restrict who can access the data in +a {@link android.content.ContentProvider}. (Content providers have an important +additional security facility available to them called +<a href="#uri">URI permissions</a> which is described later.) +Unlike the other components, +there are two separate permission attributes you can set: +{@link android.R.attr#readPermission android:readPermission} restricts who +can read from the provider, and +{@link android.R.attr#writePermission android:writePermission} restricts +who can write to it. Note that if a provider is protected with both a read +and write permission, holding only the write permission does not mean +you can read from a provider. The permissions are checked when you first +retrieve a provider (if you don't have either permission, a SecurityException +will be thrown), and as you perform operations on the provider. Using +{@link android.content.ContentResolver#query ContentResolver.query()} requires +holding the read permission; using +{@link android.content.ContentResolver#insert ContentResolver.insert()}, +{@link android.content.ContentResolver#update ContentResolver.update()}, +{@link android.content.ContentResolver#delete ContentResolver.delete()} +requires the write permission. +In all of these cases, not holding the required permission results in a +{@link java.lang.SecurityException} being thrown from the call.</p> + + +<a name="broadcasts"></a> +<h3>Enforcing Permissions when Sending Broadcasts</h3> + +<p>In addition to the permission enforcing who can send Intents to a +registered {@link android.content.BroadcastReceiver} (as described above), you +can also specify a required permission when sending a broadcast. By calling {@link +android.content.Context#sendBroadcast(android.content.Intent,String) +Context.sendBroadcast()} with a +permission string, you require that a receiver's application must hold that +permission in order to receive your broadcast.</p> + +<p>Note that both a receiver and a broadcaster can require a permission. When +this happens, both permission checks must pass for the Intent to be delivered +to the associated target.</p> + + +<a name="enforcement"></a> +<h3>Other Permission Enforcement</h3> + +<p>Arbitrarily fine-grained permissions can be enforced at any call into a +service. This is accomplished with the {@link +android.content.Context#checkCallingPermission Context.checkCallingPermission()} +method. Call with a desired +permission string and it will return an integer indicating whether that +permission has been granted to the current calling process. Note that this can +only be used when you are executing a call coming in from another process, +usually through an IDL interface published from a service or in some other way +given to another process.</p> + +<p>There are a number of other useful ways to check permissions. If you have +the pid of another process, you can use the Context method {@link +android.content.Context#checkPermission(String, int, int) Context.checkPermission(String, int, int)} +to check a permission against that pid. If you have the package name of another +application, you can use the direct PackageManager method {@link +android.content.pm.PackageManager#checkPermission(String, String) +PackageManager.checkPermission(String, String)} +to find out whether that particular package has been granted a specific permission.</p> + + +<a name="uri"></a> +<h2>URI Permissions</h2> + +<p>The standard permission system described so far is often not sufficient +when used with content providers. A content provider may want to +protect itself with read and write permissions, while its direct clients +also need to hand specific URIs to other applications for them to operate on. +A typical example is attachments in a mail application. Access to the mail +should be protected by permissions, since this is sensitive user data. However, +if a URI to an image attachment is given to an image viewer, that image viewer +will not have permission to open the attachment since it has no reason to hold +a permission to access all e-mail.</p> + +<p>The solution to this problem is per-URI permissions: when starting an +activity or returning a result to an activity, the caller can set +{@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION +Intent.FLAG_GRANT_READ_URI_PERMISSION} and/or +{@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION +Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. This grants the receiving activity +permission access the specific data URI in the Intent, regardless of whether +it has any permission to access data in the content provider corresponding +to the Intent.</p> + +<p>This mechanism allows a common capability-style model where user interaction +(opening an attachment, selecting a contact from a list, etc) drives ad-hoc +granting of fine-grained permission. This can be a key facility for reducing +the permissions needed by applications to only those directly related to their +behavior.</p> + +<p>The granting of fine-grained URI permissions does, however, require some +cooperation with the content provider holding those URIs. It is strongly +recommended that content providers implement this facility, and declare that +they support it through the +{@link android.R.styleable#AndroidManifestProvider_grantUriPermissions +android:grantUriPermissions} attribute or +{@link android.R.styleable#AndroidManifestGrantUriPermission +<grant-uri-permissions>} tag.</p> + +<p>More information can be found in the +{@link android.content.Context#grantUriPermission Context.grantUriPermission()}, +{@link android.content.Context#revokeUriPermission Context.revokeUriPermission()}, and +{@link android.content.Context#checkUriPermission Context.checkUriPermission()} +methods.</p> + diff --git a/docs/html/guide/topics/views/binding.jd b/docs/html/guide/topics/views/binding.jd new file mode 100644 index 0000000..e6fa3ea --- /dev/null +++ b/docs/html/guide/topics/views/binding.jd @@ -0,0 +1,80 @@ +page.title=Binding to Data with AdapterView +@jd:body + +<p>Some types of ViewGroup objects have a UI that is visible on the screen — {@link android.widget.AdapterView AdapterView} is one such object. AdapterView is a ViewGroup subclass whose child Views are determined by an {@link android.widget.Adapter Adapter} that binds to data of some type. AdapterView is useful whenever you need to display stored data (versus resource strings or drawables) in your layout.</p> + +<p>{@link android.widget.Gallery Gallery}, {@link android.widget.ListView ListView}, and {@link android.widget.Spinner Spinner} are examples of AdapterView subclasses that you can use to bind to a specific type of data and display it in a certain way. </p> + + +<p>AdapterView objects have two main responsibilities: </p> +<ul> + <li>Filling the layout with data + </li> + <li>Handling user selections + </li> +</ul> + +<p>The sections below describe how the AdapterView fulfills those responsibilities.</p> + +<h3> + Filling the layout with data +</h3> + +<p>This is typically done by binding the class to an {@link +android.widget.Adapter} that gets its data from somewhere — either a list that +the code supplies, or query results from the device's database. </p> + +<pre> +// Get a Spinner and bind it to an ArrayAdapter that +// references a String array. +Spinner s1 = (Spinner) findViewById(R.id.spinner1); +ArrayAdapter<CharSequence> adapter = ArrayAdapter.createFromResource( + this, R.array.colors, android.R.layout.simple_spinner_item); +adapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item); +s1.setAdapter(adapter); + +// Load a Spinner and bind it to a data query. +private static String[] PROJECTION = new String[] { + People._ID, People.NAME + }; + +Spinner s2 = (Spinner) findViewById(R.id.spinner2); +Cursor cur = managedQuery(People.CONTENT_URI, PROJECTION, null, null); + +SimpleCursorAdapter adapter2 = new SimpleCursorAdapter(this, + android.R.layout.simple_spinner_item, // Use a template + // that displays a + // text view + cur, // Give the cursor to the list adatper + new String[] {People.NAME}, // Map the NAME column in the + // people database to... + new int[] {android.R.id.text1}); // The "text1" view defined in + // the XML template + +adapter2.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item); +s2.setAdapter(adapter2); +</pre> + +<p>Note that it is necessary to have the People._ID column in projection used with CursorAdapter +or else you will get an exception.</p> +<h3> + Handling user selections +</h3> +<p> This is done by setting the class's {@link +android.widget.AdapterView.OnItemClickListener} member to a listener and +catching the selection changes. </p> +<pre> +// Create a message handling object as an anonymous class. +private OnItemClickListener mMessageClickedHandler = new OnItemClickListener() { + public void onItemClick(AdapterView parent, View v, int position, long id) + { + // Display a messagebox. + Toast.makeText(mContext,"You've got an event",Toast.LENGTH_SHORT).show(); + } +}; + +// Now hook into our object and set its onItemClickListener member +// to our class handler object. +mHistoryView = (ListView)findViewById(R.id.history); +mHistoryView.setOnItemClickListener(mMessageClickedHandler); +</pre> diff --git a/docs/html/guide/topics/views/custom-views.jd b/docs/html/guide/topics/views/custom-views.jd new file mode 100644 index 0000000..9850e17 --- /dev/null +++ b/docs/html/guide/topics/views/custom-views.jd @@ -0,0 +1,440 @@ +page.title=Building Custom Views +@jd:body + +<p>Android comes with a solid collection of Views that you can use +to construct your applications, for example:</p> + + +<p>Android offers a sophisticated and powerful componentized model for building your UI, based on the fundamental building block classes {@link android.view.View} and {@link android.view.ViewGroup}. To start with, the platform includes a variety of prebuilt View and ViewGroup subclasses — called widgets and layouts, respectively — that you can use to construct your UI. The widgets and layouts are fully implemented and handle all of their own measuring and drawing, so you can use them right away. You can make new types of UI elements simply by nesting and grouping the widgets and layouts. Using widgets and layouts is the recommended approach to building a UI for your applications.</p> + +<p>A partial list of available widgets includes {@link android.widget.Button Button}, +{@link android.widget.TextView TextView}, +{@link android.widget.EditText EditText}, +{@link android.widget.ListView ListView}, +{@link android.widget.CheckBox CheckBox}, +{@link android.widget.RadioButton RadioButton}, +{@link android.widget.Gallery Gallery}, +{@link android.widget.Spinner Spinner}, and the more special-purpose +{@link android.widget.AutoCompleteTextView AutoCompleteTextView}, +{@link android.widget.ImageSwitcher ImageSwitcher}, and +{@link android.widget.TextSwitcher TextSwitcher}. </p> + +<p>Among the layouts available are {@link android.widget.LinearLayout LinearLayout}, +{@link android.widget.FrameLayout FrameLayout}, {@link android.widget.AbsoluteLayout AbsoluteLayout},and others. For more examples, see <a href="layout">Common Layout Objects</a>.</p> + +<p>If none of the prebuilt widgets or layouts meets your needs, you can also create your own View subclass, such as a layout group or compound control. If you only need to make small adjustments to an existing widget or layout, you can simply subclass the widget or layout and override +</p> + +<p>Creating your own View subclasses gives you precise control over the appearance and function of a screen element. To give an idea of the control you get with custom views, here are some examples of what you could do with them:</p> + +<ul> + <li> + You could create a completely custom-rendered View type, for example a "volume + control" knob rendered using 2D graphics, and which resembles an + analog electronic control. + </li> + <li> + You could combine a group of View components into a new single component, perhaps + to make something like a ComboBox (a combination of popup list and free + entry text field), a dual-pane selector control (a left and right pane + with a list in each where you can re-assign which item is in which + list), and so on. + </li> + <li> + You could override the way that an EditText component is rendered on the screen + (the Notepad tutorial uses this to good effect, to create a lined-notepad + page). + </li> + <li> + You could capture other events like key presses and handle them in some custom + way (such as for a game). + </li> +</ul> +<p> +The sections below explain how to create custom Views and use them in your application. +</p> + +<p>For detailed information, see {android.view.View}. </p> + + +<h2 style="clear:right;">Contents</h2> +<dl> +<dt><a href="#basic">The Basic Approach</a></dt> +<dt><a href="#custom">Fully Customized Views</a></dt> +<dt><a href="#customexample">Customized View Example</a></dt> +<dt><a href="#compound">Compound Controls</a></dt> +<dt><a href="#tweaking">Modifying an Existing Component Type</a></dt> +</dl> + +<a name="basic"></a> +<h2>The Basic Approach +</h2> +<p> +These steps provide a high level overview of +what you need to know to get started in creating your own +View components:</p> + +<ol> + <li> + Extend an existing {@link android.view.View View} class or subclass + with your own class. + </li> + <li> + Override some of the methods from the superclass: the superclass methods + to override start with '<code>on</code>', for + example, {@link android.view.View#onDraw onDraw()}, + {@link android.view.View#onMeasure onMeasure()}, and + {@link android.view.View#onKeyDown onKeyDown()}. + <ul> + <li> + This is similar to the <code>on...</code> events in {@link android.app.Activity + Activity} or {@link android.app.ListActivity ListActivity} + that you override for life cycle and other functionality hooks. + </li> + </ul> + <li> + Use your new extension class: once completed, your new extension class + can be used in place of the view upon which it was based, but now with the new + functionality. + </li> +</ol> +<p class="note"> + Extension classes can be defined as inner classes inside the activities + that use them. This is useful because it controls access to them but + isn't necessary (perhaps you want to create a new public View for + wider use in your application). +</p> + +<a name="custom"></a> +<h2>Fully Customized Components</h2> +<p> +Fully customized components can be used to create graphical components that +appear however you wish. Perhaps a graphical VU +meter that looks like an old analog gauge, or a sing-a-long text view where +a bouncing ball moves along the words so you can sing along with a karaoke +machine. Either way, you want something that the built-in components just +won't do, no matter how you combine them.</p> +<p>Fortunately, you can easily create components that look and behave in any +way you like, limited perhaps only by your imagination, the size of the +screen, and the available processing power (remember that ultimately your +application might have to run on something with significantly less power +than your desktop workstation).</p> +<p>To create a fully customized component:</p> +<ol> + <li> + The most generic view you can extend is, unsurprisingly, {@link + android.view.View View}, so you will usually start by extending this to + create your new super component. + </li> + <li> + You can supply a constructor which can + take attributes and parameters from the XML, and you can also consume + your own such attributes and parameters (perhaps the color and range of + the VU meter, or the width and damping of the needle, etc.) + </li> + <li> + You will probably want to create your own event listeners, + property accessors and modifiers, and possibly more sophisticated + behavior in your component class as well. + </li> + <li> + You will almost certainly want to override <code>onMeasure()</code> and + are also likely to need to override <code>onDraw()</code> if you want + the component to show something. While both have default behavior, + the default <code>onDraw()</code> will do nothing, and the default + <code>onMeasure()</code> will always set a size of 100x100 — which is + probably not what you want. + </li> + <li> + Other <code>on...</code> methods may also be overridden as required. + </li> +</ol> +<h4><code>onDraw()</code> and <code>onMeasure()</code></h4> +<p><code>onDraw()</code> delivers you a {@link android.graphics.Canvas Canvas} +upon which you can implement anything you want: 2D graphics, other standard or +custom components, styled text, or anything else you can think of.</p> +<p><em>Note:</em> +Except for 3D graphics. If you want to +use 3D graphics, you must extend {@link android.view.SurfaceView SurfaceView} +instead of View, and draw from a seperate thread. See the +GLSurfaceViewActivity sample +for details.</p> +<p><code>onMeasure()</code> is a little more involved. <code>onMeasure()</code> +is a critical piece of the rendering contract between your component and its +container. <code>onMeasure()</code> should be overridden to efficiently and +accurately report the measurements of its contained parts. This is made +slightly more complex by the requirements of limits from the parent +(which are passed in to the <code>onMeasure()</code> method) and by the +requirement to call the <code>setMeasuredDimension()</code> method with the +measured width and height once they have been calculated. If you fail to +call this method from an overridden <code>onMeasure()</code> method, the +result will be an exception at measurement time.</p> +<p>At a high level, implementing <code>onMeasure()</code> looks something + like this:</p> + +<ol> + <li> + The overridden <code>onMeasure()</code> method is called with width and + height measure specifications (<code>widthMeasureSpec</code> and + <code>heighMeasureSpec</code> parameters, both are integer codes + representing dimensions) which should be treated as requirements for + the restrictions on the width and height measurements you should produce. A + full reference to the kind of restrictions these specifications can require + can be found in the reference documentation under {@link + android.view.View#onMeasure View.onMeasure(int, int)} (this reference + documentation does a pretty good job of explaining the whole measurement + operation as well). + </li> + <li> + Your component's <code>onMeasure()</code> method should calculate a + measurement width and height which will be required to render the + component. It should try to stay within the specifications passed in, + although it can choose to exceed them (in this case, the parent can + choose what to do, including clipping, scrolling, throwing an exception, + or asking the <code>onMeasure()</code> to try again, perhaps with + different measurement specifications). + </li> + <li> + Once the width and height are calculated, the <code>setMeasuredDimension(int + width, int height)</code> method must be called with the calculated + measurements. Failure to do this will result in an exception being + thrown. + </li> +</ol> + +<a name="customexample"></a> +<h3>A Custom View Example</h3> +<p>The CustomView sample in the +<a href="{@docRoot}samples/ApiDemos/index.html">API Demos</a> provides an example +of a customized View. The custom View is defined in the +<a href="{@docRoot}samples/ApiDemos/src/com/example/android/apis/view/LabelView.html">LabelView</a> +class.</p> +<p>The LabelView sample demonstrates a number of different aspects of custom components:</p> +<ul> + <li>Extending the View class for a completely custom component.</li> + <li>Parameterized constructor that takes the view inflation parameters + (parameters defined in the XML). Some of these are passed through to the + View superclass, but more importantly, there are some custom attributes defined + and used for LabelView.</li> + <li>Standard public methods of the type you would expect to see for a label + component, for example <code>setText()</code>, <code>setTextSize()</code>, + <code>setTextColor()</code> and so on.</li> + <li>An overridden <code>onMeasure</code> method to determine and set the + rendering size of the component. (Note that in LabelView, the real work is done + by a private <code>measureWidth()</code> method.)</li> + <li>An overridden <code>onDraw()</code> method to draw the label onto the + provided canvas.</li> +</ul> +<p>You can see some sample usages of the LabelView custom View in +<a href="{@docRoot}samples/ApiDemos/res/layout/custom_view_1.html">custom_view_1.xml</a> +from the samples. In particular, you can see a mix of both <code>android:</code> +namespace parameters and custom <code>app:</code> namespace parameters. These +<code>app:</code> parameters are the custom ones that the LabelView recognizes +and works with, and are defined in a styleable inner class inside of the +samples R resources definition class.</p> + +<a name="compound"></a> +<h2>Compound Controls +</h2> +<p>If you don't want to create a completely customized component, but instead +are looking to put together a reusable component that consists of a group of +existing controls, then creating a Compound Component (or Compound Control) might +fit the bill. In a nutshell, this brings together a number of more atomic +controls (or views) into a logical group of items that can be treated as a +single thing. For example, a Combo Box can be thought of as a +combination of a single line EditText field and an adjacent button with an attached + PopupList. If you press the button and select +something from the list, it populates the EditText field, but the user can +also type something directly into the EditText if they prefer.</p> +<p>In Android, there are actually two other Views readily available to do +this: {@link android.widget.Spinner Spinner} and +{@link android.widget.AutoCompleteTextView AutoCompleteTextView}, but +regardless, the concept of a Combo Box makes an easy-to-understand +example.</p> +<p>To create a compound component:</p> +<ol> + <li> + The usual starting point is a Layout of some kind, so create a class + that extends a Layout. Perhaps in the case of a Combo box we might use + a LinearLayout with horizontal orientation. Remember that other layouts + can be nested inside, so the compound component can be arbitrarily + complex and structured. Note that just like with an Activity, you can + use either the declarative (XML-based) approach to creating the + contained components, or you can nest them programmatically from your + code. + </li> + <li> + In the constructor for the new class, take whatever parameters the + superclass expects, and pass them through to the superclass constructor + first. Then you can set up the other views to use within your new + component; this is where you would create the EditText field and the + PopupList. Note that you also might introduce your own attributes and + parameters into the XML that can be pulled out and used by your + constructor. + </li> + <li> + You can also create listeners for events that your contained views might + generate, for example, a listener method for the List Item Click Listener + to update the contents of the EditText if a list selection is made. + </li> + <li> + You might also create your own properties with accessors and modifiers, + for example, allow the EditText value to be set initially in the + component and query for its contents when needed. + </li> + <li> + In the case of extending a Layout, you don't need to override the + <code>onDraw()</code> and <code>onMeasure()</code> methods since the + layout will have default behavior that will likely work just fine. However, + you can still override them if you need to. + </li> + <li> + You might override other <code>on...</code> methods, like + <code>onKeyDown()</code>, to perhaps choose certain default values from + the popup list of a combo box when a certain key is pressed. + </li> +</ol> +<p> + To summarize, the use of a Layout as the basis for a Custom Control has a +number of advantages, including:</p> + +<ul> + <li> + You can specify the layout using the declarative XML files just like + with an activity screen, or you can create views programmatically and + nest them into the layout from your code. + </li> + <li> + The <code>onDraw()</code> and <code>onMeasure()</code> methods (plus + most of the other <code>on...</code> methods) will likely have suitable behavior so + you don't have to override them. + </li> + <li> + In the end, you can very quickly construct arbitrarily complex compound + views and re-use them as if they were a single component. + </li> +</ul> +<h4>Examples of Compound Controls</h4> +<p>In the API Demos project + that comes with the SDK, there are two List + examples — Example 4 and Example 6 under Views/Lists demonstrate a + SpeechView which extends LinearLayout to make a component for displaying + Speech quotes. The corresponding classes in the sample code are + <code>List4.java</code> and <code>List6.java</code>.</p> + +<a name="tweaking"></a> +<h2>Modifying an Existing View Type +</h2> +<p>There is an even easier option for creating a custom View which is +useful in certain circumstances. If there is a component that is already very +similar to what you want, you can simply extend that component and just +override the behavior that you want to change. You can do all of the things +you would do with a fully customized component, but by starting with a more +specialized class in the View heirarchy, you can also get a lot of behavior for +free that probably does exactly what you want.</p> +<p>For example, the SDK includes a <a +href="{@docRoot}samples/NotePad/index.html">NotePad application</a> in the +samples. This demonstrates many aspects of using the Android platform, among +them is extending an EditText View to make a lined notepad. This is not a +perfect example, and the APIs for doing this might change from this early +preview, but it does demonstrate the principles.</p> +<p>If you haven't done so already, import the +NotePad sample into Eclipse (or +just look at the source using the link provided). In particular look at the definition of +<code>MyEditText</code> in the <a +href="{@docRoot}samples/NotePad/src/com/example/android/notepad/NoteEditor.html">NoteEditor.java</a> +file.</p> +<p>Some points to note here</p> +<ol> + <li> + <strong>The Definition</strong> + <p>The class is defined with the following line:</p> + <code>public static class MyEditText extends EditText</code><br><br> + + <ul> + <li> + It is defined as an inner class within the <code>NoteEditor</code> + activity, but it is public so that it could be accessed as + <code>NoteEditor.MyEditText</code> from outside of the <code>NoteEditor</code> + class if desired. + </li> + <li> + It is <code>static</code>, meaning it does not generate the so-called + "synthetic methods" that allow it to access data from the parent + class, which in turn means that it really behaves as a separate + class rather than something strongly related to <code>NoteEditor</code>. + This is a cleaner way to create inner classes if they do not need + access to state from the outer class, keeps the generated class + small, and allows it to be used easily from other classes. + </li> + <li> + It extends <code>EditText</code>, which is the View we have chosen to + customize in this case. When we are finished, the new class will be + able to substitute for a normal <code>EditText</code> view.<br> + <br> + </li> + </ul> + </li> + <li> + <strong>Class Initialization</strong> + <p>As always, the super is called first. Furthermore, + this is not a default constructor, but a parameterized one. The + EditText is created with these parameters when it is inflated from an + XML layout file, thus, our constructor needs to both take them and pass them + to the superclass constructor as well.</p> + </li> + <li> + <strong>Overridden Methods</strong> + <p>In this example, there is only one method to be overridden: + <code>onDraw()</code> — but there could easily be others needed when you + create your own custom components.</p> + <p>For the NotePad sample, overriding the <code>onDraw()</code> method allows + us to paint the blue lines on the <code>EditText</code> view canvas (the + canvas is passed into the overridden <code>onDraw()</code> method). The + super.onDraw() method is called before the method ends. The + superclass method should be invoked, but in this case, we do it at the + end after we have painted the lines we want to include.</p> + <li> + <strong>Use the Custom Component</strong> + <p>We now have our custom component, but how can we use it? In the + NotePad example, the custom component is used directly from the + declarative layout, so take a look at <code>note_editor.xml</code> in the + <code>res/layout</code> folder.</p> + <pre> +<view xmlns:android="http://schemas.android.com/apk/res/android" + class="com.android.notepad.NoteEditor$MyEditText" + id="@+id/note" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:background="@android:drawable/empty" + android:padding="10dip" + android:scrollbars="vertical" + android:fadingEdge="vertical" /> </pre> + + <ul> + <li> + The custom component is created as a generic view in the XML, and + the class is specified using the full package. Note also that the + inner class we defined is referenced using the + <code>NoteEditor$MyEditText</code> notation which is a standard way to + refer to inner classes in the Java programming language. + </li> + <li> + The other attributes and parameters in the definition are the ones + passed into the custom component constructor, and then passed + through to the EditText constructor, so they are the same + parameters that you would use for an EditText view. Note that it is + possible to add your own parameters as well, and we will touch on + this again below. + </li> + </ul> + </li> +</ol> +<p>And that's all there is to it. Admittedly this is a simple case, but +that's the point — creating custom components is only as complicated as you +need it to be.</p> +<p>A more sophisticated component may override even more <code>on...</code> methods and +introduce some of its own helper methods, substantially customizing its properties and +behavior. The only limit is your imagination and what you need the component to +do.</p> + diff --git a/docs/html/guide/topics/views/hierarchy.jd b/docs/html/guide/topics/views/hierarchy.jd new file mode 100644 index 0000000..17a13c1 --- /dev/null +++ b/docs/html/guide/topics/views/hierarchy.jd @@ -0,0 +1,47 @@ +page.title=Hierarchy of Screen Elements +@jd:body + +<p>The basic functional unit of an Android application is the <em>activity</em> — an object of the class {@link android.app.Activity android.app.Activity}. An activity can do many things, but by itself it does not have a presence on the screen. To give your activity a screen presence and design its UI, you work with <em>views</em> and <em>viewgroups</em> -- basic units of user interface expression on the Android platform.</p> + +<h2>Views</h2> +<p>A view is an object of base class {@link android.view.View android.view.View}. It's a data structure whose properties store the layout and content for a specific rectangular area of the screen. A View object handles measuring and layout, drawing, focus change, scrolling, and key/gestures for the screen area it represents. </p> +<p>The View class serves as a base class for <em>widgets </em> — a set of fully implemented subclasses that draw interactive screen elements. Widgets handle their own measuring and drawing, so you can use them to build your UI more quickly. The list of widgets available includes Text, EditText, InputMethod, MovementMethod, Button, RadioButton, Checkbox, and ScrollView.</p> + +<h2>Viewgroups </h2> + +<p>A viewgroup is an object of class {@link android.view.ViewGroup android.view.Viewgroup}. As its name indicates, a viewgroup is a special type of view object whose function is to contain and manage a subordinate set of views and other viewgroups, Viewgroups let you add structure to your UI and build up complex screen elements that can be addressed as a single entity. </p> + +<p>The Viewgroup class serves as a base class for <em>layouts</em> — a set of fully implemented subclasses that provide common types of screen layout. The layouts give you a way to build a structure for a set of views. </p> + +<h2>A Tree-Structured UI</h2> + +<p>On the Android platform, you define an Activity's UI using a tree of view and viewgroup nodes, as shown in the diagram below. The tree can be as simple or complex as you need to make it, and you can build it up using Android's set of predefined widgets and layouts or custom view types that you create yourself. </p> + +<img src={@docRoot}images/viewgroup.png alt="An example of a tree of views and viewgroups" width="312" height="211" align="center"/> + +<p>To attach the tree to the screen for rendering, your Activity calls its setContentView() method and passes a reference to the root node object. Once the Android system has the reference to the root node object, it can work directly with the node to invalidate, measure, and draw the tree. When your Activity becomes active and receives focus, the system notifies your activity and requests the root node to measure and draw the tree. The root node then requests that its child nodes draw themselves — in turn, each viewgroup node in the tree is responsible for drawing its direct children. </p> + +<p>As mentioned previously, each view group has the responsibility of + measuring its available space, laying out its children, and calling Draw() on + each child to let it render itself. The children may request a size and location + in the parent, but the parent object has the final decision on where how big + each child can be.</p> + +<h2>LayoutParams: How a Child Specifies Its Position and Size</h2> + +<p>Every viewgroup class uses a nested class that extends {@link +android.view.ViewGroup.LayoutParams ViewGroup.LayoutParams}. This subclass + contains property types that define a child's size and position, in properties + appropriate for that view group class. </p> + +<img src={@docRoot}images/layoutparams.png alt="An example of layoutparams" width="632" height="369" align="center"/> + +<p>Note that every LayoutParams subclass has its own syntax for setting +values. Each child element must define LayoutParams that are appropriate for its parent, although it may define different LayoutParams for its children. </p> + +<p>All viewgroups include width and height. Many also include margins and +borders. You can specify width and height exactly, though you probably won't want +to do this often. More often you will tell your view to size itself either to +the dimensions of its content, or to become as big as its containing object +will allow.</p> + diff --git a/docs/html/guide/topics/views/index.jd b/docs/html/guide/topics/views/index.jd new file mode 100644 index 0000000..9a15921d --- /dev/null +++ b/docs/html/guide/topics/views/index.jd @@ -0,0 +1,45 @@ +page.title=Views and Layout +@jd:body + +<p>To build a user interface fors your Android application, you work with <em>views</em> and <em>viewgroups</em> -- basic units of user interface expression on the Android platform. All views and viewgroups are descendants of the class {@link android.view.View}. To help you build your UI more quickly, Android provides a set of fully implemented views and viewgroups — called widgets and layouts — that you can use. + +The topics below describe the basics of how you use views to implement a user interface. including the types of screen elements available, the ways that you can declare them in your application, how you can bind a screen elements to local data, and how views can catch and handle screen or keypad events. </p> + +<p>For a quick start on how to create the Views you need for your UI, check out the <a href="{@docRoot}guide/tutorials/views/hello-views-index.html">Hello Views tutorials</a>. You can look at a variety of available layouts and screen elements as they would be rendered on a device, then look at the code for declaring and invoking each one. </p> + +<p>You can find additional sample code in the API Demos application, included in the SDK's samples directory. </p> + +<div class="sidebox"> +<p>Using Android resources is an important part of building your application's user interface. For information about what resources are available to you and how you use them, see the <a href="{@docRoot}guide/topics/resources/index.html">Resources</a> topics area.</p> +</div> + +<ul> + <li> + <a href="hierarchy.html">Hierarchy of Screen Elements</a> + </li> + <li> + <a href="layout.html">Common Layout Objects</a> + </li> + <li> + <a href="ui-xml.html">Declaring a UI in XML</a> + </li> + <li> + <a href="binding.html">Binding to Data with AdapterView</a> + </li> + <li> + <a href="ui-events.html">Handling UI Events</a> + </li> + <li> + <a href="themes.html">Applying Styles and Themes to Your Application</a> + </li> + <li> + <a href="custom-views.html">Building Custom Views</a> + </li> + <li> + <a href="glossary.html">UI Elements and Concepts Glossary</a> + </li> + <li> + <a href="{@docRoot}guide/tutorials/views/hello-views-index.html">Hello Views</a> + </li> + +</ul> diff --git a/docs/html/guide/topics/views/layout.jd b/docs/html/guide/topics/views/layout.jd new file mode 100644 index 0000000..f6eedbb --- /dev/null +++ b/docs/html/guide/topics/views/layout.jd @@ -0,0 +1,188 @@ +page.title=Common Layout Objects +@jd:body + +<p>The sections below describe some of the more common types of layout objects you'll be likely to use in your applications. Like other layouts, they are subclasses of {@link android.view.ViewGroup ViewGroup}.</p> + +<h2>FrameLayout<a name="framelayout" id="framelayout"></a></h2> + +<p>{@link android.widget.FrameLayout FrameLayout} is the simplest layout +object. It is intended as a blank reserved space on your screen that you can +later fill with a single object — for example, a picture that you'll swap out. +All child elements are pinned to the top left corner of the screen; you cannot +specify a location for a child of a {@link android.widget.FrameLayout +FrameLayout}. Later children will simply be drawn over earlier objects, +partially or totally obscuring them (unless the newer object is transparent). +</p> + +<h2>LinearLayout<a name="linearlayout" id="linearlayout"></a></h2> + +<p>A {@link android.widget.LinearLayout LinearLayout} aligns all children in a +single direction — vertically or horizontally, depending on what property you +set on the {@link android.widget.LinearLayout LinearLayout}. All children are +stacked one after the other, so a vertical list will only have one child per +row, no matter how wide they are, and a horizontal list will only be one row +high (the height of the tallest child, plus padding). {@link +android.widget.LinearLayout LinearLayout} respects margins between children, +and also <em>gravity</em> (right, center, or left alignment of a child). </p> + +<p>{@link android.widget.LinearLayout LinearLayout} also supports assigning a +<em>weight</em> to individual children. This value allows children to expand +to fill any remaining space on a screen. This prevents a list of small objects +from being bunched to one end of a large screen, allowing them to expand to +fill the space. Children specify a weight value, and any remaining space is +assigned to children in the proportion of their declared weight. Default +weight is zero. So, for example, if there are three text boxes, and two of +them declare a weight of 1, two of them will expand equally to fill the +remaining space, and the third will not grow any additional amount.</p> + +<div class="sidebox"> +<p><strong>Tip</strong>: To create a proportionate size +layout on the screen, create a container object that is fill_parent, assign +the children heights or widths of zero, and then assign relative weight values +to each child, depending on what proportion of the screen each should +take.</p> +</div> + +<p>The following two forms represent a {@link android.widget.LinearLayout LinearLayout} with a set of elements: a +button, some labels, some text boxes. Both have padding values to adjust the +padding nicely. The text boxes have their width set to <code>FILL_PARENT</code>; other +elements are set to <code>WRAP_CONTENT</code>. The gravity, by default, is left. The form +on the left has weight values unset (0 by default); the form on the right has +the comments text box weight set to 1. If the Name textbox had also been set +to 1, the Name and Comments text boxes would be the same height. </p> + +<p> + <img src="{@docRoot}images/linearlayout.png" alt="Linear layout with +weight attribute." width="421" height="348" /> +</p> + +<p>Within a horizontal {@link android.widget.LinearLayout LinearLayout}, items are aligned by the position of +their text base line (the first line of the first list element — topmost or +leftmost — is considered the reference line). This is so that people scanning +elements in a form shouldn't have to jump up and down to read element text in +neighboring elements. This can be turned off by setting +<code>android:baselineAligned="false"</code> in the layout XML. </p> + +<h2>TableLayout<a name="tablelayout" id="tablelayout"></a></h2> + +<p>{@link android.widget.TableLayout TableLayout} positions its children into rows + and columns. A TableLayout consists of a number of TableRow objects, + each defining a row (actually, you can have other children, which will be explained + below). TableLayout containers do not display border lines for their rows, columns, + or cells. Each row has zero or more cells; each cell can hold one View object. + The table has as many columns as the row with the most cells. A table can leave +cells empty. Cells cannot span columns, as they can in HTML. The following image + shows a table layout, with the invisible cell borders displayed as dotted lines. </p> +<p><img src="{@docRoot}images/table_layout.png" alt="TableLayout example" width="499" height="348" /></p> +<p>Columns can be hidden, can be marked to stretch to fill available screen space, + or can be marked as shrinkable to force the column to shrink until the table + fits the screen. See the reference documentation for this class for more details. </p> +<h2>AbsoluteLayout<a name="absolutelayout" id="absolutelayout"></a></h2> +<p>{@link android.widget.AbsoluteLayout AbsoluteLayout} enables children to specify + exact x/y coordinates to display on the screen, where (0,0) is the upper left + corner, and values increase as you move down or to the right. Margins are not + supported, and overlapping elements are allowed (although not recommended). We + generally recommend against using AbsoluteLayout unless you have good reasons + to use it, because it is fairly rigid and does not work well with different device + displays. </p> +<h2>RelativeLayout<a name="relativelayout" id="relativelayout"></a></h2> +<p>{@link android.widget.RelativeLayout RelativeLayout} lets children specify their + position relative to each other (specified by ID), or to the parent. So you can + align two elements by right border, or make one below another, or centered in + the screen. Elements are rendered in the order given, so if the first element + is centered in the screen, other elements aligning themselves to that element + will be aligned relative to screen center. If using XML to specify this layout + (as described later), a referenced element must be listed before you refer to + it. </p> +<p>Here is an example relative layout with the visible and invisible elements outlined. + The root screen layout object is a RelativeLayout object. </p> +<p><img src="{@docRoot}images/designing_ui_relative_layout.png" alt="RelativeLayout screen with elements highlighted." width="692" height="440" /></p> +<p>This diagram shows the class names of the screen elements, followed by a list + of the properties of each. Some of these properties are supported directly by + the element, and some are supported by its LayoutParams member (subclass RelativeLayout + for all the elements in this screen, because all elements are children of a RelativeLayout + parent object). The RelativeLayout parameters are width, height, below, alignTop, + toLeft, padding, and marginLeft. Note that some of these parameters support values + relative to other children — hence the name RelativeLayout. These include the + toLeft, alignTop, and below properties, which indicate the object to the left, + top, and below respectively. </p> +<h2>Summary of Important View Groups<a name="viewgroupsummary" id="viewgroupsummary"></a></h2> +<p>These objects all hold child UI elements. Some provide visible UI, and others + only handle child layout. </p> +<table width="100%" border="1"> + <tr> + <th scope="col">Class</th> + <th scope="col">Description</th> + </tr> + <tr> + <td>{@link android.widget.AbsoluteLayout AbsoluteLayout}<br /></td> + <td>Enables you to specify the location of child objects relative to the + parent in exact measurements (for example, pixels). </td> + </tr> + <tr> + <td>{@link android.widget.FrameLayout FrameLayout}</td> + <td>Layout that acts as a view frame to display + a single object. </td> + </tr> + <tr> + <td>{@link android.widget.Gallery Gallery} </td> + <td>A horizontal scrolling display of images, from a bound list. </td> + </tr> + <tr> + <td>{@link android.widget.GridView GridView} </td> + <td>Displays a scrolling grid of m columns and n rows.</td> + </tr> + <tr> + <td>{@link android.widget.LinearLayout LinearLayout} </td> + <td>A layout that organizes its children into a single horizontal or vertical + row. It creates a scrollbar if the length of the window exceeds the length + of the screen. </td> + </tr> + <tr> + <td>{@link android.widget.ListView ListView} </td> + <td>Displays a scrolling single column list. </td> + </tr> + <tr> + <td>{@link android.widget.RelativeLayout RelativeLayout} </td> + <td>Enables you to specify the location of child objects relative to each + other (child A to the left of child B) or to the parent (aligned to the + top of the parent). </td> + </tr> + <tr> + <td>{@link android.widget.ScrollView ScrollView} </td> + <td>A vertically scrolling column of elements. </td> + </tr> + <tr> + <td>{@link android.widget.Spinner Spinner} </td> + <td>Displays a single item at a time from a bound list, inside a one-row + textbox. Rather like a one-row listbox that can scroll either horizontally + or vertically. </td> + </tr> + <tr> + <td>{@link android.view.SurfaceView SurfaceView} </td> + <td>Provides direct access to a dedicated drawing surface. It can hold child + views layered on top of the surface, but is intended for applications + that need to draw pixels, rather than using widgets. </td> + </tr> + <tr> + <td>{@link android.widget.TabHost TabHost} </td> + <td>Provides a tab selection list that monitors clicks and enables the application + to change the screen whenever a tab is clicked. </td> + </tr> + <tr> + <td>{@link android.widget.TableLayout TableLayout} </td> + <td>A tabular layout with an arbitrary number of rows and columns, each cell + holding the widget of your choice. The rows resize to fit the largest + column. The cell borders are not + visible. </td> + </tr> + <tr> + <td>{@link android.widget.ViewFlipper ViewFlipper} </td> + <td>A list that displays one item at a time, inside a one-row textbox. It + can be set to swap items at timed intervals, like a slide show. </td> + </tr> + <tr> + <td>{@link android.widget.ViewSwitcher ViewSwitcher} </td> + <td>Same as ViewFlipper. </td> + </tr> +</table> diff --git a/docs/html/guide/topics/views/themes.jd b/docs/html/guide/topics/views/themes.jd new file mode 100644 index 0000000..7c2e973 --- /dev/null +++ b/docs/html/guide/topics/views/themes.jd @@ -0,0 +1,88 @@ +page.title=Applying Styles and Themes to Your Application +@jd:body + +<p>When designing your application, you can use <em>styles</em> and <em>themes</em> to apply uniform formatting to its various screens and UI elements. + +<ul> +<li>A style is a set of one or more formatting attributes that you can apply as a unit to single elements in your layout XML file(s). For example, you could define a style that specifies a certain text size and color, then apply it to instances of a certain type of View element. </li> +<li>A theme is a set of one or more formatting attributes that you can apply as a unit to all Activities in an application or to a single Activity. For example, you could define a theme that sets specific colors for the window frame and the panel foreground and background, and sets text sizes and colors for menus, then apply it to the Activities of your application.</li> +</ul> + +<p>Styles and themes are resources — Android provides a variety default style and theme resources that you can use, or you can declare your own custom style and theme resources. + +<p>To create custom styles and themes, you declare new resources in an XML file, stored in the your application's <code>res/values</code> directory. You can then reference the custom resources from your other XML resources or manifest or from application code. When declaring styles and themes, in an XML file, you use the same container element — a <code><style></code> element. Inside, you declare format values in one or more <code><item></code> elements.</p> + +<p>Here's an example declaration of a style: </p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <style name="SpecialText" parent="@style/Text"> + <item name="android:textSize">18sp</item> + <item name="android:textColor">#008</item> + </style> +</resources> +</pre> + +<p>As shown, you can use <code><item></code> elements to set formatting values for the style. The <code>name</code> attribute can refer to a standard string, a hex color value, or a reference to any other resource type.</p> + +<p>Note the <code>parent</code> attribute in the <code>style</code> element. This attribute lets you specify a resource from which the current style will inherit values. The style can inherit from any type of resource that holds the style(s) you want. In general, your styles should always inherit (directly or indirectly) from a standard Android style resource, so that you only have to define the values that you want to change.</p> + +<p>Here's how you would reference the custom style from a resource delared in XML, in this case, an EditText element:</p> + +<pre><EditText id="@+id/text1" + style="@style/SpecialText" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:text="Hello, World!" /></pre> + +<p>Themes are declared in <code><style></code> elements also, and are referenced in the same manner, except that you can add a <code>style</code> attribute only to <code><application></code> and <code><activity></code> elements. If you do not explicitly specify a theme, the Android system applies default theme defined by {@link android.R.style#Theme}.</p> + +<p>Here's an example of how you would set a theme for all the activites of your application. The example applies a default system theme <code>Theme.Translucent</code>.</p> + +<pre> +<!-- AndroidManifest.xml--> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.android.home"> + <application android:theme="@android:style/Theme.Translucent" > + <activity class=".Home" + ... + </activity> + </application> +</manifest> +</pre> + +<p>You can also load a theme for an Activity programmatically, if needed. +To do so, use the {@link android.app.Activity#setTheme(int) setTheme()} +method. Note that, when doing so, be sure to set the theme <em>before</em> +instantiating any Views in the context, for example, before calling +setContentView(View) or inflate(int, ViewGroup). This ensures that +the system applies the same theme for all of your UI screens. Here's an example:</p> + +<pre> + protected void onCreate(Bundle icicle) { + super.onCreate(icicle); + ... + setTheme(android.R.style.Theme_Light); + setContentView(R.layout.linear_layout_3); +} +</pre> + +<p>If you are considering loading a theme programmatically for the main +screen of your application, note that the theme would not be applied +in any animations the system would use to show the activity, which +would take place before your application starts. In most cases, if +you want to apply a theme to your main screen, doing so in XML + is a better approach. </p> + +<p>For detailed information about custom styles and themes and referencing them from your application, see +<a href="{@docRoot}reference/available-resources.html#stylesandthemes">Style +and Theme Resources</a>.</p> + +<p>For information about default themes and styles available, see {@link android.R.style}.</p> + + + + + + diff --git a/docs/html/guide/topics/views/ui-events.jd b/docs/html/guide/topics/views/ui-events.jd new file mode 100644 index 0000000..4230314 --- /dev/null +++ b/docs/html/guide/topics/views/ui-events.jd @@ -0,0 +1,31 @@ +page.title=Handling UI Events +@jd:body + +<p>Many Android classes declare callback methods for handling relevant UI events such as keypresses, touch events, focus changes, and so on. For example, {@link android.app.Activity Activity} provides the methods onKeyDown() and onKeyUp() and {@link android.widget.TextView TextView} provides onFocusChanged(). </p> + +<p>In most cases, you can handle events just by overriding the appropriate handler methods. When an event is received, the Android system calls your handler method with the event data.</p> + +<p>However, some classes do not declare handler methods for specific events. For example, {@link android.widget.Button Button} does not declare an onClick() handler method. To handle such events, you need to create an anonymous class to act as a listener for the event, then register the listener with the target class object. The example below shows how to set up a handler for click events in a Button object. </p> + + + +</p> +<pre>public class ExampleSendResult extends Activity +{ + protected void onCreate(Bundle savedValues) + { + ... + + // Listen for button clicks. + Button button = (Button)findViewById(R.id.corky); + button.setOnClickListener(mCorkyListener); + } + + // Create an anonymous class to act as a button click listener. + private OnClickListener mCorkyListener = new OnClickListener() + { + public void onClick(View v) + { + //handle click event... + } + };</pre> diff --git a/docs/html/guide/topics/views/ui-xml.jd b/docs/html/guide/topics/views/ui-xml.jd new file mode 100644 index 0000000..f0a23c9 --- /dev/null +++ b/docs/html/guide/topics/views/ui-xml.jd @@ -0,0 +1,131 @@ +page.title=Declaring a UI in XML +@jd:body + +<p>You can create your application's user interface in two ways: +<ul> +<li>You can declare UI elements statically, in XML. Android provides a straightforward XML vocabulary that corresponds to the View classes and subclasses, such as those for widgets and layouts. </li> +<li>You can instantiate screen elements dynamically, at runtime, through code in your application. Your application can refer to or create View or other class objects and manipulate their properties programmatically. </li> +</ul> + +<p>One advantage of declaring your UI in XML is that it enables you to better separate the presentation of your application from the code that controls it's behavior. Your UI description is external to your application code, which means that you can modify or adapt it without having to modify your source code and recompile. For example, you can create XML layouts for different screen orientations and for a variety of device screen sizes or languages. Additionally, declaring in XML makes it easier to see the elements and structure of your UI, so it's easier to debug problems. </p> + +<p>The Android framework gives you the flexibility to use either or both of these ways of declaring and managing your application's UI. For example, you could declare your application's default layouts in XML, including the screen elements that will appear in them and their properties. You could then add code in your application that would modify the state of the screen objects, including those declared in XML, at run time. </p> + +<p>You build your application's UI in approximately the same way, whether you are declaring it in XML or programmatically. In both cases, your UI will be a tree structure that may include multiple View or Viewgroup subclasses. <p> + +<p>In general, the XML vocabulary for declaring UI elements closely follows the structure and naming of the framework's UI-related classes and methods, where element names correspond to class names and attribute names correspond to methods. In fact, the correspondence is often so direct that you can guess what XML attribute corresponds to a class method, or guess what class corresponds to a given xml element. </p> + +<p>However, note that the XML vocabulary for defining UI is not entirely identical to the framework's classes and methods. In some cases, there are slight naming differences. For +example, the EditText element has a <code>text</code> attribute that corresponds to +EditText.setText. </p> + +<div class="sidebox"><p>For your convenience, the API reference documentation for UI related classes lists the available XML attributes that correspond to the class methods, including inherited attributes.</p> + +<p>To learn more about the available XML elements and attributes, as well as the format of the XML file, see <a +href="{@docRoot}reference/available-resources.html#layoutresources">Layout Resources</a>.</p> + </div> + +<p>Using Android's XML vocabulary, you can quickly design UI layouts and the screen elements they contain, in the same way you create HTML files — as a series of nested tags. </p> + +<p>Each layout file must contain exactly one root element, and the root element must be a View or ViewGroup object. Once you've defined the root element, you can add additional layout objects or controls as child elements of the root element, if needed. In the example below, the tree of XML elements evaluates to the outermost LinearLayout object. + +<p>After you've declared your layout in XML, you must save the file, with the <code>.xml</code> extension, in the proper location, so that it will be compiled correctly. The proper location for storing layout files is in your application's <code>res/layout/</code> directory. </p> + +<p>When you compile your application, each XML layout file is compiled into an +android.view.View resource. You can then load the layout resource from your application code, by calling <code>setContentView(R.layout.<em>layout_file_name</em>)</code> in your {@link android.app.Activity#onCreate(android.os.Bundle) Activity.onCreate()} +implementation.</p> + +<p>When you load a layout resource, the Android system initializes run-time objects corresponding to the elements in your layout. It parses the elements of your layout in-order (depth-first), instantiating the Views and adding them to their parent(s). </p> + +<p>Attributes named <code>layout_<em>something</em></code> apply to that +object's LayoutParams member. <a href="{@docRoot}reference/available-resources.html#layoutresources">Layout +Resources</a> also describes how to learn the syntax for specifying +LayoutParams properties. </p> + +<p>Also note that Android draws elements in the order in which they +appear in the XML. Therefore, if elements overlap, the last one in the XML +file will probably be drawn on top of any previously listed elements in that +same space.</p> + +<p>The following values are supported for dimensions (described in {@link +android.util.TypedValue TypedValue}):</p> + +<ul> + <li>px (pixels) </li> + <li>dip (device independent pixels) </li> + <li>sp (scaled pixels — best for text size) </li> + <li>pt (points) </li> + <li>in (inches) </li> + <li>mm (millimeters) </li> +</ul> + +<p>Example: <code>android:layout_width="25px"</code> </p> + +<p>For more information about these dimensions, see <a href="{@docRoot}reference/available-resources.html#dimension">Dimension Values</a>.</p> + +<p>The example below shows an XML file and the resulting screen in the UI. Note that the text on the +top of the screen was set by calling {@link +android.app.Activity#setTitle(java.lang.CharSequence) Activity.setTitle}. Note +that the attributes that refer to relative elements (i.e., layout_toLeft) +refer to the ID using the syntax of a relative resource +(@id/<em>id_number</em>). </p> + +<table border="1"> + <tr> + <td> + <pre><?xml version="1.0" encoding="utf-8"?> +<!-- Demonstrates using a relative layout to create a form --> +<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:background="@drawable/blue" + android:padding="10px"> + + <TextView id="@+id/label" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:text="Type here:"/> + + <EditText id="@+id/entry" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:background="@android:drawable/editbox_background" + android:layout_below="@id/label"/> + + <Button id="@+id/ok" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:layout_below="@id/entry" + android:layout_alignParentRight="true" + android:layout_marginLeft="10px" + android:text="OK" /> + + <Button android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:layout_toLeftOf="@id/ok" + android:layout_alignTop="@id/ok" + android:text="Cancel" /> +</RelativeLayout></pre></td> + <td><img src="{@docRoot}images/designing_ui_layout_example.png" alt="Screen shot showing how this layout XML file is rendered." /></td> + </tr> +</table> + +<h3>Loading the XML Resource </h3> + +<p>Loading the compiled layout resource is very easy, and done with a single +call in the activity's onCreate() method, as shown here:</p> + +<pre> +protected void onCreate(Bundle savedValues) +{ + // Be sure to call the super class. + super.onCreate(savedValues); + + // Load the compiled layout resource into the window's + // default ViewGroup. + // The source file is res/layout/hello_activity.xml + setContentView(R.layout.hello_activity); + + // Retrieve any important stored values. + restoreValues(savedValues); +} </pre> diff --git a/docs/html/guide/tutorials/hello-android.jd b/docs/html/guide/tutorials/hello-android.jd new file mode 100644 index 0000000..c37d6f9 --- /dev/null +++ b/docs/html/guide/tutorials/hello-android.jd @@ -0,0 +1,473 @@ +page.title=Hello, Android! +@jd:body + +<p>First impressions matter, and as a developer you know that the first impression +you get of a development framework is how easy it is to write "Hello, +World!" Well, in Android, it's pretty easy. Here's how it looks:</p> + +<ul> + <li><a href="#create">Create the Project</a></li> + <li><a href="#ui">Construct the UI</a></li> + <li><a href="#run">Run the Code: Hello, Android</a></li> +</ul> + +<p>The sections below spell it all out in detail. </p> + +<ul> + <li><a href="#upgrading">Upgrading the UI to an XML Layout</a> </li> + <li><a href="#debugging">Debugging Your Project</a> </li> + <li><a href="#noeclipse">Creating a Project without Eclipse</a> </li> +</ul> +<p>Let's jump in!</p> + +<a name="create"></a> + +<h2>Create the Project </h2> + +<p>Creating the project is as simple as can be. An Eclipse +plugin is available making Android development a snap. </p> + +<p>You'll need to have a development computer with the Eclipse IDE installed (see <a +href="{@docRoot}intro/installing.html#developmentrequirements">System and Software Requirements</a>), and +you'll need to install the <a +href="{@docRoot}intro/installing.html#installingplugin">Android Eclipse Plugin (ADT)</a>. Once you have those ready, come back here. </p> + +<p>First, here's a high-level summary of how to build "Hello, World!":</p> + +<ol> + <li> + Create a new "Android Project" via the <strong>File > New > Project</strong> menu. + </li> + <li> + Fill out the project details in the New Android Project dialog. + </li> + <li> + Edit the auto-generated source code template to display some output. + </li> +</ol> +<p> That's it! Next, let's go through each step above in detail. </p> +<ol class="listhead"> + <li>Create a new Android Project + <p>From Eclipse, select the <strong>File > New > Project</strong> menu item. If the Android + Plugin for Eclipse has been successfully installed, the resulting dialog + should have a folder labeled "Android" which should contain a single entry: + "Android Project".</p> + + <p><img src="{@docRoot}images/hello_world_0.png"/></p> + + <p>Once you've selected "Android Project", click the Next button.</p> + </li> + + <li>Fill out the project details + <p>The next screen allows you to enter the relevant details for your project. + Here's an example:</p> + + <p><img src="{@docRoot}images/hello_world_1.png"/></p> + + <p>Here's what each field on this screen means:</p> + + + <table> + <tbody> + <tr> + <td>Project Name </td> + <td>This is the name of the directory or folder on your computer that you + want to contain the project.</td> + </tr> + <tr> + <td>Package Name </td> + <td>This is the package namespace (following the same rules as for + packages in the Java programming language) that you want all your source code to + reside under. This also sets the package name under which the stub + Activity will be generated.<p/> + The package name you use in your application must be unique across + all packages installed on the system; for this reason, it's very + important to use a standard domain-style package for your + applications. In the example above, we used the + package domain "com.android"; you should use a + different one appropriate to your organization.</td> + </tr> + <tr> + <td>Activity Name </td> + <td>This is the name for the class stub that will be generated by the plugin. + This will be a subclass of Android's Activity class. An Activity is simply a + class that can run and do work. It can create a UI if it chooses, but it + doesn't need to. </td> + </tr> + <tr> + <td> Application Name </td> + <td> This is the human-readable title for your application. </td> + </tr> + </tbody> + </table> + +<p>The checkbox for toggling "Use default location" allows you to change the +location on disk where the project's files will be generated and stored.</p> +</li> + +<li>Edit the auto-generated source code + +<p>After the plugin runs, you'll have a class named HelloAndroid +(found in your package, HelloAndroid > src > com.android.hello). It should look like +this:</p> + +<pre>public class HelloAndroid extends Activity { + /** Called when the activity is first created. */ + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + } +}</pre> + +<p>Now, you <em>could</em> run this right away, but let's go a little further, +so we understand more about what's happening. +So, the next step is to modify some code! </p> +</li> +</ol> + +<a name="ui"></a> + +<h2>Construct the UI</h2> + +<p>Take a look at this revised code, below, and make the same changes to your HelloAndroid.java file. We'll dissect +it line by line:</p> + +<pre> +package com.android.hello; + +import android.app.Activity; +import android.os.Bundle; +import android.widget.TextView; + +public class HelloAndroid extends Activity { + /** Called when the activity is first created. */ + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + TextView tv = new TextView(this); + tv.setText("Hello, Android"); + setContentView(tv); + } +}</pre> + +<p class="note"><strong>Tip:</strong> If you forgot to import the TextView package, try this: +press <strong>Ctrl-Shift-O</strong> (<strong>Cmd-Shift-O</strong>, on Mac). This is an Eclipse +shortcut to organize imports—it identifies missing packages and adds them for you.</p> + +<p>In Android, user interfaces are composed of hierarchies of classes called +Views. A View is simply a drawable object, such as a radio button, an +animation, or (in our case) a text label. The specific name for the View +subclass that handles text is simply TextView.</p> + +<p>Here's how you construct a TextView:</p> + +<pre>TextView tv = new TextView(this);</pre> + +<p>The argument to TextView's constructor is an Android Context instance. The +Context is simply a handle to the system; it provides services like +resolving resources, obtaining access to databases and preferences, and so +on. The Activity class inherits from Context. Since our +HelloAndroid class is a subclass of Activity, it is also a Context, and so we can +pass the <code>this</code> reference to the TextView.</p> + +<p>Once we've constructed the TextView, we need to tell it what to display:</p> + +<pre>tv.setText("Hello, Android");</pre> + +<p>Nothing too surprising there.</p> + +<p>At this point, we've constructed a TextView and told it what text to +display. The final step is to connect this TextView with the on-screen +display, like so:</p> + +<pre>setContentView(tv);</pre> + +<p>The <code>setContentView()</code> method on Activity indicates to the system which +View should be associated with the Activity's UI. If an Activity doesn't +call this method, no UI is present at all and the system will display a blank +screen. For our purposes, all we want is to display some text, so we pass it +the TextView we just created.</p> + +<p>There it is — "Hello, World" in Android! The next step, of course, is +to see it running.</p> + +<a name="run"></a> + +<h2>Run the Code: Hello, Android</h2> + +<p>The Eclipse plugin makes it very easy to run your applications. Begin by +selecting the <strong>Run > Open Run Dialog</strong> menu entry (in Eclipse 3.4, it's +<strong>Run > Run Configurations</strong>). You should see a dialog +like this:</p> + +<div id="o.:l" style="PADDING:1em 0pt; TEXT-ALIGN:left"> + <img src="{@docRoot}images/hello_world_2.png"/> +</div> + +<p>Next, highlight the "Android Application" entry, and then click the icon in the +top left corner (the one depicting a sheet of paper with a plus sign in the +corner) or simply double-click the "Android Application" entry. You should +have a new launcher entry named "New_configuration".</p> + +<div id="z4_b" style="PADDING:1em 0pt; TEXT-ALIGN:left"> + <img src="{@docRoot}images/hello_world_3.png"/> +</div> + +<p>Change the name to something expressive, like "Hello, Android", and then pick +your project by clicking the Browse button. (If you have more than one +Android project open in Eclipse, be sure to pick the right one.) The +plugin will automatically scan your project for Activity subclasses, and add +each one it finds to the drop-down list under the "Activity:" label. Since +your "Hello, Android" project only has one, it will be the default, and you can +simply continue.</p> + +<p>Click the "Apply" button. Here's an example:</p> + +<div id="t66_" style="PADDING:1em 0pt; TEXT-ALIGN:left"> + <img src="{@docRoot}images/hello_world_4.png"/> +</div> + +<p>That's it — you're done! Click the Run button, and the Android Emulator +should start. Once it's booted up your application will appear. When all is said and done, you should +see something like this:</p> + +<div id="qnhl" style="PADDING:1em 0pt; TEXT-ALIGN:left"> + <img src="{@docRoot}images/hello_world_5.png"/> +</div> + +<p>That's "Hello, World" in Android. Pretty straightforward, eh? +The next sections of the tutorial offer more detailed information that you may find valuable as you +learn more about Android.</p> + +<a name="upgrading"></a> + +<h2>Upgrading the UI to an XML Layout</h2> + +<p>The "Hello, World" example you just completed uses what we call "programmatic" +UI layout. This means that you construct and build your application's UI +directly in source code. If you've done much UI programming, you're +probably familiar with how brittle that approach can sometimes be: small +changes in layout can result in big source-code headaches. It's also very +easy to forget to properly connect Views together, which can result in errors in +your layout and wasted time debugging your code.</p> + +<p>That's why Android provides an alternate UI construction model: XML-based +layout files. The easiest way to explain this concept is to show an +example. Here's an XML layout file that is identical in behavior to the +programmatically-constructed example you just completed:</p> + +<pre><?xml version="1.0" encoding="utf-8"?> +<TextView xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:text="Hello, Android"/></pre> + +<p>The general structure of an Android XML layout file is simple. It's a tree +of tags, where each tag is the name of a View class. In this example, it's +a very simple tree of one element, a TextView. You can use the +name of any class that extends View as a tag name in your XML layouts, +including custom View classes you define in your own code. This +structure makes it very easy to quickly build up UIs, using a much simpler +structure and syntax than you would in source code. This model is inspired +by the web development model, where you can separate the presentation of your +application (its UI) from the application logic used to fetch and fill in data.</p> + +<p>In this example, there are also four XML attributes. Here's a summary of what +they mean:</p> + +<table> + <tbody> + <tr> + <th> + Attribute + </th> + <th> + Meaning + </th> + </tr> + <tr> + <td> + <code>xmlns:android</code> + </td> + <td> + This is an XML namespace declaration that tells the Android tools that you are going to refer to common attributes defined in the Android namespace. The outermost tag in every Android layout file must have this attribute.<br> + </td> + </tr> + <tr> + <td> + <code>android:layout_width</code> + </td> + <td> + This attribute defines how much of the available width on the screen this View should consume. In this case, it's our only View so we want it to take up the entire screen, which is what a value of "fill_parent" means.<br> + </td> + </tr> + <tr> + <td> + <code>android:layout_height</code> + </td> + <td> + This is just like android:layout_width, except that it refers to available screen height. + </td> + </tr> + <tr> + <td> + <code>android:text</code> + </td> + <td> + This sets the text that the TextView should contain. In this example, it's our usual "Hello, Android" message. + </td> + </tr> + </tbody> +</table> + + +<p>So, that's what the XML layout looks like, but where do you put it? Under the /res/layout directory in your project. The "res" is +short for "resources" and that directory contains all the non-code assets that +your application requires. This includes things like images, localized +strings, and XML layout files.</p> + +<p>The Eclipse plugin creates one of these XML files for you. In our example +above, we simply never used it. In the Package Explorer, expand the +folder /res/layout, and edit the file main.xml. Replace its contents with +the text above and save your changes.</p> + +<p>Now open the file named R.java in your source code folder in the Package +Explorer. You'll see that it now looks something like this:</p> + +<pre> +public final class R { + public static final class attr { + }; + public static final class drawable { + public static final int icon=0x7f020000; + }; + public static final class layout { + public static final int main=0x7f030000; + }; + public static final class string { + public static final int app_name=0x7f040000; + }; +}; +</pre> + +<p>A project's R.java file is an index into all the resources defined in the +file. You use this class in your source code as a sort of short-hand +way to refer to resources you've included in your project. This is +particularly powerful with the code-completion features of IDEs like Eclipse +because it lets you quickly and interactively locate the specific reference +you're looking for.</p> + +<p>The important thing to notice for now is the inner class named "layout", and its +member field "main". The Eclipse plugin noticed that you added a new XML +layout file and then regenerated this R.java file. As you add other +resources to your projects you'll see R.java change to keep up.</p> + +<p>The last thing you need to do is modify your HelloAndroid source code to use the new +XML version of your UI, instead of the hard-coded version. Here's what +your new class will look like. As you can see, the source code becomes much +simpler:</p> + +<pre>package com.android.hello; + +import android.app.Activity; +import android.os.Bundle; + +public class HelloAndroid extends Activity { + /** Called when the activity is first created. */ + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + } +}</pre> + +<p>When you make this change, don't just copy-and-paste it in. Try out the code-completion feature on that R class. You'll probably find that it helps a lot.</p> + +<p>Now that you've made this change, go ahead and re-run your application — all +you need to do is click the green Run arrow icon, or select +<strong>Run > Run History > Hello, Android</strong> from the menu. You should see.... well, exactly the same thing +you saw before! After all, the point was to show that the two different +layout approaches produce identical results.</p> + +<p>There's a lot more to creating these XML layouts, but that's as far as we'll go +here. Read the <a +href="{@docRoot}devel/implementing-ui.html">Implementing a User Interface</a> documentation for more +information on the power of this approach.</p> + +<a name="debugging"></a> + +<h2>Debugging Your Project</h2> + +<p>The Android Plugin for Eclipse also has excellent integration with the Eclipse +debugger. To demonstrate this, let's introduce a bug into +our code. Change your HelloAndroid source code to look like this:</p> + +<pre> +package com.android.hello; + +import android.app.Activity; +import android.os.Bundle; + +public class HelloAndroid extends Activity { + /** Called when the activity is first created. */ + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + Object o = null; + o.toString(); + setContentView(R.layout.main); + } +}</pre> + +<p>This change simply introduces a NullPointerException into your code. If +you run your application again, you'll eventually see this:</p> + +<div id="go-9" style="PADDING:1em 0pt; TEXT-ALIGN:left"> + <img src="{@docRoot}images/hello_world_8.png"/> +</div> + +<p>Press "Force Quit" to terminate the application and close the emulator window.</p> + +<p>To find out more about the error, set a breakpoint in your source code +on the line <code>Object o = null;</code> (double-click on the marker bar next to the source code line). Then select <strong>Run > Debug History > Hello, +Android</strong> from the menu to enter debug mode. Your app will restart in the +emulator, but this time it will suspend when it reaches the breakpoint you +set. You can then step through the code in Eclipse's Debug Perspective, +just as you would for any other application.</p> + +<div id="w2c9" style="PADDING:1em 0pt; TEXT-ALIGN:left"> + <img src="{@docRoot}images/hello_world_9.png"/> +</div> + +<a name="noeclipse"></a> + +<h2>Creating the Project without Eclipse</h2> + +<p>If you don't use Eclipse (such as if you prefer another IDE, or simply use text +editors and command line tools) then the Eclipse plugin can't help you. +Don't worry though — you don't lose any functionality just because you don't +use Eclipse.</p> + +<p>The Android Plugin for Eclipse is really just a wrapper around a set of tools +included with the Android SDK. (These tools, like the emulator, aapt, adb, +ddms, and others are <a href="tools.html">documented elsewhere.</a>) Thus, it's possible to +wrap those tools with another tool, such as an 'ant' build file.</p> + +<p>The Android SDK includes a Python script named "activitycreator.py" that can be +used to create all the source code and directory stubs for your project, as well +as an ant-compatible build.xml file. This allows you to build your project +from the command line, or integrate it with the IDE of your choice.</p> + +<p>For example, to create a HelloAndroid project similar to the one we just created +via Eclipse, you'd use this command:</p> + +<pre>activitycreator.py --out HelloAndroid com.android.hello.HelloAndroid</pre> + +<p>To build the project, you'd then run the command 'ant'. When that command +successfully completes, you'll be left with a file named HelloAndroid.apk under +the 'bin' directory. That .apk file is an Android Package, and can be +installed and run in your emulator using the 'adb' tool.</p> + +<p>For more information on how to use these tools, please read the documentation +cited above.</p> diff --git a/docs/html/guide/tutorials/hello-world.jd b/docs/html/guide/tutorials/hello-world.jd new file mode 100644 index 0000000..ae0d8b5 --- /dev/null +++ b/docs/html/guide/tutorials/hello-world.jd @@ -0,0 +1,461 @@ +page.title=Hello, World +@jd:body + +<p>First impressions matter, and as a developer you know that the first impression +you get of a development framework is how easy it is to write "Hello, +World." Well, on Android, it's pretty easy. Here's the simple process:</p> + +<ol> + <li><a href="#create">Create the Project</a></li> + <li><a href="#ui">Construct the UI</a></li> + <li><a href="#run">Run the Code: Hello, Android</a></li> +</ol> + +<p>Afterwards, there's some additional information that you'll find useful:</p> + +<ol> + <li><a href="#upgrading">Upgrading the UI to an XML Layout</a> </li> + <li><a href="#debugging">Debugging Your Project</a> </li> + <li><a href="#noeclipse">Creating a Project without Eclipse</a> </li> +</ol> +<p>Let's jump in!</p> + +<a name="create"></a> + +<h2>Create the Project </h2> + +<p>Creating the project is as simple as can be. An Eclipse +plugin is available making Android development a snap. </p> + +<p>You'll need to have a development computer with the Eclipse IDE installed (see <a +href="intro/installing.html#developmentrequirements">System and Software Requirements</a>), and +you'll need to install the <a +href="intro/installing.html#installingplugin">Android Eclipse Plugin (ADT)</a>. Once you have those ready, come back here. </p> + +<p>First, here's a high-level summary of how to build "Hello, World!":</p> + +<ol> + <li> + Create a new "Android Project" via the <strong>File > New > Project</strong> menu. + </li> + <li> + Fill out the project details in the New Android Project dialog. + </li> + <li> + Edit the auto-generated source code template to display some output. + </li> +</ol> +<p> That's it! Next, let's go through each step above in detail. </p> +<ol class="listhead"> + <li>Create a new Android Project + <p>From Eclipse, select the <strong>File > New > Project</strong> menu item. If the Android + Plugin for Eclipse has been successfully installed, the resulting dialog + should have a folder labeled "Android" which should contain a single entry: + "Android Project".</p> + + <img src="images/hello_world_0.png"/> + + <p>Once you've selected "Android Project", click the Next button.</p> + </li> + + <li>Fill out the project details + <p>The next screen allows you to enter the relevant details for your project. + Here's an example:</p> + + <img src="images/hello_world_1.png"/> + + <p>Here's what each field on this screen means:</p> + + + <table> + <tbody> + <tr> + <td>Project Name </td> + <td>This is the name of the directory or folder on your computer that you + want to contain the project.</td> + </tr> + <tr> + <td>Package Name </td> + <td>This is the package namespace (following the same rules as for + packages in the Java programming language) that you want all your source code to + reside under. This also sets the package name under which the stub + Activity will be generated.<p/> + The package name you use in your application must be unique across + all packages installed on the system; for this reason, it's very + important to use a standard domain-style package for your + applications. In the example above, we used the + package domain "com.android"; you should use a + different one appropriate to your organization.</td> + </tr> + <tr> + <td>Activity Name </td> + <td>This is the name for the class stub that will be generated by the plugin. + This will be a subclass of Android's Activity class. An Activity is simply a + class that can run and do work. It can create a UI if it chooses, but it + doesn't need to. </td> + </tr> + <tr> + <td> Application Name </td> + <td> This is the human-readable title for your application. </td> + </tr> + </tbody> + </table> + +<p>The checkbox for toggling "Use default location" allows you to change the +location on disk where the project's files will be generated and stored.</p> +</li> + +<li>Edit the auto-generated source code + +<p>After the plugin runs, you'll have a class named HelloAndroid +(found in your package, HelloAndroid > src > com.android.hello). It should look like +this:</p> + +<pre>public class HelloAndroid extends Activity { + /** Called when the activity is first created. */ + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + } +}</pre> + +<p>Now, you <em>could</em> run this right away, but let's go a little further, +so we understand more about what's happening. +So, the next step is to modify some code! </p> +</li> +</ol> + +<a name="ui"></a> + +<h2>Construct the UI</h2> + +<p>Take a look at this revised code, below, and make the same changes to your HelloAndroid.java file. We'll dissect +it line by line:</p> + +<pre> +package com.android.hello; + +import android.app.Activity; +import android.os.Bundle; +import android.widget.TextView; + +public class HelloAndroid extends Activity { + /** Called when the activity is first created. */ + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + TextView tv = new TextView(this); + tv.setText("Hello, Android"); + setContentView(tv); + } +}</pre> + +<p class="note"><strong>Tip:</strong> If you forgot to import the TextView package, try this: +press <strong>Ctrl-Shift-O</strong> (<strong>Cmd-Shift-O</strong>, on Mac). This is an Eclipse +shortcut to organize imports—it identifies missing packages and adds them for you.</p> + +<p>In Android, user interfaces are composed of hierarchies of classes called +Views. A View is simply a drawable object, such as a radio button, an +animation, or (in our case) a text label. The specific name for the View +subclass that handles text is simply TextView.</p> + +<p>Here's how you construct a TextView:</p> + +<pre>TextView tv = new TextView(this);</pre> + +<p>The argument to TextView's constructor is an Android Context instance. The +Context is simply a handle to the system; it provides services like +resolving resources, obtaining access to databases and preferences, and so +on. The Activity class inherits from Context. Since our +HelloAndroid class is a subclass of Activity, it is also a Context, and so we can +pass the <code>this</code> reference to the TextView.</p> + +<p>Once we've constructed the TextView, we need to tell it what to display:</p> + +<pre>tv.setText("Hello, Android");</pre> + +<p>Nothing too surprising there.</p> + +<p>At this point, we've constructed a TextView and told it what text to +display. The final step is to connect this TextView with the on-screen +display, like so:</p> + +<pre>setContentView(tv);</pre> + +<p>The <code>setContentView()</code> method on Activity indicates to the system which +View should be associated with the Activity's UI. If an Activity doesn't +call this method, no UI is present at all and the system will display a blank +screen. For our purposes, all we want is to display some text, so we pass it +the TextView we just created.</p> + +<p>There it is — "Hello, World" in Android! The next step, of course, is +to see it running.</p> + +<a name="run"></a> + +<h2>Run the Code: Hello, Android</h2> + +<p>The Eclipse plugin makes it very easy to run your applications. Begin by +selecting the <strong>Run > Open Run Dialog</strong> menu entry (in Eclipse 3.4, it's +<strong>Run > Run Configurations</strong>). You should see a dialog +like this:</p> + + <img src="images/hello_world_2.png"/> + +<p>Next, highlight the "Android Application" entry, and then click the icon in the +top left corner (the one depicting a sheet of paper with a plus sign in the +corner) or simply double-click the "Android Application" entry. You should +have a new launcher entry named "New_configuration".</p> + + <img src="images/hello_world_3.png"/> + +<p>Change the name to something expressive, like "Hello, Android", and then pick +your project by clicking the Browse button. (If you have more than one +Android project open in Eclipse, be sure to pick the right one.) The +plugin will automatically scan your project for Activity subclasses, and add +each one it finds to the drop-down list under the "Activity:" label. Since +your "Hello, Android" project only has one, it will be the default, and you can +simply continue.</p> + +<p>Click the "Apply" button. Here's an example:</p> + + <img src="images/hello_world_4.png"/> + +<p>That's it — you're done! Click the Run button, and the Android Emulator +should start. Once it's booted up your application will appear. When all is said and done, you should +see something like this:</p> + + <img src="images/hello_world_5.png"/> + +<p>That's "Hello, World" in Android. Pretty straightforward, eh? +The next sections of the tutorial offer more detailed information that you may find valuable as you +learn more about Android.</p> + +<a name="upgrading"></a> + +<h2>Upgrading the UI to an XML Layout</h2> + +<p>The "Hello, World" example you just completed uses what we call "programmatic" +UI layout. This means that you construct and build your application's UI +directly in source code. If you've done much UI programming, you're +probably familiar with how brittle that approach can sometimes be: small +changes in layout can result in big source-code headaches. It's also very +easy to forget to properly connect Views together, which can result in errors in +your layout and wasted time debugging your code.</p> + +<p>That's why Android provides an alternate UI construction model: XML-based +layout files. The easiest way to explain this concept is to show an +example. Here's an XML layout file that is identical in behavior to the +programmatically-constructed example you just completed:</p> + +<pre><?xml version="1.0" encoding="utf-8"?> +<TextView xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:text="Hello, Android"/></pre> + +<p>The general structure of an Android XML layout file is simple. It's a tree +of tags, where each tag is the name of a View class. In this example, it's +a very simple tree of one element, a TextView. You can use the +name of any class that extends View as a tag name in your XML layouts, +including custom View classes you define in your own code. This +structure makes it very easy to quickly build up UIs, using a much simpler +structure and syntax than you would in source code. This model is inspired +by the web development model, where you can separate the presentation of your +application (its UI) from the application logic used to fetch and fill in data.</p> + +<p>In this example, there are also four XML attributes. Here's a summary of what +they mean:</p> + +<table> + <tbody> + <tr> + <th> + Attribute + </th> + <th> + Meaning + </th> + </tr> + <tr> + <td> + <code>xmlns:android</code> + </td> + <td> + This is an XML namespace declaration that tells the Android tools that you are going to refer to common attributes defined in the Android namespace. The outermost tag in every Android layout file must have this attribute.<br> + </td> + </tr> + <tr> + <td> + <code>android:layout_width</code> + </td> + <td> + This attribute defines how much of the available width on the screen this View should consume. In this case, it's our only View so we want it to take up the entire screen, which is what a value of "fill_parent" means.<br> + </td> + </tr> + <tr> + <td> + <code>android:layout_height</code> + </td> + <td> + This is just like android:layout_width, except that it refers to available screen height. + </td> + </tr> + <tr> + <td> + <code>android:text</code> + </td> + <td> + This sets the text that the TextView should contain. In this example, it's our usual "Hello, Android" message. + </td> + </tr> + </tbody> +</table> + + +<p>So, that's what the XML layout looks like, but where do you put it? Under the /res/layout directory in your project. The "res" is +short for "resources" and that directory contains all the non-code assets that +your application requires. This includes things like images, localized +strings, and XML layout files.</p> + +<p>The Eclipse plugin creates one of these XML files for you. In our example +above, we simply never used it. In the Package Explorer, expand the +folder /res/layout, and edit the file main.xml. Replace its contents with +the text above and save your changes.</p> + +<p>Now open the file named R.java in your source code folder in the Package +Explorer. You'll see that it now looks something like this:</p> + +<pre> +public final class R { + public static final class attr { + }; + public static final class drawable { + public static final int icon=0x7f020000; + }; + public static final class layout { + public static final int main=0x7f030000; + }; + public static final class string { + public static final int app_name=0x7f040000; + }; +}; +</pre> + +<p>A project's R.java file is an index into all the resources defined in the +file. You use this class in your source code as a sort of short-hand +way to refer to resources you've included in your project. This is +particularly powerful with the code-completion features of IDEs like Eclipse +because it lets you quickly and interactively locate the specific reference +you're looking for.</p> + +<p>The important thing to notice for now is the inner class named "layout", and its +member field "main". The Eclipse plugin noticed that you added a new XML +layout file and then regenerated this R.java file. As you add other +resources to your projects you'll see R.java change to keep up.</p> + +<p>The last thing you need to do is modify your HelloAndroid source code to use the new +XML version of your UI, instead of the hard-coded version. Here's what +your new class will look like. As you can see, the source code becomes much +simpler:</p> + +<pre>package com.android.hello; + +import android.app.Activity; +import android.os.Bundle; + +public class HelloAndroid extends Activity { + /** Called when the activity is first created. */ + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + } +}</pre> + +<p>When you make this change, don't just copy-and-paste it in. Try out the code-completion feature on that R class. You'll probably find that it helps a lot.</p> + +<p>Now that you've made this change, go ahead and re-run your application — all +you need to do is click the green Run arrow icon, or select +<strong>Run > Run History > Hello, Android</strong> from the menu. You should see.... well, exactly the same thing +you saw before! After all, the point was to show that the two different +layout approaches produce identical results.</p> + +<p>There's a lot more to creating these XML layouts, but that's as far as we'll go +here. Read the <a +href="{@docRoot}devel/implementing-ui.html">Implementing a User Interface</a> documentation for more +information on the power of this approach.</p> + +<a name="debugging"></a> + +<h2>Debugging Your Project</h2> + +<p>The Android Plugin for Eclipse also has excellent integration with the Eclipse +debugger. To demonstrate this, let's introduce a bug into +our code. Change your HelloAndroid source code to look like this:</p> + +<pre> +package com.android.hello; + +import android.app.Activity; +import android.os.Bundle; + +public class HelloAndroid extends Activity { + /** Called when the activity is first created. */ + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + Object o = null; + o.toString(); + setContentView(R.layout.main); + } +}</pre> + +<p>This change simply introduces a NullPointerException into your code. If +you run your application again, you'll eventually see this:</p> + + <img src="images/hello_world_8.png"/> + +<p>Press "Force Quit" to terminate the application and close the emulator window.</p> + +<p>To find out more about the error, set a breakpoint in your source code +on the line <code>Object o = null;</code> (double-click on the marker bar next to the source code line). Then select <strong>Run > Debug History > Hello, +Android</strong> from the menu to enter debug mode. Your app will restart in the +emulator, but this time it will suspend when it reaches the breakpoint you +set. You can then step through the code in Eclipse's Debug Perspective, +just as you would for any other application.</p> + + <img src="images/hello_world_9.png"/> + +<a name="noeclipse"></a> + +<h2>Creating the Project without Eclipse</h2> + +<p>If you don't use Eclipse (such as if you prefer another IDE, or simply use text +editors and command line tools) then the Eclipse plugin can't help you. +Don't worry though — you don't lose any functionality just because you don't +use Eclipse.</p> + +<p>The Android Plugin for Eclipse is really just a wrapper around a set of tools +included with the Android SDK. (These tools, like the emulator, aapt, adb, +ddms, and others are <a href="tools.html">documented elsewhere.</a>) Thus, it's possible to +wrap those tools with another tool, such as an 'ant' build file.</p> + +<p>The Android SDK includes a Python script named "activitycreator.py" that can be +used to create all the source code and directory stubs for your project, as well +as an ant-compatible build.xml file. This allows you to build your project +from the command line, or integrate it with the IDE of your choice.</p> + +<p>For example, to create a HelloAndroid project similar to the one we just created +via Eclipse, you'd use this command:</p> + +<pre>activitycreator.py --out HelloAndroid com.android.hello.HelloAndroid</pre> + +<p>To build the project, you'd then run the command 'ant'. When that command +successfully completes, you'll be left with a file named HelloAndroid.apk under +the 'bin' directory. That .apk file is an Android Package, and can be +installed and run in your emulator using the 'adb' tool.</p> + +<p>For more information on how to use these tools, please read the documentation +cited above.</p> diff --git a/docs/html/guide/tutorials/images/hello_world_0.png b/docs/html/guide/tutorials/images/hello_world_0.png Binary files differnew file mode 100644 index 0000000..94a4c04 --- /dev/null +++ b/docs/html/guide/tutorials/images/hello_world_0.png diff --git a/docs/html/guide/tutorials/images/hello_world_1.png b/docs/html/guide/tutorials/images/hello_world_1.png Binary files differnew file mode 100644 index 0000000..9d28044 --- /dev/null +++ b/docs/html/guide/tutorials/images/hello_world_1.png diff --git a/docs/html/guide/tutorials/images/hello_world_2.png b/docs/html/guide/tutorials/images/hello_world_2.png Binary files differnew file mode 100644 index 0000000..76e7155 --- /dev/null +++ b/docs/html/guide/tutorials/images/hello_world_2.png diff --git a/docs/html/guide/tutorials/images/hello_world_3.png b/docs/html/guide/tutorials/images/hello_world_3.png Binary files differnew file mode 100644 index 0000000..8319374 --- /dev/null +++ b/docs/html/guide/tutorials/images/hello_world_3.png diff --git a/docs/html/guide/tutorials/images/hello_world_4.png b/docs/html/guide/tutorials/images/hello_world_4.png Binary files differnew file mode 100644 index 0000000..164256c --- /dev/null +++ b/docs/html/guide/tutorials/images/hello_world_4.png diff --git a/docs/html/guide/tutorials/images/hello_world_5.png b/docs/html/guide/tutorials/images/hello_world_5.png Binary files differnew file mode 100644 index 0000000..b17ca8b --- /dev/null +++ b/docs/html/guide/tutorials/images/hello_world_5.png diff --git a/docs/html/guide/tutorials/images/hello_world_8.png b/docs/html/guide/tutorials/images/hello_world_8.png Binary files differnew file mode 100644 index 0000000..2429ba0 --- /dev/null +++ b/docs/html/guide/tutorials/images/hello_world_8.png diff --git a/docs/html/guide/tutorials/images/hello_world_9.png b/docs/html/guide/tutorials/images/hello_world_9.png Binary files differnew file mode 100644 index 0000000..e92fb4b --- /dev/null +++ b/docs/html/guide/tutorials/images/hello_world_9.png diff --git a/docs/html/guide/tutorials/index.html b/docs/html/guide/tutorials/index.html new file mode 100644 index 0000000..4881acf --- /dev/null +++ b/docs/html/guide/tutorials/index.html @@ -0,0 +1,8 @@ +<html> +<head> +<meta http-equiv="refresh" content="0;url=../index.html"> +</head> +<body> +<a href="../index.html">click here</a> if you are not redirected. +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/tutorials/notepad/codelab/NotepadCodeLab.zip b/docs/html/guide/tutorials/notepad/codelab/NotepadCodeLab.zip Binary files differnew file mode 100755 index 0000000..86f5e9d --- /dev/null +++ b/docs/html/guide/tutorials/notepad/codelab/NotepadCodeLab.zip diff --git a/docs/html/guide/tutorials/notepad/notepad-ex1.jd b/docs/html/guide/tutorials/notepad/notepad-ex1.jd new file mode 100644 index 0000000..715267f --- /dev/null +++ b/docs/html/guide/tutorials/notepad/notepad-ex1.jd @@ -0,0 +1,588 @@ +page.title=Notepad Exercise 1 +@jd:body + + +<p><em>In this exercise, you will construct a simple notes list that lets the +user add new notes but not edit them. The exercise demonstrates:</em></p> +<ul> +<li><em>The basics of <code>ListActivities</code> and creating and handling menu +options. </em></li> +<li><em>How to use a SQLite database to store the notes.</em></li> +<li><em>How to bind data from a database cursor into a ListView using a +SimpleCursorAdapter.</em></li> +<li><em>The basics of screen layouts, including how to lay out a list view, how +you can add items to the activity menu, and how the activity handles those menu +selections. </em></li> +</ul> + +<div style="float:right;white-space:nowrap"> +<span style="color:#BBB;"> + [<a href="tutorial-ex1.html" style="color:#BBB;">Exercise 1</a>]</span> + [<a href="tutorial-ex2.html">Exercise 2</a>] + [<a href="tutorial-ex3.html">Exercise 3</a>] + [<a href="tutorial-extra-credit.html">Extra Credit</a>] +</div> + + + +<h2>Step 1</h2> + + <p>Open up the <code>Notepadv1</code> project in Eclipse.</p> + + <p><code>Notepadv1</code> is a project that is provided as a starting point. It + takes care of some of the boilerplate work that you have already seen if you + followed the <a href="{@docRoot}intro/hello-android.html">Hello + Android tutorial.</a></p> + + <ol> + <li> + Start a new Android Project by clicking <strong>File</strong> > + <strong>New</strong> > <strong>Android Project</strong>.</li> + <li> + In the New Android Project dialog, select <strong>Create project from existing source</strong>.</li> + <li> + Click <strong>Browse</strong> and navigate to where you copied the <code>NotepadCodeLab</code> + (downloaded during <a href="/android/intro/tutorial.html#preparing">setup</a>). Select + <code>Notepadv1</code> and click <strong>Choose</strong>.</li> + <li> + You should see <code>Notepadv1</code> in the <em>Project name</em> and also see the <em>Location</em> + filled in with the path you selected.</li> + <li> + Click <strong>Finish</strong>. The <code>Notepadv1</code> project should open and be + visible in your Eclipse package explorer.</li> + </ol> + + <p>If you see an error about <code>AndroidManifest.xml</code>, or some + problems related to an Android zip file, right click on the project and + select <strong>Android Tools</strong> > <strong>Fix Project Properties</strong>. + (The project is looking in the wrong location for the library file, + this will fix it for you.)</p> + + <h2>Step 2</h2> + + <div class="sidebox" style="border:2px solid #FFFFDD;float:right; + background-color:#FFFFEE;margin-right:0px; + margin-bottom:.5em;margin-top:1em;padding:0em;width:240px;"> + <h2 style="border:0;font-size:12px;padding:.5em .5em .5em 1em;margin:0; + background-color:#FFFFDD;">Accessing and modifying data</h2> + <p style="padding-left:.5em;font-size:12px;margin:0; padding:.0em .5em .5em 1em;">For this + exercise, we are using a SQLite database to store our data. This is useful + if only <em>your</em> application will need to access or modify the data. If you wish for + other activities to access or modify the data, you have to expose the data using a + {@link android.content.ContentProvider ContentProvider}.</p> + <p style="padding-left:.5em;font-size:12px;margin:0; + padding:.0em .5em .5em 1em;">If you are interested, you can find out more about + <a href="{@docRoot}devel/data/contentproviders.html">content providers</a> or the whole + subject of <a href="{@docRoot}devel/data.html">Storing, Retrieving, and Exposing Data</a>. + The NotePad sample in the <code>samples/</code> folder of the SDK also has an example of how + to create a ContentProvider.</p> + </div> + + <p>Take a look at the <code>NotesDbAdapter</code> class — this class is provided to + encapsulate data access to a SQLite database that will hold our notes data + and allow us to update it.</p> + <p>At the top of the class are some constant definitions that will be used in the application + to look up data from the proper field names in the database. There is also a database creation + string defined, which is used to create a new database schema if one doesn't exist already.</p> + <p>Our database will have the name <code>data</code>, and have a single table called + <code>notes</code>, which in turn has three fields: <code>_id</code>, <code>title</code> and + <code>body</code>. The <code>_id</code> is named with an underscore convention used in a number of + places inside the Android SDK and helps keep a track of state. The <code>_id</code> + usually has to be specified when querying or updating the database (in the column projections + and so on). The other two fields are simple text fields that will store data. + </p> + <p>The constructor for <code>NotesDbAdapter</code> takes a Context, which allows it to communicate with aspects + of the Android operating system. This is quite common for classes that need to touch the + Android system in some way. The Activity class implements the Context class, so usually you will just pass + <code>this</code> from your Activity, when needing a Context.</p> + <p>The <code>open()</code> method calls up an instance of DatabaseHelper, which is our local + implementation of the SQLiteOpenHelper class. It calls <code>getWritableDatabase()</code>, + which handles creating/opening a database for us.</p> + <p><code>close()</code> just closes the database, releasing resources related to the + connection.</p> + <p><code>createNote()</code> takes strings for the title and body of a new note, + then creates that note in the database. Assuming the new note is created successfully, the + method also returns the row <code>_id</code> value for the newly created note.</p> + <p><code>deleteNote()</code> takes a <var>rowId</var> for a particular note, and deletes that note from + the database.</p> + + <p><code>fetchAllNotes()</code> issues a query to return a {@link android.database.Cursor} over all notes in the + database. The <code>query()</code> call is worth examination and understanding. The first field is the + name of the database table to query (in this case <code>DATABASE_TABLE</code> is "notes"). + The next is the list of columns we want returned, in this case we want the <code>_id</code>, + <code>title</code> and <code>body</code> columns so these are specified in the String array. + The remaining fields are, in order: <code>selection</code>, + <code>selectionArgs</code>, <code>groupBy</code>, <code>having</code> and <code>orderBy</code>. + Having these all <code>null</code> means we want all data, need no grouping, and will take the default + order. See {@link android.database.sqlite.SQLiteDatabase SQLiteDatabase} for more details.</p> + <p class="note"><b>Note:</b> A Cursor is returned rather than a collection of rows. This allows + Android to use resources efficiently -- instead of putting lots of data straight into memory + the cursor will retrieve and release data as it is needed, which is much more efficient for + tables with lots of rows.</p> + + <p><code>fetchNote()</code> is similar to <code>fetchAllNotes()</code> but just gets one note + with the <var>rowId</var> we specify. It uses a slightly different version of the + {@link android.database.sqlite.SQLiteDatabase} <code>query()</code> method. + The first parameter (set <em>true</em>) indicates that we are interested + in one distinct result. The <var>selection</var> parameter (the fourth parameter) has been specified to search + only for the row "where _id =" the <var>rowId</var> we passed in. So we are returned a Cursor on + the one row.</p> + <p>And finally, <code>updateNote()</code> takes a <var>rowId</var>, <var>title</var> and <var>body</var>, and uses a + {@link android.content.ContentValues ContentValues} instance to update the note of the given + <var>rowId</var>.</p> + +<h2 style="clear:right;">Step 3</h2> + + <div class="sidebox" style="border:2px solid #FFFFDD;float:right; + background-color:#FFFFEE;margin-right:0px; + margin-bottom:.5em;margin-top:1em;padding:0em;width:240px;"> + <h2 style="border:0;font-size:12px;padding:.5em .5em .5em 1em;margin:0; + background-color:#FFFFDD;">Layouts and activities</h2> + <p style="padding-left:.5em;font-size:12px;margin:0; + padding:.0em .5em .5em 1em;">Most Activity classes will have a layout associated with them. The layout + will be the "face" of the Activity to the user. In this case our layout will + take over the whole screen and provide a list of notes.</p> + <p style="padding-left:.5em;font-size:12px;margin:0; + padding:.0em .5em .5em 1em;">Full screen layouts are not the only option for an Activity however. You + might also want to use a <a +href="{@docRoot}kb/commontasks.html#floatingorfull">floating + layout</a> (for example, a <a +href="{@docRoot}kb/commontasks.html#dialogsandalerts">dialog + or alert</a>), + or perhaps you don't need a layout at all (the Activity will be invisible + to the user unless you specify some kind of layout for it to use).</p> + </div> + + <p>Open the <code>notepad_list.xml</code> file in <code>res/layout</code> +and + take a look at it. (You may have to + hit the <em>xml</em> tab, at the bottom, in order to view the XML markup.)</p> + + <p>This is a mostly-empty layout definition file. Here are some + things you should know about a layout file:</p> + + + <ul> + <li> + All Android layout files must start with the XML header line: + <code><?xml version="1.0" encoding="utf-8"?></code>. </li> + <li> + The next definition will often (but not always) be a layout + definition of some kind, in this case a <code>LinearLayout</code>. </li> + <li> + The XML namespace of Android should always be defined in + the top level component or layout in the XML so that <code>android:</code> tags can + be used through the rest of the file: + <p><code>xmlns:android="http://schemas.android.com/apk/res/android"</code></p> + </li> + </ul> + + <h2 style="clear:right;">Step 4</h2> + <p>We need to create the layout to hold our list. Add code inside + of the <code>LinearLayout</code> element so the whole file looks like this: </p> + <pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="wrap_content" + android:layout_height="wrap_content"> + + <ListView android:id="@android:id/list" + android:layout_width="wrap_content" + android:layout_height="wrap_content"/> + <TextView android:id="@android:id/empty" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/no_notes"/> + +</LinearLayout> +</pre> + <ul> + <li> + The <strong>@</strong> symbol in the id strings of the <code>ListView</code> and + <code>TextView</code> tags means + that the XML parser should parse and expand the rest of + the id string and use an ID resource.</li> + <li> + The <code>ListView</code> and <code>TextView</code> can be + thought as two alternative views, only one of which will be displayed at once. + ListView will be used when there are notes to be shown, while the TextView + (which has a default value of "No Notes Yet!" defined as a string + resource in <code>res/values/strings.xml</code>) will be displayed if there + aren't any notes to display.</li> + <li>The <code>list</code> and <code>empty</code> IDs are + provided for us by the Android platform, so, we must + prefix the <code>id</code> with <code>android:</code> (e.g., <code>@android:id/list</code>).</li> + <li>The View with the <code>empty</code> id is used + automatically when the {@link android.widget.ListAdapter} has no data for the ListView. The + ListAdapter knows to look for this name by default. Alternatively, you could change the + default empty view by using {@link android.widget.AdapterView#setEmptyView(View)} + on the ListView. + <p> + More broadly, the <code>android.R</code> class is a set of predefined + resources provided for you by the platform, while your project's + <code>R</code> class is the set of resources your project has defined. + Resources found in the <code>android.R</code> resource class can be + used in the XML files by using the <code>android:</code> name space prefix + (as we see here).</p> + </li> + </ul> + + <h2 style="clear:right;">Step 5</h2> + + <div class="sidebox" style="border:2px solid #FFFFDD;float:right; + background-color:#FFFFEE;margin-right:0px; + margin-bottom:.5em;margin-top:1em;padding:0em;width:240px;"> + <h2 style="border:0;font-size:12px;padding:.5em .5em .5em 1em;margin:0; + background-color:#FFFFDD;">Resources and the R class</h2> + <p style="padding-left:.5em;font-size:12px;margin:0; + padding:.0em .5em .5em 1em;">The folders under res/ in the Eclipse project are for resources. + There is a <a href="{@docRoot}kb/commontasks.html#filelist">specific structure</a> to the + folders and files under res/.</p> + <p style="padding-left:.5em;font-size:12px; +margin:0; padding:.0em .5em .5em 1em;">Resources defined in these folders and files will have + corresponding entries in the R class allowing them to be easily accessed + and used from your application. The R class is automatically generated using the contents + of the res/ folder by the eclipse plugin (or by aapt if you use the command line tools). + Furthermore, they will be bundled and deployed for you as part of the application.</p> + </p> + </div> + <p>To make the list of notes in the ListView, we also need to define a View for each row:</p> + <ol> + <li> + Create a new file under <code>res/layout</code> called + <code>notes_row.xml</code>. </li> + <li> + Add the following contents (note: again the XML header is used, and the + first node defines the Android XML namespace)<br> + <pre style="overflow:auto"> +<?xml version="1.0" encoding="utf-8"?> +<TextView android:id="@+id/text1" + xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="wrap_content" + android:layout_height="wrap_content"/></pre> + <p> + This is the View that will be used for each notes title row — it has only + one text field in it. </p> + <p>In this case we create a new id called <code>text1</code>. The + <strong>+</strong> after the <strong>@</strong> in the id string indicates that the id should + be automatically created as a resource if it does not already exist, so we are defining + <code>text1</code> on the fly and then using it.</p> + </li> + <li>Save the file.</li> + </ol> + <p>Open the <code>R.java</code> class in the + project and look at it, you should see new definitions for + <code>notes_row</code> and <code>text1</code> (our new definitions) + meaning we can now gain access to these from the our code. </p> + + <h2 style="clear:right;">Step 6</h2> +<p>Next, open the <code>Notepadv1</code> class in the source. In the following steps, we are going to + alter this class to become a list adapter and display our notes, and also + allow us to add new notes.</p> + +<p><code>Notepadv1</code> will inherit from a subclass + of <code>Activity</code> called a <code>ListActivity</code>, + which has extra functionality to accommodate the kinds of + things you might want to do with a list, for + example: displaying an arbitrary number of list items in rows on the screen, + moving through the list items, and allowing them to be selected.</p> + +<p>Take a look through the existing code in <code>Notepadv1</code> class. + There is a currently an unused private field called <code>mNoteNumber</code> that + we will use to create numbered note titles.</p> + <p>There are also three override methods defined: + <code>onCreate</code>, <code>onCreateOptionsMenu</code> and + <code>onOptionsItemSelected</code>; we need to fill these + out:</p> + <ul> + <li><code>onCreate()</code> is called when the activity is + started — it is a little like the "main" method for an Activity. We use + this to set up resources and state for the activity when it is + running.</li> + <li><code>onCreateOptionsMenu()</code> is used to populate the + menu for the Activity. This is shown when the user hits the menu button, +and + has a list of options they can select (like "Create + Note"). </li> + <li><code>onOptionsItemSelected()</code> is the other half of the + menu equation, it is used to handle events generated from the menu (e.g., + when the user selects the "Create Note" item). + </li> + </ul> + + <h2>Step 7</h2> + <p>Change the inheritance of <code>Notepadv1</code> from +<code>Activity</code> + to <code>ListActivity</code>:</p> + <pre>public class Notepadv1 extends ListActivity</pre> + <p>Note: you will have to import <code>ListActivity</code> into the +Notepadv1 + class using Eclipse, <strong>ctrl-shift-O</strong> on Windows or Linux, or + <strong>cmd-shift-O</strong> on the Mac (organize imports) will do this for you + after you've written the above change.</p> + + <h2>Step 8</h2> + <p>Fill out the body of the <code>onCreate()</code> method.</p> + <p>Here we will set the title for the Activity (shown at the top of the + screen), use the <code>notepad_list</code> layout we created in XML, + set up the <code>NotesDbAdapter</code> instance that will + access notes data, and populate the list with the available note + titles:</p> + <ol> + <li> + In the <code>onCreate</code> method, call <code>super()</code> with the + <code>savedInstanceState</code> parameter that's passed in.</li> + <li> + Call <code>setContentView()</code> and pass <code>R.layout.notepad_list</code>.</li> + <li> + At the top of the class, create a new private class field called <code>mDbHelper</code> of class + <code>NotesDbAdapter</code>. + </li> + <li> + Back in the <code>onCreate</code> method, construct a new +<code>NotesDbAdapter</code> + instance and assign it to the <code>mDbHelper</code> field (pass + <code>this</code> into the constructor for <code>DBHelper</code>) + </li> + <li> + Call the <code>open()</code> method on <code>mDbHelper</code> to open (or create) the + database. + </li> + <li> + Finally, call a new method <code>fillData()</code>, which will get the data and + populate the ListView using the helper — we haven't defined this method yet. </li> + </ol> + <p> + <code>onCreate()</code> should now look like this:</p> + <pre> + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.notepad_list); + mDbHelper = new NotesDbAdapter(this); + mDbHelper.open(); + fillData(); + }</pre> + <p>And be sure you have the <code>mDbHelper</code> field definition (right + under the mNoteNumber definition): </p> + <pre> private NotesDbAdapter mDbHelper;</pre> + + <h2>Step 9</h2> + + <div class="sidebox" style="border:2px solid #FFFFDD;float:right; + background-color:#FFFFEE;margin-right:0px; + margin-bottom:.5em;margin-top:1em;padding:0em;width:240px;"> + <h2 style="border:0;font-size:12px;padding:.5em .5em .5em 1em;margin:0; + background-color:#FFFFDD;">More on menus</h2> + <p style="padding-left:.5em;font-size:12px;margin:0; + padding:.0em .5em .5em 1em;">The notepad application we are constructing only scratches the + surface with <a href="{@docRoot}kb/commontasks.html#addmenuitems">menus</a>. </p> + <p style="padding-left:.5em;font-size:12px;margin:0; + padding:.0em .5em .5em 1em;">You can also <a href="{@docRoot}kb/commontasks.html#menukeyshortcuts">add +shortcut keys for menu items</a>, <a href="{@docRoot}kb/commontasks.html#menukeyshortcuts">create +submenus</a> and even <a href="{@docRoot}kb/commontasks.html#addingtoothermenus">add +menu items to other applications!</a>. </p> + </div> + +<p>Fill out the body of the <code>onCreateOptionsMenu()</code> method.</p> + +<p>We will now create the "Add Item" button that can be accessed by pressing the menu +button on the device. We'll specify that it occupy the first position in the menu.</p> + + <ol> + <li> + In <code>strings.xml</code> resource (under <code>res/values</code>), add + a new string named "menu_insert" with its value set to <code>Add Item</code>: + <pre><string name="menu_insert">Add Item</string></pre> + <p>Then save the file and return to <code>Notepadv1</code>.</p> + </li> + <li>Create a menu position constant at the top of the class: + <pre>public static final int INSERT_ID = Menu.FIRST;</pre> + </li> + <li>In the <code>onCreateOptionsMenu()</code> method, change the + <code>super</code> call so we capture the boolean return as <code>result</code>. We'll return this value at the end.</li> + <li>Then add the menu item with <code>menu.add()</code>.</li> + </ol> + <p>The whole method should now look like this: + <pre> + @Override + public boolean onCreateOptionsMenu(Menu menu) { + boolean result = super.onCreateOptionsMenu(menu); + menu.add(0, INSERT_ID, 0, R.string.menu_insert); + return result; + }</pre> + <p>The arguments passed to <code>add()</code> indicate: a group identifier for this menu (none, + in this case), a unique ID (defined above), the order of the item (zero indicates no preference), + and the resource of the string to use for the item.</p> + +<h2 style="clear:right;">Step 10</h2> + <p>Fill out the body of the <code>onOptionsItemSelected()</code> method:</p> + <p>This is going + to handle our new "Add Note" menu item. When this is selected, the + <code>onOptionsItemSelected()</code> method will be called with the + <code>item.getId()</code> set to <code>INSERT_ID</code> (the constant we + used to identify the menu item). We can detect this, and take the + appropriate actions:</p> + <ol> + <li> + The <code>super.onOptionsItemSelected(item)</code> method call goes at the + end of this method — we want to catch our events first! </li> + <li> + Write a switch statement on <code>item.getItemId()</code>. + <p>In the case of <var>INSERT_ID</var>, call a new method, <code>createNote()</code>, + and return true, because we have handled this event and do not want to + propagate it through the system.</p> + </li> + <li>Return the result of the superclass' <code>onOptionsItemSelected()</code> + method at the end.</li> + </ol> + <p> + The whole <code>onOptionsItemSelect()</code> method should now look like + this:</p> + <pre> + @Override + public boolean onOptionsItemSelected(MenuItem item) { + switch (item.getItemId()) { + case INSERT_ID: + createNote(); + return true; + } + + return super.onOptionsItemSelected(item); + }</pre> + +<h2>Step 11</h2> + <p>Add a new <code>createNote()</code> method:</p> + <p>In this first version of + our application, <code>createNote()</code> is not going to be very useful. +We will simply + create a new note with a title assigned to it based on a counter ("Note 1", + "Note 2"...) and with an empty body. At present we have no way of editing + the contents of a note, so for now we will have to be content making one + with some default values:</p> + <ol> + <li>Construct the name using "Note" and the counter we defined in the class: <code> + String noteName = "Note " + mNoteNumber++</code></li> + <li> + Call <code>mDbHelper.createNote()</code> using <code>noteName</code> as the + title and <code>""</code> for the body + </li> + <li> + Call <code>fillData()</code> to populate the list of notes (inefficient but + simple) — we'll create this method next.</li> + </ol> + <p> + The whole <code>createNote()</code> method should look like this: </p> + <pre> + private void createNote() { + String noteName = "Note " + mNoteNumber++; + mDbHelper.createNote(noteName, ""); + fillData(); + }</pre> + + +<h2>Step 12</h2> + <div class="sidebox" style="border:2px solid #FFFFDD;float:right; + background-color:#FFFFEE;margin-right:0px; + margin-bottom:.5em;margin-top:1em;padding:0em;width:240px;"> + <h2 style="border:0;font-size:12px;padding:.5em .5em .5em 1em;margin:0; + background-color:#FFFFDD;">List adapters</h2> + <p style="padding-left:.5em;font-size:12px;margin:0; + padding:.0em .5em .5em 1em;">Our example uses a {@link android.widget.SimpleCursorAdapter + SimpleCursorAdapter} to bind a database {@link android.database.Cursor Cursor} + into a ListView, and this is a common way to use a {@link android.widget.ListAdapter + ListAdapter}. Other options exist like {@link android.widget.ArrayAdapter ArrayAdapter} which + can be used to take a List or Array of in-memory data and bind it in to + a list as well.</p> + </div> + + <p>Define the <code>fillData()</code> method:</p> + <p>This + method uses <code>SimpleCursorAdapter,</code> which takes a database <code>Cursor</code> + and binds it to fields provided in the layout. These fields define the row elements of our list + (in this case we use the <code>text1</code> field in our + <code>notes_row.xml</code> layout), so this allows us to easily populate the list with + entries from our database.</p> + <p>To do this we have to provide a mapping from the <code>title</code> field in the returned Cursor, to + our <code>text1</code> TextView, which is done by defining two arrays: the first a string array + with the list of columns to map <em>from</em> (just "title" in this case, from the constant + <code>NotesDbAdapter.KEY_TITLE</code>) and, the second, an int array + containing references to the views that we'll bind the data <em>into</em> + (the <code>R.id.text1</code> TextView).</p> + <p>This is a bigger chunk of code, so let's first take a look at it:</p> + + <pre> + private void fillData() { + // Get all of the notes from the database and create the item list + Cursor c = mDbHelper.fetchAllNotes(); + startManagingCursor(c); + + String[] from = new String[] { NotesDbAdapter.KEY_TITLE }; + int[] to = new int[] { R.id.text1 }; + + // Now create an array adapter and set it to display using our row + SimpleCursorAdapter notes = + new SimpleCursorAdapter(this, R.layout.notes_row, c, from, to); + setListAdapter(notes); + }</pre> + + <p>Here's what we've done:</p> + <ol> + <li> + After obtaining the Cursor from <code>mDbHelper.fetchAllNotes()</code>, we + use an Activity method called + <code>startManagingCursor()</code> that allows Android to take care of the + Cursor lifecycle instead of us needing to worry about it. (We will cover the implications + of the lifecycle in exercise 3, but for now just know that this allows Android to do some + of our resource management work for us.)</li> + <li> + Then we create a string array in which we declare the column(s) we want + (just the title, in this case), and an int array that defines the View(s) + to which we'd like to bind the columns (these should be in order, respective to + the string array, but here we only have one for each).</li> + <li> + Next is the SimpleCursorAdapter instantiation. + Like many classes in Android, the SimpleCursorAdapter needs a Context in order to do its + work, so we pass in <code>this</code> for the context (since subclasses of Activity + implement Context). We pass the <code>notes_row</code> View we created as the receptacle + for the data, the Cursor we just created, and then our arrays.</li> + </ol> + <p> + In the future, remember that the mapping between the <strong>from</strong> columns and <strong>to</strong> resources + is done using the respective ordering of the two arrays. If we had more columns we wanted + to bind, and more Views to bind them in to, we would specify them in order, for example we + might use <code>{ NotesDbAdapter.KEY_TITLE, NotesDbAdapter.KEY_BODY }</code> and + <code>{ R.id.text1, R.id.text2 }</code> to bind two fields into the row (and we would also need + to define text2 in the notes_row.xml, for the body text). This is how you can bind multiple fields + into a single row (and get a custom row layout as well).</p> + <p> + If you get compiler errors about classes not being found, ctrl-shift-O or + (cmd-shift-O on the mac) to organize imports. + </p> + +<h2 style="clear:right;">Step 13</h2> + <p>Run it! + <ol> + <li> + Right click on the <code>Notepadv1</code> project.</li> + <li> + From the popup menu, select <strong>Run As</strong> > + <strong>Android Application</strong>.</li> + <li> + If you see a dialog come up, select Android Launcher as the way of running + the application (you can also use the link near the top of the dialog to + set this as your default for the workspace; this is recommended as it will + stop the plugin from asking you this every time).</li> + <li>Add new notes by hitting the menu button and selecting <em>Add + Item</em> from the menu.</li> + </ol> + +<h2 style="clear:right;">Solution and Next Steps</h2> + <p>You can see the solution to this class in <code>Notepadv1Solution</code> +from +the zip file to compare with your own.</p> + +<p>Once you are ready, move on to <a href="tutorial-ex2.html">Tutorial +Exercise 2</a> to add the ability to create, edit and delete notes.</p> +<p><a href="tutorial.html">Back to the Tutorial main page...</a></p> + diff --git a/docs/html/guide/tutorials/notepad/notepad-ex2.jd b/docs/html/guide/tutorials/notepad/notepad-ex2.jd new file mode 100644 index 0000000..ce7681b --- /dev/null +++ b/docs/html/guide/tutorials/notepad/notepad-ex2.jd @@ -0,0 +1,640 @@ +page.title=Notepad Exercise 2 +@jd:body + + +<p><em>In this exercise, you will add a second Activity to your notepad application, to let the user +create, edit, and delete notes. The new Activity assumes responsibility for creating new notes by +collecting user input and packing it into a return Bundle provided by the intent. This exercise +demonstrates:</em></p> +<ul> +<li><em>Constructing a new Activity and adding it to the Android manifest</em></li> +<li><em>Invoking another Activity asynchronously using <code>startActivityForResult()</code></em></li> +<li><em>Passing data between Activity in Bundle objects</em></li> +<li><em>How to use a more advanced screen layout</em></li> +</ul> + +<div style="float:right;white-space:nowrap"> + [<a href="tutorial-ex1.html">Exercise 1</a>] + <span style="color:#BBB;"> + [<a href="tutorial-ex2.html" style="color:#DDD;">Exercise 2</a>] + </span> + [<a href="tutorial-ex3.html">Exercise 3</a>] + [<a href="tutorial-extra-credit.html">Extra Credit</a>] +</div> + +<h2>Step 1</h2> + +<p>Create a new Android project using the sources from <code>Notepadv2</code> under the +<code>NotepadCodeLab</code> folder, just like you did for the first exercise. If you see an error about +<code>AndroidManifest.xml</code>, or some problems related to an +<code>android.zip</code> file, right click on the project and select <strong>Android +Tools</strong> > <strong>Fix Project Properties</strong>.</p> + +<p>Open the <code>Notepadv2</code> project and take a look around:</p> +<ul> + <li> + Open and look at the <code>strings.xml</code> file under + <code>res/values</code> — there are several new strings which we will use + for our new functionality + </li> + <li> + Also, open and take a look at the top of the <code>Notepadv2</code> class, + you will notice several new constants have been defined along with a new <code>mNotesCursor</code> + field used to hold the cursor we are using. + </li> + <li> + Note also that the <code>fillData()</code> method has a few more comments and now uses + the new field to store the notes Cursor. The <code>onCreate()</code> method is + unchanged from the first exercise. Also notice that the member field used to store the + notes Cursor is now called <code>mNotesCursor</code>. The <code>m</code> denotes a member + field and is part of the Android coding style standards. + </li> + <li> + There are also a couple of new overridden methods + (<code>onListItemClick()</code> and <code>onActivityResult()</code>) + which we will be filling in below. + </li> +</ul> + + +<h2>Step 2</h2> + + <p>Add an entry to the menu for deleting a note:</p> +<ol> + <li> + In the <code>onCreateOptionsMenu()</code> method, add a new line: + <pre>menu.add(0, DELETE_ID, 0, R.string.menu_delete);</pre> + </li> + <li> + The whole method should now look like this:<br> + <pre> +@Override +public boolean onCreateOptionsMenu(Menu menu) { + super.onCreateOptionsMenu(menu); + menu.add(0, INSERT_ID, 0, R.string.menu_insert); + menu.add(0, DELETE_ID, 0, R.string.menu_delete); + return true; +}</pre> + </li> +</ol> + +<h2>Step 3</h2> + <p>In the <code>onMenuItemSelected()</code> method, add a new case for + <code>DELETE_ID</code>:</p> + <pre> +mDbHelper.deleteNote(getListView().getSelectedItemId()); +fillData(); +return true;</pre> + + <ol> + <li> + Here, we use the <code>deleteNote</code> method to remove the note specified by ID. + In order to get the ID, we call <code>getListView().getSelectedItemId()</code>. + </li> + <li> + Then we fill the data to keep everything up to date. + </li> + </ol> + <p> + The whole method should now look like this:</p> + <pre> +@Override +public boolean onMenuItemSelected(int featureId, MenuItem item) { + switch(item.getItemId()) { + case INSERT_ID: + createNote(); + return true; + case DELETE_ID: + mDbHelper.deleteNote(getListView().getSelectedItemId()); + fillData(); + return true; + } + + return super.onMenuItemSelected(featureId, item); +}</pre> + +<h2 style="clear:right;">Step 4</h2> +<div class="sidebox" style="border:2px solid #FFFFDD;float:right; + background-color:#FFFFEE;margin-right:0px; + margin-bottom:.5em;margin-top:1em;padding:0em;width:240px;"> + <h2 style="border:0;font-size:12px;padding:.5em .5em .5em 1em;margin:0; + background-color:#FFFFDD;">Starting Other Activities</h2> + <p style="padding-left:.5em;font-size:12px;margin:0; + padding:.0em .5em .5em 1em;">In this example our Intent uses a class name specifically. + As well as + <a href="{@docRoot}kb/commontasks.html#intentexamples">starting intents</a> in + classes we already know about, be they in our own application or another + application, we can also create Intents without knowing exactly which + application will handle it.</p> + <p style="padding-left:.5em;font-size:12px;margin:0; + padding:.0em .5em .5em 1em;">For example, we might want to open a page in a + browser, and for this we still use + an Intent. But instead of specifying a class to handle it, we use + a predefined Intent constant, and a content URI that describes what we + want to do. See {@link android.content.Intent + android.content.Intent} for more information.</p> +</div> + + <p>Fill in the body of the <code>createNote()</code> method: + <p>Create a new <code>Intent</code> to create a note + (<code>ACTIVITY_CREATE</code>) using the <code>NoteEdit</code> class. + Then fire the Intent using the <code>startActivityForResult()</code> method + call:</p> + <pre style="overflow:auto"> +Intent i = new Intent(this, NoteEdit.class); +startActivityForResult(i, ACTIVITY_CREATE);</pre> + <p>This form of the Intent call targets a specific class in our Activity, in this case + <code>NoteEdit</code>. Since the Intent class will need to communicate with the Android + operating system to route requests, we also have to provide a Context (<code>this</code>).</p> + <p>The <code>startActivityForResult()</code> method fires the Intent in a way that causes a method + in our Activity to be called when the new Activity is completed. The method in our Activity + that receives the callback is called + <code>onActivityResult()</code> and we will implement it in a later step. The other way + to call an Activity is using <code>startActivity()</code> but this is a "fire-and-forget" way + of calling it — in this manner, our Activity is not informed when the Activity is completed, and there is + no way to return result information from the called Activity with <code>startActivity()</code>. + <p>Don't worry about the fact that <code>NoteEdit</code> doesn't exist yet, + we will fix that soon. </p> + </li> + + +<h2>Step 5</h2> + + <p>Fill in the body of the <code>onListItemClick()</code> override.</p> + <p><code>onListItemClick()</code> is a callback method that we'll override. It is called when + the user selects an item from the list. It is passed four parameters: the + <code>ListView</code> object it was invoked from, the <code>View</code> + inside the <code>ListView</code> that was clicked on, the + <code>position</code> in the list that was clicked, and the + <code>mRowId</code> of the item that was clicked. In this instance we can + ignore the first two parameters (we only have one <code>ListView</code> it + could be), and we ignore the <code>mRowId</code> as well. All we are + interested in is the <code>position</code> that the user selected. We use + this to get the data from the correct row, and bundle it up to send to + the <code>NoteEdit</code> Activity.</p> + <p>In our implementation of the callback, the method creates an + <code>Intent</code> to edit the note using + the <code>NoteEdit</code> class. It then adds data into the extras Bundle of + the Intent, which will be passed to the called Activity. We use it + to pass in the title and body text, and the <code>mRowId</code> for the note we are + editing. Finally, it will fire the Intent using the + <code>startActivityForResult()</code> method call. Here's the code that + belongs in <code>onListItemClick()</code>:</p> + <pre> +super.onListItemClick(l, v, position, id); +Cursor c = mNotesCursor; +c.moveToPosition(position); +Intent i = new Intent(this, NoteEdit.class); +i.putExtra(NotesDbAdapter.KEY_ROWID, id); +i.putExtra(NotesDbAdapter.KEY_TITLE, c.getString( + c.getColumnIndexOrThrow(NotesDbAdapter.KEY_TITLE))); +i.putExtra(NotesDbAdapter.KEY_BODY, c.getString( + c.getColumnIndexOrThrow(NotesDbAdapter.KEY_BODY))); +startActivityForResult(i, ACTIVITY_EDIT);</pre> + <ul> + <li> + <code>putExtra()</code> is the method to add items into the extras Bundle + to pass in to intent invocations. Here, we are + using the Bundle to pass in the title, body and mRowId of the note we want to edit. + </li> + <li> + The details of the note are pulled out from our query Cursor, which we move to the + proper position for the element that was selected in the list, with + the <code>moveToPosition()</code> method.</li> + <li>With the extras added to the Intent, we invoke the Intent on the + <code>NoteEdit</code> class by passing <code>startActivityForResult()</code> + the Intent and the request code. (The request code will be + returned to <code>onActivityResult</code> as the <code>requestCode</code> parameter.)</li> + </ul> + <p class="note"><b>Note:</b> We assign the mNotesCursor field to a local variable at the + start of the method. This is done as an optimization of the Android code. Accessing a local + variable is much more efficient than accessing a field in the Dalvik VM, so by doing this + we make only one access to the field, and five accesses to the local variable, making the + routine much more efficient. It is recommended that you use this optimization when possible.</p> + + +<h2>Step 6</h2> + +<p>The above <code>createNote()</code> and <code>onListItemClick()</code> + methods use an asynchronous Intent invocation. We need a handler for the callback, so here we fill + in the body of the <code>onActivityResult()</code>. </p> +<p><code>onActivityResult()</code> is the overridden method + which will be called when an Activity returns with a result. (Remember, an Activity + will only return a result if launched with <code>startActivityForResult</code>.) The parameters provided + to the callback are: </p> + <ul> + <li><code>requestCode</code> — the original request code + specified in the Intent invocation (either <code>ACTIVITY_CREATE</code> or + <code>ACTIVITY_EDIT</code> for us). + </li> + <li><code>resultCode</code> — the result (or error code) of the call, this + should be zero if everything was OK, but may have a non-zero code indicating + that something failed. There are standard result codes available, and you + can also create your own constants to indicate specific problems. + </li> + <li><code>intent</code> — this is an Intent created by the Activity returning + results. It can be used to return data in the Intent "extras." + </li> + </ul> + <p>The combination of <code>startActivityForResult()</code> and + <code>onActivityResult()</code> can be thought of as an asynchronous RPC + (remote procedure call) and forms the recommended way for an Activity to invoke + another and share services.</p> + <p>Here's the code that belongs in your <code>onActivityResult()</code>:</p> + <pre> +super.onActivityResult(requestCode, resultCode, intent); +Bundle extras = intent.getExtras(); + +switch(requestCode) { +case ACTIVITY_CREATE: + String title = extras.getString(NotesDbAdapter.KEY_TITLE); + String body = extras.getString(NotesDbAdapter.KEY_BODY); + mDbHelper.createNote(title, body); + fillData(); + break; +case ACTIVITY_EDIT: + Long mRowId = extras.getLong(NotesDbAdapter.KEY_ROWID); + if (mRowId != null) { + String editTitle = extras.getString(NotesDbAdapter.KEY_TITLE); + String editBody = extras.getString(NotesDbAdapter.KEY_BODY); + mDbHelper.updateNote(mRowId, editTitle, editBody); + } + fillData(); + break; +}</pre> + + <ul> + <li> + We are handling both the <code>ACTIVITY_CREATE</code> and + <code>ACTIVITY_EDIT</code> activity results in this method. + </li> + <li> + In the case of a create, we pull the title and body from the extras (retrieved from the + returned Intent) and use them to create a new note. + </li> + <li> + In the case of an edit, we pull the mRowId as well, and use that to update + the note in the database. + </li> + <li> + <code>fillData()</code> at the end ensures everything is up to date . + </li> + </ul> + + +<h2>Step 7</h2> + + <div class="sidebox" style="border:2px solid #FFFFDD;float:right; + background-color:#FFFFEE;margin-right:0px; + margin-bottom:.5em;margin-top:1em;padding:0em;width:240px;"> + <h2 style="border:0;font-size:12px;padding:.5em .5em .5em 1em;margin:0; + background-color:#FFFFDD;">The Art of Layout</h2> + <p style="padding-left:.5em;font-size:12px;margin:0; padding:.0em .5em .5em 1em;">The provided + note_edit.xml layout file is the most sophisticated one in the application we will be building, + but that doesn't mean it is even close to the kind of sophistication you will be likely to want + in real Android applications.</p> + <p style="padding-left:.5em;font-size:12px;margin:0; padding:.0em .5em .5em 1em;">Creating a + good UI is part art and part science, and the rest is work. Mastering <a + href="{@docRoot}devel/implementing-ui.html">Android layout</a> is an essential part of creating + a good looking Android application.</p> + <p style="padding-left:.5em;font-size:12px;margin:0; + padding:.0em .5em .5em 1em;">Take a look at the + <a href="{@docRoot}reference/view-gallery.html">View Gallery</a> + for some example layouts and how to use them. The ApiDemos sample project is also a + great resource from which to learn how to create different layouts.</p> + </div> + +<p>Open the file <code>note_edit.xml</code> that has been provided and take a + look at it. This is the UI code for the Note Editor.</p> + <p>This is the most + sophisticated UI we have dealt with yet. The file is given to you to avoid + problems that may sneak in when typing the code. (The XML is very strict + about case sensitivity and structure, mistakes in these are the usual cause + of problems with layout.)</p> + <p>There is a new parameter used + here that we haven't seen before: <code>android:layout_weight</code> (in + this case set to use the value 1 in each case).</p> + <p><code>layout_weight</code> is used in LinearLayouts + to assign "importance" to Views within the layout. All Views have a default + <code>layout_weight</code> of zero, meaning they take up only as much room + on the screen as they need to be displayed. Assigning a value higher than + zero will split up the rest of the available space in the parent View, according + to the value of each View's <code>layout_weight</code> and its ratio to the + overall <code>layout_weight</code> specified in the current layout for this + and other View elements.</p> + <p>To give an example: let's say we have a text label + and two text edit elements in a horizontal row. The label has no + <code>layout_weight</code> specified, so it takes up the minimum space + required to render. If the <code>layout_weight</code> of each of the two + text edit elements is set to 1, the remaining width in the parent layout will + be split equally between them (because we claim they are equally important). + If the first one has a <code>layout_weight</code> of 1 + and the second has a <code>layout_weight</code> of 2, then one third of the + remaining space will be given to the first, and two thirds to the + second (because we claim the second one is more important).</p> + <p>This layout also demonstrates how to nest multiple layouts + inside each other to achieve a more complex and pleasant layout. In this + example, a horizontal linear layout is nested inside the vertical one to + allow the title label and text field to be alongside each other, + horizontally.</p> + + +<h2 style="clear:right;">Step 8</h2> + + <p>Create a <code>NoteEdit</code> class that extends + <code>android.app.Activity</code>.</p> + <p>This is the first time we will have + created an Activity without the Android Eclipse plugin doing it for us. When + you do so, the <code>onCreate()</code> method is not automatically + overridden for you. It is hard to imagine an Activity that doesn't override + the <code>onCreate()</code> method, so this should be the first thing you do.</p> + <ol> + <li>Right click on the <code>com.android.demo.notepad2</code> package + in the Package Explorer, and select <strong>New</strong> > <strong>Class</strong> from the popup + menu.</li> + <li>Fill in <code>NoteEdit</code> for the <code>Name:</code> field in the + dialog.</li> + <li>In the <code>Superclass:</code> field, enter + <code>android.app.Activity</code> (you can also just type Activity and hit + Ctrl-Space on Windows and Linux or Cmd-Space on the Mac, to invoke code + assist and find the right package and class).</li> + <li>Click <strong>Finish</strong>.</li> + <li>In the resulting <code>NoteEdit</code> class, right click in the editor + window and select <strong>Source</strong> > <strong>Override/Implement Methods...</strong></li> + <li>Scroll down through the checklist in the dialog until you see + <code>onCreate(Bundle)</code> — and check the box next to it.</li> + <li>Click <strong>OK</strong>.<p>The method should now appear in your class.</p></li> + </ol> + +<h2>Step 9</h2> + +<p>Fill in the body of the <code>onCreate()</code> method for <code>NoteEdit</code>.</p> + +<p>This will set the title of our new Activity to say "Edit Note" (one + of the strings defined in <code>strings.xml</code>). It will also set the + content view to use our <code>note_edit.xml</code> layout file. We can then + grab handles to the title and body text edit views, and the confirm button, + so that our class can use them to set and get the note title and body, + and attach an event to the confirm button for when it is pressed by the + user.</p> + <p>We can then unbundle the values that were passed in to the Activity + with the extras Bundle attached to the calling Intent. We'll use them to pre-populate + the title and body text edit views so that the user can edit them. + Then we will grab and store the <code>mRowId</code> so we can keep + track of what note the user is editing.</p> + + <ol> + <li> + Inside <code>onCreate()</code>, set up the layout:<br> + <pre>setContentView(R.layout.note_edit);</pre> + </li> + <li> + Find the edit and button components we need: + <p>These are found by the + IDs associated to them in the R class, and need to be cast to the right + type of <code>View</code> (<code>EditText</code> for the two text views, + and <code>Button</code> for the confirm button):</p> + <pre> +mTitleText = (EditText) findViewById(R.id.title); +mBodyText = (EditText) findViewById(R.id.body); +Button confirmButton = (Button) findViewById(R.id.confirm);</pre> + <p>Note that <code>mTitleText</code> and <code>mBodyText</code> are member + fields (you need to declare them at the top of the class definition).</p> + </li> + <li>At the top of the class, declare a <code>Long mRowId</code> private field to store + the current <code>mRowId</code> being edited (if any). + </li> + <li>Continuing inside <code>onCreate()</code>, + add code to initialize the <code>title</code>, <code>body</code> and + <code>mRowId</code> from the extras Bundle in + the Intent (if it is present):<br> + <pre> +mRowId = null; +Bundle extras = getIntent().getExtras(); +if (extras != null) { + String title = extras.getString(NotesDbAdapter.KEY_TITLE); + String body = extras.getString(NotesDbAdapter.KEY_BODY); + mRowId = extras.getLong(NotesDbAdapter.KEY_ROWID); + + if (title != null) { + mTitleText.setText(title); + } + if (body != null) { + mBodyText.setText(body); + } +}</pre> + <ul> + <li> + We are pulling the <code>title</code> and + <code>body</code> out of the + <code>extras</code> Bundle that was set from the + Intent invocation. + </li><li> + We also null-protect the text field setting (i.e., we don't want to set + the text fields to null accidentally).</li> + </ul> + </li> + <li> + Create an <code>onClickListener()</code> for the button: + <p>Listeners can be one of the more confusing aspects of UI + implementation, but + what we are trying to achieve in this case is simple. We want an + <code>onClick()</code> method to be called when the user presses the + confirm button, and use that to do some work and return the values + of the edited note to the Intent caller. We do this using something called + an anonymous inner class. This is a bit confusing to look at unless you + have seen them before, but all you really need to take away from this is + that you can refer to this code in the future to see how to create a + listener and attach it to a button. (Listeners are a common idiom + in Java development, particularly for user interfaces.) Here's the empty listener:<br> + <pre> +confirmButton.setOnClickListener(new View.OnClickListener() { + + public void onClick(View view) { + + } + +});</pre> + </li> + </ol> +<h2>Step 10</h2> + +<p>Fill in the body of the <code>onClick()</code> method in our listener.</p> + + <p>This is the code that will be run when the user clicks on the + confirm button. We want this to grab the title and body text from the edit + text fields, and put them into the return Bundle so that they can be passed + back to the Activity that invoked this <code>NoteEdit</code> Activity. If the + operation is an edit rather than a create, we also want to put the + <code>mRowId</code> into the Bundle so that the + <code>Notepadv2</code> class can save the changes back to the correct + note.</p> + <ol> + <li> + Create a <code>Bundle</code> and put the title and body text into it using the + constants defined in Notepadv2 as keys:<br> + <pre> +Bundle bundle = new Bundle(); + +bundle.putString(NotesDbAdapter.KEY_TITLE, mTitleText.getText().toString()); +bundle.putString(NotesDbAdapter.KEY_BODY, mBodyText.getText().toString()); +if (mRowId != null) { + bundle.putLong(NotesDbAdapter.KEY_ROWID, mRowId); +}</pre> + </li> + <li> + Set the result information (the Bundle) in a new Intent and finish the Activity: + <pre> +Intent mIntent = new Intent(); +mIntent.putExtras(bundle); +setResult(RESULT_OK, mIntent); +finish();</pre> + <ul> + <li>The Intent is simply our data carrier that carries our Bundle + (with the title, body and mRowId).</li> + <li>The <code>setResult()</code> method is used to set the result + code and return Intent to be passed back to the + Intent caller. In this case everything worked, so we return RESULT_OK for the + result code.</li> + <li>The <code>finish()</code> call is used to signal that the Activity + is done (like a return call). Anything set in the Result will then be + returned to the caller, along with execution control.</li> + </ul> + </li> + </ol> + <p>The full <code>onCreate()</code> method (plus supporting class fields) should + now look like this:</p> + <pre> +private EditText mTitleText; +private EditText mBodyText; +private Long mRowId; + +@Override +protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.note_edit); + + mTitleText = (EditText) findViewById(R.id.title); + mBodyText = (EditText) findViewById(R.id.body); + + Button confirmButton = (Button) findViewById(R.id.confirm); + + mRowId = null; + Bundle extras = getIntent().getExtras(); + if (extras != null) { + String title = extras.getString(NotesDbAdapter.KEY_TITLE); + String body = extras.getString(NotesDbAdapter.KEY_BODY); + mRowId = extras.getLong(NotesDbAdapter.KEY_ROWID); + + if (title != null) { + mTitleText.setText(title); + } + if (body != null) { + mBodyText.setText(body); + } + } + + confirmButton.setOnClickListener(new View.OnClickListener() { + + public void onClick(View view) { + Bundle bundle = new Bundle(); + + bundle.putString(NotesDbAdapter.KEY_TITLE, mTitleText.getText().toString()); + bundle.putString(NotesDbAdapter.KEY_BODY, mBodyText.getText().toString()); + if (mRowId != null) { + bundle.putLong(NotesDbAdapter.KEY_ROWID, mRowId); + } + + Intent mIntent = new Intent(); + mIntent.putExtras(bundle); + setResult(RESULT_OK, mIntent); + finish(); + } + }); +}</pre> + </li> + </ol> + +<h2>Step 11</h2> + +<div class="sidebox" style="border:2px solid #FFFFDD;float:right; + background-color:#FFFFEE;margin-right:0px; + margin-bottom:.5em;margin-top:1em;padding:0em;width:240px;"> + <h2 style="border:0;font-size:12px;padding:.5em .5em .5em 1em;margin:0; + background-color:#FFFFDD;">The All-Important Android Manifest File</h2> + <p style="padding-left:.5em;font-size:12px;margin:0; + padding:.0em .5em .5em 1em;">The AndroidManifest.xml file is the way in which Android sees your + application. This file defines the category of the application, where + it shows up (or even if it shows up) in the launcher or settings, what + activities, services, and content providers it defines, what intents it can + receive, and more. </p> + <p style="padding-left:.5em;font-size:12px;margin:0; + padding:.0em .5em .5em 1em;">For more information, see the reference document + <a href="{@docRoot}devel/bblocks-manifest.html">AndroidManifest.xml</a></p> + </div> + +<p>Finally, the new Activity has to be defined in the manifest file:</p> + <p>Before the new Activity can be seen by Android, it needs its own + Activity entry in the <code>AndroidManifest.xml</code> file. This is to let + the system know that it is there and can be called. We could also specify + which IntentFilters the activity implements here, but we are going to skip + this for now and just let Android know that the Activity is + defined.</p> + <p>There is a Manifest editor included in the Eclipse plugin that makes it much easier + to edit the AndroidManifest file, and we will use this. If you prefer to edit the file directly + or are not using the Eclipse plugin, see the box at the end for information on how to do this + without using the new Manifest editor.<p> + <ol> + <li>Double click on the <code>AndroidManifest.xml</code> file in the package explorer to open it. + </li> + <li>Click the <strong>Application</strong> tab at the bottom of the Manifest editor.</li> + <li>Click <strong>Add...</strong> in the Application Nodes section. + <p>If you see a dialog with radiobuttons at the top, select the top radio button: + "Create a new element at the top level, in Application".</p></li> + <li>Make sure "(A) Activity" is selected in the selection pane of the dialog, and click <strong>OK</strong>.</li> + <li>Click on the new "Activity" node, in the Application Nodes section, then + type <code>.NoteEdit</code> into the <em>Name*</em> + field to the right. Press Return/Enter.</li> + </ol> + <p>The Android Manifest editor helps you add more complex entries into the AndroidManifest.xml + file, have a look around at some of the other options available (but be careful not to select + them otherwise they will be added to your Manifest). This editor should help you understand + and alter the AndroidManifest.xml file as you move on to more advanced Android applications.</p> + + <p class="note">If you prefer to edit this file directly, simply open the + <code>AndroidManifest.xml</code> file and look at the source (use the + <code>AndroidManifest.xml</code> tab in the eclipse editor to see the source code directly). + Then edit the file as follows:<br> + <code><activity android:name=".NoteEdit"></activity></code><br><br> + This should be placed just below the line that reads:<br> + <code></activity></code> for the <code>.Notepadv2</code> activity.</p> + +<h2 style="clear:right;">Step 12</h2> + +<p>Now Run it!</p> +<p>You should now be able to add real notes from +the menu, as well as delete an existing one. Notice that in order to delete, you must +first use the directional controls on the device to highlight the note. +Furthermore, selecting a note title from the list should bring up the note +editor to let you edit it. Press confirm when finished to save the changes +back to the database. + +<h2>Solution and Next Steps</h2> + +<p>You can see the solution to this exercise in <code>Notepadv2Solution</code> +from the zip file to compare with your own.</p> +<p>Now try editing a note, and then hitting the back button on the emulator +instead of the confirm button (the back button is below the menu button). You +will see an error come up. Clearly our application still has some problems. +Worse still, if you did make some changes and hit the back button, when you go +back into the notepad to look at the note you changed, you will find that all +your changes have been lost. In the next exercise we will fix these +problems.</p> + +<p> +Once you are ready, move on to <a href="tutorial-ex3.html">Tutorial +Exercise 3</a> where you will fix the problems with the back button and lost +edits by introducing a proper life cycle into the NoteEdit Activity.</p> + +<p><a href="tutorial.html">Back to the Tutorial main page...</a>.</p> + diff --git a/docs/html/guide/tutorials/notepad/notepad-ex3.jd b/docs/html/guide/tutorials/notepad/notepad-ex3.jd new file mode 100644 index 0000000..b42734f --- /dev/null +++ b/docs/html/guide/tutorials/notepad/notepad-ex3.jd @@ -0,0 +1,358 @@ +page.title=Notepad Exercise 3 +@jd:body + + +<p><em>In this exercise, you will use life-cycle event callbacks to store and +retrieve application state data. This exercise demonstrates:</em></p> +<ul> +<li><em>Life-cycle events and how your application can use them</em></li> +<li><em>Techniques for maintaining application state</em></li> +</ul> + +<div style="float:right;white-space:nowrap"> + [<a href="tutorial-ex1.html">Exercise 1</a>] + [<a href="tutorial-ex2.html">Exercise 2</a>] + <span style="color:#BBB;"> + [<a href="tutorial-ex3.html" style="color:#BBB;">Exercise 3</a>] + </span> + [<a href="tutorial-extra-credit.html">Extra Credit</a>] +</div> + +<h2>Step 1</h2> + +<p>Import <code>Notepadv3</code> into Eclipse. If you see an error about +<code>AndroidManifest.xml,</code> or some problems related to an Android zip +file, right click on the project and select <strong>Android Tools</strong> > +<strong>Fix Project Properties</strong> from the popup menu. The starting point for this exercise is +exactly where we left off at the end of the Notepadv2. </p> +<p>The current application has some problems — hitting the back button when editing +causes a crash, and anything else that happens during editing will cause the +edits to be lost.</p> +<p>To fix this, we will move most of the functionality for creating and editing +the note into the NoteEdit class, and introduce a full life cycle for editing +notes.</p> + + <ol> + <li>Remove the code in <code>NoteEdit</code> that parses the title and body + from the extras Bundle. + <p>Instead, we are going to use the <code>DBHelper</code> class + to access the notes from the database directly. All we need passed into the + NoteEdit Activity is a <code>mRowId</code> (but only if we are editing, if creating we pass + nothing). Remove these lines:</p> + <pre> +String title = extras.getString(NotesDbAdapter.KEY_TITLE); +String body = extras.getString(NotesDbAdapter.KEY_BODY);</pre> + </li> + <li>We will also get rid of the properties that were being passed in + the <code>extras</code> Bundle, which we were using to set the title + and body text edit values in the UI. So delete: + <pre> +if (title != null) { + mTitleText.setText(title); +} +if (body != null) { + mBodyText.setText(body); +}</pre> + </li> + </ol> + +<h2>Step 2</h2> + +<p>Create a class field for a <code>NotesDbAdapter</code> at the top of the NoteEdit class:</p> + <pre> private NotesDbAdapter mDbHelper;</pre> +<p>Also add an instance of <code>NotesDbAdapter</code> in the + <code>onCreate()</code> method (right below the <code>super.onCreate()</code> call):</p> + <pre> + mDbHelper = new NotesDbAdapter(this);<br> + mDbHelper.open();</pre> + +<h2>Step 3</h2> + +<p>In <code>NoteEdit</code>, we need to check the <var>savedInstanceState</var> for the +<code>mRowId</code>, in case the note + editing contains a saved state in the Bundle, which we should recover (this would happen + if our Activity lost focus and then restarted).</p> + <ol> + <li> + Replace the code that currently initializes the <code>mRowId</code>:<br> + <pre> + mRowId = null; + + Bundle extras = getIntent().getExtras(); + if (extras != null) { + mRowId = extras.getLong(NotesDbAdapter.KEY_ROWID); + } + </pre> + with this: + <pre> + mRowId = savedInstanceState != null ? savedInstanceState.getLong(NotesDbAdapter.KEY_ROWID) + : null; + if (mRowId == null) { + Bundle extras = getIntent().getExtras(); + mRowId = extras != null ? extras.getLong(NotesDbAdapter.KEY_ROWID) + : null; + } + </pre> + </li> + <li> + Note the null check for <code>savedInstanceState</code>, and we still need to load up + <code>mRowId</code> from the <code>extras</code> Bundle if it is not + provided by the <code>savedInstanceState</code>. This is a ternary operator shorthand + to safely either use the value or null if it is not present. + </li> + </ol> + +<h2>Step 4</h2> + +<p>Next, we need to populate the fields based on the <code>mRowId</code> if we + have it:</p> + <pre>populateFields();</pre> + <p>This goes before the <code>confirmButton.setOnClickListener()</code> line. + We'll define this method in a moment.</p> + +<h2>Step 5</h2> + +<p>Get rid of the Bundle creation and Bundle value settings from the + <code>onClick()</code> handler method. The Activity no longer needs to + return any extra information to the caller. And because we no longer have + an Intent to return, we'll use the shorter version + of <code>setResult()</code>:</p> + <pre> +public void onClick(View view) { + setResult(RESULT_OK); + finish(); +}</pre> + <p>We will take care of storing the updates or new notes in the database + ourselves, using the life-cycle methods.</p> + + <p>The whole <code>onCreate()</code> method should now look like this:</p> + <pre> +super.onCreate(savedInstanceState); + +mDbHelper = new NotesDbAdapter(this); +mDbHelper.open(); + +setContentView(R.layout.note_edit); + +mTitleText = (EditText) findViewById(R.id.title); +mBodyText = (EditText) findViewById(R.id.body); + +Button confirmButton = (Button) findViewById(R.id.confirm); + +mRowId = savedInstanceState != null ? savedInstanceState.getLong(NotesDbAdapter.KEY_ROWID) + : null; +if (mRowId == null) { + Bundle extras = getIntent().getExtras(); + mRowId = extras != null ? extras.getLong(NotesDbAdapter.KEY_ROWID) + : null; +} + +populateFields(); + +confirmButton.setOnClickListener(new View.OnClickListener() { + + public void onClick(View view) { + setResult(RESULT_OK); + finish(); + } + +});</pre> + +<h2>Step 6</h2> + +<p>Define the <code>populateFields()</code> method.</p> + <pre> +private void populateFields() { + if (mRowId != null) { + Cursor note = mDbHelper.fetchNote(mRowId); + startManagingCursor(note); + mTitleText.setText(note.getString( + note.getColumnIndexOrThrow(NotesDbAdapter.KEY_TITLE))); + mBodyText.setText(note.getString( + note.getColumnIndexOrThrow(NotesDbAdapter.KEY_BODY))); + } +}</pre> +<p>This method uses the <code>NotesDbAdapter.fetchNote()</code> method to find the right note to +edit, then it calls <code>startManagingCursor()</code> from the <code>Activity</code> class, which +is an Android convenience method provided to take care of the Cursor life-cycle. This will release +and re-create resources as dictated by the Activity life-cycle, so we don't need to worry about +doing that ourselves. After that, we just look up the title and body values from the Cursor +and populate the View elements with them.</p> + + +<h2>Step 7</h2> + + <div class="sidebox" style="border:2px solid #FFFFDD;float:right; + background-color:#FFFFEE;margin-right:0px;margin-bottom:.5em; + margin-top:1em;padding:0em;width:240px;"> + <h2 style="border:0;font-size:12px;padding:.5em .5em .5em 1em;margin:0; + background-color:#FFFFDD;">Why handling life-cycle events is important</h2> + <p style="padding-left:.5em;font-size:12px;margin:0; + padding:.0em .5em .5em 1em;">If you are used to always having control in your applications, you + might not understand why all this life-cycle work is necessary. The reason + is that in Android, you are not in control of your Activity, the + operating system is!</p> + <p style="padding-left:.5em;font-size:12px;margin:0; + padding:.0em .5em .5em 1em;">As we have already seen, the Android model is based around activities + calling each other. When one Activity calls another, the current Activity + is paused at the very least, and may be killed altogether if the + system starts to run low on resources. If this happens, your Activity will + have to store enough state to come back up later, preferably in the same + state it was in when it was killed.</p> + <p style="padding-left:.5em;font-size:12px;margin:0;padding:.0em .5em .5em 1em;"> + Android has a <a href="{@docRoot}intro/lifecycle.html">well-defined life cycle</a>. + Life-cycle events can happen even if you are not handing off control to + another Activity explicitly. For example, perhaps a call comes in to the + handset. If this happens, and your Activity is running, it will be swapped + out while the call Activity takes over.</p> + </div> + +<p>Still in the <code>NoteEdit</code> class, we now override the methods + <code>onSaveInstanceState()</code>, <code>onPause()</code> and + <code>onResume()</code>. These are our life-cycle methods + (along with <code>onCreate()</code> which we already have).</p> + +<p><code>onSaveInstanceState()</code> is called by Android if the + Activity is being stopped and <strong>may be killed before it is + resumed!</strong> This means it should store any state necessary to + re-initialize to the same condition when the Activity is restarted. It is + the counterpart to the <code>onCreate()</code> method, and in fact the + <code>savedInstanceState</code> Bundle passed in to <code>onCreate()</code> is the same + Bundle that you construct as <code>outState</code> in the + <code>onSaveInstanceState()</code> method.</p> + +<p><code>onPause()</code> and <code>onResume()</code> are also + complimentary methods. <code>onPause()</code> is always called when the + Activity ends, even if we instigated that (with a <code>finish()</code> call for example). + We will use this to save the current note back to the database. Good + practice is to release any resources that can be released during an + <code>onPause()</code> as well, to take up less resources when in the + passive state. <code>onResume()</code> will call our <code>populateFields()</code> method + to read the note out of the database again and populate the fields.</p> + +<p>So, add some space after the <code>populateFields()</code> method + and add the following life-cycle methods:</p> + <ol type="a"> + <li><code> + onSaveInstanceState()</code>: + <pre> + @Override + protected void onSaveInstanceState(Bundle outState) { + super.onSaveInstanceState(outState); + outState.putLong(NotesDbAdapter.KEY_ROWID, mRowId); + }</pre> + </li> + <li><code> + onPause()</code>: + <pre> + @Override + protected void onPause() { + super.onPause(); + saveState(); + }</pre> + <p>We'll define <code>saveState()</code> next.</p> + </li> + <li><code> + onResume()</code>: + <pre> + @Override + protected void onResume() { + super.onResume(); + populateFields(); + }</pre> + </li> + </ol> + + +<h2 style="clear:right;">Step 8</h2> + +<p>Define the <code>saveState()</code> method to put the data out to the +database.</p> + <pre> + private void saveState() { + String title = mTitleText.getText().toString(); + String body = mBodyText.getText().toString(); + + if (mRowId == null) { + long id = mDbHelper.createNote(title, body); + if (id > 0) { + mRowId = id; + } + } else { + mDbHelper.updateNote(mRowId, title, body); + } + }</pre> + <p>Note that we capture the return value from <code>createNote()</code> and if a valid row ID is + returned, we store it in the <code>mRowId</code> field so that we can update the note in future + rather than create a new one (which otherwise might happen if the life-cycle events are + triggered).</p> + + +<h2 style="clear:right;">Step 9</h2> + +<p>Now pull out the previous handling code from the + <code>onActivityResult()</code> method in the <code>Notepadv3</code> + class.</p> +<p>All of the note retrieval and updating now happens within the + <code>NoteEdit</code> life cycle, so all the <code>onActivityResult()</code> + method needs to do is update its view of the data, no other work is + necessary. The resulting method should look like this:</p> +<pre> +@Override +protected void onActivityResult(int requestCode, int resultCode, + Intent intent) { + super.onActivityResult(requestCode, resultCode, intent); + fillData(); +}</pre> + +<p>Because the other class now does the work, all this has to do is refresh + the data.</p> + +<h2>Step 10</h2> + +<p>Also remove the lines which set the title and body from the + <code>onListItemClick()</code> method (again they are no longer needed, + only the <code>mRowId</code> is):</p> +<pre> + Cursor c = mNotesCursor; + c.moveToPosition(position);</pre> +<br> +and also remove: +<br> +<pre> + i.putExtra(NotesDbAdapter.KEY_TITLE, c.getString( + c.getColumnIndex(NotesDbAdapter.KEY_TITLE))); + i.putExtra(NotesDbAdapter.KEY_BODY, c.getString( + c.getColumnIndex(NotesDbAdapter.KEY_BODY)));</pre> +<br> +so that all that should be left in that method is: +<br> +<pre> + super.onListItemClick(l, v, position, id); + Intent i = new Intent(this, NoteEdit.class); + i.putExtra(NotesDbAdapter.KEY_ROWID, id); + startActivityForResult(i, ACTIVITY_EDIT);</pre> + + <p>You can also now remove the mNotesCursor field from the class, and set it back to using + a local variable in the <code>fillData()</code> method: +<br><pre> + Cursor notesCursor = mDbHelper.fetchAllNotes();</pre></p> + <p>Note that the <code>m</code> in <code>mNotesCursor</code> denotes a member field, so when we + make <code>notesCursor</code> a local variable, we drop the <code>m</code>. Remember to rename the + other occurrences of <code>mNotesCursor</code> in your <code>fillData()</code> method. +</ol> +<p> +Run it! (use <em>Run As -> Android Application</em> on the project right +click menu again)</p> + +<h2>Solution and Next Steps</h2> + +<p>You can see the solution to this exercise in <code>Notepadv3Solution</code> +from +the zip file to compare with your own.</p> +<p> +When you are ready, move on to the <a href="{@docRoot}intro/tutorial-extra-credit.html">Tutorial +Extra Credit</a> exercise, where you can use the Eclipse debugger to +examine the life-cycle events as they happen.</p> +<p><a href="{@docRoot}intro/tutorial.html">Back to the Tutorial main +page...</a></p> diff --git a/docs/html/guide/tutorials/notepad/notepad-extra-credit.jd b/docs/html/guide/tutorials/notepad/notepad-extra-credit.jd new file mode 100644 index 0000000..9ab84ce --- /dev/null +++ b/docs/html/guide/tutorials/notepad/notepad-extra-credit.jd @@ -0,0 +1,70 @@ +page.title=Tutorial: Extra Credit +@jd:body + + +<p><em>In this exercise, you will use the debugger to look at the work you did +in Exercise 3. This exercise demonstrates:</em></p> +<ul> +<li><em>How to set breakpoints to observe execution</em> </li> +<li><em>How to run your application in debug mode</code></em></li> +</ul> + +<div style="float:right;white-space:nowrap"> + + [<a href="tutorial-ex1.html">Exercise 1</a>] + [<a href="tutorial-ex2.html">Exercise 2</a>] + [<a href="tutorial-ex3.html">Exercise 3</a>] + <span style="color:#BBB;"> + [<a href="tutorial-extra-credit.html" style="color:#BBB;">Extra Credit</a>] + </span> +</div> + +<h2>Step 1</h2> + +<p>Using the working <code>Notepadv3</code>, put breakpoints in the code at the + beginning of the <code>onCreate()</code>, <code>onPause()</code>, + <code>onSaveInstanceState()</code> and <code>onResume()</code> methods in the + <code>NoteEdit</code> class (if you are not familiar with Eclipse, just + right click in the narrow grey border on the left of the edit window at the + line you want a breakpoint, and select <em>Toggle Breakpoint</em>, you +should see a blue dot appear).</p> + +<h2>Step 2</h2> + +<p>Now start the notepad demo in debug mode:</p> + +<ol type="a"> + <li> + Right click on the <code>Notepadv3</code> project and from the Debug menu + select <em>Debug As -> Android Application.</em></li> + <li> + The Android emulator should say <em>"waiting for debugger to connect"</em> + briefly and then run the application.</li> + <li> + If it gets stuck on the waiting... screen, quit the emulator and Eclipse, + from the command line do an <code>adb kill-server</code>, and then restart +Eclipse and try again.</li></ol> + + <h2>Step 3</h2> + +<p>When you edit or create a new note you should see the breakpoints getting + hit and the execution stopping.</p> + + <h2>Step 4</h2> + +<p>Hit the Resume button to let execution continue (yellow rectangle with a +green triangle to its right in the Eclipse toolbars near the top).</p> + +<h2>Step 5</h2> + +<p>Experiment a bit with the confirm and back buttons, and try pressing Home and + making other mode changes. Watch what life-cycle events are generated and +when.</p> + +<p>The Android Eclipse plugin not only offers excellent debugging support for +your application development, but also superb profiling support. You can also +try using <a href="{@docRoot}reference/traceview.html">Traceview</a> to profile your application. If your application is running too slow, this can help you +find the bottlenecks and fix them.</p> +<p><a href="{@docRoot}intro/tutorial.html">Back to the Tutorial main +page...</a></p> + diff --git a/docs/html/guide/tutorials/notepad/notepad-index.jd b/docs/html/guide/tutorials/notepad/notepad-index.jd new file mode 100644 index 0000000..151c50d --- /dev/null +++ b/docs/html/guide/tutorials/notepad/notepad-index.jd @@ -0,0 +1,143 @@ +page.title=Notepad Tutorial +@jd:body + + +<p>The tutorial in this section gives you a "hands-on" introduction +to the Android framework and the tools you use to build applications on it. +Starting from a preconfigured project file, it guides you through the process of +developing a simple notepad application and provides concrete examples of how to +set up the project, develop the application logic and user interface, and then +compile and run the application. </p> + +<p>The tutorial presents the notepad application development as a set of +exercises (see below), each consisting of several steps. You can follow along +with the steps in each exercise and gradually build up and refine your +application. The exercises explain each step in detail and provide all the +sample code you need to complete the application. </p> + +<p>When you are finished with the tutorial, you will have created a functioning +Android application and learned in depth about many of the most important +concepts in Android development. If you want to add more complex features to +your application, you can examine the code in an alternative implementation +of a notepad application, in the +<a href="{@docRoot}samples/NotePad/index.html">Sample Code</a> documentation. </p> + + +<a name="who"></a> +<h2>Who Should Use this Tutorial</h2> + +<p>This tutorial is designed for experienced developers, especially those with +knowledge of the Java programming language. If you haven't written Java +applications before, you can still use the tutorial, but you might need to work +at a slower pace. </p> + +<p>The tutorial assumes that you have some familiarity with the basic Android +application concepts and terminology. If you aren't yet familiar with those, you +should read <a href="{@docRoot}intro/anatomy.html">Overview of an Android +Application</a> before continuing. </p> + +<p>Also note that this tutorial uses +the Eclipse development environment, with the Android plugin installed. If you +are not using Eclipse, you can follow the exercises and build the application, +but you will need to determine how to accomplish the Eclipse-specific +steps in your environment. </p> + +<a name="preparing"></a> +<h2>Preparing for the Exercises</h2> + +<p>This tutorial builds on the information provided in the <a +href="{@docRoot}intro/installing.html">Installing the SDK</a> and <a +href="{@docRoot}intro/hello-android.html">Hello Android</a> +documents, which explain in detail how to set up your development environment +for building Android applications. Before you start this tutorial, you should +read both these documents, have the SDK installed, and your work environment set up.</p> + +<p>To prepare for this lesson:</p> + +<ol> + <li>Download the <a href="codelab/NotepadCodeLab.zip">project + exercises archive (.zip)</a></li> + <li>Unpack the archive file to a suitable location on your machine</li> + <li>Open the <code>NotepadCodeLab</code> folder</li> +</ol> + +<p>Inside the <code>NotepadCodeLab</code> folder, you should see six project +files: <code>Notepadv1</code>, + <code>Notepadv2</code>, <code>Notepadv3</code>, + <code>Notepadv1Solution</code>, <code>Notepadv2Solution</code> + and <code>Notepadv3Solution</code>. The <code>Notepadv#</code> projects are +the starting points for each of the exercises, while the +<code>Notepadv#Solution</code> projects are the exercise + solutions. If you are having trouble with a particular exercise, you + can compare your current work against the exercise solution.</p> + +<a name="exercises"></a> +<h2> Exercises</h2> + + <p>The table below lists the tutorial exercises and describes the development +areas that each covers. Each exercise assumes that you have completed any +previous exercises.</p> + + <table border="0" style="padding:4px;spacing:2px;" summary="This +table lists the +tutorial examples and describes what each covers. "> + <tr> + <th width="120"><a href="{@docRoot}intro/tutorial-ex1.html">Exercise +1</a></th> + <td>Start here. Construct a simple notes list that lets the user add new notes but not +edit them. Demonstrates the basics of <code>ListActivity</code> and creating +and handling + menu options. Uses a SQLite database to store the notes.</td> + </tr> + <tr> + <th><a href="{@docRoot}intro/tutorial-ex2.html">Exercise 2</a></th> + <td>Add a second Activity to the +application. Demonstrates constructing a +new Activity, adding it to the Android manifest, passing data between the +activities, and using more advanced screen layout. Also shows how to +invoke another Activity to return a result, using +<code>startActivityForResult()</code>.</td> + </tr> + <tr> + <th><a href="{@docRoot}intro/tutorial-ex3.html">Exercise 3</a></th> + <td>Add handling of life-cycle events to +the application, to let it +maintain application state across the life cycle. </td> + </tr> + <tr> + <th><a href="{@docRoot}intro/tutorial-extra-credit.html">Extra +Credit</a></th> + <td>Demonstrates how to use the Eclipse +debugger and how you can use it to +view life-cycle events as they are generated. This section is optional but +highly recommended.</td> + </tr> +</table> + + +<a name="other"></a> +<h2>Other Resources and Further Learning</h2> +<ul> +<li>For a lighter but broader introduction to concepts not covered in the +tutorial, +take a look at <a href="{@docRoot}kb/commontasks.html">Common Android Tasks</a>.</li> +<li>The Android SDK includes a variety of fully functioning sample applications +that make excellent opportunities for further learning. You can find the sample +applications in the <code>samples/</code> directory of your downloaded SDK.</li> +<li>This tutorial draws from the full Notepad application included in the +<code>samples/</code> directory of the SDK, though it does not match it exactly. +When you are done with the tutorial, +it is highly recommended that you take a closer look at this version of the Notepad +application, +as it demonstrates a variety of interesting additions for your application, +such as:</li> + <ul> + <li>Setting up a custom striped list for the list of notes.</li> + <li>Creating a custom text edit view that overrides the <code>draw()</code> +method to + make it look like a lined notepad.</li> + <li>Implementing a full <code>ContentProvider</code> for notes.</li> + <li>Reverting and discarding edits instead of just automatically saving +them.</li> +</ul> +</ul> diff --git a/docs/html/guide/tutorials/views/hello-autocomplete.jd b/docs/html/guide/tutorials/views/hello-autocomplete.jd new file mode 100644 index 0000000..9f97b32 --- /dev/null +++ b/docs/html/guide/tutorials/views/hello-autocomplete.jd @@ -0,0 +1,114 @@ +page.title=Hello, AutoCompleteTextView +@jd:body + +<p>{@link android.widget.AutoCompleteTextView} is an implementation of the EditText widget that will provide +auto-complete suggestions as the user types. The suggestions are extracted from a collection of strings.</p> + + +<ol> + <li>Start a new project/Activity called HelloAutoComplete.</li> + <li>Open the layout file. + Make it like so: +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:orientation="horizontal" + android:layout_width="fill_parent" + android:layout_height="wrap_content"> + + <TextView + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="Country" /> + + <AutoCompleteTextView android:id="@+id/edit" + android:layout_width="fill_parent" + android:layout_height="wrap_content"/> + +</LinearLayout> +</pre> +</li> + +<li>Open HelloAutoComplete.java and insert the following as the <code>onCreate</code> method: +<pre> +@Override +protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + + AutoCompleteTextView textView = (AutoCompleteTextView) findViewById(R.id.edit); + ArrayAdapter<String> adapter = new ArrayAdapter<String>(this, + android.R.layout.simple_dropdown_item_1line, R.array.planets); + textView.setAdapter(adapter); +} +</pre> + <p>Here, we create an AutoComplteteTextView from our layout. We then + create an {@link android.widget.ArrayAdapter} that binds a <code>simple_dropdown_item_1line</code> + layout item to each entry in the <code>COUNTRIES</code> array (which we'll add next). + The last part sets the ArrayAdapter to associate with our AutoCompleteTextView.</p> +</li> + +<li>After the <code>onCreate()</code> method, add the String array: +<pre> +static final String[] COUNTRIES = new String[] { + "Afghanistan", "Albania", "Algeria", "American Samoa", "Andorra", + "Angola", "Anguilla", "Antarctica", "Antigua and Barbuda", "Argentina", + "Armenia", "Aruba", "Australia", "Austria", "Azerbaijan", + "Bahrain", "Bangladesh", "Barbados", "Belarus", "Belgium", + "Belize", "Benin", "Bermuda", "Bhutan", "Bolivia", + "Bosnia and Herzegovina", "Botswana", "Bouvet Island", "Brazil", "British Indian Ocean Territory", + "British Virgin Islands", "Brunei", "Bulgaria", "Burkina Faso", "Burundi", + "Cote d'Ivoire", "Cambodia", "Cameroon", "Canada", "Cape Verde", + "Cayman Islands", "Central African Republic", "Chad", "Chile", "China", + "Christmas Island", "Cocos (Keeling) Islands", "Colombia", "Comoros", "Congo", + "Cook Islands", "Costa Rica", "Croatia", "Cuba", "Cyprus", "Czech Republic", + "Democratic Republic of the Congo", "Denmark", "Djibouti", "Dominica", "Dominican Republic", + "East Timor", "Ecuador", "Egypt", "El Salvador", "Equatorial Guinea", "Eritrea", + "Estonia", "Ethiopia", "Faeroe Islands", "Falkland Islands", "Fiji", "Finland", + "Former Yugoslav Republic of Macedonia", "France", "French Guiana", "French Polynesia", + "French Southern Territories", "Gabon", "Georgia", "Germany", "Ghana", "Gibraltar", + "Greece", "Greenland", "Grenada", "Guadeloupe", "Guam", "Guatemala", "Guinea", "Guinea-Bissau", + "Guyana", "Haiti", "Heard Island and McDonald Islands", "Honduras", "Hong Kong", "Hungary", + "Iceland", "India", "Indonesia", "Iran", "Iraq", "Ireland", "Israel", "Italy", "Jamaica", + "Japan", "Jordan", "Kazakhstan", "Kenya", "Kiribati", "Kuwait", "Kyrgyzstan", "Laos", + "Latvia", "Lebanon", "Lesotho", "Liberia", "Libya", "Liechtenstein", "Lithuania", "Luxembourg", + "Macau", "Madagascar", "Malawi", "Malaysia", "Maldives", "Mali", "Malta", "Marshall Islands", + "Martinique", "Mauritania", "Mauritius", "Mayotte", "Mexico", "Micronesia", "Moldova", + "Monaco", "Mongolia", "Montserrat", "Morocco", "Mozambique", "Myanmar", "Namibia", + "Nauru", "Nepal", "Netherlands", "Netherlands Antilles", "New Caledonia", "New Zealand", + "Nicaragua", "Niger", "Nigeria", "Niue", "Norfolk Island", "North Korea", "Northern Marianas", + "Norway", "Oman", "Pakistan", "Palau", "Panama", "Papua New Guinea", "Paraguay", "Peru", + "Philippines", "Pitcairn Islands", "Poland", "Portugal", "Puerto Rico", "Qatar", + "Reunion", "Romania", "Russia", "Rwanda", "Sqo Tome and Principe", "Saint Helena", + "Saint Kitts and Nevis", "Saint Lucia", "Saint Pierre and Miquelon", + "Saint Vincent and the Grenadines", "Samoa", "San Marino", "Saudi Arabia", "Senegal", + "Seychelles", "Sierra Leone", "Singapore", "Slovakia", "Slovenia", "Solomon Islands", + "Somalia", "South Africa", "South Georgia and the South Sandwich Islands", "South Korea", + "Spain", "Sri Lanka", "Sudan", "Suriname", "Svalbard and Jan Mayen", "Swaziland", "Sweden", + "Switzerland", "Syria", "Taiwan", "Tajikistan", "Tanzania", "Thailand", "The Bahamas", + "The Gambia", "Togo", "Tokelau", "Tonga", "Trinidad and Tobago", "Tunisia", "Turkey", + "Turkmenistan", "Turks and Caicos Islands", "Tuvalu", "Virgin Islands", "Uganda", + "Ukraine", "United Arab Emirates", "United Kingdom", + "United States", "United States Minor Outlying Islands", "Uruguay", "Uzbekistan", + "Vanuatu", "Vatican City", "Venezuela", "Vietnam", "Wallis and Futuna", "Western Sahara", + "Yemen", "Yugoslavia", "Zambia", "Zimbabwe" +}; +</pre> + <p>This is the list of suggestions that will be offered as the user types into the + AutoCompleteTextView.</p> +</li> + +<li>Now run it.</li> +</ol> +<p>As you type, you should see something like this:</p> +<img src="images/hello-autocomplete.png" width="150px" /> + + +<h3>References</h3> +<ul> + <li>{@link android.R.layout}</li> + <li>{@link android.widget.ArrayAdapter}</li> + <li>{@link android.widget.AutoCompleteTextView}</li> +</ul> + +<p><a href="{@docRoot}guide/tutorials/views/hello-views-index.html">← Back to Hello Views</a></p> diff --git a/docs/html/guide/tutorials/views/hello-datepicker.jd b/docs/html/guide/tutorials/views/hello-datepicker.jd new file mode 100644 index 0000000..b35d4db --- /dev/null +++ b/docs/html/guide/tutorials/views/hello-datepicker.jd @@ -0,0 +1,149 @@ +page.title=Hello, DatePicker +@jd:body + +<p>A {@link android.widget.DatePicker} is a widget that allows the user to select a month, day and year.</p> + + +<ol> + <li>Start a new project/Activity called HelloDatePicker.</li> + <li>Open the layout file and make it like so: + <pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:orientation="vertical"> + + <TextView android:id="@+id/dateDisplay" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text=""/> + + <Button android:id="@+id/pickDate" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="Change the date"/> + +</LinearLayout> +</pre> + <p>For the layout, we're using a vertical LinearLayout, with a {@link android.widget.TextView} that + will display the date and a {@link android.widget.Button} that will initiate the DatePicker dialog. + With this layout, the TextView will sit above the Button. + The text value in the TextView is set empty, as it will be filled + with the current date when our Activity runs.</p> + </li> + + <li>Open HelloDatePicker.java. Insert the following to the HelloDatePicker class: +<pre> + private TextView mDateDisplay; + private Button mPickDate; + + private int mYear; + private int mMonth; + private int mDay; + + static final int DATE_DIALOG_ID = 0; + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + + // capture our View elements + mDateDisplay = (TextView) findViewById(R.id.dateDisplay); + mPickDate = (Button) findViewById(R.id.pickDate); + + // add a click listener to the button + mPickDate.setOnClickListener(new View.OnClickListener() { + public void onClick(View v) { + showDialog(DATE_DIALOG_ID); + } + }); + + // get the current date + final Calendar c = Calendar.getInstance(); + mYear = c.get(Calendar.YEAR); + mMonth = c.get(Calendar.MONTH); + mDay = c.get(Calendar.DAY_OF_MONTH); + + // display the current date + updateDisplay(); + } +</pre> +<p class="note"><strong>Tip:</strong> Press Ctrl(or Cmd) + Shift + O to import all needed packages.</p> + <p>We start by instantiating variables for our Views and date fields. + The <code>DATE_DIALOG_ID</code> is a static integer that uniquely identifies the Dialog. In the + <code>onCreate()</code> method, we get prepared by setting the layout and capturing the View elements. + Then we create an on-click listener for the Button, so that when it is clicked it will + show our DatePicker dialog. The <code>showDialog()</code> method will pop-up the date picker dialog + by calling the <code>onCreateDialog()</code> callback method + (which we'll define in the next section). We then create an + instance of {@link java.util.Calendar} and get the current year, month and day. Finally, we call + <code>updateDisplay()</code>—our own method (defined later) that will fill the TextView.</p> +</li> + +<li>After the <code>onCreate()</code> method, add the <code>onCreateDialog()</code> callback method +(which is called by <code>showDialog()</code>) +<pre> +@Override +protected Dialog onCreateDialog(int id) { + switch (id) { + case DATE_DIALOG_ID: + return new DatePickerDialog(this, + mDateSetListener, + mYear, mMonth, mDay); + } + return null; +} +</pre> + <p>This method is passed the identifier we gave <code>showDialog()</code> and initializes + the DatePicker to the date we retrieved from our Calendar instance.</p> +</li> + +<li>Following that, add the <code>updateDisplay()</code> method: +<pre> + // updates the date we display in the TextView + private void updateDisplay() { + mDateDisplay.setText( + new StringBuilder() + // Month is 0 based so add 1 + .append(mMonth + 1).append("-") + .append(mDay).append("-") + .append(mYear).append(" ")); + } +</pre> +<p>This uses the member date values to write the date to our TextView.</p> +</li> +<li>Finally, add a listener that will be called when the user sets a new date: +<pre> + // the callback received when the user "sets" the date in the dialog + private DatePickerDialog.OnDateSetListener mDateSetListener = + new DatePickerDialog.OnDateSetListener() { + + public void onDateSet(DatePicker view, int year, + int monthOfYear, int dayOfMonth) { + mYear = year; + mMonth = monthOfYear; + mDay = dayOfMonth; + updateDisplay(); + } + }; +</pre> + <p>This <code>OnDateSetListener</code> method listens for when the user is done setting the date + (clicks the "Set" button). At that time, this fires and we update our member fields with + the new date defined by the user and update our TextView by calling <code>updateDisplay()</code>.</p> +</li> + +<li>Now run it.</li> +</ol> +<p>When you press the "Change the date" button, you should see the following:</p> +<img src="images/hello-datepicker.png" width="150px" /> + +<h3>References</h3> +<ul> +<li>{@link android.widget.DatePicker}</li> +<li>{@link android.widget.Button}</li> +<li>{@link android.widget.TextView}</li> +<li>{@link java.util.Calendar}</li> +</ul> +<p><a href="{@docRoot}guide/tutorials/views/hello-views-index.html">← Back to Hello Views</a></p> diff --git a/docs/html/guide/tutorials/views/hello-formstuff.jd b/docs/html/guide/tutorials/views/hello-formstuff.jd new file mode 100644 index 0000000..80ae6ce --- /dev/null +++ b/docs/html/guide/tutorials/views/hello-formstuff.jd @@ -0,0 +1,261 @@ +page.title=Hello, Form Stuff +@jd:body + +<p>This page introduces a variety of widgets, like image buttons, +text fields, checkboxes and radio buttons.</p> + + +<ol> + <li>Start a new project/Activity called HelloFormStuff.</li> + <li>Your layout file should have a basic LinearLayout: + <pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:orientation="vertical" + android:layout_width="fill_parent" + android:layout_height="fill_parent" > + +</LinearLayout> +</pre> + <p>For each widget you want to add, just put the respective View inside here.</p> +</li> +</ol> +<p class="note"><strong>Tip:</strong> As you add new Android code, press Ctrl(or Cmd) + Shift + O +to import all needed packages.</p> + + +<h2>ImageButton</h2> +<p>A button with a custom image on it. +We'll make it display a message when pressed.</p> +<ol> + <li><img src="images/android.png" align="right"/> + Drag the Android image on the right (or your own image) into the + res/drawables/ directory of your project. + We'll use this for the button.</li> + <li>Open the layout file and, inside the LinearLayout, add the {@link android.widget.ImageButton} element: +<pre> +<ImageButton + android:id="@+id/android_button" + android:layout_width="100dip" + android:layout_height="wrap_content" + android:src="@drawable/android" /> +</pre> + <p>The source of the button + is from the res/drawables/ directory, where we've placed the android.png.</p> + <p class="note"><strong>Tip:</strong> You can also reference some of the many built-in + images from the Android {@link android.R.drawable} resources, + like <code>ic_media_play</code>, for a "play" button image. To do so, change the source + attribute to <code>android:src="@android:drawable/ic_media_play"</code>.</p> +</li> +<li>To make the button to actually do something, add the following +code at the end of the <code>onCreate()</code> method: +<pre> +ImageButton button = (ImageButton) findViewById(R.id.android_button); +button.setOnClickListener(new OnClickListener() { + public void onClick(View v) { + // Perform action on clicks + Toast.makeText(HelloFormStuff.this, "Beep Bop", Toast.LENGTH_SHORT).show(); + } +}); +</pre> +<p>This captures our ImageButton from the layout, then adds an on-click listener to it. +The {@link android.view.View.OnClickListener} must define the <code>onClick()</code> method, which +defines the action to be made when the button is clicked. Here, we show a +{@link android.widget.Toast} message when clicked.</p> +</li> +<li>Run it.</li> +</ol> + + +<h2>EditText</h2> +<p>A text field for user input. We'll make it display the text entered so far when the "Enter" key is pressed.</p> + +<ol> + <li>Open the layout file and, inside the LinearLayout, add the {@link android.widget.EditText} element: +<pre> +<EditText + android:id="@+id/edittext" + android:layout_width="fill_parent" + android:layout_height="wrap_content"/> +</pre> +</li> +<li>To do something with the text that the user enters, add the following code +to the end of the <code>onCreate()</code> method: +<pre> +EditText edittext = (EditText) findViewById(R.id.edittext); +edittext.setOnKeyListener(new OnKeyListener() { + public boolean onKey(View v, int keyCode, KeyEvent event) { + if ((event.getAction() == KeyEvent.ACTION_DOWN) && (keyCode == KeyEvent.KEYCODE_ENTER)) { + // Perform action on key press + Toast.makeText(HelloImageButton.this, edittext.getText(), Toast.LENGTH_SHORT).show(); + return true; + } + return false; + } +}); +</pre> +<p>This captures our EditText element from the layout, then adds an on-key listener to it. +The {@link android.view.View.OnKeyListener} must define the <code>onKey()</code> method, which +defines the action to be made when a key is pressed. In this case, we want to listen for the +Enter key (when pressed down), then pop up a {@link android.widget.Toast} message with the +text from the EditText field. Be sure to return <var>true</var> after the event is handled, +so that the event doesn't bubble-up and get handled by the View (which would result in a +carriage return in the text field).</p> +<li>Run it.</li> +</ol> + + +<h2>CheckBox</h2> +<p>A checkbox for selecting items. We'll make it display the the current state when pressed.</p> + +<ol> + <li>Open the layout file and, inside the LinearLayout, add the {@link android.widget.CheckBox} element: +<pre> +<CheckBox android:id="@+id/checkbox" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="check it out" /> +</pre> +</li> +<li>To do something when the state is changed, add the following code +to the end of the <code>onCreate()</code> method: +<pre> +final CheckBox checkbox = (CheckBox) findViewById(R.id.checkbox); +checkbox.setOnClickListener(new OnClickListener() { + public void onClick(View v) { + // Perform action on clicks + if (checkbox.isChecked()) { + Toast.makeText(HelloImageButton.this, "Selected", Toast.LENGTH_SHORT).show(); + } else { + Toast.makeText(HelloImageButton.this, "Not selected", Toast.LENGTH_SHORT).show(); + } + } +}); +</pre> +<p>This captures our CheckBox element from the layout, then adds an on-click listener to it. +The {@link android.view.View.OnClickListener} must define the <code>onClick()</code> method, which +defines the action to be made when the checkbox is clicked. Here, we query the current state of the +checkbox, then pop up a {@link android.widget.Toast} message that displays the current state. +Notice that the CheckBox handles its own state change between checked and un-checked, so we just +ask which it currently is.</p> +<li>Run it.</li> +</ol> +<p class="note"><strong>Tip:</strong> If you find that you need to change the state +in another way (such as when loading a saved {@link android.preference.CheckBoxPreference}), +use <code>setChecked(true)</code> or <code>toggle()</code>.</p> + + +<h2>RadioButton</h2> +<p>Two mutually-exclusive radio buttons—enabling one disables the other. +When each is pressed, we'll pop up a message.</p> + +<ol> + <li>Open the layout file and, inside the LinearLayout, add two {@link android.widget.RadioButton}s, +inside a {@link android.widget.RadioGroup}: +<pre> +<RadioGroup + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:orientation="vertical"> + + <RadioButton android:id="@+id/radio_red" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="Red" /> + + <RadioButton android:id="@+id/radio_blue" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="Blue" /> + +</RadioGroup> +</pre> +</li> +<li>To do something when each is selected, we'll need an OnClickListener. Unlike the other +listeners we've created, instead of creating this one as an anonymous inner class, +we'll create it as a new object. This way, we can re-use the OnClickLIstener for +both RadioButtons. So, add the following code in the HelloFormStuff Activity +(<em>outside</em> the <code>onCreate()</code> method): +<pre> +OnClickListener radio_listener = new OnClickListener() { + public void onClick(View v) { + // Perform action on clicks + RadioButton rb = (RadioButton) v; + Toast.makeText(HelloImageButton.this, rb.getText(), Toast.LENGTH_SHORT).show(); + } +}; +</pre> +<p>Our <code>onClick()</code> method will be handed the View clicked, so the first thing to do +is cast it into a RadioButton. Then we pop up a +{@link android.widget.Toast} message that displays the selection.</p> +<li>Now, at the bottom of the <code>onCreate()</code> method, add the following: +<pre> + final RadioButton radio_red = (RadioButton) findViewById(R.id.radio_red); + final RadioButton radio_blue = (RadioButton) findViewById(R.id.radio_blue); + radio_red.setOnClickListener(radio_listener); + radio_blue.setOnClickListener(radio_listener); +</pre> +<p>This captures each of the RadioButtons from our layout and adds the newly-created +OnClickListener to each.</p> +<li>Run it.</li> +</ol> +<p class="note"><strong>Tip:</strong> If you find that you need to change the state of a +RadioButton in another way (such as when loading a saved {@link android.preference.CheckBoxPreference}), +use <code>setChecked(true)</code> or <code>toggle()</code>.</p> + + +<h2>ToggleButton</h2> +<p>A button used specifically for toggling something on and off.</p> + +<ol> + <li>Open the layout file and, inside the LinearLayout, add the {@link android.widget.ToggleButton} element: +<pre> +<ToggleButton android:id="@+id/togglebutton" + android:layout_width="wrap_content" + android:layout_height="wrap_content" /> +</pre> +</li> +<li>To do something when the state is changed, add the following code +to the end of the <code>onCreate()</code> method: +<pre> +final ToggleButton togglebutton = (ToggleButton) findViewById(R.id.togglebutton); +togglebutton.setOnClickListener(new OnClickListener() { + public void onClick(View v) { + // Perform action on clicks + if (togglebutton.isChecked()) { + Toast.makeText(HelloImageButton.this, "ON", Toast.LENGTH_SHORT).show(); + } else { + Toast.makeText(HelloImageButton.this, "OFF", Toast.LENGTH_SHORT).show(); + } + } +}); +</pre> +<p>This captures our ToggleButton element from the layout, then adds an on-click listener to it. +The {@link android.view.View.OnClickListener} must define the <code>onClick()</code> method, which +defines the action to be made when the button is clicked. Here, we query the current state of the +ToggleButton, then pop up a {@link android.widget.Toast} message that displays the current state. +Notice that the ToggleButton handles its own state change between checked and un-checked, so we just +ask which it is.</p> +<li>Run it.</li> +</ol> + +<p class="note"><strong>Tip:</strong> By default, the text on the button is "ON" and "OFF", but +you can change each of these with <code>setTextOn(<var>CharSequence</var>)</code> and +<code>setTextOff(<var>CharSequence</var>)</code>. And, if you find that you need to change the state +in another way (such as when loading a saved {@link android.preference.CheckBoxPreference}), +use <code>setChecked(true)</code> or <code>toggle()</code>. </p> + + +<p>If you've added all the form items above, your application should look something like this:</p> +<img src="images/hello-formstuff.png" width="150px" /> + +<h3>References</h3> +<ul> + <li>{@link android.widget.ImageButton}</li> + <li>{@link android.widget.EditText}</li> + <li>{@link android.widget.CheckBox}</li> + <li>{@link android.widget.RadioButton}</li> + <li>{@link android.widget.ToggleButton}</li> +</ul> + +<p><a href="{@docRoot}guide/tutorials/views/hello-views-index.html">← Back to Hello Views</a></p> diff --git a/docs/html/guide/tutorials/views/hello-gallery.jd b/docs/html/guide/tutorials/views/hello-gallery.jd new file mode 100644 index 0000000..af01757 --- /dev/null +++ b/docs/html/guide/tutorials/views/hello-gallery.jd @@ -0,0 +1,133 @@ +page.title=Hello, Gallery +@jd:body + +<p>A {@link android.widget.Gallery} is a View commonly used to display items in a horizontally scrolling list +that locks the current selection at the center. When one is selected, we'll show a message.</p> + + +<ol> + <li>Start a new project/Activity called HelloGallery.</li> + <li>Add some images to your res/drawable/ directory.</li> + <li>Open the layout file and make it like so: +<pre> +<?xml version="1.0" encoding="utf-8"?> +<Gallery xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/gallery" + android:layout_width="fill_parent" + android:layout_height="wrap_content" +/> +</pre> +</li> + + +<li>Open the HelloGallery.java file. Insert the following for the <code>onCreate()</code> method: +<pre> +@Override +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + + Gallery g = (Gallery) findViewById(R.id.gallery); + g.setAdapter(new ImageAdapter(this)); + + g.setOnItemClickListener(new OnItemClickListener() { + public void onItemClick(AdapterView parent, View v, int position, long id) { + Toast.makeText(HelloGallery.this, "" + position, Toast.LENGTH_SHORT).show(); + } + }); +} +</pre> + <p>We start as usual: set the layout and capture the View we want (our Gallery). +We then set an Adapter, called ImageAdapter for the Gallery—this is a new class that +we'll create next. Then we create an item click listener for the Gallery. This is like a normal +on-click listener (which you might be familiar with for buttons), but it listens to each item +that we've added to the Gallery. The <code>onItemClick()</code> callback method +receives the AdapterView where the click occurred, the specific View that received the click, the +position of the View clicked (zero-based), and the row id of the item clicked (if applicable). All +that we care about is the position, so that we can pop up a {@link android.widget.Toast} message that +tells us the index position of the item clicked. We do this with <code>Toast.makeText().show()</code>. +</p> +</li> + +<li>After the <code>onCreate()</code> method, add the <code>ImageAdapter</code> class: +<pre> +public class ImageAdapter extends BaseAdapter { + int mGalleryItemBackground; + private Context mContext; + + private Integer[] mImageIds = { + R.drawable.sample_1, + R.drawable.sample_2, + R.drawable.sample_3, + R.drawable.sample_4, + R.drawable.sample_5, + R.drawable.sample_6, + R.drawable.sample_7 + }; + + public ImageAdapter(Context c) { + mContext = c; + TypedArray a = obtainStyledAttributes(android.R.styleable.Theme); + mGalleryItemBackground = a.getResourceId( + android.R.styleable.Theme_galleryItemBackground, 0); + a.recycle(); + } + + public int getCount() { + return mImageIds.length; + } + + public Object getItem(int position) { + return position; + } + + public long getItemId(int position) { + return position; + } + + public View getView(int position, View convertView, ViewGroup parent) { + ImageView i = new ImageView(mContext); + + i.setImageResource(mImageIds[position]); + i.setLayoutParams(new Gallery.LayoutParams(150, 100)); + i.setScaleType(ImageView.ScaleType.FIT_XY); + i.setBackgroundResource(mGalleryItemBackground); + + return i; + } +} +</pre> +<p>First, there are a few member variables, including an array of IDs that reference +the images we placed in our drawable resources directory.</p> +<p>Next is the constructor, where we define the member Context. The rest of the constructor +sets up a reference for our Gallery them, which adds the nice framing for each Gallery item. +Once we have our <code>mGalleryItemBackground</code>, it's important to recycle the +StyledAttribute for later re-use.</p> +<p>The next three methods are required for basic member queries. +But then we have the <code>getView()</code> method, which is called +for each item read by our ImageAdapter, when the Gallery is being built. Here, we +use our member Context to create a new {@link android.widget.ImageView}. We then define +the image resource with the current position of the Gallery items (corresponding to our +array of drawables), set the dimensions for the ImageView, +set the image scaling to fit the ImageView dimensions, then finally set the +background theme for the ImageView.</p> + +<p>See {@link android.widget.ImageView.ScaleType} +for other image scaling options, in case you want to avoid stretching images that don't +exactly match the ImageView dimensions.</p> + +<li>Now run it.</li> +</ol> +<p>You should see something like this:</p> +<img src="images/hello-gallery.png" width="150px" /> + + +<h3>References</h3> +<ul> + <li>{@link android.widget.BaseAdapter}</li> + <li>{@link android.widget.Gallery}</li> + <li>{@link android.widget.ImageView}</li> + <li>{@link android.widget.Toast}</li> +</ul> +<p><a href="{@docRoot}guide/tutorials/views/hello-views-index.html">← Back to Hello Views</a></p> + diff --git a/docs/html/guide/tutorials/views/hello-gridview.jd b/docs/html/guide/tutorials/views/hello-gridview.jd new file mode 100644 index 0000000..d5c8628 --- /dev/null +++ b/docs/html/guide/tutorials/views/hello-gridview.jd @@ -0,0 +1,127 @@ +page.title=Hello, GridView +@jd:body + +<p>A {@link android.widget.GridView} displays items in a two-dimensional, scrolling grid. The items +are acquired from a {@link android.widget.ListAdapter}.</p> + + +<ol> + <li>Start a new project/Activity called HelloGridView.</li> + <li>Find some photos you'd like to use, or copy some from the SDK samples res/drawable/ + folder of your project.</li> + <li>Open the layout and make it like so: +<pre> +<?xml version="1.0" encoding="utf-8"?> +<GridView xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/gridview" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:numColumns="auto_fit" + android:verticalSpacing="10dp" + android:horizontalSpacing="10dp" + android:columnWidth="90dp" + android:stretchMode="columnWidth" + android:gravity="center" +/> +</li> + <li>Open the HelloGridView Java file. Insert the following for the <code>onCreate()</code> method: +<pre> +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + + GridView gridview = (GridView) findViewById(R.id.gridview); + gridview.setAdapter(new ImageAdapter(this)); +} +</pre> + <p>Here, we get a handle on our GridView, from the layout, and give it an Adapter. + We're actually going to create our own Adapter called ImageAdapter.</p> +</li> +<li>Create a new class (nested or otherwise), called ImageAdapter, which extends {@link android.widget.BaseAdapter}: +<pre> +public class ImageAdapter extends BaseAdapter { + private Context mContext; + + public ImageAdapter(Context c) { + mContext = c; + } + + public int getCount() { + return mThumbIds.length; + } + + public Object getItem(int position) { + return null; + } + + public long getItemId(int position) { + return 0; + } + + // create a new ImageView for each item referenced by the Adapter + public View getView(int position, View convertView, ViewGroup parent) { + ImageView imageView; + if (convertView == null) { // if it's not recycled, initialize some attributes + imageView = new ImageView(mContext); + imageView.setLayoutParams(new GridView.LayoutParams(85, 85)); + imageView.setScaleType(ImageView.ScaleType.CENTER_CROP); + imageView.setPadding(8, 8, 8, 8); + } else { + imageView = (ImageView) convertView; + } + + imageView.setImageResource(mThumbIds[position]); + return imageView; + } + + // references to our images + private Integer[] mThumbIds = { + R.drawable.sample_2, R.drawable.sample_3, + R.drawable.sample_4, R.drawable.sample_5, + R.drawable.sample_6, R.drawable.sample_7, + R.drawable.sample_0, R.drawable.sample_1, + R.drawable.sample_2, R.drawable.sample_3, + R.drawable.sample_4, R.drawable.sample_5, + R.drawable.sample_6, R.drawable.sample_7, + R.drawable.sample_0, R.drawable.sample_1, + R.drawable.sample_2, R.drawable.sample_3, + R.drawable.sample_4, R.drawable.sample_5, + R.drawable.sample_6, R.drawable.sample_7 + }; +} +</pre> + <p>First we take care of some required methods inherited from BaseAdapter. + The constructor and <code>getCount()</code> are self-explanitory. Normally, <code>getItem()</code> + should return the actual object at the specified position in our Adapter, but for this Hello World, + we're not going to bother. Likewise, <code>getItemId()</code> should return the row id of + the item, but right now we don't care.</p> + <p>However, <code>getView()</code> is the method we care about. This one creates a new View for each image that we + put in our ImageAdapter. So we're going to create an ImageView each time. When this is called, we're + going to receive a View, which is likely a recycled View object (at least after the first call), so we + check for this—if it's null, we initialize the ImageView and setup all the properties we want. + The <code>LayoutParams()</code> initialization sets the height and width of the View—this ensures + that no matter the drawable size, each image is resized and cropped to fit in the ImageView (if necessary). + With <code>setScaleType()</code>, we say that images should be cropped toward the center (if necessary). + And finally, we set the padding within the ImageView. (Note that, if the images have various aspect-ratios, + as they do in this demo, then less padding will cause for more cropping of the image, if it does not match + the dimensions given to the ImageView.) At the end of <code>getView()</code> we set the image resource and + return the ImageView.</p> + <p>All that's left is our array or drawable resources at the bottom.</p> +</li> +<li>Run it.</li> +</ol> +<p>Your grid layout should look something like this:</p> +<img src="images/hello-gridview.png" width="150px" /> + +<p>Try experimenting with the behaviors of the GridView and ImageView by adjusting their properties. For example, + instead of setting the ImageView LayoutParams, you can try using + {@link android.widget.ImageView#setAdjustViewBounds(boolean)}. </p> + +<h3>References</h3> +<ul> + <li>{@link android.widget.GridView}</li> + <li>{@link android.widget.ImageView}</li> + <li>{@link android.widget.BaseAdapter}</li> +</ul> + +<p><a href="{@docRoot}guide/tutorials/views/hello-views-index.html">← Back to Hello Views</a></p> diff --git a/docs/html/guide/tutorials/views/hello-linearlayout.jd b/docs/html/guide/tutorials/views/hello-linearlayout.jd new file mode 100644 index 0000000..ecea062 --- /dev/null +++ b/docs/html/guide/tutorials/views/hello-linearlayout.jd @@ -0,0 +1,128 @@ +page.title=Hello, LinearLayout +@jd:body + +<p>A {@link android.widget.LinearLayout} is a GroupView that will lay child View elements +vertically or horizontally.</p> + + +<ol> + <li>Start a new project/Activity called HelloLinearLayout.</li> + <li>Open the layout file. + Make it like so: +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:orientation="vertical" + android:layout_width="fill_parent" + android:layout_height="fill_parent"> + + <LinearLayout + android:orientation="horizontal" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:layout_weight="1"> + + <TextView + android:text="red" + android:gravity="center_horizontal" + android:background="#aa0000" + android:layout_width="wrap_content" + android:layout_height="fill_parent" + android:layout_weight="1"/> + + <TextView + android:text="green" + android:gravity="center_horizontal" + android:background="#00aa00" + android:layout_width="wrap_content" + android:layout_height="fill_parent" + android:layout_weight="1"/> + + <TextView + android:text="blue" + android:gravity="center_horizontal" + android:background="#0000aa" + android:layout_width="wrap_content" + android:layout_height="fill_parent" + android:layout_weight="1"/> + + <TextView + android:text="yellow" + android:gravity="center_horizontal" + android:background="#aaaa00" + android:layout_width="wrap_content" + android:layout_height="fill_parent" + android:layout_weight="1"/> + + </LinearLayout> + + <LinearLayout + android:orientation="vertical" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:layout_weight="1"> + + <TextView + android:text="row one" + android:textSize="15pt" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:layout_weight="1"/> + + <TextView + android:text="row two" + android:textSize="15pt" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:layout_weight="1"/> + + <TextView + android:text="row three" + android:textSize="15pt" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:layout_weight="1"/> + + <TextView + android:text="row four" + android:textSize="15pt" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:layout_weight="1"/> + + </LinearLayout> + +</LinearLayout> +</pre> + <p>Carefully inspect the XML. You'll notice how this layout works a lot like + an HTML layout. There is one parent LinearLayout that is defined to lay + its child elements vertically. The first child is another LinearLayout that uses a horizontal layout + and the second uses a vertical layout. Each LinearLayout contains several {@link android.widget.TextView} + elements.</p> +</li> +<li>Now open the HelloLinearLayout Activity and be sure it loads this layout in the <code>onCreate()</code> method:</p> +<pre> +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); +} +</pre> +<p><code>R.layout.main</code> refers to the <code>main.xml</code> layout file.</p> +</li> +<li>Run it.</li> +</ol> +<p>You should see the following:</p> +<img src="images/hello-linearlayout.png" width="150px" /> + +<p>Notice how the various XML attributes define the View's behavior. +Pay attention to the effect of the <code>layout_weight</code>. Try + experimenting with different values to see how the screen real estate is + distributed based on the weight of each element.</p> + +<h3>References</h3> +<ul> + <li>{@link android.widget.LinearLayout}</li> +<li>{@link android.widget.TextView}</li> +</ul> + +<p><a href="{@docRoot}guide/tutorials/views/hello-views-index.html">← Back to Hello Views</a></p> diff --git a/docs/html/guide/tutorials/views/hello-listview.jd b/docs/html/guide/tutorials/views/hello-listview.jd new file mode 100644 index 0000000..41b7f6e --- /dev/null +++ b/docs/html/guide/tutorials/views/hello-listview.jd @@ -0,0 +1,89 @@ +page.title=Hello, ListView +@jd:body + +<p>A {@link android.widget.ListView} is a View that shows items in a vertically scrolling list. The items are + acquired from a {@link android.widget.ListAdapter}.</p> + + +<ol> + <li>Start a new project/ListActivity called HelloListView.</li> + <li>Open the HelloListView Java file. Make the class extend ListActivity (instead of Activity). + <pre>public class HelloListView extends ListActivity {</pre> + </li> + <li>Insert the following for the <code>onCreate()</code> method: +<pre> +@Override +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + + setListAdapter(new ArrayAdapter<String>(this, + android.R.layout.simple_list_item_1, COUNTRIES)); + getListView().setTextFilterEnabled(true); +} +</pre> + <p>Notice that we don't need to load a layout (at least, not in this case, because we're using + the whole screen for our list). Instead, we just call <code>setListAdapter()</code> (which automatically + adds a ListView to the ListActivity), and provide it with an ArrayAdapter that binds a + <code>simple_list_item_1</code> layout item to each entry in the <code>COUNTRIES</code> + array (added next). The next line of code adds a text filter to the ListView, so that when the user + begins typing, the list will filter the entire view to display only the items that match the entry.</p> + </li> + <li>Following the <code>onCreate()</code> method, add the String array: +<pre> + static final String[] COUNTRIES = new String[] { + "Afghanistan", "Albania", "Algeria", "American Samoa", "Andorra", + "Angola", "Anguilla", "Antarctica", "Antigua and Barbuda", "Argentina", + "Armenia", "Aruba", "Australia", "Austria", "Azerbaijan", + "Bahrain", "Bangladesh", "Barbados", "Belarus", "Belgium", + "Belize", "Benin", "Bermuda", "Bhutan", "Bolivia", + "Bosnia and Herzegovina", "Botswana", "Bouvet Island", "Brazil", "British Indian Ocean Territory", + "British Virgin Islands", "Brunei", "Bulgaria", "Burkina Faso", "Burundi", + "Cote d'Ivoire", "Cambodia", "Cameroon", "Canada", "Cape Verde", + "Cayman Islands", "Central African Republic", "Chad", "Chile", "China", + "Christmas Island", "Cocos (Keeling) Islands", "Colombia", "Comoros", "Congo", + "Cook Islands", "Costa Rica", "Croatia", "Cuba", "Cyprus", "Czech Republic", + "Democratic Republic of the Congo", "Denmark", "Djibouti", "Dominica", "Dominican Republic", + "East Timor", "Ecuador", "Egypt", "El Salvador", "Equatorial Guinea", "Eritrea", + "Estonia", "Ethiopia", "Faeroe Islands", "Falkland Islands", "Fiji", "Finland", + "Former Yugoslav Republic of Macedonia", "France", "French Guiana", "French Polynesia", + "French Southern Territories", "Gabon", "Georgia", "Germany", "Ghana", "Gibraltar", + "Greece", "Greenland", "Grenada", "Guadeloupe", "Guam", "Guatemala", "Guinea", "Guinea-Bissau", + "Guyana", "Haiti", "Heard Island and McDonald Islands", "Honduras", "Hong Kong", "Hungary", + "Iceland", "India", "Indonesia", "Iran", "Iraq", "Ireland", "Israel", "Italy", "Jamaica", + "Japan", "Jordan", "Kazakhstan", "Kenya", "Kiribati", "Kuwait", "Kyrgyzstan", "Laos", + "Latvia", "Lebanon", "Lesotho", "Liberia", "Libya", "Liechtenstein", "Lithuania", "Luxembourg", + "Macau", "Madagascar", "Malawi", "Malaysia", "Maldives", "Mali", "Malta", "Marshall Islands", + "Martinique", "Mauritania", "Mauritius", "Mayotte", "Mexico", "Micronesia", "Moldova", + "Monaco", "Mongolia", "Montserrat", "Morocco", "Mozambique", "Myanmar", "Namibia", + "Nauru", "Nepal", "Netherlands", "Netherlands Antilles", "New Caledonia", "New Zealand", + "Nicaragua", "Niger", "Nigeria", "Niue", "Norfolk Island", "North Korea", "Northern Marianas", + "Norway", "Oman", "Pakistan", "Palau", "Panama", "Papua New Guinea", "Paraguay", "Peru", + "Philippines", "Pitcairn Islands", "Poland", "Portugal", "Puerto Rico", "Qatar", + "Reunion", "Romania", "Russia", "Rwanda", "Sqo Tome and Principe", "Saint Helena", + "Saint Kitts and Nevis", "Saint Lucia", "Saint Pierre and Miquelon", + "Saint Vincent and the Grenadines", "Samoa", "San Marino", "Saudi Arabia", "Senegal", + "Seychelles", "Sierra Leone", "Singapore", "Slovakia", "Slovenia", "Solomon Islands", + "Somalia", "South Africa", "South Georgia and the South Sandwich Islands", "South Korea", + "Spain", "Sri Lanka", "Sudan", "Suriname", "Svalbard and Jan Mayen", "Swaziland", "Sweden", + "Switzerland", "Syria", "Taiwan", "Tajikistan", "Tanzania", "Thailand", "The Bahamas", + "The Gambia", "Togo", "Tokelau", "Tonga", "Trinidad and Tobago", "Tunisia", "Turkey", + "Turkmenistan", "Turks and Caicos Islands", "Tuvalu", "Virgin Islands", "Uganda", + "Ukraine", "United Arab Emirates", "United Kingdom", + "United States", "United States Minor Outlying Islands", "Uruguay", "Uzbekistan", + "Vanuatu", "Vatican City", "Venezuela", "Vietnam", "Wallis and Futuna", "Western Sahara", + "Yemen", "Yugoslavia", "Zambia", "Zimbabwe" + }; +</pre> +</li> +<li> Run it.</li> +</ol> +<p>You can scroll the list, or type to filter it. You should see something like this:</p> +<img src="images/hello-listview.png" width="150px" /> + +<h3>References</h3> +<ul> + <li>{@link android.widget.ListView}</li> + <li>{@link android.widget.ListAdapter}</li> +</ul> + +<p><a href="{@docRoot}guide/tutorials/views/hello-views-index.html">← Back to Hello Views</a></p> diff --git a/docs/html/guide/tutorials/views/hello-mapview.jd b/docs/html/guide/tutorials/views/hello-mapview.jd new file mode 100644 index 0000000..5b23f9b --- /dev/null +++ b/docs/html/guide/tutorials/views/hello-mapview.jd @@ -0,0 +1,231 @@ +page.title=Hello, MapView +@jd:body + +<p>A MapView allows you to create your own map-viewing Activity. +First, we'll create a simple Activity that can view and navigate a map. Then we will add some overlay items.</p> + +<ol> + <li>Start a new project/Activity called HelloMapView. + + <li>Because we're using the Google Maps library, + which is not a part of the standard Android library, we need to + declare it in the Android Manifest. Open the AndroidManifest.xml + file and add the following as a child of the <code><application></code> element: + + <pre><uses-library android:name="com.google.android.maps" /></pre> + </li> + + <li>Open the layout file. Define the layout with a MapView inside a RelativeLayout: + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/mainlayout" + android:orientation="vertical" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + > + + <com.google.android.maps.MapView + android:id="@+id/mapview" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:clickable="true" + android:apiKey="myapikey" + /> + +<RelativeLayout> +</pre> + + <p>The <code>android:apiKey</code> should actually contain a legitimate value that's + associated to your application. For now, it's okay to just leave this as an + arbitrary string. But to run on 1.0 software, an authentic key will be needed.</p></li> + + <li>Now open the HelloMapView.java file. For this Activity, we're going to extend the special sub-class of + Activity called MapActivity, so change the class declaration to extend + MapActicity, instead of Activity:</p> + + <pre>public class HelloMapView extends MapActivity {</pre> + + <li>The <code>isRouteDisplayed()</code> method is requires, so add it inside the class: +<pre> +@Override +protected boolean isRouteDisplayed() { + return false; +} +</pre> +<p>You can actually run this now, but all it does is allow you to pan around the map.</p> +<p>Android provides a handy {@link android.widget.ZoomControls} widget for zooming in and out of a View. +MapView can automatically hook one for us by requesting it with the <code>getZoomControls()</code> +method. Let's do this.</p> + +<li>Go back to the layout file. We need a new ViewGroup element, in which we'll + place the ZoomControls. Just below the MapView element (but inside the RelativeLayout), add this element: +<pre> +<LinearLayout + android:id="@+id/zoomview" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:layout_alignBottom="@id/mapview" + android:layout_centerHorizontal="true" +/></pre> + + <p>It doesn't really matter what kind of ViewGroup we use, because we just want a + container that we can position within our root RelativeLayout.</p> + + <p>The last two attributes are available only to an element that's a child of a + RelativeLayout. <code>layout_alignBottom</code> aligns the bottom of this element to the bottom of + the element identified with a resource tag (which must be a sibling to this element). + <code>layout_centerHorizontal</code> centers this on the horizontal plane.</p></li> + + <li>Now go back to the HelloMapView class. We'll now retrieve the ZoomControls object from + the MapView and add it to our new layout element. First, at the top of the HelloMapView, + instantiate handles for the MapView and LinearLayout, plus a ZoomControl object: +<pre> +LinearLayout linearLayout; +MapView mapView; +ZoomControls mZoom;</pre></li> + + <li>Then initialize each of these in <code>onCreate()</code>. We'll capture the LinearLayout and + MapView through their layout resources. Then get the ZoomControls from the MapView:: +<pre> +linearLayout = (LinearLayout) findViewById(R.id.zoomview); +mapView = (MapView) findViewById(R.id.mapview); +mZoom = (ZoomControls) mapView.getZoomControls();</pre> + + <p>By using the ZoomControls object provided by MapView, we don't have to do any of the work + required to actually perform the zoom operations. The ZoomControls widget that MapView + returns for us is already hooked into the MapView and works as soon as we add it to the + layout. The controls will appear whenever the user touches the map, then dissapear after + a few moments of inactivity.</p></li> + + <li>Now just plug our ZoomControls into the LinearLayout we added: + + <pre>linearLayout.addView(mZoom);</pre></li> + + <li>Run it.</li> +</ol> + +<hr/> + +<p>So, we now have full interaction controls. All well and good, but what we really want our map +for is custom markers and layovers. Let's add some Overlay +objects to our map. To do this, we're going to +implement the ItemizedOverlay +class, which can manage a whole set of Overlay items for us.</p> + +<ol> + <li>Create a new Java class named HelloItemizedOverlay that implements ItemizedOverlay. + + <p>Right-click the package name in the Eclipse Package Explorer, and select New > Class. Fill-in + the Name field as <em>HelloItemizedOverlay</em>. For the Superclass, enter + <em>com.google.android.maps.ItemizedOverlay</em>. Click the checkbox for <em>Constructors from + superclass</em>. Click Finish.</p></li> + + <li> First thing, we need an OverlayItem ArrayList, in which we'll put each of the OverlayItem + objects we want on our map. Add this at the top of the HelloItemizedOverlay class: + + <pre>private ArrayList<OverlayItem> mOverlays = new ArrayList<OverlayItem>();</pre></li> + + <li>All the constructor does is define the default marker to be used on each of the OverlayItems. + In order for the Drawable to actually get drawn, it must have its bounds defined. And we want the + center-point at the bottom of the image to be the point at which it's attached to the map + coordinates. We handle all this with the boundCenterBottom() method. Wrap this around our + defaultMarker, so the super constructor call looks like this: + + <pre>super(boundCenterBottom(defaultMarker));</pre></li> + + <li>In order to add new OverlayItems to our ArrayList, we need a new public method. We'll handle + this with the following method: + +<pre> +public void addOverlay(OverlayItem overlay) { + mOverlays.add(overlay); + populate(); +}</pre> + + <p>Each time we add a new OverlayItem, we must call <code>populate()</code>, which will read each of out + OverlayItems and prepare them to be drawn.</p></li> + + <li>In order for the <code>populate()</code> method to read each OverlayItem, it will make a request to + <code>createItem(int)</code>. We must define this method to properly read from our ArrayList. Replace the + existing contents of the createItem method with a <code>get()</code> call to our ArrayList: + + <pre>return mOverlays.get(i);</pre></li> + + <li>We're also required to override the <code>size()</code> method. Replace the existing contents of the + method with a size request to our ArrayList: + + <pre>return mOverlays.size();</pre></li> +</ol> + + +<p>That's it for the HelloItemizedOverlay class. We're now ready to use it.</p> + +<hr/> +<p>Go back to the HelloMapView +class. We'll start by creating one OverlayItem, adding to an instance of our HelloItemizedOverlay, +and then adding this to the MapView.</p> + +<img src="images/androidmarker.png" align="right" /> +<p>First, we need the image that we'll use for our map overlay. Here, we'll use the Android on the +right as our marker. Drag this image (or your own) to the res/drawable/ directory of your project workspace.</p> + +<p>Now we're ready to work in the HelloMapView:</p> + +<ol> + <li>First we need some more types. Add the following at the top of the HelloMapView class: + +<pre> +List<Overlay> mapOverlays; +Drawable drawable; +HelloItemizedOverlay itemizedOverlay;</pre></li> + + <li>Now pick up where we left off in the <code>onCreate()</code> method. Instantiate the + new fields: + +<pre> +mapoverlays = mapView.getOverlays(); +drawable = this.getResources().getDrawable(R.drawable.banana); +itemizedoverlay = new HelloItemizedOverlay(drawable);</pre> + + <p>All overlay elements on a map are held by the MapView, so when we want to add some, we must + first retrieve the List with <code>getOverlays()</code> methods. We instantiate the Drawable, which will + be used as our map marker, by using our Context resources to get the Drawable we placed in + the res/drawable/ directory. Our HelloItemizedOverlay takes the Drawable in order to set the + default marker.</p></li> + + <li>Now let's make our first OverlayItem by creating a GeoPoint + that defines our map coordinates, then pass it to a new OverlayItem: + +<pre> +GeoPoint point = new GeoPoint(19240000,-99120000); +OverlayItem overlayitem = new OverlayItem(point, "", "");</pre> + + <p>GeoPoint coordinates are based in microdegrees (degrees * 1e6). The OverlayItem takes this + GeoPoint and two strings. Here, we won't concern ourselves with the strings, which can display + text when we click our marker, because we haven't yet written the click handler for the OverlayItem.</p></li> + + <li>All that's left is for us to add this OverlayItem to our collection in the HelloItemizedOverlay, + and add this to the List of Overlay objects retrieved from the MapView: + +<pre> +itemizedoverlay.addOverlay(overlayitem); +mapoverlays.add(itemizedoverlay);</pre></li> + + <li>Run it!</li> +</ol> + +<p>We've sent our droid to Mexico City. Hola, Mundo!</p> +<p>You should see the following:</p> +<img src="images/hello-mapview.png" width="150px" /> + +<p>Because we created our ItemizedOverlay class with an ArrayList, we can continue adding new +OverlayItems. Try adding another one. Before the <code>addOverlay()</code> method is called, add these lines:</p> +<pre> +GeoPoint point2 = new GeoPoint(35410000, 139460000); +OverlayItem overlayitem2 = new OverlayItem(point2, "", ""); +</pre> +<p>Run it again... We've sent a new droid to Tokyo. Sekai, konichiwa!</p> + +<p><a href="{@docRoot}guide/tutorials/views/hello-views-index.html">← Back to Hello Views</a></p> diff --git a/docs/html/guide/tutorials/views/hello-relativelayout.jd b/docs/html/guide/tutorials/views/hello-relativelayout.jd new file mode 100644 index 0000000..4467631 --- /dev/null +++ b/docs/html/guide/tutorials/views/hello-relativelayout.jd @@ -0,0 +1,77 @@ +page.title=Hello, RelativeLayout +@jd:body + +<p>A {@link android.widget.RelativeLayout} is a ViewGroup that allows you to layout child elements +in positions relative to the parent or siblings elements.</p> + +<ol> + <li>Start a new project/Activity called HelloRelativeLayout.</li> + <li>Open the layout file. Make it like so: +<pre> +<?xml version="1.0" encoding="utf-8"?> +<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent"> + + <TextView + android:id="@+id/label" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:text="Type here:"/> + + <EditText + android:id="@+id/entry" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:background="@android:drawable/editbox_background" + android:layout_below="@id/label"/> + + <Button + android:id="@+id/ok" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:layout_below="@id/entry" + android:layout_alignParentRight="true" + android:layout_marginLeft="10dip" + android:text="OK" /> + + <Button + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:layout_toLeftOf="@id/ok" + android:layout_alignTop="@id/ok" + android:text="Cancel" /> + +</RelativeLayout> +</pre> +<p>Pay attention to each of the additional <code>layout_*</code> attributes (besides the +usual width and height, which are required for all elements). When using relative layout, +we use attributes like <code>layout_below</code> and <code>layout_toLeftOf</code> to describe +how we'd like to position each View. Naturally, these are different relative positions, and the +value of the attribute is the id of the element we want the position relative to.</p> +</li> +<li>Make sure your Activity loads this layout in the <code>onCreate()</code> method:</p> +<pre> +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); +} +</pre> +<p><code>R.layout.main</code> refers to the <code>main.xml</code> layout file.</p> +</li> +<li>Run it.</li> +</ol> +<p>You should see the following:</p> +<img src="images/hello-relativelayout.png" width="150px" /> + +<h3>Resources</h3> +<ul> + <li>{@link android.widget.RelativeLayout}</li> + <li>{@link android.widget.TextView}</li> + <li>{@link android.widget.EditText}</li> + <li>{@link android.widget.Button}</li> +</ul> + + +<p><a href="{@docRoot}guide/tutorials/views/hello-views-index.html">← Back to Hello Views</a></p> + diff --git a/docs/html/guide/tutorials/views/hello-spinner.jd b/docs/html/guide/tutorials/views/hello-spinner.jd new file mode 100644 index 0000000..4a0f12f --- /dev/null +++ b/docs/html/guide/tutorials/views/hello-spinner.jd @@ -0,0 +1,105 @@ +page.title=Hello, Spinner +@jd:body + +<p>A {@link android.widget.Spinner} is a widget that allows the user to select an item from a group. +It is similar to a dropdown list and will allow scrolling when the +list exceeds the available vertical space on the screen.</p> + + +<ol> + <li>Start a new project/Activity called HelloSpinner.</li> + <li>Open the layout file. + Make it like so: +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:orientation="vertical" + android:padding="10dip" + android:layout_width="fill_parent" + android:layout_height="wrap_content"> + + <TextView + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:layout_marginTop="10dip" + android:text="Please select a planet:" + /> + + <Spinner + android:id="@+id/spinner" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:drawSelectorOnTop="true" + android:prompt="@string/planet_prompt" + /> + +</LinearLayout> +</pre> + <p>Notice that the Spinner's <code>android:prompt</code> is a string resource. In + this case, Android does not allow it to be a string, it must be a reference to a resource. + So...</p> +</li> + +<li>Open the strings.xml file in res/values/ and add the following <code><string></code> +element inside the <code><resources></code> element: +<pre> +<string name="planet_prompt">Choose a planet</string> +</pre> +</li> + +<li>Create a new XML file in res/values/ called arrays.xml. Insert the following: +<pre> +<resources> + + <string-array name="planets"> + <item>Mercury</item> + <item>Venus</item> + <item>Earth</item> + <item>Mars</item> + <item>Jupiter</item> + <item>Saturn</item> + <item>Uranus</item> + <item>Neptune</item> + </string-array> + +</resources> +</pre> + <p>This is the list of items (planets) that the user can select from in the Spinner widget.</p> +</li> + +<li>Now open the HelloSpinner.java file. Insert the following code into the HelloSpinner class: +<pre> +@Override +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + + Spinner s = (Spinner) findViewById(R.id.spinner); + ArrayAdapter<CharSequence> adapter = ArrayAdapter.createFromResource( + this, R.array.planets, android.R.layout.simple_spinner_item); + adapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item); + s.setAdapter(adapter); +} +</pre> + <p>That's it. We start by creating a Spinner from our layout. We then create an {@link android.widget.ArrayAdapter} + that binds each element of our string array to a layout view—we pass <code>createFromResource</code> our Context, + the array of selectable items and the type of layout we'd like each one bound to. We then call + <code>setDropDownViewResource()</code> to define the type of layout in which to present the + entire collection. Finally, we set this Adapter to associate with our Spinner, + so the string items have a place to go.</p> +</li> + +<li>Now run it.</li> +</ol> +<p>It should look like this:</p> +<img src="images/hello-spinner.png" width="150px" /> + + +<h3>Resources</h3> +<ul> + <li>{@link android.R.layout}</li> + <li>{@link android.widget.ArrayAdapter}</li> + <li>{@link android.widget.Spinner}</li> +</ul> + +<p><a href="{@docRoot}guide/tutorials/views/hello-views-index.html">← Back to Hello Views</a></p> diff --git a/docs/html/guide/tutorials/views/hello-tablelayout.jd b/docs/html/guide/tutorials/views/hello-tablelayout.jd new file mode 100644 index 0000000..e7f2de5 --- /dev/null +++ b/docs/html/guide/tutorials/views/hello-tablelayout.jd @@ -0,0 +1,119 @@ +page.title=Hello, TableLayout +@jd:body + +<p>A {@link android.widget.TableLayout} is a ViewGroup that +will lay child View elements into rows and columns.</p> + + +<ol> + <li>Start a new project/Activity called HelloTableLayout.</li> + <li>Open the layout file. + Make it like so: +<pre> +<?xml version="1.0" encoding="utf-8"?> +<TableLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:stretchColumns="1"> + + <TableRow> + <TextView + android:layout_column="1" + android:text="Open..." + android:padding="3dip" /> + <TextView + android:text="Ctrl-O" + android:gravity="right" + android:padding="3dip" /> + </TableRow> + + <TableRow> + <TextView + android:layout_column="1" + android:text="Save..." + android:padding="3dip" /> + <TextView + android:text="Ctrl-S" + android:gravity="right" + android:padding="3dip" /> + </TableRow> + + <TableRow> + <TextView + android:layout_column="1" + android:text="Save As..." + android:padding="3dip" /> + <TextView + android:text="Ctrl-Shift-S" + android:gravity="right" + android:padding="3dip" /> + </TableRow> + + <View + android:layout_height="2dip" + android:background="#FF909090" /> + + <TableRow> + <TextView + android:text="X" + android:padding="3dip" /> + <TextView + android:text="Import..." + android:padding="3dip" /> + </TableRow> + + <TableRow> + <TextView + android:text="X" + android:padding="3dip" /> + <TextView + android:text="Export..." + android:padding="3dip" /> + <TextView + android:text="Ctrl-E" + android:gravity="right" + android:padding="3dip" /> + </TableRow> + + <View + android:layout_height="2dip" + android:background="#FF909090" /> + + <TableRow> + <TextView + android:layout_column="1" + android:text="Quit" + android:padding="3dip" /> + </TableRow> +</TableLayout> +</pre> +<p>Notice how this resembles the structure of an HTML table. <code>TableLayout</code> is like the +<code>table</code> element; <code>TableRow</code> is like a <code>tr</code> element; but for our cells like +the html <code>td</code> element, we can use any kind of View. Here, we use <code>TextView</code> for the cells.</p> + +</li> +<li>Make sure your Activity loads this layout in the <code>onCreate()</code> method: +<pre> +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); +} +</pre> +<p><code>R.layout.main</code> refers to the <code>main.xml</code> layout file.</p> +</li> +<li>Run it.</li> +</ol> +<p>You should see the following:</p> +<img src="images/hello-tablelayout.png" width="150px" /> + +<h3>References</h3> +<ul> + <li>{@link android.widget.TableLayout}</li> + <li>{@link android.widget.TableRow}</li> + <li>{@link android.widget.TextView}</li> +</ul> + + +<p><a href="{@docRoot}guide/tutorials/views/hello-views-index.html">← Back to Hello Views</a></p> + + diff --git a/docs/html/guide/tutorials/views/hello-timepicker.jd b/docs/html/guide/tutorials/views/hello-timepicker.jd new file mode 100644 index 0000000..2faad00 --- /dev/null +++ b/docs/html/guide/tutorials/views/hello-timepicker.jd @@ -0,0 +1,157 @@ +page.title=Hello, TimePicker +@jd:body + +<p>A {@link android.widget.TimePicker} is a widget that allows the +user to select the time by hour, minute and AM or PM.</p> + + +<ol> + <li>Start a new project/Activity called HelloTimePicker.</li> + <li>Open the layout file and make it like so: + <pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:orientation="vertical"> + + <TextView android:id="@+id/timeDisplay" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text=""/> + + <Button android:id="@+id/pickTime" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="Change the time"/> + +</LinearLayout> +</pre> + <p>For the layout, we're using a vertical LinearLayout, with a {@link android.widget.TextView} that + will display the time and a {@link android.widget.Button} that will initiate the + {@link android.widget.TimePicker} dialog. + With this layout, the TextView will sit above the Button. + The text value in the TextView is set empty, as it will be filled by our Activity + with the current time.</p> + </li> + + <li>Open HelloTimePicker.java. Insert the following to the HelloTimePicker class: +<pre> +private TextView mTimeDisplay; +private Button mPickTime; + +private int mHour; +private int mMinute; + +static final int TIME_DIALOG_ID = 0; + +@Override +protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + + // capture our View elements + mTimeDisplay = (TextView) findViewById(R.id.timeDisplay); + mPickTime = (Button) findViewById(R.id.pickTime); + + // add a click listener to the button + mPickTime.setOnClickListener(new View.OnClickListener() { + public void onClick(View v) { + showDialog(TIME_DIALOG_ID); + } + }); + + // get the current time + final Calendar c = Calendar.getInstance(); + mHour = c.get(Calendar.HOUR_OF_DAY); + mMinute = c.get(Calendar.MINUTE); + + // display the current date + updateDisplay(); +} +</pre> +<p class="note"><strong>Tip:</strong> Press Ctrl(or Cmd) + Shift + O to import all needed packages.</p> + <p>We start by instantiating variables for our View elements and time fields. + The <code>TIME_DIALOG_ID</code> is a static integer that uniquely identifies the dialog. In the + <code>onCreate()</code> method, we get prepared by setting the layout and capturing the View elements. + We then set an on-click listener for the Button, so that when it is clicked, it will + show our TimePicker dialog. The <code>showDialog()</code> method will perform a callback + to our Activity. (We'll define this callback in the next section.) We then create an + instance of {@link java.util.Calendar} and get the current hour and minute. Finally, we call + <code>updateDisplay()</code>—our own method that will fill the TextView with the time.</p> +</li> + +<li>After the <code>onCreate()</code> method, add the <code>onCreateDialog()</code> callback method: +<pre> +@Override +protected Dialog onCreateDialog(int id) { + switch (id) { + case TIME_DIALOG_ID: + return new TimePickerDialog(this, + mTimeSetListener, mHour, mMinute, false); + } + return null; +} +</pre> + <p>This is passed the identifier we gave <code>showDialog()</code> and initializes + the TimePicker to the time we retrieved from our Calendar instance. It will be called by + <code>showDialog()</code>.</p> +</li> + +<li>Now add our <code>updateDisplay()</code> method: +<pre> +// updates the time we display in the TextView +private void updateDisplay() { + mTimeDisplay.setText( + new StringBuilder() + .append(pad(mHour)).append(":") + .append(pad(mMinute))); +} +</pre> + <p>This simply takes our member fields for the time and inserts them in + the <code>mTimeDisplay</code> TextView. Note that we call a new method, <code>pad()</code>, + on the hour and minute. (We'll create this method in the last step.)</p> +</li> + +<li>Next, add a listener to be called when the time is reset: +<pre> +// the callback received when the user "sets" the time in the dialog +private TimePickerDialog.OnTimeSetListener mTimeSetListener = + new TimePickerDialog.OnTimeSetListener() { + public void onTimeSet(TimePicker view, int hourOfDay, int minute) { + mHour = hourOfDay; + mMinute = minute; + updateDisplay(); + } + }; +</pre> + <p>Now when the user is done setting the time (clicks the "Set" button), we update our member fields with + the new time and update our TextView.</p> +</li> +<li>Finally, add the <code>pad()</code> method that we called from the <code>updateDisplay()</code>: +<pre> +private static String pad(int c) { + if (c >= 10) + return String.valueOf(c); + else + return "0" + String.valueOf(c); +} +</pre> + <p>This method returns the appropriate String representation of the hour or minute. + It will prefix a zero to the number if it's a single digit. + </p> +</li> + +<li>Now run it.</li> +</ol> +<p>When you press the "Change the time" button, you should see the following:</p> +<img src="images/hello-timepicker.png" width="150px" /> + +<h3>References</h3> +<ol> + <li>{@link android.widget.TimePicker}</li> + <li>{@link android.widget.Button}</li> + <li>{@link android.widget.TextView}</li> + <li>{@link java.util.Calendar}</li> +</ol> +<p><a href="{@docRoot}guide/tutorials/views/hello-views-index.html">← Back to Hello Views</a></p> diff --git a/docs/html/guide/tutorials/views/hello-views-index.jd b/docs/html/guide/tutorials/views/hello-views-index.jd new file mode 100644 index 0000000..fd00233 --- /dev/null +++ b/docs/html/guide/tutorials/views/hello-views-index.jd @@ -0,0 +1,112 @@ +page.title=Hello, Views +@jd:body + +<style> +.view {float:left; margin:10px; font-size:120%; font-weight:bold;} +.view img {border:1px solid black; margin-top:5px; padding:5px;} +</style> + +<p>This collection of "Hello World"-style tutorials is designed +to get you quickly started with common Android Views and widgets. The aim is to let you copy and paste +these kinds of boring bits so you can focus on developing the code that makes your Android application rock. +Of course, we'll discuss some of the given code so that it all makes sense.</p> + +<p>Note that a certain amount of knowledge is assumed for these tutorials. If you haven't +completed the <a href="{@docRoot}guide/tutorials/hello-world.html">Hello World tutorial</a>, +please do so—it will teach you many things you should know about basic +Android development and Eclipse features. More specifically, you should know:</p> +<ul> + <li>How to create a new Android project.</li> + <li>The basic structure of an Android project (resource files, layout files, etc.).</li> + <li>The essential components of an {@link android.app.Activity}.</li> + <li>How to build and run a project.</li> +</ul> +<p>Please, also notice that, in order to make these tutorials simple, some may +not convey the better Android coding practices. In particular, many of them +use hard-coded strings in the layout files—the better practice is to reference strings from +your strings.xml file.</p> +<p>With this knowledge, you're ready to begin, so take your pick.</p> + +<div> + +<div class="view"> +<a href="hello-linearlayout.html">LinearLayout<br/> +<img src="images/hello-linearlayout.png" height="285" width="200" /></a> +</div> +<div class="view"> +<a href="hello-relativelayout.html">RelativeLayout<br/> +<img src="images/hello-relativelayout.png" height="285" width="200" /></a> +</div> +<div class="view"> +<a href="hello-tablelayout.html">TableLayout<br/> +<img src="images/hello-tablelayout.png" height="285" width="200" /></a> +</div> + +<div class="view"> +<a href="hello-datepicker.html">DatePicker<br/> +<img src="images/hello-datepicker.png" height="285" width="200" /></a> +</div> + +<div class="view"> +<a href="hello-timepicker.html">TimePicker<br/> +<img src="images/hello-timepicker.png" height="285" width="200" /></a> +</div> +<div class="view"> +<a href="hello-formstuff.html">Form Stuff<br/> +<img src="images/hello-formstuff.png" height="285" width="200" /></a> +</div> +<div class="view"> +<a href="hello-spinner.html">Spinner<br/> +<img src="images/hello-spinner.png" height="285" width="200" /></a> +</div> + +<div class="view"> +<a href="hello-autocomplete.html">AutoComplete<br/> +<img src="images/hello-autocomplete.png" height="285" width="200" /></a> +</div> +<div class="view"> +<a href="hello-listview.html">ListView<br/> +<img src="images/hello-listview.png" height="285" width="200" /></a> +</div> +<div class="view"> +<a href="hello-gridview.html">GridView<br/> +<img src="images/hello-gridview.png" height="285" width="200" /></a> +</div> + +<div class="view"> +<a href="hello-gallery.html">Gallery<br/> +<img src="images/hello-gallery.png" height="285" width="200" /></a> +</div> +<div class="view"> +<a href="hello-mapview.html">MapView<br/> +<img src="images/hello-mapview.png" height="285" width="200" /></a> +</div> + +<div class="view"> +<a href="hello-webview.html">WebView<br/> +<img src="images/hello-webview.png" height="285" width="200" /></a> +</div> + +<!-- +TODO + +<div class="view"> +<a href="hello-popupwindow.html">PopupWindow<br/> +<img src="images/hello-popupwindow.png" height="285" width="200" /></a> +</div> +<div class="view"> +<a href="hello-tabhost.html">TabHost / TabWidget<br/> +<img src="images/hello-tabhost.png" height="285" width="200" /></a> +</div> +ProgressBar; RatingBar; FrameLayout + +--> + +<p class="note" style="clear:left"> +There are plenty more Views and widgets available. See the {@link android.view.View} class +for more on View layouts, and the {@link android.widget widget package} +for more useful widgets. And for more raw code samples, visit the +<a href="{@docRoot}samples/ApiDemos/src/com/example/android/apis/view/index.html">Api Demos</a>. +These can also be found offline, in <code>/<your-SDK>/samples/ApiDemos</code>.</p> +</div> + diff --git a/docs/html/guide/tutorials/views/hello-webview.jd b/docs/html/guide/tutorials/views/hello-webview.jd new file mode 100644 index 0000000..542f91f --- /dev/null +++ b/docs/html/guide/tutorials/views/hello-webview.jd @@ -0,0 +1,117 @@ +page.title=Hello, WebView +@jd:body + +<p>A {@link android.webkit.WebView} allows you to create your own web browser Activity. In this tutorial, +we'll create a simple Activity that can view web pages.</p> + +<ol> + <li>Create a new project/Activity called HelloWebView.</li> + <li>Open the layout file. Insert a WebView so it looks like so: +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:orientation="vertical"> + + <WebView + android:id="@+id/webview" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + /> + +</LinearLayout> +</pre></li> + + <li>Now open the HelloWebView.java file. + At the top of the class, instantiate a WebView object: +<pre>WebView webview;</pre> + <p> Then add the following at the end of the <code>onCreate()</code> method:</p> +<pre> +webview = (WebView) findViewById(R.id.webview); +webview.getSettings().setJavaScriptEnabled(true); +webview.loadUrl("http://www.google.com"); +</pre> + + <p>This captures the WebView we created in our layout, then requests a + {@link android.webkit.WebSettings} object and enables JavaScript. + Then we load a URL.</p></li> + + <li>Because we're accessing the internet, we need to add the appropriate + permissions to the Android manifest file. So open the AndroidManifest.xml file + and, add the following as a child of the <code><manifest></code> element: + + <pre><uses-permission android:name="android.permission.INTERNET" /></pre></li> + + <li>Now run it.</li> +</ol> +<p> You now have the world's simplest web page viewer. + It's not quite a browser yet. It only loads the page we've requested.</p> + +<hr/> + +<p>We can load a page, but as soon as we click a link, the default Android web browser +handles the Intent, instead of our own WebView handling the action. So now we'll +override the {@link android.webkit.WebViewClient} to enable us to handle our own URL loading.</p> + +<ol> + <li>In the HelloAndroid Activity, add this nested private class: +<pre> +private class HelloWebViewClient extends WebViewClient { + @Override + public boolean shouldOverrideUrlLoading(WebView view, String url) { + view.loadUrl(url); + return true; + } +}</pre></li> + + <li>Now, in the <code>onCreate()</code> method, set an instance of the <code>HelloWebViewClient</code> + as our WebViewClient: + <pre>webview.setWebViewClient(new WebViewClientDemo());</pre> + + <p>This line should immediately follow the initialization of our WebView object.</p> + <p>What we've done is create a WebViewClient that will load any URL selected in our +WebView in the same WebView. You can see this in the <code>shouldOverrideUrlLoading()</code> +method, above—it is passed the current WebView and the URL, so all we do +is load the URL in the given view. Returning <var>true</var> says that we've handled the URL +ourselves and the event should not bubble-up.</p> + <p>If you try it again, new pages will now load in the HelloWebView Activity. However, you'll notice that +we can't navigate back. We need to handle the back button +on the device, so that it will return to the previous page, rather than exit the application.</p> + </li> + + <li>To handle the back button key press, add the following method inside the HelloWebView +Activity: +<pre> +@Override +public boolean onKeyDown(int keyCode, KeyEvent event) { + if ((keyCode == KeyEvent.KEYCODE_BACK) && webview.canGoBack()) { + webview.goBack(); + return true; + } + return super.onKeyDown(keyCode, event); +}</pre> + <p>The condition uses a {@link android.view.KeyEvent} to check + whether the key pressed is the BACK button and whether the + WebView is actually capable of navigating back (if it has a history). If both are + <em>not</em> true, then we send the event up the chain (and the Activity will close). + But if both <em>are</em> true, then we call <code>goBack()</code>, + which will navigate back one step in the history. We then return true to indicate + that we've handled the event.</p> +</li> +</ol> +<p>When you open the application, it should look like this:</p> +<img src="images/hello-webview.png" width="150px" /> + +<h3>Resource</h3> +<ul> +<li>{@link android.webkit.WebView}</li> +<li>{@link android.webkit.WebViewClient}</li> +<li>{@link android.view.KeyEvent}</li> +</ul> + +<p><a href="{@docRoot}guide/tutorials/views/hello-views-index.html">← Back to Hello Views</a></p> + + + + diff --git a/docs/html/guide/tutorials/views/images/android.png b/docs/html/guide/tutorials/views/images/android.png Binary files differnew file mode 100755 index 0000000..39a1ac7 --- /dev/null +++ b/docs/html/guide/tutorials/views/images/android.png diff --git a/docs/html/guide/tutorials/views/images/androidmarker.png b/docs/html/guide/tutorials/views/images/androidmarker.png Binary files differnew file mode 100755 index 0000000..8c43d46 --- /dev/null +++ b/docs/html/guide/tutorials/views/images/androidmarker.png diff --git a/docs/html/guide/tutorials/views/images/hello-autocomplete.png b/docs/html/guide/tutorials/views/images/hello-autocomplete.png Binary files differnew file mode 100755 index 0000000..e1fd80d --- /dev/null +++ b/docs/html/guide/tutorials/views/images/hello-autocomplete.png diff --git a/docs/html/guide/tutorials/views/images/hello-datepicker.png b/docs/html/guide/tutorials/views/images/hello-datepicker.png Binary files differnew file mode 100755 index 0000000..2075066 --- /dev/null +++ b/docs/html/guide/tutorials/views/images/hello-datepicker.png diff --git a/docs/html/guide/tutorials/views/images/hello-formstuff.png b/docs/html/guide/tutorials/views/images/hello-formstuff.png Binary files differnew file mode 100755 index 0000000..3b4bf54 --- /dev/null +++ b/docs/html/guide/tutorials/views/images/hello-formstuff.png diff --git a/docs/html/guide/tutorials/views/images/hello-gallery.png b/docs/html/guide/tutorials/views/images/hello-gallery.png Binary files differnew file mode 100755 index 0000000..22d1eaf --- /dev/null +++ b/docs/html/guide/tutorials/views/images/hello-gallery.png diff --git a/docs/html/guide/tutorials/views/images/hello-gridview.png b/docs/html/guide/tutorials/views/images/hello-gridview.png Binary files differnew file mode 100755 index 0000000..2def0df --- /dev/null +++ b/docs/html/guide/tutorials/views/images/hello-gridview.png diff --git a/docs/html/guide/tutorials/views/images/hello-linearlayout.png b/docs/html/guide/tutorials/views/images/hello-linearlayout.png Binary files differnew file mode 100755 index 0000000..dfef819 --- /dev/null +++ b/docs/html/guide/tutorials/views/images/hello-linearlayout.png diff --git a/docs/html/guide/tutorials/views/images/hello-listview.png b/docs/html/guide/tutorials/views/images/hello-listview.png Binary files differnew file mode 100755 index 0000000..a1cf7aa --- /dev/null +++ b/docs/html/guide/tutorials/views/images/hello-listview.png diff --git a/docs/html/guide/tutorials/views/images/hello-mapview.png b/docs/html/guide/tutorials/views/images/hello-mapview.png Binary files differnew file mode 100755 index 0000000..0956760 --- /dev/null +++ b/docs/html/guide/tutorials/views/images/hello-mapview.png diff --git a/docs/html/guide/tutorials/views/images/hello-relativelayout.png b/docs/html/guide/tutorials/views/images/hello-relativelayout.png Binary files differnew file mode 100755 index 0000000..ec4d9d4 --- /dev/null +++ b/docs/html/guide/tutorials/views/images/hello-relativelayout.png diff --git a/docs/html/guide/tutorials/views/images/hello-spinner.png b/docs/html/guide/tutorials/views/images/hello-spinner.png Binary files differnew file mode 100755 index 0000000..42e2a91 --- /dev/null +++ b/docs/html/guide/tutorials/views/images/hello-spinner.png diff --git a/docs/html/guide/tutorials/views/images/hello-tablelayout.png b/docs/html/guide/tutorials/views/images/hello-tablelayout.png Binary files differnew file mode 100755 index 0000000..3d80e7f --- /dev/null +++ b/docs/html/guide/tutorials/views/images/hello-tablelayout.png diff --git a/docs/html/guide/tutorials/views/images/hello-timepicker.png b/docs/html/guide/tutorials/views/images/hello-timepicker.png Binary files differnew file mode 100755 index 0000000..bd5a1ee --- /dev/null +++ b/docs/html/guide/tutorials/views/images/hello-timepicker.png diff --git a/docs/html/guide/tutorials/views/images/hello-webview.png b/docs/html/guide/tutorials/views/images/hello-webview.png Binary files differnew file mode 100755 index 0000000..283ce7d --- /dev/null +++ b/docs/html/guide/tutorials/views/images/hello-webview.png diff --git a/docs/html/images/activity_lifecycle.png b/docs/html/images/activity_lifecycle.png Binary files differnew file mode 100644 index 0000000..b3e2534 --- /dev/null +++ b/docs/html/images/activity_lifecycle.png diff --git a/docs/html/images/adc1r1_deck.pdf b/docs/html/images/adc1r1_deck.pdf Binary files differnew file mode 100644 index 0000000..e76a554 --- /dev/null +++ b/docs/html/images/adc1r1_deck.pdf diff --git a/docs/html/images/android_adc.gif b/docs/html/images/android_adc.gif Binary files differnew file mode 100644 index 0000000..469a73a --- /dev/null +++ b/docs/html/images/android_adc.gif diff --git a/docs/html/images/android_icon_125.png b/docs/html/images/android_icon_125.png Binary files differnew file mode 100644 index 0000000..f526193 --- /dev/null +++ b/docs/html/images/android_icon_125.png diff --git a/docs/html/images/anr.png b/docs/html/images/anr.png Binary files differnew file mode 100644 index 0000000..f6e16ef --- /dev/null +++ b/docs/html/images/anr.png diff --git a/docs/html/images/content_uri.png b/docs/html/images/content_uri.png Binary files differnew file mode 100644 index 0000000..1fb6d09 --- /dev/null +++ b/docs/html/images/content_uri.png diff --git a/docs/html/images/designing_ui_layout_example.png b/docs/html/images/designing_ui_layout_example.png Binary files differnew file mode 100644 index 0000000..7d90b31 --- /dev/null +++ b/docs/html/images/designing_ui_layout_example.png diff --git a/docs/html/images/designing_ui_relative_layout.png b/docs/html/images/designing_ui_relative_layout.png Binary files differnew file mode 100644 index 0000000..8e373a5 --- /dev/null +++ b/docs/html/images/designing_ui_relative_layout.png diff --git a/docs/html/images/draw9patch-bad.png b/docs/html/images/draw9patch-bad.png Binary files differnew file mode 100755 index 0000000..186d9ce9 --- /dev/null +++ b/docs/html/images/draw9patch-bad.png diff --git a/docs/html/images/draw9patch-norm.png b/docs/html/images/draw9patch-norm.png Binary files differnew file mode 100755 index 0000000..0cba944 --- /dev/null +++ b/docs/html/images/draw9patch-norm.png diff --git a/docs/html/images/e-mini-hvga-l.png b/docs/html/images/e-mini-hvga-l.png Binary files differnew file mode 100644 index 0000000..f68853f --- /dev/null +++ b/docs/html/images/e-mini-hvga-l.png diff --git a/docs/html/images/e-mini-hvga-p.png b/docs/html/images/e-mini-hvga-p.png Binary files differnew file mode 100644 index 0000000..3cf0db9 --- /dev/null +++ b/docs/html/images/e-mini-hvga-p.png diff --git a/docs/html/images/e-mini-qvga-l.png b/docs/html/images/e-mini-qvga-l.png Binary files differnew file mode 100644 index 0000000..3138b9f --- /dev/null +++ b/docs/html/images/e-mini-qvga-l.png diff --git a/docs/html/images/e-mini-qvga-p.png b/docs/html/images/e-mini-qvga-p.png Binary files differnew file mode 100644 index 0000000..54f2cc1 --- /dev/null +++ b/docs/html/images/e-mini-qvga-p.png diff --git a/docs/html/images/emulator-hvga-p.png b/docs/html/images/emulator-hvga-p.png Binary files differnew file mode 100644 index 0000000..f3b8900 --- /dev/null +++ b/docs/html/images/emulator-hvga-p.png diff --git a/docs/html/images/emulator.png b/docs/html/images/emulator.png Binary files differnew file mode 100644 index 0000000..9c6860a --- /dev/null +++ b/docs/html/images/emulator.png diff --git a/docs/html/images/gradient_drawable.png b/docs/html/images/gradient_drawable.png Binary files differnew file mode 100644 index 0000000..4ea846a --- /dev/null +++ b/docs/html/images/gradient_drawable.png diff --git a/docs/html/images/hello_world_0.png b/docs/html/images/hello_world_0.png Binary files differnew file mode 100644 index 0000000..c174fba --- /dev/null +++ b/docs/html/images/hello_world_0.png diff --git a/docs/html/images/hello_world_1.png b/docs/html/images/hello_world_1.png Binary files differnew file mode 100644 index 0000000..f08438a --- /dev/null +++ b/docs/html/images/hello_world_1.png diff --git a/docs/html/images/hello_world_2.png b/docs/html/images/hello_world_2.png Binary files differnew file mode 100644 index 0000000..58f5703 --- /dev/null +++ b/docs/html/images/hello_world_2.png diff --git a/docs/html/images/hello_world_3.png b/docs/html/images/hello_world_3.png Binary files differnew file mode 100644 index 0000000..d2d2ff6 --- /dev/null +++ b/docs/html/images/hello_world_3.png diff --git a/docs/html/images/hello_world_4.png b/docs/html/images/hello_world_4.png Binary files differnew file mode 100644 index 0000000..5c41e80 --- /dev/null +++ b/docs/html/images/hello_world_4.png diff --git a/docs/html/images/hello_world_5.png b/docs/html/images/hello_world_5.png Binary files differnew file mode 100644 index 0000000..96b830a --- /dev/null +++ b/docs/html/images/hello_world_5.png diff --git a/docs/html/images/hello_world_8.png b/docs/html/images/hello_world_8.png Binary files differnew file mode 100644 index 0000000..07db360 --- /dev/null +++ b/docs/html/images/hello_world_8.png diff --git a/docs/html/images/hello_world_9.png b/docs/html/images/hello_world_9.png Binary files differnew file mode 100644 index 0000000..e172e63 --- /dev/null +++ b/docs/html/images/hello_world_9.png diff --git a/docs/html/images/hierarchyviewer-layout.png b/docs/html/images/hierarchyviewer-layout.png Binary files differnew file mode 100755 index 0000000..217f058 --- /dev/null +++ b/docs/html/images/hierarchyviewer-layout.png diff --git a/docs/html/images/hierarchyviewer-pixelperfect.png b/docs/html/images/hierarchyviewer-pixelperfect.png Binary files differnew file mode 100755 index 0000000..bce3673 --- /dev/null +++ b/docs/html/images/hierarchyviewer-pixelperfect.png diff --git a/docs/html/images/icon_barriers.png b/docs/html/images/icon_barriers.png Binary files differnew file mode 100644 index 0000000..73345ef --- /dev/null +++ b/docs/html/images/icon_barriers.png diff --git a/docs/html/images/icon_equal.png b/docs/html/images/icon_equal.png Binary files differnew file mode 100644 index 0000000..5548de1 --- /dev/null +++ b/docs/html/images/icon_equal.png diff --git a/docs/html/images/icon_fast.png b/docs/html/images/icon_fast.png Binary files differnew file mode 100644 index 0000000..4962db9 --- /dev/null +++ b/docs/html/images/icon_fast.png diff --git a/docs/html/images/icon_open.png b/docs/html/images/icon_open.png Binary files differnew file mode 100644 index 0000000..0db4e8e --- /dev/null +++ b/docs/html/images/icon_open.png diff --git a/docs/html/images/judgebio_charles.jpg b/docs/html/images/judgebio_charles.jpg Binary files differnew file mode 100644 index 0000000..2449cfe --- /dev/null +++ b/docs/html/images/judgebio_charles.jpg diff --git a/docs/html/images/judgebio_dibona.jpg b/docs/html/images/judgebio_dibona.jpg Binary files differnew file mode 100644 index 0000000..91869fb --- /dev/null +++ b/docs/html/images/judgebio_dibona.jpg diff --git a/docs/html/images/judgebio_gadi.jpg b/docs/html/images/judgebio_gadi.jpg Binary files differnew file mode 100644 index 0000000..d1e40c3 --- /dev/null +++ b/docs/html/images/judgebio_gadi.jpg diff --git a/docs/html/images/judgebio_jens.jpg b/docs/html/images/judgebio_jens.jpg Binary files differnew file mode 100644 index 0000000..6f07254 --- /dev/null +++ b/docs/html/images/judgebio_jens.jpg diff --git a/docs/html/images/judgebio_jeremiah.jpg b/docs/html/images/judgebio_jeremiah.jpg Binary files differnew file mode 100644 index 0000000..c91b43f --- /dev/null +++ b/docs/html/images/judgebio_jeremiah.jpg diff --git a/docs/html/images/judgebio_kristian.jpg b/docs/html/images/judgebio_kristian.jpg Binary files differnew file mode 100644 index 0000000..19e93dd --- /dev/null +++ b/docs/html/images/judgebio_kristian.jpg diff --git a/docs/html/images/judgebio_leon.jpg b/docs/html/images/judgebio_leon.jpg Binary files differnew file mode 100644 index 0000000..c648bd3 --- /dev/null +++ b/docs/html/images/judgebio_leon.jpg diff --git a/docs/html/images/layoutparams.png b/docs/html/images/layoutparams.png Binary files differnew file mode 100644 index 0000000..d2f547c --- /dev/null +++ b/docs/html/images/layoutparams.png diff --git a/docs/html/images/like_thumb1.png b/docs/html/images/like_thumb1.png Binary files differnew file mode 100644 index 0000000..098cfaf --- /dev/null +++ b/docs/html/images/like_thumb1.png diff --git a/docs/html/images/like_thumb2.png b/docs/html/images/like_thumb2.png Binary files differnew file mode 100644 index 0000000..ef9d2d2 --- /dev/null +++ b/docs/html/images/like_thumb2.png diff --git a/docs/html/images/like_thumb3.png b/docs/html/images/like_thumb3.png Binary files differnew file mode 100644 index 0000000..543f2de --- /dev/null +++ b/docs/html/images/like_thumb3.png diff --git a/docs/html/images/like_thumb4.png b/docs/html/images/like_thumb4.png Binary files differnew file mode 100644 index 0000000..1f5e7e4 --- /dev/null +++ b/docs/html/images/like_thumb4.png diff --git a/docs/html/images/linearlayout.png b/docs/html/images/linearlayout.png Binary files differnew file mode 100644 index 0000000..cbb7ef4 --- /dev/null +++ b/docs/html/images/linearlayout.png diff --git a/docs/html/images/logo_android.gif b/docs/html/images/logo_android.gif Binary files differnew file mode 100644 index 0000000..0a84d1b --- /dev/null +++ b/docs/html/images/logo_android.gif diff --git a/docs/html/images/mediarecorder_state_diagram.gif b/docs/html/images/mediarecorder_state_diagram.gif Binary files differnew file mode 100644 index 0000000..28b8be5 --- /dev/null +++ b/docs/html/images/mediarecorder_state_diagram.gif diff --git a/docs/html/images/ninepatch_examples.png b/docs/html/images/ninepatch_examples.png Binary files differnew file mode 100644 index 0000000..bd64bfd --- /dev/null +++ b/docs/html/images/ninepatch_examples.png diff --git a/docs/html/images/ninepatch_raw.png b/docs/html/images/ninepatch_raw.png Binary files differnew file mode 100644 index 0000000..80d8b69 --- /dev/null +++ b/docs/html/images/ninepatch_raw.png diff --git a/docs/html/images/no_scrollview.png b/docs/html/images/no_scrollview.png Binary files differnew file mode 100644 index 0000000..d1b4ee0 --- /dev/null +++ b/docs/html/images/no_scrollview.png diff --git a/docs/html/images/notepad.png b/docs/html/images/notepad.png Binary files differnew file mode 100644 index 0000000..01b0f6d --- /dev/null +++ b/docs/html/images/notepad.png diff --git a/docs/html/images/padding_margins.png b/docs/html/images/padding_margins.png Binary files differnew file mode 100644 index 0000000..4b2a576 --- /dev/null +++ b/docs/html/images/padding_margins.png diff --git a/docs/html/images/setting_width_and_height.png b/docs/html/images/setting_width_and_height.png Binary files differnew file mode 100644 index 0000000..ac9e6b8 --- /dev/null +++ b/docs/html/images/setting_width_and_height.png diff --git a/docs/html/images/system-architecture.jpg b/docs/html/images/system-architecture.jpg Binary files differnew file mode 100644 index 0000000..8831483 --- /dev/null +++ b/docs/html/images/system-architecture.jpg diff --git a/docs/html/images/table_layout.png b/docs/html/images/table_layout.png Binary files differnew file mode 100644 index 0000000..bc1a47c --- /dev/null +++ b/docs/html/images/table_layout.png diff --git a/docs/html/images/tracedump.png b/docs/html/images/tracedump.png Binary files differnew file mode 100644 index 0000000..53036ae --- /dev/null +++ b/docs/html/images/tracedump.png diff --git a/docs/html/images/traceview_profile.png b/docs/html/images/traceview_profile.png Binary files differnew file mode 100644 index 0000000..fbb4d68 --- /dev/null +++ b/docs/html/images/traceview_profile.png diff --git a/docs/html/images/traceview_timeline.png b/docs/html/images/traceview_timeline.png Binary files differnew file mode 100644 index 0000000..8ebcaba --- /dev/null +++ b/docs/html/images/traceview_timeline.png diff --git a/docs/html/images/video_thumb_dan.png b/docs/html/images/video_thumb_dan.png Binary files differnew file mode 100644 index 0000000..85231d7 --- /dev/null +++ b/docs/html/images/video_thumb_dan.png diff --git a/docs/html/images/video_thumb_mike.png b/docs/html/images/video_thumb_mike.png Binary files differnew file mode 100644 index 0000000..87daf21 --- /dev/null +++ b/docs/html/images/video_thumb_mike.png diff --git a/docs/html/images/viewgroup.png b/docs/html/images/viewgroup.png Binary files differnew file mode 100644 index 0000000..a4c2518 --- /dev/null +++ b/docs/html/images/viewgroup.png diff --git a/docs/html/images/views_autocomplete.png b/docs/html/images/views_autocomplete.png Binary files differnew file mode 100644 index 0000000..9e9b69c --- /dev/null +++ b/docs/html/images/views_autocomplete.png diff --git a/docs/html/images/views_controls_example2.png b/docs/html/images/views_controls_example2.png Binary files differnew file mode 100644 index 0000000..198d848 --- /dev/null +++ b/docs/html/images/views_controls_example2.png diff --git a/docs/html/images/views_datewidgets_example1_pickdate.png b/docs/html/images/views_datewidgets_example1_pickdate.png Binary files differnew file mode 100644 index 0000000..581a80f --- /dev/null +++ b/docs/html/images/views_datewidgets_example1_pickdate.png diff --git a/docs/html/images/views_datewidgets_example1_picktime.png b/docs/html/images/views_datewidgets_example1_picktime.png Binary files differnew file mode 100644 index 0000000..7d91665 --- /dev/null +++ b/docs/html/images/views_datewidgets_example1_picktime.png diff --git a/docs/html/images/views_gallery_example1.png b/docs/html/images/views_gallery_example1.png Binary files differnew file mode 100644 index 0000000..103fad8 --- /dev/null +++ b/docs/html/images/views_gallery_example1.png diff --git a/docs/html/images/views_grid_example2.png b/docs/html/images/views_grid_example2.png Binary files differnew file mode 100644 index 0000000..16590b7 --- /dev/null +++ b/docs/html/images/views_grid_example2.png diff --git a/docs/html/images/views_image_switcher.png b/docs/html/images/views_image_switcher.png Binary files differnew file mode 100644 index 0000000..601e123 --- /dev/null +++ b/docs/html/images/views_image_switcher.png diff --git a/docs/html/images/views_imagebutton_example1.png b/docs/html/images/views_imagebutton_example1.png Binary files differnew file mode 100644 index 0000000..a6bb81b --- /dev/null +++ b/docs/html/images/views_imagebutton_example1.png diff --git a/docs/html/images/views_layouts_linearlayout_example1.png b/docs/html/images/views_layouts_linearlayout_example1.png Binary files differnew file mode 100644 index 0000000..2c201f6 --- /dev/null +++ b/docs/html/images/views_layouts_linearlayout_example1.png diff --git a/docs/html/images/views_layouts_linearlayout_example7.png b/docs/html/images/views_layouts_linearlayout_example7.png Binary files differnew file mode 100644 index 0000000..f8e4770 --- /dev/null +++ b/docs/html/images/views_layouts_linearlayout_example7.png diff --git a/docs/html/images/views_layouts_relativelayout_example2.png b/docs/html/images/views_layouts_relativelayout_example2.png Binary files differnew file mode 100644 index 0000000..395ecb9 --- /dev/null +++ b/docs/html/images/views_layouts_relativelayout_example2.png diff --git a/docs/html/images/views_layouts_tablelayout_example10.png b/docs/html/images/views_layouts_tablelayout_example10.png Binary files differnew file mode 100644 index 0000000..2f96fa2 --- /dev/null +++ b/docs/html/images/views_layouts_tablelayout_example10.png diff --git a/docs/html/images/views_layouts_tablelayout_spanning.png b/docs/html/images/views_layouts_tablelayout_spanning.png Binary files differnew file mode 100644 index 0000000..143ce34 --- /dev/null +++ b/docs/html/images/views_layouts_tablelayout_spanning.png diff --git a/docs/html/images/views_lists_example1.png b/docs/html/images/views_lists_example1.png Binary files differnew file mode 100644 index 0000000..067d247 --- /dev/null +++ b/docs/html/images/views_lists_example1.png diff --git a/docs/html/images/views_spinner.png b/docs/html/images/views_spinner.png Binary files differnew file mode 100644 index 0000000..99513a3 --- /dev/null +++ b/docs/html/images/views_spinner.png diff --git a/docs/html/images/zippy_bullet.gif b/docs/html/images/zippy_bullet.gif Binary files differnew file mode 100755 index 0000000..e06601f --- /dev/null +++ b/docs/html/images/zippy_bullet.gif diff --git a/docs/html/images/zippy_closed.gif b/docs/html/images/zippy_closed.gif Binary files differnew file mode 100755 index 0000000..7f25fcd --- /dev/null +++ b/docs/html/images/zippy_closed.gif diff --git a/docs/html/images/zippy_open.gif b/docs/html/images/zippy_open.gif Binary files differnew file mode 100755 index 0000000..e14f0f9 --- /dev/null +++ b/docs/html/images/zippy_open.gif diff --git a/docs/html/index.jd b/docs/html/index.jd new file mode 100644 index 0000000..e9959a5 --- /dev/null +++ b/docs/html/index.jd @@ -0,0 +1,114 @@ +home=true +page.title=Home +@jd:body + + +<script type="text/javascript" src="{@docRoot}assets/carousel.js"></script> +<script type="text/javascript"> + var preview = function() { showPreview('amazonmp3'); }; + addLoadEvent(preview); +</script> + + <div id="mainBodyFixed"> + <div id="mainBodyLeft"> + <div id="homeMiddle"> + <div id="homeTitle"> + <div style="float:left;"> + <h2>Just Announced: Developer Challenge 2</h2> + </div> + <div style="float:right;" align="center"> + <a href="{@docRoot}adc/adc2.html">Sign up today!</a><br /> + <img src="{@docRoot}assets/images/icon_robot.jpg" style="padding:8px 10px 8px 10px; clear:both;" /> + </div> + </div><!-- end homeTitle --> + <div id="carouselMain"> + <div id="carouselImg"></div> + <div id="carouselDesc"></div> + </div> + <div class="clearer"></div> + <div class="app-list-container" align="center"> + <a href="javascript:{}" id="arrow-left" onclick="" class="arrow-left-off"></a> + <div id="list-clip"> + <div style="left: 0px;" id="app-list"> + <!--ps:app-list--> + <a id="droidlink-amazonmp3" href="javascript:showPreview('amazonmp3')"> + <img src="{@docRoot}assets/images/amazonmp3-sm.png" alt="Amazon MP3 for Android"> + </a> + <a id="droidlink-bonsaiblast" href="javascript:showPreview('bonsaiblast')"> + <img src="{@docRoot}assets/images/bonsaiblast-sm.png" alt="Bonsai Blast"> + </a> + <a id="droidlink-breadcrumbz" href="javascript:showPreview('breadcrumbz')"> + <img src="{@docRoot}assets/images/breadcrumbz-sm.png" alt="BreadCrumbz"> + </a> + <a id="droidlink-cookingcapsules" href="javascript:showPreview('cookingcapsules')"> + <img src="{@docRoot}assets/images/cookingcapsules-sm.png" alt="Cooking Capsulesâ„¢ Taster"> + </a> + <!--pe:app-list--> + </div> + </div><!-- end list-clip --> + <a href="javascript:page_right()" id="arrow-right" onclick="" class="arrow-right-on"></a> + <div class="clearer"></div> + </div><!-- end app-list container --> + </div><!-- end homeMiddle --> + + <div style="clear:both"> </div> + + <div id="homeBottom"> + <table> + <tr> + <td> + <br /> + <h2>Featured Developer App: BreadCrumbz</h2> + <p>Amos Yoffe takes navigation to the next level with BreadCrumbz.</p> + <p><a href="http://www.bcrumbz.com">Learn more about this developer →</a></p> + </td> + <td> + <img src="{@docRoot}assets/images/logo_breadcrumbz.jpg" /> + </td> + </tr> + </table> + </div><!-- end homeBottom --> + </div><!-- end mainBodyLeft --> + + <div id="mainBodyRight"> + <table id="rightColumn"> + <tr> + <td class="imageCell"><img src="{@docRoot}assets/images/icon_download.jpg" /></td> + <td> + <h2 class="green">Download</h2> + <p>Latest SDK</p> + <p><a href="{@docRoot}sdk/">Download now</a></p> + </td> + </tr> + <tr> + <td colspan="2"><div class="seperator"> </div></td> + </tr> + <tr> + <td class="imageCell"><img src="{@docRoot}assets/images/icon_market.jpg" /></td> + <td valign="middle"><br /><h2 class="green">Market</h2></td> + </tr> + <tr> + <td colspan="2"> + <br /> + <p>Android Market is an open service that will give developers the opportunity to distribute applications to handsets.</p> + <p><a href="http://www.android.com/market.html">Learn more →</a></p> + </td> + </tr> + <tr> + <td colspan="2"><div class="seperator"> </div></td> + </tr> + <tr> + <td class="imageCell"><img src="{@docRoot}assets/images/icon_contribute.jpg" /></td> + <td> + <h2 class="green">Contribute</h2> + <p>Create using our open source codebase and help us keep this project growing.</p> + <p><a href="http://open.android.com">Learn more →</a></p> + </td> + </tr> + <tr> + <td colspan="2"><div class="seperator"> </div></td> + </tr> + </table> + </div> + </div> + diff --git a/docs/html/maps-api-signup.html b/docs/html/maps-api-signup.html new file mode 100644 index 0000000..a604b2a --- /dev/null +++ b/docs/html/maps-api-signup.html @@ -0,0 +1,369 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html> + <head> + +<meta http-equiv="content-type" content="text/html; charset=utf-8"/> +<title>Sign Up for the Android Maps API - Android Maps API - Google Code</title> +<link href="http://code.google.com/css/codesite.pack.01312008.css" type="text/css" rel="stylesheet"></link> +<script src="http://code.google.com//js/codesite.pack.01312008.js" type="text/javascript"></script> +<link rel="search" type="application/opensearchdescription+xml" title="Google Code" href="/osd.xml" /> + +<!--[if IE]><link rel="stylesheet" type="text/css" href="/css/iehacks.css" /><![endif]--> + + +<script type="text/javascript"> +//<![CDATA[ + +function CheckForm(form) { + if (!form["agreeTerms"].checked) { + alert("To get an Android Maps API key, " + + "you must agree to the API terms by checking the checkbox."); + } else { + var fp = form["fp"].value; + if (fp.length < 32) { + alert("Please enter the MD5 fingerprint of the certificate you will use to sign your Android Application."); + form["fp"].focus(); + } else { + top.location = "http://www.google.com/glm/mmap/a/api?fp=" + + encodeURIComponent(fp); + } + } + return false; +} + +//]]> +</script> + </head> + + <body class="gc-documentation"> + <div id="gc-container"> +<a name="top"></a> +<div id="skipto"> + + +</div> +<div id="gc-header"> + <div id="logo"><a href="/"> + + <img src="/images/cleardot.gif" height="1px" width="1px" alt="Google Code Home Page" id="gc-logo-img"/> + + </a></div> + <div id="search"> + <div id="searchForm" class="searchForm" style="display:none"> + <form action="" accept-charset="utf-8" class="gsc-search-box" onsubmit="executeGSearch(document.getElementById('gsearchInput').value); return false;"> + <table class="gsc-search-box" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="gsc-input"> + <input id="gsearchInput" type="text" name="q" maxlength="2048" class="gsc-input" autocomplete="off" title="Google Code Search" style="width:345px"/> + </td> + <td class="gsc-search-button"> + <div id='cs-searchresults' onclick='event.cancelBubble = true;'></div> + <input title="Search" id="gsearchButton" class="gsc-search-button" value="Search" type="submit"/> + </td> + </tr> + <tr> + <td class="greytext">e.g. "ajax apis" or "open source"</td> + </tr> + </tbody> + </table> + </form> + </div> <!-- end searchForm --> + <div id="searchForm2" class="searchForm2" style="display:block"> + <form id="cse" action="http://www.google.com/cse"> + <input type="hidden" name="cref" value="http://code.google.com/cse/googlecode-context.xml" /> + <input type="text" name="q" maxlength="2048" autocomplete="off" title="Google Code Search" style="width:345px"/> + <input type="submit" name="sa" value="Search" title="Search"/><br/> + <div class="greytext">e.g. "ajax apis" or "open source"</div> + </form> + </div> <!-- end searchForm2 --> + </div> <!-- end search --> +</div> <!-- end gc-header --> + + +<div id="codesiteContent"> + +<a name="gc-topnav-anchor"></a> +<div id="gc-topnav"> + <h1>Android Maps API Key Signup</h1> + <ul id="docs" class="gc-topnav-tabs"> + <li id="home_link"> + <a href="/android/" title="Android Developer Site">Home</a> + </li> + + <li id="docs_link"> + <a href="/android/toolbox/apis/lbs.html" title="Android Maps API Documentation">Docs</a> + </li> + + <li> + <a href="http://googlegeodevelopers.blogspot.com/" title="Official Google Maps API blog">Maps Blog</a> + </li> + + <li> + <a href="http://android-developers.blogspot.com/" title="Official Android Developers Blog">Android Blog</a> + </li> + </ul> +</div> <!-- end gc-topnav --> + + +<div> +<!-- + <div class="g-section g-tpl-170"> + + <a name="gc-toc-anchor"></a> + <div class="g-unit g-first" id="gc-toc"> + <ul> + <li>Add some sidebar content?</li> + </ul> + <div class="line"></div> + </div> +--> + + <a name="gc-pagecontent-anchor"></a> + <div class="g-unit" id="gc-pagecontent"> + <h1 class="page_title">Sign Up for the Android Maps API</h1> + +<p>The Android Maps API lets you embed +<a href="/android/reference/com/google/android/maps/MapView.html">Google +Maps</a> in your own Android applications. A single Maps API key is +valid for all applications signed by a single certificate. See +this <a href="/android/intro/develop-and-debug.html#signing">documentation +page</a> for more information about application signing. To get a +Maps API key for your certificate, you will need to provide its the certificate's +fingerprint. This can be obtained using Keytool. For example, on +Linux or Mac OSX, you would examine your debug keystore like this: +<pre class="prettyprint">$ keytool -list -keystore ~/.android/debug.keystore +... +Certificate fingerprint (MD5): 94:1E:43:49:87:73:BB:E6:A6:88:D7:20:F1:8E:B5:98 +</pre> + +<p>If you use different keys for signing development builds and +release builds, you will need to obtain a separate Maps API key for +each certificate. Each key will only work in applications signed by +the corresponding certificate.</p> + +<p>You also need a <a href="http://www.google.com/accounts/">Google Account</a> +to get a Maps API key, and your API key will be connected to your Google Account.</p> +<br/> +<div id="termsbox" style="margin-left: 2em"> +<textarea rows="15" cols="70" readonly="readonly" onfocus="this.blur()"> +Android Maps APIs Terms of Service + +Last Updated: October 13, 2008 + +Thanks for your interest in the Android Maps APIs. The Android Maps APIs are a collection of services (including, but not limited to, the "com.google.android.maps.MapView" and "android.location.Geocoder" classes) that allow you to include maps, geocoding, and other content from Google and its content providers in your Android applications. The Android Maps APIs explicitly do not include any driving directions data or local search data that may be owned or licensed by Google. + + +1. Your relationship with Google. + 1.1. Your use of any of the Android Maps APIs (referred to in this document as the "Maps API(s)" or the "Service") is subject to the terms of a legal agreement between you and Google Inc., whose principal place of business is at 1600 Amphitheatre Parkway, Mountain View, CA 94043, United States ("Google"). This legal agreement is referred to as the "Terms." + 1.2. Unless otherwise agreed in writing with Google, the Terms will include the following: 1) the terms and conditions set forth in this document (the "Maps APIs Terms"); 2) the Legal Notices (http://www.google.com/intl/en-us/help/legalnotices_maps.html); and 3) the Privacy Policy (http://www.google.com/privacy.html). Before you use the Maps APIs, you should read each of the documents comprising the Terms, and print or save a local copy for your records. + 1.3. If you use the Maps APIs in conjunction with any other Google products or services, including any other Google API, (collectively, the "Services"), your agreement with Google will also include the terms applicable to those Services. All of these are referred to as the "Additional Terms." If Additional Terms apply, they will be accessible to you either within or through your use of that Service. If there is any contradiction between what any Additional Terms say and what the Maps APIs Terms say, then the Maps APIs Terms will take precedence only as it relates to the Maps APIs, and not to any other Services. + 1.4. Google reserves the right to make changes to the Terms from time to time. When these changes are made, Google will make a new copy of the Terms available at http://code.google.com/android/maps-api-tos.pdf. You understand and agree that if you use the Service after the date on which the Terms have changed, Google will treat your use as acceptance of the updated Terms. If a modification is unacceptable to you, you may terminate the agreement by ceasing use of the Maps APIs as well distribution of any applications that use the Maps APIs. + 1.5. Definitions + (a) "Content" means any content provided through the Service, including map and terrain data, photographic imagery, traffic data, or any other content. + (b) "Maps API Implementation" means a software application that uses the Maps APIs to obtain and display Content in conjunction with Your Content, according to these Terms. + (c) "Your Content" means any content that you provide in your Maps API Implementation, including data, images, video, or software. Your Content does not include the Content. + + +2. Accepting the Terms + 2.1. In order to use the Maps APIs you must agree to the Terms. You can accept the Terms by: (a) clicking to accept or agree to the Terms, where this option is made available to you by Google in the user interface for the Service; or (b) using the Maps APIs. In this case, you understand and agree that Google will treat your use of the Maps APIs as acceptance of the Terms from that point onwards. + 2.2. You may not use the Maps APIs and may not accept the Terms if you are a person barred from using the Service under the laws of the United States or the country in which you are resident or from which you use the Service. + 2.3. You represent that you have full power, capacity and authority to accept these Terms. If you are accepting on behalf of your employer or another entity, you represent that you have full legal authority to bind your employer or such entity to these Terms. If you don't have the legal authority to bind, please ensure that an authorized person from your entity consents to and accepts these Terms. + + +3. Privacy and Personal Information + 3.1. For information about Google's data protection practices, please read Google's Privacy Policy at http://www.google.com/privacy.html. This policy explains how Google treats your personal information and protects your privacy when you use the Service. + 3.2. You agree to the use of your data in accordance with Google's Privacy Policy. + + +4. Provision of Service by Google + 4.1. Google has subsidiaries and affiliated legal entities around the world ("Subsidiaries and Affiliates"). Sometimes, these companies will be providing the Service to you on behalf of Google itself. You acknowledge and agree that Subsidiaries and Affiliates will be entitled to provide the Service to you. + 4.2. Google is constantly innovating in order to provide the best possible experience for its users. You acknowledge and agree that the form and nature of the Service that Google provides may change from time to time without prior notice to you. As part of this continuing innovation, you acknowledge and agree that Google may stop (temporarily or permanently) providing the Service (or any features within the Service) to you or to users generally at Google's sole discretion, without prior notice to you. Google reserves the right to refuse or discontinue the Service to anyone, and to disable users' access to the Service, including the Maps APIs or any Content, at any time in its sole discretion with or without notice. + 4.3. You acknowledge and agree that Google may impose or adjust the limit on the number of transactions you may send or receive through the Service; such fixed upper limits may be set by Google at any time, at Google's discretion. + 4.4. Google reserves the right to release subsequent versions of the Maps APIs and to require you to obtain and use the most recent version. + 4.5. The Service currently does not include advertising in the Content. However, Google reserves the right to include advertising in the Content provided to you through the Service, but will provide you with sixty (60) days notice prior to the commencement of advertising. Such notice may be provided on relevant Google websites, including but not limited to theÿGoogle Maps API Blog (http://googlemapsapi.blogspot.com) and theÿGoogle Maps API Groupÿ(http://groups.google.com/group/Google-Maps-API) or such successor URLs that Google may designate from time to time. During that 60 day period, you may terminate your use of the Service, or provide notice of your refusal to accept advertising in accordance with Google's policies and procedures for providing such notice (which Google may make available from time to time in its sole discretion). + + +5. Use of the Service by You + 5.1. In order to access the Service, you must have a Google Account. You agree that any information you give to Google in connection with your Google Account or your continued use of the Service will always be accurate, correct and up to date. + 5.2. After supplying Google with your account information and the MD5 fingerprint for the certificate used to sign your application, and accepting the Terms, you will be issued an alphanumeric key assigned to you by Google that is uniquely associated with your Google Account and the application certificate. Your Maps API implementation?s MapView must include this alphanumeric key, either using the "android:apiKey" XML attribute or using the appropriate MapView constructor, as described in the Android MapView documentation (http://code.google.com/android/reference/com/google/android/maps/MapView.html). + 5.3. There is currently no limit to the number of keys you may obtain in this manner provided that you use a different certificate for each key you obtain and that you use the same Google Account for every key you obtain. You agree that each key is only valid for applications signed with the corresponding certificate. You agree that Google may, in its sole discretion, impose a limit on the number of keys that may be obtained in the future. You agree that your continued use of any of the keys assigned by Google or distribution of any applications using such keys constitutes your continued agreement to these Terms. + 5.4. Subject to these Terms, you may develop, display and/or distribute your Maps API Implementation as part of a commercial or non-commercial enterprise. + 5.5. Your Maps API Implementation and Your Content must not violate Google's Software Principles available at http://www.google.com/intl/en/corporate/software_principles.html (or such successor URL as Google may provide) and any other policies as Google may develop from time to time and make available to you. + 5.6. You agree to use the Service only for purposes that are permitted by: (1) the Terms; (2) any applicable third-party contract, law, or regulation; and (3) any applicable policies or guidelines made available by Google. By way of example, and not as a limitation, you agree that when using the Service, you will not + a. defame, abuse, harass, stalk, threaten or otherwise violate the legal rights (such as rights of privacy and publicity) of others; + b. upload, post, transmit or otherwise make available any inappropriate, defamatory, obscene, or unlawful content; + c. upload, post, transmit or otherwise make available any content that infringes any patent, trademark, copyright, trade secret or other proprietary right of any party, unless you are the owner of the rights, or have the permission of the owner or other legal justification to use such content; + d. upload, post, transmit or otherwise make available messages that promote pyramid schemes, chain letters, or disruptive commercial messages or advertisements; + e. download any file posted by another that you know, or reasonably should know, cannot legally be distributed in such manner; + f. impersonate another person or entity, or falsify or delete any author attributions or labels of the origin or source of Content, or other material; + g. restrict or inhibit any other users from using and enjoying the Service; + h. remove, obscure, or fail to display the Terms of Use link as presented through the Service or described in the Service documentation; + i. remove, alter, or obscure any copyright, trademark or other proprietary rights notices or labels of origin or proprietary rights designation contained in or on Google Services or Content; + j. delete, obscure, or in any manner alter any warning, notice (not limited to any copyright or other proprietary rights notice), or link which appears in the Service or the Content + k. interfere with or disrupt Google Services or servers or networks connected to Google Services, or disobey any requirements, procedures, policies or regulations of networks connected to Google Services; + l. use any robot, spider, site search/retrieval application, or other device to retrieve or index any portion of the Service or Content or collect information about users for any unauthorized purpose; + m. display content in your Maps API Implementation that falsely expresses or implies that such content is sponsored or endorsed by Google; + n. create user accounts by automated means or under false or fraudulent pretenses, or obtain or attempt to obtain keys for the Service using multiple Google Accounts; + o. promote or provide instructional information about illegal activities; + p. promote physical harm or injury against any group or individual; or + q. transmit any viruses, worms, defects, Trojan horses, or any items of a destructive nature. + 5.7. You agree that if you use the Service to develop a Maps API Implementation for use by other users, you will protect the privacy and legal rights of those users. If your Maps API Implementation provides you or another party with information about users, including but not limited to personally identifiable information or non-personally identifiable usage information, you must make the users aware that the information will be available to you or another party, and you must provide legally adequate privacy notice and protection for those users. If your application stores information submitted by users, it must do so securely. If your Maps API Implementation allows a user to provide you with Google Account information, you may only use that information to access the user's Google Account when, and for the limited purposes for which, the user has given you permission to do so. + 5.8. You agree that you are solely responsible for (and that Google has no responsibility to you or to any third party for) any breach of your obligations under the Terms or any applicable law or regulation, and for the consequences (including any loss or damage which Google may suffer) of any such breach. + + +6. Google?s Proprietary Rights + 6.1. Ownership. You acknowledge and agree that Google (or Google's licensors and their suppliers, as applicable) own all legal right, title and interest in and to the Service and Content, including any intellectual property rights that subsist in the Service and Content (whether those rights happen to be registered or not, and wherever in the world those rights may exist). + 6.2. Brand Feature License. For purposes of these Terms, "Brand Features" will mean the trade names, trademarks, service marks, logos, domain names, and other distinctive brand features of each party, respectively, as secured by such party from time to time. Google grants to you a nontransferable, nonsublicenseable, nonexclusive license during the Term to display Google's Brand Features for the purpose of promoting or advertising that you use the Service in accordance with this Section 6.2 and for the purpose of fulfilling your obligations under Section 6.5 below. You grant to Google a nontransferable, nonexclusive license during the Term to use Your Brand Features to advertise that you are using the Service. In using Google Brand Features, you will not: + a. display a Google Brand Feature in any manner that implies a relationship or affiliation with, sponsorship, or endorsement by Google, other than your use of the Service, or that can be reasonably interpreted to suggest editorial content has been authored by, or represents the views or opinions of Google or Google personnel; + b. use Google Brand Features to disparage Google, its products or Services; + c. display a Google Brand Feature on your site if it contains or displays adult content or promotes illegal activities, gambling, or the sale of tobacco or alcohol to persons under twenty-one (21) years of age; + d. have the Google logo as the largest logo in your application (except as displayed in the map image itself); + e. display a Google Brand Feature as the most prominent element in any part of your application; + f. display a Google Brand Feature in a manner that is misleading, defamatory, infringing, libelous, disparaging, obscene or otherwise objectionable to Google; + g. display a Google Brand Feature on a site that violates any law or regulation; or + h. remove, distort or alter any element of a Google Brand Feature (this includes squeezing, stretching, inverting, discoloring, etc.). + 6.3. You understand and agree that Google has the sole discretion to determine whether your use of Google brand features is in accordance with the above restrictions. + 6.4. Except as set forth in this Section 6, nothing in the Terms will grant or will be deemed to grant to one party any right, title or interest in or to the other party's Brand Features. All use by you of Google's Brand Features (including any goodwill associated therewith) will inure to the benefit of Google. At no time during or after the Term will you challenge or assist others to challenge the Brand Features of Google (except to the extent such restriction is prohibited by law) or the registration thereof by Google, nor will you attempt to register any Brand Features (including domain names) that are confusingly similar in any way (including but not limited to, sound, appearance and spelling) to those of Google. + 6.5. You agree that you will not remove, obscure, or alter any proprietary rights notices (including copyright and trademark notices, Terms of Use links, or Brand Features) that may be affixed to or provided through the Service. Where such notices are not affixed within the Service, you agree to display such notices according to the Service documentation if so specified. + + +7. License from Google + 7.1. Service. Google gives you a personal, worldwide, royalty-free, non-assignable and non-exclusive license to use the Service as provided by Google, in the manner permitted by the Terms. + 7.2. Content. Google gives you a personal, worldwide, royalty-free, non-assignable and non-exclusive license to access, use, publicly perform and publicly display the Content in your Maps API Implementation, as the Content is provided in the Service, and in the manner permitted by the Terms. Specifically, you understand the following: + a. Content, not limited to map data, traffic, and directions, is provided for planning purposes only. You may find that weather conditions, construction projects, closures, or other events may cause road conditions or directions to differ from the results depicted in the Content. You should exercise judgment in your use of the Content. + b. Certain Content is provided under license from third parties (http://www.google.com/intl/en_us/help/legalnotices_maps.html), including Tele Atlas B.V. ("Tele Atlas"), and is subject to copyright and other intellectual property rights owned by or licensed to Tele Atlas and/or such third parties. You may be held liable for any unauthorized copying or disclosure of this content. Your use of Tele Atlas map data is subject to additional restrictions located in the Legal Notices (http://www.google.com/intl/en_us/help/legalnotices_maps.html) page. + 7.3. In addition to the license granted here, you may use certain Content according to the terms set forth in our Permission Guidelines for Google Maps and Google Earth (http://www.google.com/permissions/geoguidelines.html). + 7.4. U.S. Government Restricted Rights. If the Service is being used or accessed by or on behalf of the United States government, such use is subject to additional terms located in the "Government End Users" section of our Legal Notices (http://www.google.com/intl/en_us/help/legalnotices_maps.html) page. + 7.5. Google reserves the sole right and discretion to determine whether your use of the Service and Content is in conformance with these Terms. + + +8. License Restrictions. Except as expressly permitted under the Terms, or unless you have received prior written authorization from Google (or, as applicable, from the provider of particular Content), the license granted to you in Section 7 is conditioned on your adherence to all of the restrictions in this Section 8. Under this Section 8, you must not (nor may you permit anyone else to): + 8.1. access or use the Service or any Content through any technology or means other than those provided in the Service, or through other explicitly authorized means Google may designate; + 8.2. copy, translate, modify, create a derivative work of, pre-fetch, cache, or publicly display any Content or any part thereof. + 8.3. redistribute, sublicense, rent, publish, sell, assign, lease, market, transfer, or otherwise make the Service or Content available to third parties; + 8.4. reverse engineer, decompile or otherwise attempt to extract the source code of the Service or any part thereof, unless this is expressly permitted or required by applicable law; + 8.5. use the Service in a manner that gives your or any other person access to mass downloads or bulk feeds of any Content, including but not limited to numerical latitude or longitude coordinates; + 8.6. delete, obscure, or in any manner alter any warning, notice (including but not limited to any copyright or other proprietary rights notice), or link that appears in the Service or the Content; + 8.7. use the Service or Content with any products, systems, or applications for or in connection with (a) real time navigation or route guidance based on position input from a sensor (including but not limited to any visual or audible turn-by-turn route guidance); or (b) any systems or functions for automatic or autonomous control of vehicle behavior; or (c) dispatch, fleet management, business asset tracking, or similar enterprise applications (for avoidance of doubt, you are permitted to use the Service to create Maps API Implementations to track people or assets equipped with a sensor, where the tracking of the people or assets is not critical to the core business or service of the application user. For example, you are permitted to use the Maps APIs to create "Friend Finder" applications that allow consumers to track the locations of their friends? mobile devices, but you are not permitted to use the Maps APIs to create "Business Asset Tracking" applications that track or locate business or government users? field sales or field service personnel, vehicles or other assets that are critical (not incidental) to the core business or service of the application user); + 8.8 print more than 5,000 copies of sales collateral materials containing a screenshot with Tele Atlas Content for commercial sales lead generation ("Direct Marketing"); (if you desire (a) to use Tele Atlas Content for Direct Marketing in excess of the above amount, or (b) to incorporate Tele Atlas Content as a core part of printed matter (such as printed maps or guide books) that you redistribute for a fee, you must contact Tele Atlas to obtain a license to do so); or + 8.9 offer a professional batch geocoding service that uses the Content contained in any Google Services. + + +9. Content License from You + 9.1. You retain copyright and any other rights you already hold in Your Content. If you decide to submit or post Your Content to Google, you give Google a perpetual, irrevocable, worldwide, royalty-free, and non-exclusive license to reproduce, adapt, modify, translate, publish, publicly perform, publicly display and distribute Your Content. This license is solely for the purpose of enabling Google to display, distribute and promote the Service. + 9.2. You agree that this license includes a right for Google to make such Content available to other companies, organizations or individuals with whom Google has relationships for the provision of syndicated services, and to use such Content in connection with the provision of those services. + 9.3. You understand that Google, in performing the required technical steps to provide the Service to our users, may (a) transmit or distribute your Content over various public networks and in various media; and (b) make such changes to your Content as are necessary to conform and adapt that Content to the technical requirements of connecting networks, devices, services or media. You agree that this license will permit Google to take these actions. + 9.4. You confirm and warrant to Google that you have all the rights, power and authority necessary to grant the above license. + + +10. Your Passwords and Account Security + 10.1. You agree and understand that you are responsible for maintaining the confidentiality of passwords or developer keys associated with any account you use to access the Service. Accordingly, you agree that you will be solely responsible to Google for your use of the Service including, but not limited to, activities that occur under your account or developer key. If you become aware of any unauthorized use of your password or of your account, you agree to notify Google immediately. + + +11. Terminating this Agreement + 11.1. The Terms will continue to apply until terminated by either you or Google as set out below. + 11.2. You may terminate your legal agreement with Google by discontinuing your use of the Service at any time, removing the Maps API code from your Maps API Implementation, and ceasing the distribution of any Maps API Implementation that uses the Maps API. You do not need to specifically inform Google when you stop using the Service. + 11.3. Google may, at any time, terminate its legal agreement with you at its discretion without prior notice to you. + 11.4. Nothing in this Section will affect Google's rights regarding provision of the Service under Section 4 of the Terms. + 11.5. When this legal agreement comes to an end, those Terms that by their nature are intended to continue indefinitely will continue to apply, including but not limited to Sections 6.1, 6.3 and 6.4 (Google?s Proprietary Rights); 11.4 and 11.5 (Terminating this Agreement); 12 (Exclusion of Warranties); 13 (Limitation of Liability); 14 (Indemnity); and 18 (General Legal Terms). + + +12. EXCLUSION OF WARRANTIES + 12.1. NOTHING IN THESE TERMS, INCLUDING SECTIONS 12 AND 13, WILL EXCLUDE OR LIMIT GOOGLE'S WARRANTY OR LIABILITY FOR LOSSES WHICH MAY NOT BE LAWFULLY EXCLUDED OR LIMITED BY APPLICABLE LAW. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF CERTAIN WARRANTIES OR CONDITIONS OR THE LIMITATION OR EXCLUSION OF LIABILITY FOR CERTAIN TYPES OF LOSS OR DAMAGES. ACCORDINGLY, ONLY THE LIMITATIONS THAT ARE LAWFUL IN YOUR JURISDICTION WILL APPLY TO YOU, AND GOOGLE?S LIABILITY WILL BE LIMITED TO THE MAXIMUM EXTENT PERMITTED BY LAW. + 12.2. YOU EXPRESSLY UNDERSTAND AND AGREE THAT YOUR USE OF THE SERVICE AND THE CONTENT IS AT YOUR SOLE RISK AND THAT THE SERVICE AND THE CONTENT ARE PROVIDED "AS IS" AND "AS AVAILABLE." IN PARTICULAR, GOOGLE, ITS SUBSIDIARIES AND AFFILIATES, AND ITS LICENSORS AND THEIR SUPPLIERS, DO NOT REPRESENT OR WARRANT TO YOU THAT: + a. YOUR USE OF THE SERVICE WILL MEET YOUR REQUIREMENTS; + b. YOUR USE OF THE SERVICE WILL BE UNINTERRUPTED, TIMELY, SECURE OR FREE FROM ERROR; + c. ANY INFORMATION OBTAINED BY YOU AS A RESULT OF YOUR USE OF THE SERVICES WILL BE ACCURATE OR RELIABLE; AND + d. THAT DEFECTS IN THE OPERATION OR FUNCTIONALITY OF ANY SOFTWARE PROVIDED TO YOU AS PART OF THE SERVICES WILL BE CORRECTED. + 12.3. ANY CONTENT OBTAINED THROUGH THE USE OF THE SERVICES IS DONE AT YOUR OWN DISCRETION AND RISK AND YOU WILL BE SOLELY RESPONSIBLE FOR ANY DAMAGE TO YOUR COMPUTER SYSTEM OR OTHER DEVICE, LOSS OF DATA, OR ANY OTHER DAMAGE OR INJURY THAT RESULTS FROM THE DOWNLOAD OR USE OF ANY SUCH CONTENT. + 12.4. NO ADVICE OR INFORMATION, WHETHER ORAL OR WRITTEN, OBTAINED BY YOU FROM GOOGLE, OR THROUGH OR FROM THE SERVICE OR CONTENT, WILL CREATE ANY WARRANTY NOT EXPRESSLY STATED IN THE TERMS. + 12.5. GOOGLE, ITS LICENSORS AND THEIR SUPPLIERS FURTHER EXPRESSLY DISCLAIM ALL WARRANTIES AND CONDITIONS OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. + + +13. LIMITATION OF LIABILITY + 13.1. EXCEPT AS EXPRESSLY PROVIDED IN THE INDEMNITY PROVISION (SECTION 14) AND SUBJECT TO SECTION 12.1, YOU EXPRESSLY UNDERSTAND AND AGREE THAT GOOGLE, ITS SUBSIDIARIES AND AFFILIATES, AND GOOGLE?S LICENSORS AND THEIR SUPPLIERS, WILL NOT BE LIABLE TO YOU FOR: + a. ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR EXEMPLARY DAMAGES THAT MAY BE INCURRED BY YOU, HOWEVER CAUSED AND UNDER ANY THEORY OF LIABILITY (INCLUDING, BUT NOT BE LIMITED TO, ANY LOSS OF PROFIT (WHETHER INCURRED DIRECTLY OR INDIRECTLY), ANY LOSS OF GOODWILL OR BUSINESS REPUTATION, ANY LOSS OF DATA, COST OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR OTHER INTANGIBLE LOSS); + b. ANY LOSS OR DAMAGE AS A RESULT OF: + i. ANY RELIANCE PLACED BY YOU ON THE COMPLETENESS, ACCURACY OR EXISTENCE OF ANY ADVERTISING, OR AS A RESULT OF ANY RELATIONSHIP OR TRANSACTION BETWEEN YOU AND ANY ADVERTISER OR SPONSOR WHOSE ADVERTISING APPEARS ON THE SERVICES; + ii. ANY CHANGES THAT GOOGLE MAY MAKE TO THE SERVICES, OR ANY PERMANENT OR TEMPORARY CESSATION IN THE PROVISION OF THE SERVICES (OR ANY FEATURES WITHIN THE SERVICES); + iii. THE DELETION OF, CORRUPTION OF, OR FAILURE TO STORE, ANY CONTENT AND OTHER COMMUNICATIONS DATA MAINTAINED OR TRANSMITTED BY OR THROUGH YOUR USE OF THE SERVICES; + iv. YOUR FAILURE TO PROVIDE GOOGLE WITH ACCURATE ACCOUNT INFORMATION; OR + v. YOUR FAILURE TO KEEP YOUR PASSWORD OR ACCOUNT DETAILS SECURE AND CONFIDENTIAL. + 13.2. THE LIMITATIONS ON GOOGLE'S LIABILITY TO YOU IN SECTION 13.1 ABOVE WILL APPLY WHETHER OR NOT GOOGLE, ITS AFFILIATES, LICENSORS OR THEIR SUPPLIERS HAVE BEEN ADVISED OF OR SHOULD HAVE BEEN AWARE OF THE POSSIBILITY OF ANY SUCH LOSSES OR DAMAGES. + + +14. Indemnity + 14.1. You hereby agree to indemnify, defend and hold Google, its strategic partners, officers, directors, agents, affiliates, licensors and their suppliers ("the Indemnified Parties") harmless from and against any claim or liability arising out of: (a) your use of the Maps APIs in breach of the Terms or applicable policies; (b) your Maps API Implementation; (c) any use by users of your Maps API Implementation; (d) any breach of or noncompliance with any representation, warranty or obligation in these Terms or applicable policies; and (e) any claim that your Maps API Implementation or Your Content violates any applicable law, including but not limited to any claim that your Maps API Implementation infringes the rights of a third party. You will cooperate as fully as reasonably required in the defense of any claim. Google reserves the right, at its own expense, to assume the exclusive defense and control of any matter subject to indemnification by you. You acknowledge that damages for improper use of the Maps APIs may be irreparable; therefore, Google is entitled to seek equitable relief, including but not limited to preliminary injunction and injunction, in addition to all other remedies. + + +15. Copyright Policies + 15.1. It is Google's policy to respond to notices of alleged copyright infringement that comply with applicable international intellectual property law (including, in the United States, the Digital Millennium Copyright Act) and to terminate the accounts of repeat infringers. Details of Google's policy can be found at http://www.google.com/igoogle_dmca.html. + + +16. Other Content + 16.1. The Service may include hyperlinks to other web sites or content or resources. Google has no control over any web sites or resources that are provided by companies or persons other than Google. You acknowledge and agree that Google is not responsible for the availability of any such external sites or resources, and does not endorse any advertising, products or other materials on or available from such web sites or resources. + 16.2. You acknowledge and agree that Google is not liable for any loss or damage that may be incurred by you as a result of the availability of those external sites or resources, or as a result of any reliance placed by you on the completeness, accuracy or existence of any advertising, products, or other materials on, or available from, such web sites or resources. + + +17. Language of the Terms + 17.1. Where Google has provided you with a translation of the English language version of the Terms, you agree that the translation is provided for your convenience only and that the English language version of the Terms will govern your relationship with Google. + 17.2. If there is any contradiction between the English language version of the Terms and a translation of the Terms, the English language version will take precedence. + + +18. General Legal Terms + 18.1. The Terms constitute the whole legal agreement between you and Google and govern your use of the Service and Content, and completely replace and supersede any prior agreements between you and Google, written or oral, in relation to the Service and Content. The Terms may be assigned by Google and will inure to the benefit of Google, its successors and assigns. + 18.2. You agree that Google may provide you with notices, including those regarding changes to the Terms, by email, regular mail, or postings on the Service. + 18.3. You agree that if Google does not exercise or enforce any legal right or remedy contained in the Terms (or that Google has the benefit of under any applicable law), this will not be taken to be a formal waiver of Google's rights and that those rights or remedies will still be available to Google. Any waiver of any provision of these Terms will be effective only if Google expressly states in a signed writing that it is waiving a specified Term. + 18.4. If any court of law that has jurisdiction rules that any provision of these Terms is invalid, then that provision will be removed from the Terms without affecting the rest of the Terms. The remaining provisions of the Terms will continue to be valid and enforceable. + 18.5. You acknowledge and agree that each member of the group of companies of which Google is the parent will be third party beneficiaries to the Terms and that such other companies will be entitled to directly enforce, and rely upon, any provision of the Terms that confers a benefit on (or rights in favor of) them. Other than this, no other person or company will be a third party beneficiary to the Terms. + 18.6. The Terms, and your relationship with Google under the Terms, will be governed by the laws of the State of California, USA, without regard to its conflict of laws provisions. You and Google agree to submit to the exclusive jurisdiction of the courts located in the County of Santa Clara, California, USA, to resolve any legal matter arising from the Terms. Notwithstanding this, you agree that Google will be allowed to apply for injunctive remedies (or an equivalent type of urgent legal relief) in any jurisdiction. +</textarea> +</div> + +<form action="signup.html" method="get" onsubmit="return CheckForm(this)"> + <div class="terms"> + <table style="width:95%"> + <tr> + <td style="width:1em"><input type="checkbox" name="agreeTerms" value="1"/></td> + <td>I have read and agree with the terms and conditions <span class="printable">(<a href="maps-api-tos.pdf">printable version</a>)</span></td> + </tr> + <tr> + <td></td> + <td> + My certificate's MD5 fingerprint: + <input type="text" name="fp" size="47" value=""/> + </td> + </tr> + <tr> + <td></td> + <td><input type="submit" value="Generate API Key"/></td> + </tr> + </table> + </div> +</form> + + <!-- end body text --> + + + </div><!-- end gc-pagecontent --> + </div><!-- end gooey wrapper --> + + </div> <!-- end codesite content --> + +<div id="gc-footer" dir="ltr"> + <div class="text"> + + ©2008 Google - + <a href="/">Code Home</a> - + <a href="http://www.google.com/accounts/TOS">Site Terms of Service</a> - + <a href="http://www.google.com/privacy.html">Privacy Policy</a> - + <a href="/more/">Site Directory</a> + <br /> + <br /> + <!-- end gc-footer --> + </div> +</div><!-- end gc-containter --> + </body> +</html> + diff --git a/docs/html/maps-api-tos.pdf b/docs/html/maps-api-tos.pdf Binary files differnew file mode 100644 index 0000000..80c2836 --- /dev/null +++ b/docs/html/maps-api-tos.pdf diff --git a/docs/html/publish/index.jd b/docs/html/publish/index.jd new file mode 100644 index 0000000..63f2e68 --- /dev/null +++ b/docs/html/publish/index.jd @@ -0,0 +1,5 @@ +publish=true +page.title=Publish Your Application +@jd:body + +FIXME diff --git a/docs/html/publish/publish_toc.cs b/docs/html/publish/publish_toc.cs new file mode 100644 index 0000000..c6f5c65 --- /dev/null +++ b/docs/html/publish/publish_toc.cs @@ -0,0 +1 @@ +<ul>
<li>Publish
<ul>
<li><a href="">Publish</a></li>
<li><a href="">Publish</a></li>
</ul>
</li>
</ul>
FIXME
diff --git a/docs/html/reference/index.html b/docs/html/reference/index.html new file mode 100644 index 0000000..8d516b1 --- /dev/null +++ b/docs/html/reference/index.html @@ -0,0 +1,8 @@ +<html> +<head> +<title>Redirecting...</title> +<meta http-equiv="refresh" content="0;url=packages.html"> +</head> +<body> +</body> +</html> diff --git a/docs/html/reference/reference_toc.cs b/docs/html/reference/reference_toc.cs new file mode 100644 index 0000000..60e9d5f --- /dev/null +++ b/docs/html/reference/reference_toc.cs @@ -0,0 +1 @@ +<ul>
<li>API Ref
<ul>
<li><a href="">API Ref</a></li>
<li><a href="">API Ref</a></li>
</ul>
</li>
</ul>
FIXME
diff --git a/docs/html/resources/bootcamp.pdf b/docs/html/resources/bootcamp.pdf Binary files differnew file mode 100644 index 0000000..a817b96 --- /dev/null +++ b/docs/html/resources/bootcamp.pdf diff --git a/docs/html/roadmap.jd b/docs/html/roadmap.jd new file mode 100644 index 0000000..1198638 --- /dev/null +++ b/docs/html/roadmap.jd @@ -0,0 +1,120 @@ +page.title=Developer Roadmap +@jd:body +<h1>Android Developer Roadmap</h1> +<h2>Introduction</h2> +<p> +On 12 November, 2007, we made available the first early look at the Android +SDK to give developers an opportunity to explore Android and build +applications for the Android Developer Challenge. That was followed by the +"M5" early look build. +</p><p> +Since then, we've been hard at work with our <a +href="http://www.openhandsetalliance.com/">partners</a> preparing the first +device for launch and finalizing the APIs and platform. The developer +feedback we received via the "early look" SDKs has been extremely valuable in +that process. This Roadmap outlines our plans for +the coming months, and lets you know what to expect as we near device +availability. +</p><p> +This is the top-level Roadmap. Individual components of Android (such as +the Dalvik virtual machine, the Android Developer Tools, and so on) will have +their own roadmaps, once we complete the source code release. Those roadmaps +will be linked to this page, as they become available. +</p> +<h2>Timeline</h2> +<p> +To orient yourself, consult this brief timeline. Read on for details on these +milestones. +</p><ul> +<li>12 November, 2007 - "Early Look" SDK released</li> +<li>January to August, 2008 - Android Developer Challenge I</li> +<li>18 August, 2008 - Android 0.9 SDK beta released</li> +<li>28 August, 2008 - Android Market introduced</li> +<li>23 September, 2008 - Android 1.0 SDK Release 1 available (first actual +1.0-compatible SDK)</li> +<li>22 October, 2008 - Android 1.0 devices available at retail</li> +<li>Q4 2008 - Source code released</li> +<li>Q4 2008 - Key Announcement on Android Developer Challenge II</li> +</ul> +<h2>SDK Naming and Compatibility</h2> +<p> +Before we dive into details, here is a quick note on how we name SDKs. +</p><p> +We've adopted the following naming convention for Android SDKs: + "Android <Platform> SDK, release <Release>" +</p><p> +The downloadable file names for the SDKs will have this naming convention: + "android-sdk-<Host-OS>-<Platform>_r<Release>.zip" +</p><p> +The "<Platform>" refers to the version of the Android platform with which the +SDK is compatible. For instance, an SDK that can be used to build +applications that will run on Android 1.0 is considered to be an "Android 1.0 +SDK". However, since we do expect to release bug fixes and enhancements for +the various tools included in the SDK (such as the emulator, Eclipse plugin, +DDMS, and so on) we need to distinguish between releases of the SDK that can +be used to build for the same Android platform. That's what we will use the +"<Release>" for. +</p><p> +For example, the first SDK that is compatible with Android 1.0 is named +"Android 1.0 SDK, release 1", and will have file names such as +"android-sdk-windows-1.0_r1.zip". In the future, after we release a +hypothetical Android 2.0 platform version, you might see an SDK named "Android +2.0 SDK, release 3", which would refer to the third released SDK compatible +with Android 2.0. +</p> +<h2>Details of Key Events</h2> +<h3>Ongoing SDK Releases</h3> +<p> +The SDK consists of two general pieces: a version of the Android platform +itself (that runs in the emulator), and the accompanying developer tools that +surround it. This means that when we ship SDK releases, all releases within a +given series (such as all the SDKs for Android 1.0) will consist of +essentially the same platform image, but with different, updated tools. +</p><p> +In August, we released Android 0.9 SDK, beta. The Android +platform image was not quite 1.0-final (which is why we identified it as 0.9), +and the tools were not yet final (which is why we referred to it as +beta.) </p> + +<p>For the SDK that includes the Android 1.0 platform and updated tools, +we've dropped the beta labeling and released "Android 1.0 SDK, release +1". Applications developed on this SDK version will be compatible with +devices that run the Android 1.0 platform.</p> + +<h3>Device Availability</h3> +<p>The first Android-powered device, the T-Mobile G1, was announced on 23 September, +2008. To learn more about the T-Mobile G1, see the <a href="http://www.t-mobileg1.com">T-Mobile G1 site</a>. + +<p>Other partners will be releasing Android-powered devices in the future. +We will update this space with more specific information about each device +release, as it becomes +available.</p> + +<h3>Source Code Release</h3> +<p> +We are currently in the process of preparing for the release of the source +code. This includes a few key tasks: +</p><ul> +<li>Selection of hosting infrastructure</li> +<li>Updating the build infrastructure for general use</li> +<li>Creation of a project governance framework</li> +<li>Final examination of source code for release approval</li> +<li>Physical upload and release packaging of the source code</li> +</ul><p> +This work is already under way, but since Android contains some 8 million +lines of code, it's a lengthy process. We expect this process to conclude +(and source code to be released) in Q4 of 2008. +</p> +<h3>Android Developer Challenge II</h3> +<p> +When Android was announced on 5 November, 2007, Google also announced a $10 +million <a href="{@docRoot}adc.html">Android Developer Challenge</a>, split into two separate $5 million +events. The first Android Developer Challenge ran from January 2008 through +August 2008, and was intended to give developers an opportunity to explore +their ideas using the early look SDK and build prototype applications -- to +"get in on the ground floor." The second Challenge will give developers a +chance to build polished applications once hardware is available. +</p><p> +We'll be making some interesting announcements regarding ADC II soon, in Q3 or +Q4. +</p> diff --git a/docs/html/samples/index.jd b/docs/html/samples/index.jd new file mode 100644 index 0000000..6219f9a --- /dev/null +++ b/docs/html/samples/index.jd @@ -0,0 +1,23 @@ +page.title=Android SDK +page.onlyfortemplate=codesite +@jd:body +<h1>Sample Code</h1> + +<p>The Android SDK ships with several sample projects. They are:</p> + +<dl> + <dt><a href="{@docRoot}samples/ApiDemos/index.html">API Demos</a></dt> + <dd>A demonstration of many of the Android APIs.</dd> + + <dt><a href="{@docRoot}samples/LunarLander/index.html">Lunar Lander</a></dt> + <dd>Your objective: to land on the moon.</dd> + + <dt><a href="{@docRoot}samples/NotePad/index.html">Note Pad</a></dt> + <dd>A simple note pad application.</dd> +</dl> + +<p>To run these samples, you should <a +href="{@docRoot}intro/installing.html#creatingaproject">import them into +Eclipse</a> or <a href="{@docRoot}intro/installing.html#otherides">use +activitycreator.py</a>, as described in the <a +href="{@docRoot}intro/installing.html">Installing the SDK</a>.</p> diff --git a/docs/html/sdk/1.0_r1/RELEASENOTES.jd b/docs/html/sdk/1.0_r1/RELEASENOTES.jd new file mode 100644 index 0000000..bb2e485 --- /dev/null +++ b/docs/html/sdk/1.0_r1/RELEASENOTES.jd @@ -0,0 +1,639 @@ +page.title=Release Notes +@jd:body + +<p>For the latest known issues, please ensure that you're viewing this page at: <a href="http://code.google.com/android/RELEASENOTES.html">http://code.google.com/android/RELEASENOTES.html</a>.</p> + +<a name="1.0_r1"></a> + +<h2>Android 1.0 SDK, Release 1</h2> + +<p>This SDK release is the first to include the Android 1.0 platform and application API. Applications developed on this SDK will be compatible with mobile devices running the Android 1.0 platform, when such devices are available.</p> + +<p>This release includes mainly bug fixes, although some smaller features were added. The Android 1.0 also includes several API changes from the 0.9 version. For more information on API changes, see the <a href="{@docRoot}migrating/0.9-1.0/changes-overview.html">Overview of Changes</a> and the <a href="{@docRoot}migrating/0.9-1.0/changes.html">API Differences Report</a>. For those porting from the M5 release, the SDK also includes the legacy changes overview and API Differences Reports. See the current Overview of Changes for more information. </p> + +<h3>ADT Plugin Compatibility</h3> + +<p>For this version of the SDK — Android 1.0 SDK, Release 1 — the compatible version of the Android Development Tools (ADT) Plugin for Eclipse is <strong>0.8.0</strong>. If you are using a previous version of ADT, you should update to the latest version for use with this SDK. For information about how to update your ADT plugin, see <a href="{@docRoot}intro/upgrading.html">Upgrading the SDK</a>.</p> + +<h3>Installation and Upgrade Notes</h3> + +<p>If you've been developing an application using a previous SDK version and you want the application to run on Android-powered mobile devices, you must port the application to the Android 1.0 SDK. Please see <a href="{@docRoot}intro/upgrading.html">Upgrading the SDK</a> for detailed instructions on how to make the transition to this release. Be sure to wipe application user data (emulator option <code>-wipe-data</code>) when running your application on the Android 1.0 SDK emulator.</p> + +<p>If you're installing the Android SDK for the first time, please see the instructions in <a href="{@docRoot}intro/installing.html">Installing the SDK</a>. + +<h3>Other Notes</h3> + +<p><strong>MapView API Key</strong></p> + +<p>MapView is a class that lets you easily integrate Google Maps into your application. Before you can access the maps data, you will need to register with the Google Maps service and receive a Maps API Key, which you then add to your MapView for authentication to the server.</p> + +<p>Currently, the registration service for MapView is not yet active and Google Maps is not yet enforcing the Maps API Key requirement. However, note that the registration service will be activated soon, so that MapViews in any application deployed to a mobile device will require registration and a valid Maps API Key. </p> + +<p>As soon as the registration service becomes available, we will update the page at <a href="http://code.google.com/android/toolbox/apis/mapkey.html">http://code.google.com/android/toolbox/apis/mapkey.html</a> with details about how and where to register. Please check that page periodically for registration information, if you are using a MapView.</p> + + +<h3>Resolved Issues, Changes</h3> + +<p><strong>Emulator</strong></p> +<ul> +<li>Emulator now saves the user image in <android>/SDK1.0/</code></li> +<li>Fixed EsounD-related freezes on Linux.</li> +<li>Fixed the documentation in -help-audio. '-audio list' doesn't work, one + needs to call -help-audio-out and -help-audio-in to get the list of valid + audio backends.</li> +<li>Fixed scrollwheel Dpad emulation in rotated mode. before that, using the + scroll-wheel would always generated Dpad Up/Down events, even when in + landscape mode.</li> +<li>Several Obsolete command options were removed.</li> +<li>Setting the network speed through the console or the -netspeed option will + properly modify the connectivity icon on the device.</li> +<li>Setting the GSM voice registration state to 'roaming' in the console will + properly modify the voice icon on the device</li> +</ul> + +<p><strong>SQLite</strong></p> +<ul> +<li>SQLite is now included in the SDK package on all platforms. </li> +</ul> + +<h3>Known Issues</h3> + +<p><strong>JUnit and Eclipse/ADT</strong></p> +<ul> +<li>If you are developing in Eclipse/ADT and want to add JUnit test +classes, you can do so. However, you need to set up a custom JUnit configuration +before your tests will run properly. For detailed information about how to set +up the JUnit configuration, see the troubleshooting topic <a +href="{@docRoot}kb/troubleshooting.html#addjunit">Running a Junit test class +in Eclipse</a>.</li> +</ul> + +<p><strong>Other</strong></p> + +<ul> +<li>It is not possible to send MMS messages between emulator instances. </li> +<li>In some cases, you may encounter problems when using the browser on an +emulator started with the command-line option <code>-http-proxy</code>. </li> +<li>We regret to inform developers that Android 1.0 will not include support for +dot-matrix printers.</li> +<li>On the OSX platform, if you manually remove the ~/.android directory +using <code>rm -rf ~/.android</code>, then try to run +the emulator, it crashes. This happens because the emulator fails to create +a new .android directory before attempting to create the child SDK1.0 directory. +To work around this issue, manually create a new .android directory using +<code>mkdir ~/.android</code>, then run the emulator. The emulator +creates the SDK1.0 directory and starts normally. </li> +<li>The final set of Intent patterns honored by Android 1.0 has not yet been +fully documented. Documentation will be provided in future releases.</li> +<li>In ADT Editor, you can add at most ten new resource values at a time, +in a given res/values/*.xml, using the form in the Android Resources pane. +If you add more than ten, the Android Resources pane will not display the +attributes fields for the additional resource entries. To work around this +problem, you can close the file in the editor and open it again, or you +can edit the resource entries in the XML text mode. </li> +<li>The emulator's battery-control commands (<code>power <option></code>) +are not working in this release.</li> +</ul> + +<p>Unless otherwise noted, Known Issues from Android 0.9 SDK also apply to Android 1.0 SDK, Release 1.</p> + + +<a name="0.9_r1" id="0.9_r1"></a> + +<h2>Android 0.9 SDK Beta (r1)</h2> + +<p>This is the first release of the Android SDK that is formally on the path to Android 1.0. The release is considered beta. (Previous releases were considered early looks at the SDK, and were not formally on the path toward Android 1.0.) This release may not be fully compatible with Android 1.0, when released, meaning that applications you build using this SDK may not run on final Android 1.0 devices. However, the differences between this release and final 1.0-compatible releases are expected to be small. No major API changes are planned.</p> + +<p>This beta SDK release contains a large number of bug fixes and improvements from the early-look SDKs. The sections below describe the highlights of the release, but do not provide an exhaustive or comprehensive list of changes. For additional detail, see the <a href="{@docRoot}migrating/m5-0.9/changes-overview.html">API Changes Overview</a>, the <a href="{@docRoot}migrating/m5-0.9/changes.html">API Differences Report</a>, and the main <a href="{@docRoot}documentation.html">SDK documentation</a>.</p> + +<p>If you are not viewing this document online at <a href="http://code.google.com/android/RELEASENOTES.html" title="http://code.google.com/android/RELEASENOTES.html">http://code.google.com/android/RELEASENOTES.html</a>, please visit that page to see any additional information added since the SDK was released.</p> + +<h3>Installation Notes</h3> + +<p>If you've been developing Android applications using the M5 early look of the Android SDK, please see <a href="{@docRoot}intro/upgrading.html">Upgrading the SDK</a> for detailed instructions on how to make the transition to this release. Be sure to wipe emulator data before using the 0.9 beta emulator after using the M3 or M5 emulator.</p> + +<p>If you are installing the Android SDK for the first time, please see the instructions in <a href="{@docRoot}intro/installing.html">Installing the SDK</a></p> + +<h3>New Features and Notable Changes</h3> + +<p><strong>Behavior and System Changes</strong></p> +<ul> + <li>New Home screen and many user interface updates + </li> + <li>Minor changes to Activity lifecycle and task management + </li> + <li>New window option to request OpenGL acceleration for certain kinds of View structures + </li> +</ul> +<p> + <b> + Significant API Changes</b> +</p> +<ul> + <li>onFreeze(Bundle) renamed to onSaveInstanceState(Bundle), to better reflect the fact that it does not represent an actual change in application lifecycle + </li> + <li>IntentReceivers are now known as BroadcastReceivers (but still operate on Intents.) + </li> + <li>Various parts of the API cleaned up to use Intents instead of Bundles; Intent itself improved to reduce the need for separate payload Bundles.</li> + <li>ContentProvider Cursors have had significant changes to make them easier to create and remove certain data consistency bugs. + </li> + <li>Changes to menus to make them more flexible; also added context menus (similar to "right mouse button" menus) + </li> + <li>Changes to the Sensor API to make reading sensors more convenient and reduce the need to poll + </li> + <li>Improvements to the Camera API + </li> + <li>Significant changes to the Location API to make it easier to use and better self-documenting + </li> + <li>API cleanup on MapViews + </li> + <li>Performance-related changes to the MediaPlayer, as well as support for new types of ringtones + </li> + <li>Apache HTTPClient installation upgraded to 4.x of that API; 3.x version is removed + </li> + <li>HTTPClient 4.x removes multipart methods, include HttpMime which is an extension of Mime4j (http://james.apache.org/mime4j/index.html) in your project instead + </li> + <li>Improvements to WiFi and related networking + </li> + <li>New Preferences API to easily store small amounts of data + </li> + <li>Improvements to the Telephony API, including ability to obtain source number of incoming phone calls + </li> + <li>Variety of improvements to the View API + </li> + <li>Variety of improvements to component management, such as the ability to keep components private, better control over when processes are started, and ability to "alias" an Activity to more than one entry in AndroidManifest.xml + </li> + <li>Improvements to how the Browser and WebView, such as better control over content downloads + </li> + <li>A number of enhancements to XML layouts, such as the new <merge> tag + </li> + <li>Numerous improvements to the standard widgets + </li> + <li>Network access now requires that applications obtain a permission in their AndroidManifest.xml files. + </li> +</ul> +<p> + <b> + Maps & Location</b> +</p> +<ul> + <li>The MapView will require an API key on final Android 1.0 devices. This key can be obtained at no cost from Google, and will allow access to the full MapView API. In this release, the API key must be provided but can be any dummy value. In the final 1.0-compatible SDKs, this will need to be a real key. + </li> + <li>The KML-based mock location provider supported in previous releases is no longer supported. In the current SDK, you can use the emulator console to send GPS fix updates to the emulator and applications running on it. Also, the DDMS tool provides an UI that you can use to easily upload GPX and KML files. DDMS handles playback of the KML or GPX tracks automatically. </li> +</ul> +<p> + <b>ADT Plugin for Eclipse</b></p> + <p>The ADT Plugin that accompanies this SDK includes a preview of the Graphical Layout Editor. Files located in <project>/res/layout[-qualifiers]/ will be opened with the new layout editor. This is very much a work in progress, and provided here for preview purpose. The editor feature is subject to change. +</p> +<ul> + <li>Dual page editor with a WYSIWYG page (the graphical editor) and an XML page with content assist. + </li> + <li>The interactivity in the editor itself is limited to selection at the moment. Actions on the layout elements can be done from the following standard Eclipse views: Outline (add/remove/up/down), and Properties (editing of all the element properties with a tooltip in the status bar). + </li> + <li>Top part of the editor allows you to display the layout in different configurations (language, orientation, size, etc...), and different themes. + + <ul> + <li>All referenced resources (strings, bitmaps, etc...) are resolved based on the selected configuration/theme. + </li> + <li>A green check mark next to a resource qualifier indicates that the opened file matches the value of the qualifier. A warning sign indicates that the opened file does not specifies any value for this qualifier. + </li> + <li>If a different version of the opened layout matches the new configuration selection (in a different res/layout-qualifier folder) then the editor automatically switches to that new file. + </li> + </ul> + </li> + <li>Custom Views are supported, however if they do too much in their constructor/onDraw method, it may not work (the layout library used by the editor only includes a sub-part of the Android framework). Check the android console for errors/exceptions. + </li> +</ul> + +<p>Known issues/limitations for Graphical Layout Editor include:</p> + + <ul> + <li>Font display is very close but not equals to on-device rendering since the font engine in Java slightly differs from the font engine in Android. This should not have any impact on your layouts. + </li> + <li>Creating new views in a relative layout automatically puts each new elements below each other using the <i>layout_below</i> attribute. However, until the layout file is saved, they will appear stacked on top of each other. + </li> + <li>Some XML based drawables don't draw. Fading in the scroll/list view appears as a white rectangle. Generally do not expect every single fancy drawing feature of the android framework to be supported in the layout editor (but we're working on it). + </li> + <li>Themes defined in the project are not added to the theme drop-down. + </li> + <li>No animation support! + </li> + <li>No support for WebView, MapView and SurfaceView. + </li> + <li>No UI support for <merge>, <include>, <ViewStub> elements. You can add these elements to your manifest using the xml editor only. + </li> + <li>If a layout fails to render in a way that prevents the whole editor from opening, you can: + + <ul> + <li>open that particular file in a different editor: right click the file in the package explorer and choose Open With... > XML editor + </li> + <li>completely disable the layout editor, by setting a system wide environment variable called ANDROID_DISABLE_LAYOUT to any value. + </li> + </ul> + <li>If a layout fails to render, check the android console (in the standard Eclipse Console view). Errors/Exceptions will be displayed in there. + </li> + </ul> + </li> +</ul> +<p>Other ADT features/notes include:</p> +<ul> + <li>There is a new launch option for activity. You can choose to launch the default activity (finds an activity configured to show up in the home screen), or a specific activity, or none.</li> + <li>Normal Java resources (non Java files placed in package folders) are now properly packaged in the final package, and can be accessed through normal java API such as ClassLoader.getResourceAsStream()</li> + <li>Launch configuration now has an option to wipe emulator data on launch. This always asks for confirmation.</li> + <li>Launch configuration now has an option to disable the boot animation. This will let the emulator start faster on older computers.</li> + <li>Installation of application is now more robust and will notify of installation failure. Also installation is blocking, removing issues where ADT tried to launch the activity before the app was installed.</li> + +</ul> + +<p><b>Ant Build Tools</b></p> + +<ul> + <li><span>External jar libraries are now directly supported by build.xml, just drop them in the libs directory.</li> +</ul> + +<p><b>Emulator</b></p> + +<ul> + <li>The console port number of a given emulator instance is now displayed in its window's title bar.</li> + <li>You can define the console port number used by a given emulator instance. +To do so, start the instance with the '-port <port>' option and +specify which port the emulator should bind to for the console. <port> must be an *even* integer between 5554 and 5584 inclusive. The corresponding ADB port will be <port>+1.</li> + <li>The <code>-adb-port</code> command is deprecated. Please do not use it, as it will be removed soon and you cannot use both -port and -adb-port at the same time.</li> + <li>Voice/sms are automatically forwarded to other emulator instances running on the same machine, as long as you use their console port number as the destination phone number. For example, if you have two emulators running, the first one will typically use console port 5554, and the second one will use port 5556, dialing 5556 on the first emulator will generate an incoming call on the second emulator. You can also hold/unhold calls. This also works when sending SMS messages from one emulator to the other.</li> + <li>A new <code>-scale <fraction></code> option allows you to scale the emulator window. </li> + <li>A new <code>-no-boot-anim</code> option tells the emulator to disable the boot animation. On slower systems, this can significantly reduce the time to boot the system in the emulator.</li> + +</ul> + +<p> + <b>Other Development Tools</b> +</p> + +<p>The SDK includes several new development tools, such as</p> +<ul> + <li><a href="{@docRoot}reference/hierarchy-viewer.html">HierarchyViewer</a> is a visual tool for inspecting and debugging your user interfaces and layout. </li> + <li><a href="{@docRoot}reference/draw9patch.html">Draw 9-patch</a> allows you to easily create a NinePatch graphic using a WYSIWYG editor. </li> + <li>The <a href="{@docRoot}reference/monkey.html">UI/Application Exerciser Monkey</a> generates pseudo-random system and user events, for testing your application. </li> +</ul> +<p> + <b>Application Signing</b> +</p> +<ul> + <li>Starting with this release, Android .apk files must be cryptographically signed, or the system will reject them upon installation. The purpose of this requirement is to securely and uniquely identify developers, so that the system can -- for example -- safely let multiple .apk files signed by the same developer share resources. + </li> + <li>There are no requirements on the key used to sign .apk files; locally-generated and self-signed keys are allowed. There is no PKI, and developers will not be required to purchase certificates, or similar. For developers who use the Eclipse/ADT plugin, application signing will be largely automatic. Developers who do not use Eclipse/ADT can use the standard Java jarsigner tool to sign .apk files. + </li> +</ul> +<p> + <b>Sample Code</b> +</p> +<ul> + <li>LunarLander has been converted to render into a SurfaceView via a background Thread, for better performance. + </li> + <li>New sample: the source code for the now-obsolete Home screen from M5 is included as an example of how to construct a Home screen replacement. + </li> +</ul> +<p> + <b> + Removed Functionality</b> +</p> +<ul> + <li>Due to significant API changes in the upstream open-source project and due to the timeline of getting certain Bluetooth profile implementations certified, a comprehensive Bluetooth API will not be possible or present in Android 1.0. + </li> + <li>Due to the security risks inherent in accepting arbitrary data from "outside" the device, the data messaging facility of the GTalkService will not be present in Android 1.0. The GTalkService will provide connectivity to Google's servers for Google Talk instant messaging, but the API has been removed from this release while we improve the service. Note that this will be a Google-specific service and is not part of the core of Android. + </li> + <li>We know that these changes will affect many developers who have worked with the prior early looks at the SDK, and we are very sorry for the resulting inconvenience. We look forward to the possibilty of restoring some or all of this functionality in a later version of the Android platform. + </li> +</ul> +<p> + <b> + Miscellaneous</b> +</p> +<ul> + <li>Many internal and non-public APIs have been removed from the documentation. Classes and methods that are not present in the documentation are non-public and should not be used, even though they may appear in tools such as IDEs. A future version of the SDK will ship with an android.jar file that contains only public classes, to help developers avoid accidentally using non-public APIs. + </li> + <li>A few extraneous APIs (such as unnecessary packages under java.awt) have been removed. + </li> + <li>Several additional tools are included, such as a utility for easily drawing 9-patch images. + </li> + <li>The DDMS utility has been refactored into library form. This is not of direct interest to application developers, but may be of interest to vendors interested in integrating the Android SDK into their products. Watch for more information about the ddmlib library soon. + </li> + <li>For performance and maintainability reasons, some APIs were moved into separate modules that must be explicitly included in the application via a directive in AndroidManifest.xml. Notable APIs that fall into this category are the MapView, and the java.awt.* classes, which each now reside in separate modules that must be imported. Developers who overlook this requirement will see ClassNotFoundExceptions that seem spurious. + </li> + <li>Developers who use 'adb push' to install applications must now use 'adb install', since the full package manager is now implemented. 'adb push' will no longer work to install .apk files. + </li> + <li>The emulator supports a variety of new options, and some existing options have been changed. Please consult the updated emulator documentation for details. + </li> +</ul> + +<h3> + Resolved Issues +</h3> +<p> + The list below is not comprehensive, but instead highlights the most interesting fixes since the last SDK release. +</p> +<ul> + <li>More of the standard Android user applications are now included, such as the Music and Messaging applications. + </li> + <li>Many bug fixes to the Media Player + </li> + <li>Emulator performance is improved, especially for startup + </li> + <li>More internal APIs are removed from class documentation. (However, this work is not quite yet complete.) + </li> + <li>It's now much easier to add media content to the SD card and have the ContentProvider locate and expose it to other applications. + </li> +</ul> + +<h3> + Known Issues +</h3> +<ul> + <li>The final set of Intent patterns honored by Android 1.0 has not yet been fully documented. Documentation will be provided in future releases. + </li> + <li>We regret to inform developers that Android 1.0 will not support 3.5" floppy disks. + </li> + <li>Unfortunately, the ability to play audio streams from memory (such as via an InputStream or Reader) will not be possible in Android 1.0. As a workaround, we recommend that developers save media content to SD card and use MediaPlayer to play from a file URI, or embed a small HTTP server and play from a URI on localhost (such as http://127.0.0.1:4242/something). + </li> + <li>Android now supports modules or libraries that can be optionally linked into applications; a good example is the MapView, which has been moved into such a library. However, Android 1.0 will not support the ability for third-party developers to create such libraries for sharing with other applications. + </li> + <li>We believe that we have eliminated the problem with very long emulator startups on Windows, but had some trouble reproducing the issue. We are interested in feedback from developers, if this issue persists. + </li> +</ul> + + + + +<a name="m5-rc15"></a> + +<h2>Version m5-rc15</h2> + +<h3>Installation Notes</h3> + +<p>If you've already been developing using an m3 or earlier m5 version of the Android SDK, please see <a href="{@docRoot}intro/upgrading.html">Upgrading the SDK</a> for detailed instructions on how to make the transition to m5.</p> + +<p>If you're installing the Android SDK for the first time, please see the instructions on <a href="{@docRoot}intro/installing.html">Installing the SDK</a>.</p> + +<h3>New Features</h3> + +<p>m5-rc15 does not introduce any new features.</p> + +<h3>Resolved Issues</h3> + +<ul> + <li>1012640: Incorrect handling of BMP images.</li> +</ul> + +<h3>Known Issues</h3> + +<p>Unless otherwise noted, Known Issues from m5-rc14 also apply to m5-rc15.</p> + +<a name="m5-rc14"></a> + +<h2>Version m5-rc14</h2> + +<h3>Installation Notes</h3> + +<p>If you've already been developing using an m3 version of the Android SDK, please see <a href="{@docRoot}intro/upgrading.html">Upgrading the SDK</a> for detailed instructions on how to make the transition to m5-rc14.</p> + +<p>If you're installing the Android SDK for the first time, please see the instructions on <a href="{@docRoot}intro/installing.html">Installing the SDK</a>.</p> + +<h3>New Features</h3> + +<p>Changes to the Android APIs introduced in m5-rc14 are summarized in <a href="{@docRoot}migrating/m3-to-m5/m5-api-changes.html">this document</a>.</p> + +<p>In addition to changes in the Android APIs, m5-rc14 also introduces changes to the Android Developer Tools:</p> + +<h4>emulator</h4> +<ul> + <li>The Android emulator now support SD card images up to 128 GB in size. The previous limit was 2 GB.</li> +</ul> + +<h4>DDMS</h4> +<ul> + <li>Support for managing multiple devices has been integrated into DDMS. This should make it easier to debug applications that are run on multiple device scenarios.</li> +</ul> + +<h4>ADT</h4> +<ul> + <li>ADT now attempts to connect a debugger to any application that shows up + in the wait-for-debugger state, even if this application was not launched + from Eclipse. + <br /><br /> + The connection is actually established only if there exists a project + in the Eclipse workspace that contains an <code>AndroidManifest.xml</code> + declaring a package matching the name of the process. + To force this connection from your code, use <code>Debug.waitForDebugger()</code>. Activities declaring that they require their own process through the + "process" attribute with a value like ":someProcess" will be + recognized and a debugger will be connected accordingly. + This should make it easier to debug intent receivers, services, + providers, and other activities not launched from the standard app + launcher.<br /><br /></li> + <li>ADT has launch modes for device target selection. Automatic mode will: 1) launch an emulator if no device is present, 2) automatically target the device if only one is connected, and 3) prompt the user if 2 or more are connected. Manual mode will always prompt the user.<br /><br /></li> + <li>ADT also contains the same support for multiple devices that has been introduced into DDMS.</li> +</ul> + +<h4>AIDL</h4> +<ul> + <li>AIDL files that import and reuse types is now supported by activityCreator.py and ADT.</li> +</ul> + +<h4>traceview</h4> +<ul> + <li>The <a href="{@docRoot}reference/traceview.html">traceview</a> tool is now included in the SDK.</li> +</ul> + +<h3>Resolved Issues</h3> + +<p>The following Known Issues from m3-rc20 have been resolved:</p> +<ul> + <li>917572: The activityCreator created incorrect IntelliJ scripts</li> + <li>917465: Unanswered incoming calls placed from the emulator console will result in an unfinished call UI if you press the call back button</li> + <li>917247: dmtracedump and traceview tools are not available in the SDK</li> + <li>912168: Extremely rapid or prolonged scrolling in the Maps application or MapsView will result in application errors</li> + <li>905852: adb emits warnings about deprecated API use on Mac OS X 10.5</li> + <li>905242: The Run dialog sometimes failed to show the Android Launcher</li> + <li>901122: The focus ring in the browser is sometimes incorrect</li> + <li>896274: On Windows, the emulator sometimes starts off-screen</li> + <li>778432: Icons for newly installed applications do not display</li> +</ul> + +<h3>Known Issues</h3> + +<p>The following are known issues in m5-rc14:</p> + +<ul> + <li>1017312: The emulator window size has been reduced slightly, to allow it to be fully visible on smaller screens. This causes a slight clipping of the HVGA emulator skin but does not affect its function.</li> + <li>1021777: Setting a power requirement in a <code>Criteria</code> object passed to <code>{@link android.location.LocationManager#getBestProvider getBestProvider()}</code> will result in a value not being returned.</li> + <li>1025850: Emulator failing to launch from the Eclipse plugin due to wrong custom command line parameters do not report the error anywhere and silently fails.</li> +</ul> + +<p>Unless otherwise noted, Known Issues from m3-rc20a also apply to m5-rc14.</p> + +<a name="m3-rc37a"></a> + +<h2>Version m3-rc37a</h2> + +<p>Version m3-rc37a and ADT 0.3.3 were released on December 14, 2007.</p> + +<h3>Installation Notes</h3> + +<h4>ADT Plugin Upgrade Requires Re-Installation of Plugin</h4> + +<p>Because of changes in the ADT Plugin and other tools, you will need to uninstall your existing ADT Plugin and then re-install the new version (ADT 0.3.3). For complete information, see <a href="{@docRoot}intro/upgrading.html">Upgrading the SDK</a>. </p> + +<h3>New Features</h3> + +<h4>Android Debug Bridge (ADB)</h4> +<ul> +<li>Now supports multiple emulators on one host computer. Please note that you need to use the <code>-data</code> option when starting secondary emulators, to allow those instances to save their data across sessions. Also, DDMS does not yet support debugging on multiple emulators yet. </li> +</ul> + +<h4>ADT Plugin for Eclipse</h4> +<ul> +<li>Adds editor capabilities for working with Android manifest files, such as syntax highlighting and autocompletion. The editor capabilities require the Web Tools WST plugin for Eclipse, which is included in <a href="http://www.eclipse.org/downloads/moreinfo/compare.php">most Eclipse packages</a>. Not having WST does not prevent the ADT plugin from working. If necessary, you can download and install WST from the Web Tools Project <a href="http://download.eclipse.org/webtools/downloads">downloads page</a>. To update directly from an Eclipse installation, you can add a remote update site with this URL: http://download.eclipse.org/webtools/updates . Note that installing WST on Eclipse 3.4 will require installing other packages, as detailed on the WTP downloads page</a>. +</li> +<li>Now retries to launch the app on the emulator if it fails due to timing issues when the emulator is booting.</li> +<li>Adds support for loading custom skins from the <SDK>/lib/images/skins/ directory. The Skin dropdown in the Emulator tab is now built from the content of the skins/ directory in order to support developer-made skins.</li> +<li>Adds an Emulator control panel. This is a UI on top of the emulator console that allows you to change the state of the network and gsm connection, and to initiate incoming voice call. (This is also present in standalone DDMS.)</li> +<li>Adds support for referenced projects. Android projects will add to the apk package any code from referenced projects.</li> +<li>Eclipse console now warns if an .apk that is pushed to the device declares the same package as another already installed package.</li> +<li>Java classes generated by the Eclipse plugin are now marked as derived automatically, so that Team plugins do not consider them as regular source.</li> +</ul> + +<h4>Emulator Console</h4> +<ul> +<li>Now provides support for emulating inbound SMS messages. The ADT plugin and DDMS provide integrated access to this capability. For more information about how to emulate inbound SMS from the console, see <a href="{@docRoot}reference/emulator.html#sms">SMS Emulation</a>. </li> +</ul> + +<h4>Emulator</h4> +<ul><li>The default emulator skin has been changed to HVGA-P from QVGA-L. For information about emulator skins and how to load a specific skin when starting the emulator, see <a href="{@docRoot}reference/emulator.html#skins">Using Emulator Skins</a>.</li> +</ul> + +<h3>Resolved Issues</h3> + +<h4>907947</h4> +<p><code>adb -version</code> now returns a version number.</p> + +<h4>917462</h4> +<p>Audio on Windows is fixed and is no longer 'choppy'. </p> + +<h4>Removed Manifest File Locking on Mac OS X</h4> + +<p>ADT plugin now uses a custom java editor for R.java/Manifest.java, to make those files non-editable. This is to replace the current locking mechanism which causes issues on Mac OS (preventing projects from being deleted). Note that your project must recompile at least once for the lock to be removed from the files.</p> + +<h4>The following known issues noted in m3-rc20 are now fixed:</h4> +<p> +<ul> +<li>890937: Emulator does not support non-qwerty keyboards. +<li>894618: <code>adb shell</code> may fail to connect when used the first time. +<li>896274: On Windows, the emulator window may start off-screen. +<li>899949: The emulator may fail to start with <code>-useaudio</code> on some environments. +<li>912619: Emulator console listens on non-local ports 5554-5584. +<li>917399: On Windows, running multiple emulator consoles can result in unexpected behavior when simulating incoming telephone calls. +</ul> +</p> + +<h3>Known Issues</h3> + +<p>Unless otherwise noted, Known Issues from m3-rc22a also apply to m3-rc37a.</p> + + +<a name="m3-rc22a"></a> + +<h2>Version m3-rc22a</h2> + +<p>Version m3-rc22a and ADT 0.3.1 were released on November 16, 2007.</p> + +<h3>Resolved Issues</h3> + +<h4>920067</h4> +<p>The New Android Project wizard provided by ADT 0.3.1 now properly displays error messages when used with Eclipse 3.2 on Windows.</p> + +<h4>920045</h4> +<p>The <code>AndroidManifest.xml</code> files generated by ADT 0.3.1 now include the XML element required for displaying the associated app in the "Applications" menu. If you have applications created with ADT 0.3.0, simply ensure that your <code>AndroidManifest.xml</code> file contains the following highlighted line:</p> +<pre> +... + <intent-filter> + <action android:value="android.intent.action.MAIN" /> + <strong><category android:value="android.intent.category.LAUNCHER" /></strong> + </intent-filter> +... +</pre> + +<h4>920098</h4> +<p>ADT 0.3.1 is now compatible with Eclipse 3.4.</p> + +<h4>920282</h4> +<p>Fixes a NullPointerException that is thrown in certain situations with the DDMS perspective in Eclipse.</p> + +<h4>918637</h4> +<p>Address a keyboard lock-up issue when using <code>adb</code> on Mac OS X 10.4 and 10.5.</p> + +<h3>Known Issues</h3> + +<p>Unless otherwise noted, known issues from m3-rc20a also apply to m3-rc22a.</p> + +<a name="m3-rc20a"></a> + +<h2>Version m3-rc20a</h2> +<h3>Known Issues</h3> + +<p>The following are known issues in m3-rc20a:</p> + +<h4>778432 - <span style="font-weight: normal; font-size: 13px; font-style: italic">Resolved in <a href="#m5-rc14">m5</a></span></h4> +<p>In certain circumstances, icons for newly installed applications do not display as expected.</p> + +<h4>890937 - <span style="font-weight: normal; font-size: 13px; font-style: italic">Resolved in <a href="#m3-rc37a">m3-rc37a</a></span></h4> +<p>The emulator currently does not support non-QWERTY keyboards.</p> + +<h4>894618 - <span style="font-weight: normal; font-size: 13px; font-style: italic">Resolved in <a href="#m3-rc37a">m3-rc37a</a></span></h4> +<p>The adb shell command may fail to connect when used for the first time.</p> + +<h4>896274 - <span style="font-weight: normal; font-size: 13px; font-style: italic">Resolved in <a href="#m5-rc14">m5</a></span></h4> +<p>On Windows, the emulator screen will sometimes show up off-screen when it is started. The workaround for this is to right-click on the emulator taskbar entry, select Move, and move the window using keyboard arrow keys</p> + +<h4>899949 - <span style="font-weight: normal; font-size: 13px; font-style: italic">Resolved in <a href="#m3-rc37a">m3-rc37a</a></span></h4> +<p>The emulator may fail to start when using the <code>-useaudio</code> in some environments</p> + +<h4>901122 - <span style="font-weight: normal; font-size: 13px; font-style: italic">Resolved in <a href="#m5-rc14">m5</a></span></h4> +<p>The focus ring shown in the browser may sometimes not properly wrap links.</p> + +<h4>905242 - <span style="font-weight: normal; font-size: 13px; font-style: italic">Resolved in <a href="#m5-rc14">m5</a></span></h4> +<p>On Mac OS X 10.5, the Eclipse plugin's Run Dialog may sometimes fail to show the option to select the Android Launcher.</p> + +<h4>905852 - <span style="font-weight: normal; font-size: 13px; font-style: italic">Resolved in <a href="#m5-rc14">m5</a></span></h4> +<p>On Mac OS X 10.5, adb will emit warnings about deprecated API use when first used.</p> + +<h4>912168 - <span style="font-weight: normal; font-size: 13px; font-style: italic">Resolved in <a href="#m5-rc14">m5</a></span></h4> +<p>extremely rapid or prolonged scrolling in the Maps application or in a MapView will result in application errors.</p> + +<h4>912619 - <span style="font-weight: normal; font-size: 13px; font-style: italic">Resolved in <a href="#m3-rc37a">m3-rc37a</a></span></h4> +<p>The emulator console listens for connections on ports 5554-5587. Future versions will only accept connections from localhost. It is recommend that you use a firewall to block external connections to those ports on your development machine.</p> + +<h4>912849</h4> +<p>On Mac OS X 10.4, the emulator may hang if started in the background (i.e. <code>./emulator &</code>).</p> + +<h4>914692</h4> +<p>On Mac OS X 10.5, the emulator will emit warnings about deprecated API use when started from the command line.</p> + +<h4>917247 - <span style="font-weight: normal; font-size: 13px; font-style: italic">Resolved in <a href="#m5-rc14">m5</a></span></h4> +<p>The dmtracedump and traceview tools are not available in the SDK.</p> + +<h4>917399 - <span style="font-weight: normal; font-size: 13px; font-style: italic">Resolved in <a href="#m3-rc37a">m3-rc37a</a></span></h4> +<p>On Windows, running multiple emulator consoles can result in unexpected behavior when simulating incoming telephone calls.</p> + +<h4>917465 - <span style="font-weight: normal; font-size: 13px; font-style: italic">Resolved in <a href="#m5-rc14">m5</a></span></h4> +<p>Unanswered incoming calls placed from the emulator console, will result in an unfinished call UI if you press the call back button.</p> + +<h4>917572 - <span style="font-weight: normal; font-size: 13px; font-style: italic">Resolved in <a href="#m5-rc14">m5</a></span></h4> +<p>Using activityCreator with the <code>--ide intellij</code> option creates IntelliJ scripts with incorrect documentation location specified. To correct, change value for the <code><JAVADOC></code> element in the generated .ipr file from <code>file://.../docs/framework</code> to <code>file://.../docs/reference</code>.</p> + +<h4>917579</h4> +<p>On Ubuntu 7.10 (Gusty), the Eclipse package installed by the <code>apt-get install eclipse</code> command uses java-gcj by default. This configuration is not compatible with the Android Eclipse plugin (ADT) and will result in "Class not found" errors whenever you access an ADT feature.</p> + <p>The resolution for this issue is to install a Sun JDK</p> + <pre>sudo update-java-alternatives --jre java-1.5.0-sun</pre> + <p>and then configure Eclipse to use it by exporting the following environment variable:</p> + <pre>export JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun</pre> + <p>or by adding following to your <code>.eclipse/eclipserc file</code>:</p> + <pre>JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun</pre> diff --git a/docs/html/sdk/1.0_r1/download.jd b/docs/html/sdk/1.0_r1/download.jd new file mode 100644 index 0000000..c767271 --- /dev/null +++ b/docs/html/sdk/1.0_r1/download.jd @@ -0,0 +1,26 @@ +page.title=Download the Android SDK +@jd:body + +<p>Please review the Android SDK License Agreement carefully before +downloading the SDK. The License Agreement constitutes a contract between you +and Google with respect to your use of the SDK.</p> +<iframe src="terms_body.html" style="border: 1px solid black; height:400px; width: 100%; margin: 1em 0;"></iframe> +<script language="JavaScript"> +function verify() { + document.getElementById('agreeButton').disabled = !document.getElementById('agreeCheckbox').checked; +} +</script> +<input id="agreeCheckbox" type="checkbox" onclick="verify();"/>I agree to the terms of the SDK License +<br/><br/> +<script language="JavaScript"> +function submit() { + var agreeCheckbox = document.getElementById('agreeCheckbox'); + if (agreeCheckbox.checked) { + document.location = "download_list.html"; + } +} +</script> +<input id='agreeButton' value="Continue" type="button" onclick="submit();"/> +<script language="JavaScript"> +document.getElementById('agreeButton').disabled = true; +</script> diff --git a/docs/html/sdk/1.0_r1/download_list.jd b/docs/html/sdk/1.0_r1/download_list.jd new file mode 100644 index 0000000..6278936 --- /dev/null +++ b/docs/html/sdk/1.0_r1/download_list.jd @@ -0,0 +1,49 @@ +page.title=Download the Android SDK +@jd:body + +<p>Before downloading, please read the <a href="terms.html">Terms</a> that govern your use of the Android SDK.</p> + <p class="note"><strong>Please note:</strong> The Android SDK is under <b>active development</b>. Please keep this in mind as + you explore its capabilities. If you discover any issues, we + welcome you to notify us of them via our + <a href="http://code.google.com/p/android/issues/list">Issue Tracker</a>.</p> + +<p><a href="download_previous.html">Download previous versions</a></p> + + <h2>Android 1.0 SDK, Release 1</h2> + <p><em>September 23, 2008 - <a href="RELEASENOTES.html">Release Notes</a></em></p> + + <p class="note"><b>Note:</b> If upgrading from a previous release, + please read the <a href="intro/upgrading.html">upgrade instructions</a> and + <a href="migrating/0.9-1.0/changes-overview.html">API changes overview</a>.<br/> + For a more detailed list of changes, refer to + the <a href="migrating/0.9-1.0/changes.html">API differences report</a>.</p> + +<table> +<tr> + <th>Windows</th> + <th>Mac OS X</th> + <th>Linux</th> +</tr> +<tr> + <td>SHINY DOWNLOAD BUTTON <br/>94040470 bytes <br/>MD5 checksum:<br/>d69f4ee93d4010f726c04302662fd999</td> + <td>SHINY DOWNLOAD BUTTON <br/>91733388 bytes <br/>MD5 checksum:<br/>564876ada22872e50c2866806de9fc5c</td> + <td>SHINY DOWNLOAD BUTTON <br/>92107223 bytes <br/>MD5 checksum:<br/>2660b4029039b7d714e59827e9a9a11d</td> +</tr> +</table> + + <p>For more information on the SDK:</p> + <ul> + <li><a href="intro/installing.html#developmentrequirements">System and Software Requirements</a></li> + <li><a href="intro/installing.html">Guide to Installing the SDK</a></li> + </ul> + +<h2>Using Eclipse? Install the plugin</h2> +<p>Android provides an Eclipse plugin to help make programming and debugging + easier.</p> +<div class="linkbox"><a href="intro/installing.html#installingplugin">Install the Eclipse plugin</a></div> + + +<h2>Open Source</h2> +<p> + Mirrors of open source software used to build the Android SDK are available via the <a href="http://code.google.com/p/android/downloads/list">Android project page</a> hosted on Google Code. +</p> diff --git a/docs/html/sdk/1.0_r1/download_previous.jd b/docs/html/sdk/1.0_r1/download_previous.jd new file mode 100644 index 0000000..3469746 --- /dev/null +++ b/docs/html/sdk/1.0_r1/download_previous.jd @@ -0,0 +1,188 @@ +page.title=Download the Android SDK - Full Version History +@jd:body + +<p>Before downloading, please read the <a href="terms.html">Terms</a> that govern your use of the Android SDK.</p> + +<p><a href="download_list.html">Download the latest version</a></p> + + <h2>Android 0.9 SDK beta</h2> + <p><em>August 18, 2008 - <a href="RELEASENOTES#0.9_beta.html">Release Notes</a></em></p> + <table> + <tr> + <th>Platform</th> + <th>Package</th> + <th>Size</th> + <th>MD5 Checksum</th> + </tr> + + <tr> + <td>Windows</td> + <td><a href="http://dl.google.com/android/android-sdk-windows-0.9_beta.zip">android-sdk-windows-0.9_beta.zip</a></td> + <td>93,126,573 bytes</td> + <td>305031ad8335d1b6040bdd5a65349d6d</td> + </tr> + <tr class="alt"> + + <td>Mac OS X (intel)</td> + <td><a href="http://dl.google.com/android/android-sdk-mac_x86-0.9_beta.zip">android-sdk-mac_x86-0.9_beta.zip</a></td> + <td>91,374,464 bytes</td> + <td>9a6969159091cede46302e11049fe3ca</td> + </tr> + <tr> + <td>Linux (i386)</td> + + <td><a href="http://dl.google.com/android/android-sdk-linux_x86-0.9_beta.zip">android-sdk-linux_x86-0.9_beta.zip</a></td> + <td>91,821,068 bytes</td> + <td>077e5ef549dd9c5be54bd88e6a8e196c</td> + </tr> + </table> + +<h2>Version m5-rc15</h2> + <p><em>March 3, 2008 - <a href="RELEASENOTES.html#m5-rc15">Release Notes</a></em></p> + <table> + <tr> + <th>Platform</th> + <th>Package</th> + <th>Size</th> + <th>MD5 Checksum</th> + </tr> + <tr> + <td>Windows</td> + <td><a href="http://dl.google.com/android/android-sdk_m5-rc15_windows.zip">android-sdk_m5-rc15_windows.zip</a></td> + <td>79 MB</td> + <td>ecce40bc50201886d95ba2690cdbc5ce</td> + </tr> + <tr class="alt"> + <td>Mac OS X (intel)</td> + <td><a href="http://dl.google.com/android/android-sdk_m5-rc15_mac-x86.zip">android-sdk_m5-rc15_mac-x86.zip</a></td> + <td>76 MB</td> + <td>45a6385bbc1b2cb295409cfc81fb04b4</td> + </tr> + <tr> + <td>Linux (i386)</td> + <td><a href="http://dl.google.com/android/android-sdk_m5-rc15_linux-x86.zip">android-sdk_m5-rc15_linux-x86.zip</a></td> + <td>76 MB</td> + <td>e913f785afecdeed34c30639fd8c5862</td> + </tr> + </table> + + + <h2>Version m5-rc14</h2> + <p><em>February 12, 2008 - <a href="RELEASENOTES.html#m5-rc14">Release Notes</a></em></p> + <table> + <tr> + <th>Platform</th> + <th>Package</th> + <th>Size</th> + <th>MD5 Checksum</th> + </tr> + <tr> + <td>Windows</td> + <td><a href="http://dl.google.com/android/android-sdk_m5-rc14_windows.zip">android-sdk_m5-rc14_windows.zip</a></td> + <td>79 MB</td> + <td>ecc75c1e69588350634ca25867ce05a0</td> + </tr> + <tr class="alt"> + <td>Mac OS X (intel)</td> + <td><a href="http://dl.google.com/android/android-sdk_m5-rc14_mac-x86.zip">android-sdk_m5-rc14_mac-x86.zip</a></td> + <td>76 MB</td> + <td>844c80d0adb1a326f5a9fff262c61efc</td> + </tr> + <tr> + <td>Linux (i386)</td> + <td><a href="http://dl.google.com/android/android-sdk_m5-rc14_linux-x86.zip">android-sdk_m5-rc14_linux-x86.zip</a></td> + <td>76 MB</td> + <td>f8b863c8a880afe9bb84124f5976aab1</td> + </tr> + </table> + + + <h2>Version m3-rc37a</h2> + <p><em>December 14, 2007 - <a href="RELEASENOTES.html#m3-rc37a">Release Notes</a></em></p> + <table> + <tr> + <th>Platform</th> + <th>Package</th> + <th>Size</th> + <th>MD5 Checksum</th> + </tr> + <tr> + <td>Windows</td> + <td><a href="http://dl.google.com/android/android_sdk_windows_m3-rc37a.zip">android_sdk_windows_m3-rc37a.zip</a></td> + <td>58 MB</td> + <td>5db5aea20a2c2f010baefc4b1091a575</td> + </tr> + <tr class="alt"> + <td>Mac OS X (intel)</td> + <td><a href="http://dl.google.com/android/android_sdk_darwin_m3-rc37a.zip">android_sdk_darwin_m3-rc37a.zip</a></td> + <td>54 MB</td> + <td>0b22e73fbd07b4af4009387afce3a37f</td> + </tr> + <tr> + <td>Linux (i386)</td> + <td><a href="http://dl.google.com/android/android_sdk_linux_m3-rc37a.zip">android_sdk_linux_m3-rc37a.zip</a></td> + <td>54 MB</td> + <td>41285beecc4f9926e6ecf5f12610b356</td> + </tr> + </table> + + + <h2>Version m3-rc22a</h2> + <p><em>November 16, 2007 - <a href="RELEASENOTES.html#m3-rc22a">Release Notes</a></em></p> + <table> + <tr> + <th>Platform</th> + <th>Package</th> + <th>Size</th> + <th>MD5 Checksum</th> + </tr> + <tr> + <td>Windows</td> + <td><a href="http://dl.google.com/android/android_sdk_windows_m3-rc22a.zip">android_sdk_windows_m3-rc22a.zip</a></td> + <td>59 MB</td> + <td>aa3dee05a9872752a3bc4efd0f93e98b</td> + </tr> + <tr class="alt"> + <td>Mac OS X (intel)</td> + <td><a href="http://dl.google.com/android/android_sdk_darwin_m3-rc22a.zip">android_sdk_darwin_m3-rc22a.zip</a></td> + <td>55 MB</td> + <td>0547f45614ad94c3af22c3c0aa6f709f</td> + </tr> + <tr> + <td>Linux (i386)</td> + <td><a href="http://dl.google.com/android/android_sdk_linux_m3-rc22a.zip">android_sdk_linux_m3-rc22a.zip</a></td> + <td>55 MB</td> + <td>84b3455de5cdfd841a172c13d24c382e</td> + </tr> + </table> + + + <h2>Version m3-rc20a</h2> + <p><em>November 12, 2007 - <a href="RELEASENOTES.html#m3-rc20a">Release Notes</a></em></p> + <table> + <tr> + <th>Platform</th> + <th>Package</th> + <th>Size</th> + <th>MD5 Checksum</th> + </tr> + <tr> + <td>Windows</td> + <td><a href="http://dl.google.com/android/android_sdk_windows_m3-rc20a.zip">android_sdk_windows_m3-rc20a.zip</a></td> + <td>59 MB</td> + <td>a404b875708df7339ba77bdf2e08dc06</td> + </tr> + <tr class="alt"> + <td>Mac OS X (intel)</td> + <td><a href="http://dl.google.com/android/android_sdk_darwin_m3-rc20a.zip">android_sdk_darwin_m3-rc20a.zip</a></td> + <td>55 MB</td> + <td>8fc29aeaa45eda84bfac854ebd02a6da</td> + </tr> + <tr> + <td>Linux (i386)</td> + <td><a href="http://dl.google.com/android/android_sdk_linux_m3-rc20a.zip">android_sdk_linux_m3-rc20a.zip</a></td> + <td>55 MB</td> + <td>9196759df9b69cd89a220b156f133364</td> + </tr> + </table> + diff --git a/docs/html/sdk/1.0_r1/index.jd b/docs/html/sdk/1.0_r1/index.jd new file mode 100644 index 0000000..7ad4e88 --- /dev/null +++ b/docs/html/sdk/1.0_r1/index.jd @@ -0,0 +1,18 @@ +page.title=Download 1.0r1 + +sdk.version=Android 1.0 SDK, release 1 +sdk.date=September 23, 2008 + +sdk.win_download=android-sdk-windows-1.0_r1.zip +sdk.win_bytes=89.7 MB +sdk.win_checksum=d69f4ee93d4010f726c04302662fd999 + +sdk.mac_download=android-sdk-mac_x86-1.0_r1.zip +sdk.mac_bytes=87.5 MB +sdk.mac_checksum=564876ada22872e50c2866806de9fc5c + +sdk.linux_download=android-sdk-linux_x86-1.0_r1.zip +sdk.linux_bytes=87.8 MB +sdk.linux_checksum=2660b4029039b7d714e59827e9a9a11d + +@jd:body diff --git a/docs/html/sdk/1.0_r1/installing.jd b/docs/html/sdk/1.0_r1/installing.jd new file mode 100644 index 0000000..7eb5d2b --- /dev/null +++ b/docs/html/sdk/1.0_r1/installing.jd @@ -0,0 +1,297 @@ +page.title=Installing the SDK +@jd:body + + +<p>This page describes how to install the Android SDK and set up your development environment. If you haven't +downloaded the SDK yet, you can use the link below to get started. Then read the rest of this document to learn +how to install, configure, and use the SDK to create Android applications.</p> + +<div class="linkbox"><a href="http://code.google.com/android/download.html">Download the SDK</a></div> + +<h4 style="margin-top">Upgrading?</h4> + +<p>If you have already developed applications using an earlier version of the +SDK, please skip this page and read the +<b><a href="{@docRoot}intro/upgrading.html">Upgrading the SDK</a></b> document. +</p> + + +<h2 id="developmentrequirements">System and Software Requirements</h2> + +<p>To develop Android applications using the code and tools in the Android SDK, +you need a suitable development computer and development environment, as described below.</p> + +<p><strong>Supported Operating Systems:</strong></p> +<ul> + <li>Windows XP or Vista</li> + <li>Mac OS X 10.4.8 or later (x86 only)</li> + <li>Linux (tested on Linux Ubuntu Dapper Drake)</li> +</ul> + +<p><strong>Supported Development Environments:</strong></p> +<ul> + <li>Eclipse IDE + <ul> + <li><a href="http://www.eclipse.org/downloads/">Eclipse</a> 3.3 (Europa), 3.4 (Ganymede) + <ul> + <li>Eclipse <a href="http://www.eclipse.org/jdt">JDT</a> plugin (included in most Eclipse IDE packages) </li> + <li><a href="http://www.eclipse.org/webtools">WST</a> (optional, but needed for the Android Editors feature; included in <a href="http://www.eclipse.org/downloads/moreinfo/compare.php">most Eclipse IDE packages</a>)</li> + </ul> + </li> + <li><a href="http://java.sun.com/javase/downloads/index.jsp">JDK 5 or JDK 6</a> (JRE alone is not sufficient)</li> + <li><a href="installing.html#installingplugin">Android Development Tools plugin</a> (optional)</li> + <li><strong>Not</strong> compatible with Gnu Compiler for Java (gcj)</li> + </ul> + </li> + <li>Other development environments or IDEs + <ul> + <li><a href="http://java.sun.com/javase/downloads/index.jsp">JDK 5 or JDK 6</a> (JRE alone is not sufficient)</li> + <li><a href="http://ant.apache.org/">Apache Ant</a> 1.6.5 or later for Linux and Mac, 1.7 or later for Windows</li> + <li><strong>Not</strong> compatible with Gnu Compiler for Java (gcj)</li> + </ul> + </li> +</ul> + +<p class="note"><strong>Note:</strong> If JDK is already installed on your development computer, please take a moment to make sure that it meets the version requirements listed above. In +particular, note that some Linux distributions may include JDK 1.4 or Gnu Compiler for Java, both of which are not supported for Android development. </p> + +<a name="installingsdk"></a> +<a name="setup"></a> + +<h2>Installing the SDK</h2> + + <p>After downloading the SDK, unpack the .zip archive to a suitable location on your machine. By default, the SDK files are unpacked into a directory named <code>android_sdk_<em><platform</em>>_<em><release></em>_<em><build></em></code>. The directory contains the subdirectories <code>tools/</code>, <code>samples/</code>, and others. </p> + + <p>Make a note of the name and location of the unpacked SDK directory on your system — you will need to refer to the SDK directory later, when setting up the Android plugin or using SDK tools. </p> + + <p>Optionally, you can add the path to the SDK <code>tools</code> directory to your path. As mentioned above, the <code>tools/</code> directory is located in the SDK directory. </p> + <ul> + <li>On Linux, edit your ~/.bash_profile or ~/.bashrc file. Look + for a line that sets the PATH environment variable and add the + full path to the <code>tools/</code> directory to it. If you don't + see a line setting the path, you can add one:</li> + + <ul><code>export PATH=${PATH}:<em><your_sdk_dir></em>/tools</code></ul> + + <li>On a Mac, look in your home directory for .bash_profile and + proceed as for Linux. You can create the .bash_profile, if + you haven't already set one up on your machine. </li> + + <li>On Windows, right click on My Computer, and select Properties. + Under the Advanced tab, hit the Environment Variables button, and in the + dialog that comes up, double-click on Path under System Variables. Add the full path to the <code>tools/</code> directory to the path. </li> + </ul> + + <p>Adding <code>tools</code> to your path lets you run Android Debug Bridge (adb) and the other command line <a href="{@docRoot}intro/tools.html">tools</a> without needing to supply the full path to the tools directory. Note that, if you update your SDK, you should remember to update your PATH settings to point to the new location, if different.</p> + + +<a name="installingplugin"></a> + +<h2>Installing the Eclipse Plugin (ADT)</h2> + +<p>If you will be using the Eclipse IDE as your environment for developing Android applications, you can install a custom plugin called Android Development Tools (ADT), which adds integrated support for Android projects and tools. The ADT plugin includes a variety of powerful extensions that make creating, running, and debugging Android applications faster and easier.</p> + +<p>If you <em>will not</em> be using the Eclipse IDE, you do not need to download or install the ADT plugin.</p> + +<p>To download and install the ADT plugin, follow the steps below for your respective Eclipse version. </p> + +<table style="font-size:100%"> +<tr><th>Eclipse 3.3 (Europa)</th><th>Eclipse 3.4 (Ganymede)</th></tr> +<tr> +<td width="50%"> +<ol> + <li>Start Eclipse, then select <strong>Help</strong> > <strong>Software Updates</strong> > <strong>Find + and Install...</strong>. </li> + + <li>In the dialog that appears, select <strong>Search for new features to install</strong> and click <strong>Next</strong>. </li> + <li>Click <strong>New Remote Site</strong>. </li> + <li>In the resulting dialog box, enter a name for the remote site (e.g. Android Plugin) and enter this as its URL: + <pre>https://dl-ssl.google.com/android/eclipse/</pre> + + Click <strong>OK</strong>. </li> + <li>You should now see the new site added to the search list (and checked). + Click <strong>Finish</strong>. </li> + <li>In the subsequent Search Results dialog box, select the checkbox for + <strong>Android Plugin</strong> > <strong>Developer Tools</strong>. + This will check both features: "Android Developer Tools", and "Android + Editors". The Android Editors feature is optional, but recommended. If + you choose to install it, you need the WST plugin mentioned earlier in this + page.<br/> + Click <strong>Next</strong>. </li> + <li>Read the license agreement and then select <strong>Accept terms of the license agreement</strong>. + Click <strong>Next</strong>. </li> + <li>Click <strong>Finish</strong>. </li> + + <li>The ADT plugin is not signed; you can accept the installation anyway + by clicking <strong>Install All</strong>. </li> + <li>Restart Eclipse. </li> +</ol> + +</td> +<td> + +<ol> + <li>Start Eclipse, then select <strong>Help</strong> > <strong>Software Updates...</strong>. + </li> + <li>In the dialog that appears, click the <strong>Available Software</strong> tab. + </li> + <li>Click <strong>Add Site...</strong> + </li> + <li>Enter this as the Location: + <pre>https://dl-ssl.google.com/android/eclipse/</pre> + Click <strong>OK</strong>. </li> + <li>Back in the Available Software view, you should see the plugin. Select the checkbox next to + <em>Developer Tools</em> and click <strong>Install...</strong> + </li> + <li>On the subsequent Install window, "Android Developer Tools", and "Android Editors" should both be checked. + The Android Editors feature is optional, but recommended. If + you choose to install it, you need the WST plugin mentioned earlier in this + page.<br/> + Click <strong>Finish</strong>. + </li> + <li>Restart Eclipse. </li> +</ol> + +</td> +</tr> +</table> + +<p>After restart, <strong>update your Eclipse preferences</strong> to point to the SDK directory:</p> +<ol> + <li>Select <strong>Window</strong> > <strong>Preferences...</strong> to open the Preferences + panel. (Mac OS X: <strong>Eclipse</strong> > <strong>Preferences</strong>) </li> + <li>Select <strong>Android</strong> from the left panel. </li> + <li>For the SDK Location in the main panel, click <strong>Browse...</strong> and locate the SDK directory. </li> + <li>Click <strong>Apply</strong>, then <strong>OK</strong>.</li> +</ol> + +<h3>Troubleshooting ADT Installation</h3> +<p> +If you are having trouble downloading the ADT plugin after following the steps above, here are some suggestions: </p> + +<ul> + <li>In Step 4, try changing the remote update site URL to use <code>http</code>, rather than <code>https</code>. </li> + <li>If you are behind a firewall (such as a corporate firewall), make + sure that you have properly configured your proxy settings in Eclipse. + In Eclipse 3.3/3.4, you can configure proxy information from the main + Eclipse menu in <strong>Window</strong> (on Mac, <strong>Eclipse</strong>) > <strong>Preferences</strong> > <strong>General</strong> > <strong>Network Connections</strong>.</li> +</ul> +<p> +If you are still unable to use Eclipse to download the ADT plugin, follow these steps to download and install the plugin from your computer: +</p> +<ol> +<li><a href="{@docRoot}adt_download.html">Download the ADT zip file</a> (do not unpack it). +<li>Follow steps 1 and 2 in the default install instructions (above). +<li>In Eclipse 3.3, click <strong>New Archive Site...</strong>. <br/> + In Eclipse 3.4, click <strong>Add Site...</strong>, then <strong>Archive...</strong> +<li>Browse and select the downloaded the zip file. +<li>Follow the remaining procedures, above, starting from steps 5. +</ol> +<p> +Note that to update your plugin, you will have to follow these steps again instead of the default update instructions.</p> + + +<p>Note that the "Android Editors" feature of ADT requires several optional +Eclipse components (for example, WST). If you encounter an error when +installing ADT, your Eclipse installion might not include those components. +For information about how to quickly add the necessary components to your +Eclipse installation, see the troubleshooting topic +<a href="{@docRoot}kb/troubleshooting.html#installeclipsecomponents">ADT Installation Error: "requires plug-in org.eclipse.wst.sse.ui"</a>.</p> + +<a name="Updating_the_ADT_plugin" id="Updating_the_ADT_plugin"></a> + +<h3>Updating the ADT Plugin </h3> + +<p>In some cases, a new ADT plugin may become available for your existing version of the SDK. You can use the steps below to update +the ADT plugin from inside Eclipse. </p> + +<table style="font-size:100%"> +<tr><th>Eclipse 3.3 (Europa)</th><th>Eclipse 3.4 (Ganymede)</th></tr> +<tr> +<td width="50%"> +<ol> + <li> Select <strong>Help</strong> > <strong>Software Updates</strong> > <strong>Find and Install...</strong>. </li> + <li> Select <strong>Search for updates of the currently installed features</strong> and click <strong>Finish</strong>. </li> + <li> If an update for ADT is available, select and install. </li> +</ol> + +<p> Alternatively, </p> +<ol> + <li> Select <strong>Help</strong> > <strong>Software Updates</strong> > <strong>Manage Configuration</strong>. </li> + <li> Navigate down the tree and select <strong>Android Development Tools <version></strong> </li> + <li> Select <strong>Scan for Updates</strong> under <strong>Available Tasks</strong>.</li> +</ol> +</td> +<td> +<ol> + <li>Select <strong>Help</strong> > <strong>Software Updates...</strong></li> + <li>Select the <strong>Installed Software</strong> tab.</li> + <li>Click <strong>Update...</strong></li> + <li>If an update for ADT is available, select it and click <strong>Finish</strong>.</li> +</ol> +</td> +</tr> +</table> + +<a name="installnotes"></a> + +<h2>Installation Notes</h2> +<h4>Ubuntu Linux Notes</h4> +<ul> + <li>If you need help installing and configuring Java on your +development machine, you might find these resources helpful: + <ul> + <li><a href="https://help.ubuntu.com/community/Java">https://help.ubuntu.com/community/Java </a></li> + <li><a href="https://help.ubuntu.com/community/Java">https://help.ubuntu.com/community/JavaInstallation </a></li> + </ul> + </li> +<li>Here are the steps to install Java and Eclipse, prior to installing +the Android SDK and ADT Plugin. +<ol> + <li>If you are running a 64-bit distribution on your development +machine, you need to install the <code>ia32-libs</code> package using +<code>apt-get:</code>: + <pre>apt-get install ia32-libs</pre></li> + <li>Next, install Java: + <pre>apt-get install sun-java6-bin</pre></li> + <li>The Ubuntu package manager does not currently offer an Eclipse 3.3 + version for download, so we recommend that you download Eclipse from +eclipse.org (<a +href="http://www.eclipse.org/downloads/">http://www.eclipse.org/ +downloads/</a>). A Java or RCP version of Eclipse is recommended.</li> +<li>Follow the steps given in previous sections to install the SDK +and the ADT plugin. </li> +</ol> +</ul> +<h4>Other Linux Notes</h4> +<ul> + <li>If you encounter this error when installing the ADT Plugin for +Eclipse: + <pre>An error occurred during provisioning. +Cannot connect to keystore. +JKS</pre> + your development machine lacks a suitable Java VM. Installing Sun +Java 6 will resolve this issue and you can then reinstall the ADT +Plugin.</li> + <li>If JDK is already installed on your development computer, please +take a moment to make sure that it meets the version requirements listed +at the top of this page. In particular, note that some Linux +distributions may include JDK 1.4 or Gnu Compiler for Java, both of +which are not supported for Android development.</li> +</ul> + +<a name="developingwitheclipse"></a> +<a name="existingcode"></a> +<a name="creatingaproject" id="creatingaproject"></a> +<a name="launchconfig" id="launchconfig"></a> +<a name="installingrunningdebugging" id="installingrunningdebugging"></a> +<a name="otherides" id="otherides"></a> +<a name="buildingwithant"></a> +<a name="debugging" id="debugging"></a> +<a name="additionaldebugging" id="additionaldebugging"></a> +<a name="toptips" id="toptips"></a> +<a name="debughelpers"></a> +<a name="uninstalling" id="uninstalling"></a> +<a name="tips" id="tips"></a> +<a name="eclipse" id="eclipse"></a> +<a name="building"></a> diff --git a/docs/html/sdk/1.0_r1/sdk_toc.cs b/docs/html/sdk/1.0_r1/sdk_toc.cs new file mode 100644 index 0000000..057e037 --- /dev/null +++ b/docs/html/sdk/1.0_r1/sdk_toc.cs @@ -0,0 +1 @@ +<ul>
<li><strong><a href="index.html">SDK 1.0</a></strong></li>
<ul>
<li><a href="installing.html">Installing</a></li>
<li><a href="upgrading.html">Upgrading</a></li>
<li><a href="terms.html">License Agreement</a></li>
<li><a href="RELEASENOTES.html">Release Notes</a></li>
</ul>
</li>
</ul>
FIXME
\ No newline at end of file diff --git a/docs/html/sdk/1.0_r1/terms.jd b/docs/html/sdk/1.0_r1/terms.jd new file mode 100644 index 0000000..5c6e6fc --- /dev/null +++ b/docs/html/sdk/1.0_r1/terms.jd @@ -0,0 +1,7 @@ +page.title=Terms and Conditions +@jd:body + +<?cs include:"terms_body.html" ?> + + + diff --git a/docs/html/sdk/1.0_r1/terms_body.html b/docs/html/sdk/1.0_r1/terms_body.html new file mode 100644 index 0000000..403593a --- /dev/null +++ b/docs/html/sdk/1.0_r1/terms_body.html @@ -0,0 +1,216 @@ +<h1> + Android Software Development Kit License Agreement +</h1> +<h2> + 1. Introduction +</h2> +<p> + 1.1 The Android Software Development Kit (referred to in this License Agreement as the "SDK" and specifically including the Android system files and packaged APIs) is licensed to you subject to the terms of this License Agreement. This License Agreement forms a legally binding contract between you and Google in relation to your use of the SDK. +</p> +<p> + 1.2 "Google" means Google Inc., a Delaware corporation with principal place of business at 1600 Amphitheatre Parkway, Mountain View, CA 94043, United States. +</p> +<h2> + 2. Accepting this License Agreement +</h2> +<p> + 2.1 In order to use the SDK, you must first agree to this License Agreement. You may not use the SDK if you do not accept this License Agreement. +</p> +<p> + 2.2 You can accept this License Agreement by: +</p> +<p> + (A) clicking to accept or agree to this License Agreement, where this option is made available to you; or +</p> +<p> + (B) by actually using the SDK. In this case, you agree that use of the SDK constitutes acceptance of the Licensing Agreement from that point onwards. +</p> +<p> + 2.3 You may not use the SDK and may not accept the Licensing Agreement if you are a person barred from receiving the SDK under the laws of the United States or other countries including the country in which you are resident or from which you use the SDK. +</p> +<p> + 2.4 If you are agreeing to be bound by this License Agreement on behalf of your employer or other entity, you represent and warrant that you have full legal authority to bind your employer or such entity to this License Agreement. If you do not have the requisite authority, you may not accept the Licensing Agreement or use the SDK on behalf of your employer or other entity. +</p> +<h2> + 3. SDK License from Google +</h2> +<p> + 3.1 Subject to the terms of this License Agreement, Google grants you a limited, worldwide, royalty-free, non- assignable and non-exclusive license to use the SDK solely to develop applications to run on the Android platform. +</p> +<p> + 3.2 You agree that Google or third parties own all legal right, title and interest in and to the SDK, including any Intellectual Property Rights that subsist in the SDK. "Intellectual Property Rights" means any and all rights under patent law, copyright law, trade secret law, trademark law, and any and all other proprietary rights. The Android Open Source Project +</p> +<p> + 3.3 Except to the extent required by applicable third party licenses, you may not copy (except for backup purposes), modify, adapt, redistribute, decompile, reverse engineer, disassemble, or create derivative works of the SDK or any part of the SDK. Except to the extent required by applicable third party licenses, you may not load any part of the SDK onto a mobile handset or any other hardware device except a personal computer, combine any part of the SDK with other software, or distribute any software or device incorporating a part of the SDK. +</p> +<p> + 3.4 Use, reproduction and distribution of components of the SDK licensed under an open source software license are governed solely by the terms of that open source software license and not this License Agreement. +</p> +<p> + 3.5 You agree that the form and nature of the SDK that Google provides may change without prior notice to you and that future versions of the SDK may be incompatible with applications developed on previous versions of the SDK. You agree that Google may stop (permanently or temporarily) providing the SDK (or any features within the SDK) to you or to users generally at Google's sole discretion, without prior notice to you. +</p> +<p> + 3.6 Nothing in this License Agreement gives you a right to use any of Google's trade names, trademarks, service marks, logos, domain names, or other distinctive brand features. +</p> +<p> + 3.7 You agree that you will not remove, obscure, or alter any proprietary rights notices (including copyright and trademark notices) that may be affixed to or contained within the SDK. +</p> +<h2> + 4. Use of the SDK by You +</h2> +<p> + 4.1 Google agrees that it obtains no right, title or interest from you (or your licensors) under this License Agreement in or to any software applications that you develop using the SDK, including any intellectual property rights which subsist in those applications. +</p> +<p> + 4.2 You agree to use the SDK and write applications only for purposes that are permitted by (a) this License Agreement and (b) any applicable law, regulation or generally accepted practices or guidelines in the relevant jurisdictions (including any laws regarding the export of data or software to and from the United States or other relevant countries). +</p> +<p> + 4.3 You agree that if you use the SDK to develop applications for general public users, you will protect the privacy and legal rights of those users. If the users provide you with user names, passwords, or other login information or personal information, your must make the users aware that the information will be available to your application, and you must provide legally adequate privacy notice and protection for those users. If your application stores personal or sensitive information provided by users, it must do so securely. If the user provides your application with Google Account information, your application may only use that information to access the user's Google Account when, and for the limited purposes for which, the user has given you permission to do so. +</p> +<p> + 4.4 You agree that you will not engage in any activity with the SDK, including the development or distribution of an application, that interferes with, disrupts, damages, or accesses in an unauthorized manner the servers, networks, or other properties or services of any third party including, but not limited to, Google or any mobile communications carrier. +</p> +<p> + 4.5 You agree that you are solely responsible for (and that Google has no responsibility to you or to any third party for) any data, content, or resources that you create, transmit or display through the Android platform and/or applications for the Android platform, and for the consequences of your actions (including any loss or damage which Google may suffer) by doing so. +</p> +<p> + 4.6 You agree that you are solely responsible for (and that Google has no responsibility to you or to any third party for) any breach of your obligations under this License Agreement, any applicable third party contract or Terms of Service, or any applicable law or regulation, and for the consequences (including any loss or damage which Google or any third party may suffer) of any such breach. +</p> +<h2> + 5. Your Developer Credentials +</h2> +<p> + 5.1 You agree that you are responsible for maintaining the confidentiality of any developer credentials that may be issued to you by Google or which you may choose yourself and that you will be solely responsible for all applications that are developed under your developer credentials. +</p> +<h2> + 6. Privacy and Information +</h2> +<p> + 6.1 In order to continually innovate and improve the SDK, Google may collect certain usage statistics from the software including but not limited to a unique identifier, associated IP address, version number of the software, and information on which tools and/or services in the SDK are being used and how they are being used. Before any of this information is collected, the SDK will notify you and seek your consent. If you withhold consent, the information will not be collected. +</p> +<p> + 6.2 The data collected is examined in the aggregate to improve the SDK and is maintained in accordance with Google's Privacy Policy. +</p> +<h2> + 7. Third Party Applications for the Android Platform +</h2> +<p> + 7.1 If you use the SDK to run applications developed by a third party or that access data, content or resources provided by a third party, you agree that Google is not responsible for those applications, data, content, or resources. You understand that all data, content or resources which you may access through such third party applications are the sole responsibility of the person from which they originated and that Google is not liable for any loss or damage that you may experience as a result of the use or access of any of those third party applications, data, content, or resources. +</p> +<p> + 7.2 You should be aware the data, content, and resources presented to you through such a third party application may be protected by intellectual property rights which are owned by the providers (or by other persons or companies on their behalf). You may not modify, rent, lease, loan, sell, distribute or create derivative works based on these data, content, or resources (either in whole or in part) unless you have been specifically given permission to do so by the relevant owners. +</p> +<p> + 7.3 You acknowledge that your use of such third party applications, data, content, or resources may be subject to separate terms between you and the relevant third party. In that case, this License Agreement does not affect your legal relationship with these third parties. +</p> +<h2> + 8. Using Android APIs +</h2> +<p> + 8.1 Android Maps API +</p> +<p> + 8.1.1 If you use the Android Maps API (described in the SDK by the Package names "com.google.android.maps" and "com.android.location.Geocoder"), the terms of your binding legal agreement with Google include this License Agreement, the <a href="http://www.google.com/apis/maps/terms.html">Google Maps API Terms of Service</a> and the <a href="http://www.google.com/intl/en_ALL/help/terms_local.html">Google Maps Terms of Service</a>. You must read and agree to those Terms of Service before you use the Android Maps API. +</p> +<p> + 8.1.2 If you use the Android Maps API to retrieve map or satellite image data from Google, you must include the following copyright notice in your application or service in a manner that is reasonably available to users: +</p> +<p> + "Copyright Notice: Data: (c)2007 TeleAtlas, AND, Europa Technologies, Kingway, Map Data Sciences Pty Ltd, PSMA, ZENRIN, Geocentre, MapLink/TeleAtlas; Imagery: (c)2007 DigitalGlobe, EarthSat, Sanborn, NYGIS, Scankort, TerraMetrics, MassGIS Commonwealth of Massachusetts, Digital Earth Technology." +</p> +<p> + 8.2 Google Data APIs +</p> +<p> + 8.2.1 If you use any API to retrieve data from Google, you acknowledge that the data may be protected by intellectual property rights which are owned by those who provide that data (or by other persons or companies on their behalf). You may not modify, rent, lease, loan, sell, distribute or create derivative works based on this data (either in whole or in part) unless you have been specifically given permission to do so by the owners of that data. +</p> +<p> + 8.2.2 If you use any API to retrieve a user's data from Google, you acknowledge and agree that you shall retrieve data only with the user's explicit consent and only when, and for the limited purposes for which, the user has given you permission to do so. +</p> +<h2> + 9. Terminating this License Agreement +</h2> +<p> + 9.1 This License Agreement will continue to apply until terminated by either you or Google as set out below. +</p> +<p> + 9.2 If you want to terminate this License Agreement, you may do so by ceasing your use of the SDK and any relevant developer credentials. +</p> +<p> + 9.3 Google may at any time, terminate this License Agreement with you if: +</p> +<p> + (A) you have breached any provision of this License Agreement; or +</p> +<p> + (B) Google is required to do so by law; or +</p> +<p> + (C) the partner with whom Google offered certain parts of SDK (such as APIs) to you has terminated its relationship with Google or ceased to offer certain parts of the SDK to you; or +</p> +<p> + (D) Google decides to no longer providing the SDK or certain parts of the SDK to users in the country in which you are resident or from which you use the service, or the provision of the SDK or certain SDK services to you by Google is, in Google's sole discretion, no longer commercially viable. +</p> +<p> + 9.4 When this License Agreement comes to an end, all of the legal rights, obligations and liabilities that you and Google have benefited from, been subject to (or which have accrued over time whilst this License Agreement has been in force) or which are expressed to continue indefinitely, shall be unaffected by this cessation, and the provisions of paragraph 14.7 shall continue to apply to such rights, obligations and liabilities indefinitely. +</p> +<h2> + 10. DISCLAIMER OF WARRANTIES +</h2> +<p> + 10.1 YOU EXPRESSLY UNDERSTAND AND AGREE THAT YOUR USE OF THE SDK IS AT YOUR SOLE RISK AND THAT THE SDK IS PROVIDED "AS IS" AND "AS AVAILABLE" WITHOUT WARRANTY OF ANY KIND FROM GOOGLE. +</p> +<p> + 10.2 YOUR USE OF THE SDK AND ANY MATERIAL DOWNLOADED OR OTHERWISE OBTAINED THROUGH THE USE OF THE SDK IS AT YOUR OWN DISCRETION AND RISK AND YOU ARE SOLELY RESPONSIBLE FOR ANY DAMAGE TO YOUR COMPUTER SYSTEM OR OTHER DEVICE OR LOSS OF DATA THAT RESULTS FROM SUCH USE. +</p> +<p> + 10.3 GOOGLE FURTHER EXPRESSLY DISCLAIMS ALL WARRANTIES AND CONDITIONS OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. +</p> +<h2> + 11. LIMITATION OF LIABILITY +</h2> +<p> + 11.1 YOU EXPRESSLY UNDERSTAND AND AGREE THAT GOOGLE, ITS SUBSIDIARIES AND AFFILIATES, AND ITS LICENSORS SHALL NOT BE LIABLE TO YOU UNDER ANY THEORY OF LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL CONSEQUENTIAL OR EXEMPLARY DAMAGES THAT MAY BE INCURRED BY YOU, INCLUDING ANY LOSS OF DATA, WHETHER OR NOT GOOGLE OR ITS REPRESENTATIVES HAVE BEEN ADVISED OF OR SHOULD HAVE BEEN AWARE OF THE POSSIBILITY OF ANY SUCH LOSSES ARISING. +</p> +<h2> + 12. Indemnification +</h2> +<p> + 12.1 To the maximum extent permitted by law, you agree to defend, indemnify and hold harmless Google, its affiliates and their respective directors, officers, employees and agents from and against any and all claims, actions, suits or proceedings, as well as any and all losses, liabilities, damages, costs and expenses (including reasonable attorneys fees) arising out of or accruing from (a) your use of the SDK, (b) any application you develop on the SDK that infringes any copyright, trademark, trade secret, trade dress, patent or other intellectual property right of any person or defames any person or violates their rights of publicity or privacy, and (c) any non-compliance by you with this License Agreement. +</p> +<h2> + 13. Changes to the License Agreement +</h2> +<p> + 13.1 Google may make changes to the License Agreement as it distributes new versions of the SDK. When these changes are made, Google will make a new version of the License Agreement available on the website where the SDK is made available and with the SDK downloadable. +</p> +<p> + 13.2 You agree that your use of a specific version of the SDK is governed by the License Agreement included with that version of the SDK. +</p> +<h2> + 14. General Legal Terms +</h2> +<p> + 14.1 This License Agreement constitute the whole legal agreement between you and Google and govern your use of the SDK (excluding any services which Google may provide to you under a separate written agreement), and completely replace any prior agreements between you and Google in relation to the SDK. +</p> +<p> + 14.2 You agree that if Google does not exercise or enforce any legal right or remedy which is contained in this License Agreement (or which Google has the benefit of under any applicable law), this will not be taken to be a formal waiver of Google's rights and that those rights or remedies will still be available to Google. +</p> +<p> + 14.3 If any court of law, having the jurisdiction to decide on this matter, rules that any provision of this License Agreement is invalid, then that provision will be removed from this License Agreement without affecting the rest of this License Agreement. The remaining provisions of this License Agreement will continue to be valid and enforceable. +</p> +<p> + 14.4 You acknowledge and agree that each member of the group of companies of which Google is the parent shall be third party beneficiaries to this License Agreement and that such other companies shall be entitled to directly enforce, and rely upon, any provision of this License Agreement that confers a benefit on (or rights in favor of) them. Other than this, no other person or company shall be third party beneficiaries to this License Agreement. +</p> +<p> + 14.5 EXPORT RESTRICTIONS. THE SDK IS SUBJECT TO UNITED STATES EXPORT LAWS AND REGULATIONS. YOU MUST COMPLY WITH ALL DOMESTIC AND INTERNATIONAL EXPORT LAWS AND REGULATIONS THAT APPLY TO THE SDK. THESE LAWS INCLUDE RESTRICTIONS ON DESTINATIONS, END USERS AND END USE. +</p> +<p> + 14.6 The rights granted in this License Agreement may not be assigned or transferred by either you or Google without the prior written approval of the other party. Neither you nor Google shall be permitted to delegate their responsibilities or obligations under this License Agreement without the prior written approval of the other party. +</p> +<p> + 14.7 This License Agreement, and your relationship with Google under this License Agreement, shall be governed by the laws of the State of California without regard to its conflict of laws provisions. You and Google agree to submit to the exclusive jurisdiction of the courts located within the county of Santa Clara, California to resolve any legal matter arising from this License Agreement. Notwithstanding this, you agree that Google shall still be allowed to apply for injunctive remedies (or an equivalent type of urgent legal relief) in any jurisdiction. +</p> +<p> + <em>August 18, 2008</em> +</p> diff --git a/docs/html/sdk/1.0_r1/upgrading.jd b/docs/html/sdk/1.0_r1/upgrading.jd new file mode 100644 index 0000000..67bcc6a --- /dev/null +++ b/docs/html/sdk/1.0_r1/upgrading.jd @@ -0,0 +1,151 @@ +page.title=Upgrading the SDK +@jd:body + +<div class="sidebox-wrapper"> + <div class="sidebox-inner"> + + <h2>Useful Links</h2> + + <ul class="noindent"> + <li><a href="{@docRoot}migrating/0.9-1.0/changes-overview.html">Overview of Changes</a> + <p>A high-level look at what's changed in Android, with + discussion of how the changes may affect your apps.</p></li> + + <li><a href="{@docRoot}migrating/0.9-1.0/changes.html">API Diff Report</a> + <p>A detailed report that lists all the specific changes in the latest SDK.</p></li> + + <li><a href="{@docRoot}RELEASENOTES.html">Release Notes</a> + <p>Version details, known issues, and resolved issues. </p></li> + + <li><a href="http://groups.google.com/group/android-developers">Android Developers Group</a> + <p>A forum where you can discuss migration issues and learn from other Android developers. </p></li> + + <li><a href="http://code.google.com/p/android/issues/list">Android Issue Tracker</a> + <p>If you think you may have found a bug, use the issue tracker to report it.</p></li> + </ul> + + </div> +</div><!-- class-sidebox --> + + +<p>This guide will help you migrate your development environment and applications +to the latest version of the SDK. Use this guide if you've been developing applications +on a previous version of the Android SDK. +</p> + +<p>To ensure that your applications are compliant with the Android 1.0 system available +on mobile devices, you need to install the new SDK and port your existing Android +applications to the updated API. The sections below guide you through the process.</p> + +<h2 id="install-new">Install the new SDK</h2> + +<p><a href="{@docRoot}download.html">Download the SDK</a> and unpack it into a safe location.</p> + +<p>After unpacking the new SDK, you should:</p> + +<ul> + <li>Wipe your emulator data. <p>Some data formats have changed since the last + SDK release, so any previously saved data in your emulator must be removed. Open a console/terminal + and navigate to the <code>/tools</code> directory of your SDK. Launch the + emulator with the <code>-wipe-data</code> option. </p> + <p>Windows: <code>emulator -wipe-data</code><br/> + Mac/Linux: <code>./emulator -wipe-data</code></p> + </li> + <li>Update your PATH variable (Mac/Linux; optional). <p>If you had previously setup your + PATH variable to point to the SDK tools directory, then you'll need to update it to + point to the new SDK. E.g., for a <code>.bashrc</code> or <code>.bash_profile</code> file: + <code>export PATH=$PATH:<em><your_new_sdk_dir></em>/tools</code></p> + </li> +</ul> + +<h2 id="update-plugin">Update your ADT Eclipse Plugin</h2> + +<p>If you develop on Eclipse and are using the ADT plugin, follow these steps to install the new plugin that accompanies the latest SDK.</p> + +<table style="font-size:100%"> +<tr><th>Eclipse 3.3 (Europa)</th><th>Eclipse 3.4 (Ganymede)</th></tr> +<tr> +<td width="50%"> +<ol> + <li> Select <strong>Help</strong> > <strong>Software Updates</strong> > <strong>Find and Install...</strong>. </li> + <li> Select <strong>Search for updates of the currently installed features</strong> and click <strong>Finish</strong>. </li> + <li> If any update for ADT is available, select and install. </li> + <li> Restart Eclipse.</li> +</ol> +</td> +<td> +<ol> + <li>Select <strong>Help</strong> > <strong>Software Updates...</strong></li> + <li>Select the <strong>Installed Software</strong> tab.</li> + <li>Click <strong>Update...</strong></li> + <li>If an update for ADT is available, select it and click <strong>Finish</strong>.</li> + <li>Restart Eclipse.</li> +</ol> +</td> +</tr> +</table> + +<p>After restart, update your Eclipse preferences to point to the SDK directory:</p> + <ol> + <li>Select <strong>Window</strong> > <strong>Preferences...</strong> to open the Preferences panel. (Mac OSX: <strong>Eclipse</strong> > <strong>Preferences</strong>)</li> + <li>Select <strong>Android</strong> from the left panel.</li> + <li>For the SDK Location in the main panel, click <strong>Browse...</strong> and locate the SDK directory.</li> + <li>Click <strong>Apply</strong>, then <strong>OK</strong>.</li> + </ol> + +<h2 id="sign">Set Up Application Signing</h2> + +<p>All applications must now be signed before you can install them on the emulator. Both +the ADT plugin and the Ant-based build tools support this requirement by signing compiled +.apk files with a debug key. To do so, the build tools use the Keytool utility included +in the JDK to to create a keystore and a key with a known alias and password. For more +information, see <a href="{@docRoot}intro/develop-and-debug.html">Signing Your Applications</a>. + +<p>To support signing, you should first make sure that Keytool is available to the SDK build +tools. In most cases, you can tell the SDK build tools how to find Keytool by making sure that +your JAVA_HOME environment variable is set and that it references a suitable JDK. Alternatively, +you can add the JDK version of Keytool to your PATH variable.</p> + +<p>If you are developing on a version of Linux that originally came with Gnu Compiler for Java, +make sure that the system is using the JDK version of Keytool, rather than the gcj version. +If keytool is already in your PATH, it might be pointing to a symlink at /usr/bin/keytool. +In this case, check the symlink target to make sure that it points to the keytool in the JDK.</p> + +<p>If you use Ant to build your .apk files (rather than ADT for Eclipse), you must regenerate +your build.xml file. To do that, follow these steps:</p> +<ol> + <li>In your Android application project directory, locate and delete the current build.xml file.</li> + <li>Run activitycreator, directing output to the folder containing your application project. + +<pre>- exec activitycreator --out <project folder> your.activity.YourActivity</pre> + + </li> +</ol> + +<p>Run in this way, activityCreator will not erase or create new Java files (or manifest files), +provided the activity and package already exists. It is important that the package and the activity +are real. The tool creates a new build.xml file, as well as a new directory called "libs" in which +to place 3rd jar files, which are now automatically handled by the Ant script.</p> + +<h2 id="migrate">Migrate your applications</h2> + +<p>After updating your SDK, you will likely encounter breakages in your code, due to +framework and API changes. You'll need to update your code to match changes in the Andriod APIs.</p> + +<p>One way to start is to open your project in Eclipse and see where the ADT +identifies errors in your application. From there, you can lookup +respective changes in the +<a href="{@docRoot}migrating/0.9-1.0/changes-overview.html">Overview of Changes</a> +and <a href="{@docRoot}migrating/0.9-1.0/changes.html">API Diffs Report</a>.</p> + +<p>If you have additional trouble updating your code, visit the +<a href="{@docRoot}groups.html">Android Discussion Groups</a> to seek help from +other Android developers.</p> + +<p>If you have modified one of the ApiDemos applications and would like to migrate it +to the new SDK, note that you will need to uninstall the version of ApiDemos that comes +preinstalled in the emulator. For more information, or if you encounter an "reinstallation" +error when running or installing ApiDemos, see the troubleshooting topic +<a href="{@docRoot}kb/troubleshooting.html#apidemosreinstall">I can't install ApiDemos +apps in my IDE because of a signing error</a> for information about how to solve the problem.</p> + diff --git a/docs/html/sdk/index.html b/docs/html/sdk/index.html new file mode 100644 index 0000000..c5468dd --- /dev/null +++ b/docs/html/sdk/index.html @@ -0,0 +1,6 @@ +<html> +<head> +<title>Redirecting...</title> +<meta http-equiv="refresh" content="0;url=1.0_r1/index.html"> +</head> +</html>
\ No newline at end of file diff --git a/docs/html/sdk/sdk_toc.cs b/docs/html/sdk/sdk_toc.cs new file mode 100644 index 0000000..76421a3 --- /dev/null +++ b/docs/html/sdk/sdk_toc.cs @@ -0,0 +1 @@ +<ul>
<li><h2>SDK 1.0</h2>
<ul>
<li><strong><a href="<?cs var:toroot ?>sdk/1.0_r1/index.html">Release 1</a></strong>
<ul>
<li><a href="<?cs var:toroot ?>sdk/1.0_r1/installing.html">Installing</a></li>
<li><a href="<?cs var:toroot ?>sdk/1.0_r1/upgrading.html">Upgrading</a></li>
<li><a href="<?cs var:toroot ?>sdk/1.0_r1/terms.html">License Agreement</a></li>
<li><a href="<?cs var:toroot ?>sdk/1.0_r1/RELEASENOTES.html">Release Notes</a></li>
</ul>
</li>
<!--
<li><strong><a href="<?cs var:toroot ?>sdk/1.0_r2/index.html">Release 2</a></strong>
<ul>
<li><a href="<?cs var:toroot ?>sdk/1.0_r2/installing.html">Installing</a></li>
<li><a href="<?cs var:toroot ?>sdk/1.0_r2/upgrading.html">Upgrading</a></li>
<li><a href="<?cs var:toroot ?>sdk/1.0_r2/terms.html">License Agreement</a></li>
<li><a href="<?cs var:toroot ?>sdk/1.0_r2/RELEASENOTES.html">Release Notes</a></li>
</ul>
</li>
-->
</ul>
</li>
<!-- just a template
<li><h2>SDK 1.1</h2>
<ul>
<li><strong><a href="<?cs var:toroot ?>sdk/1.1_r1/index.html">Release 1</a></strong>
<ul>
<li><a href="<?cs var:toroot ?>sdk/1.1_r1/installing.html">Installing</a></li>
<li><a href="<?cs var:toroot ?>sdk/1.1_r1/upgrading.html">Upgrading</a></li>
<li><a href="<?cs var:toroot ?>sdk/1.1_r1/terms.html">License Agreement</a></li>
<li><a href="<?cs var:toroot ?>sdk/1.1_r1/RELEASENOTES.html">Release Notes</a></li>
</ul>
</li>
<li><strong><a href="<?cs var:toroot ?>sdk/1.1_r2/index.html">Release 2</a></strong>
<ul>
<li><a href="<?cs var:toroot ?>sdk/1.1_r2/installing.html">Installing</a></li>
<li><a href="<?cs var:toroot ?>sdk/1.1_r2/upgrading.html">Upgrading</a></li>
<li><a href="<?cs var:toroot ?>sdk/1.1_r2/terms.html">License Agreement</a></li>
<li><a href="<?cs var:toroot ?>sdk/1.1_r2/RELEASENOTES.html">Release Notes</a></li>
</ul>
</li>
</ul>
</li>
-->
</ul>
\ No newline at end of file diff --git a/docs/html/search.jd b/docs/html/search.jd new file mode 100755 index 0000000..d5e6f92 --- /dev/null +++ b/docs/html/search.jd @@ -0,0 +1,81 @@ +page.title=Search Results
+@jd:body
+
+
+<script src="http://www.google.com/jsapi" type="text/javascript"></script>
+<script type="text/javascript">
+ google.load('search', '1');
+
+ // the cse class encapsulates a left and right search control
+ // both controls are driven by a shared search form
+ function cse() {
+ var sFormDiv = document.getElementById("searchForm");
+ var leftScDiv = document.getElementById("leftSearchControl");
+
+ // create a left, right search control
+ // create a custom search form
+ this.leftControl = new google.search.SearchControl();
+ this.searchForm = new google.search.SearchForm(true, sFormDiv);
+
+ // bind clear and submit functions
+ this.searchForm.setOnSubmitCallback(this, cse.prototype.onSubmit);
+ this.searchForm.setOnClearCallback(this, cse.prototype.onClear);
+
+ // set up for small result sets
+ this.leftControl.setResultSetSize(google.search.Search.LARGE_RESULTSET);
+
+ var searcher;
+ var options;
+
+ // configure left control
+ // Site Restrict to CSE ID for reviews
+ searcher = new google.search.WebSearch();
+ options = new google.search.SearcherOptions();
+ //searcher.setSiteRestriction("000455696194071821846:reviews");
+ //searcher.setUserDefinedLabel("Product Reviews");
+ options.setExpandMode(GSearchControl.EXPAND_MODE_OPEN);
+ this.leftControl.addSearcher(searcher, options);
+
+ // draw the left and right controls
+ this.leftControl.draw(leftScDiv);
+
+ // execute a starter search
+ urlquery=location.href.split("?");
+ urlterms=urlquery[1].split(",");
+ document.getElementById("searchTitle").innerHTML = urlterms[0];
+ this.searchForm.execute(urlterms[0]);
+
+ }
+
+ // when the form fires a submit, grab its
+ // value and call the left and right control
+ cse.prototype.onSubmit = function(form) {
+ var q = form.input.value;
+ if (q && q!= "") {
+ this.leftControl.execute(q);
+
+ document.getElementById("searchTitle").innerHTML = "search results for " + q;
+ }
+ return false;
+ }
+
+ // when the form fires a clear, call the left and right control
+ cse.prototype.onClear = function(form) {
+ //this.leftControl.clearAllResults();
+ //form.input.value = "";
+ document.getElementById("searchTitle").innerHTML = form.input.value;
+ return false;
+ }
+
+ function OnLoad() {
+ new cse();
+ }
+ google.setOnLoadCallback(OnLoad, true);
+</script>
+
+<div id="mainBodyFixed">
+ <h2 id="searchTitle">search results</h2>
+ <img src="{@docRoot}assets/images/hr_gray_main.jpg" />
+ <div><br /></div>
+ <div id="leftSearchControl" class="search-control">Loading...</div>
+</div>
diff --git a/docs/html/security_at_android_dot_com.txt b/docs/html/security_at_android_dot_com.txt new file mode 100644 index 0000000..daeda53 --- /dev/null +++ b/docs/html/security_at_android_dot_com.txt @@ -0,0 +1,40 @@ +-----BEGIN PGP PUBLIC KEY BLOCK----- +Version: GnuPG v1.4.2.2 (GNU/Linux) + +mQGiBEigu7MRBAD7gZJzevtYLB3c1pE7uMwu+zHzGGJDrEyEaz0lYTAaJ2YXmJ1+ +IvmvBI/iMrRqpFLR35uUcz2UHgJtIP+xenCF4WIhHv5wg3XvBvTgG/ooZaj1gtez +miXV2bXTlEMxSqsZKvkieQRrMv3eV2VYhgaPvp8xJhl+xs8eVhlrmMv94wCgzWUw +BrOICLPF5lANocvkqGNO3UUEAMH7GguhvXNlIUncqOpHC0N4FGPirPh/6nYxa9iZ +kQEEg6mB6wPkaHZ5ddpagzFC6AncoOrhX5HPin9T6+cPhdIIQMogJOqDZ4xsAYCY +KwjkoLQjfMdS5CYrMihFm4guNMKpWPfCe/T4TU7tFmTug8nnAIPFh2BNm8/EqHpg +jR4JA/9wJMxv+2eFuFGeLtiPjo+o2+AfIxTTEIlWyNkO+a9KkzmPY/JP4OyVGKjM +V+aO0vZ6FamdlrXAaAPm1ULmY5pC15P/hNr0YAbN28Y8cwNGuuKGbiYvYD35KKhs +5c5/pfMy0rgDElhFTGd4rpZdkHei3lwF5cyV0htv5s2lwGJKnrQnQW5kcm9pZCBT +ZWN1cml0eSA8c2VjdXJpdHlAYW5kcm9pZC5jb20+iGAEExECACAFAkigu7MCGwMG +CwkIBwMCBBUCCAMEFgIDAQIeAQIXgAAKCRBzHmufAFQPw547AKDIDW3mDx+84xk1 +EfzH/uNQQLYBBgCeMabHPlx+2+IGnfPsQ8UsxMPLFnO5BA0ESKC72BAQALKb8W8l +U3Xs+lbquuVEA5x+mNnJriRnq1q1ZA8J43z0lCqT6n+q/nICuE/SjGxfp+8G/K3/ +LrIfBWLLQHZMQyk/1Eild/ZoRxNAbjTGiQY6HWrZOd+Z2fWiSN03nSSpWImPbua3 +6LwSRRZNmZ77tdY0hI9TqJzqax1WQWk7IxfWubNTbNsPiktm/d6C2P04OkKOAmr8 +QCqKLLCO578zYLTgraL6F4g2YVurGgAB1KFSX2F8fh6Igr+pIW/ytoS9n2H+uecR +l+2RB6Pq7MahwZvPPeMavwUMPQpOI6Or3pYZTzp/IJWNyL6MOBzV5q4gkD0xYtEq +Ihr1hX1IdiGdOA4oH1Rk1K/XIPwLelQdYp3ftiReh4/Gb3kfKCxpmMXL1f/ndx6N +zIiqweDU5mZBpXBsBzFZfUDALL4VGqpc2eEltkVtD0RuQI2YaImBjOPsHI4StN5t +2OspWke4xJGf0PqRVjTDJmtUrIJX4X5Fh8M85unHYYIpBCaDbM/7/xIaNQbQfdeO +6yqGrj/0WAjL34wbo4D12BiPeoUTreD60aNwmpu5z1NRPS2Wn+6kTIHGhf47wGTZ +v9OFYWhgSs3INpna4VA4E8SpOWPd8LFYLs9clAlaUhqJyLJ3JlmXmhGnWM41z+p9 +RA8UQXhvQcvYJSR77SC4O503wdVKJ07OH6WbAAMFD/4yjBZ+X7QBIKTLHXAIQBjB +526iOhmfxyIgmX4vWcggJFZrBxPFulkGJj65Mwr9AwZeIceukKQUGcf2LpEoIdZY +dP8gEshRDZQ1Y3GDD9ukChRDoK9kFIxnYmH8euU/TwTPtAEEDASfwEZnM5DcJQOA +Q6G3GVKr/8uwmT5hUn5sR2L9vmrjw1nPkfZeDQNBmeTI8A+byosp6Nxl8thJIGNt +8UTa02+g/nbf+ODRrEf3xeeFUNb14kTqULNT/hTj8/6xDwxwaF2ms60kYxA/EXDB +21jqmhnfUwjSa++R38Qig9tGwOo83Z7uNCqtU3caFW1P55iD/Sju/ZecHVSgfq6j +2H7mNWfvB9ILkS7w1w/InjEA7LpY9jtmPKDIYYQ7YGZuxFwOxtw69ulkS6ddc1Pt +AQ5oe0d59rBicE8R7rBCxwzMihG5ctJ+a+t4/MHqi6jy/WI9OK+SwWmCeT1nVy6F +NZ00QOPe89DFBCqhj4qSGfjOtCEKAM7SOhkyEYJ8jk5KrsLOcWPOM9i3uus1RquG +XJ2Cljt6zJYtEnpkjrw+Ge0SBDNEMGZEBLbEZKECtNJ2NBrMRKYeAseCGNQ+uJOz +8vL7ztUKoi1SbFGuHkv5N2NmPq42QrN8dftW01DceGDnJ1KHRvCUbpPcyQYFhRFb +nxd3tMIEGO83iEmozvJfB4hJBBgRAgAJBQJIoLvYAhsMAAoJEHMea58AVA/D6ewA +ninKQSW+oL4z28F3T0GHag38WeWyAJ45d7dx4z0GxhTm2b9DclLombY+nw== +=XyBX +-----END PGP PUBLIC KEY BLOCK----- diff --git a/docs/overview-ext.html b/docs/overview-ext.html new file mode 100644 index 0000000..5720245 --- /dev/null +++ b/docs/overview-ext.html @@ -0,0 +1,8 @@ +<body>
+Some random libraries that we've imported:
+<ul>
+ <li>GData</li>
+ <li>Apache commons HTTPClient</li>
+ <li>A sax parser</li>
+</ul>
+</body>
|
