diff options
| author | The Android Open Source Project <initial-contribution@android.com> | 2009-02-10 15:44:00 -0800 |
|---|---|---|
| committer | The Android Open Source Project <initial-contribution@android.com> | 2009-02-10 15:44:00 -0800 |
| commit | d24b8183b93e781080b2c16c487e60d51c12da31 (patch) | |
| tree | fbb89154858984eb8e41556da7e9433040d55cd4 /docs | |
| parent | f1e484acb594a726fb57ad0ae4cfe902c7f35858 (diff) | |
| download | frameworks_base-d24b8183b93e781080b2c16c487e60d51c12da31.zip frameworks_base-d24b8183b93e781080b2c16c487e60d51c12da31.tar.gz frameworks_base-d24b8183b93e781080b2c16c487e60d51c12da31.tar.bz2 | |
auto import from //branches/cupcake/...@130745
Diffstat (limited to 'docs')
87 files changed, 4253 insertions, 1936 deletions
diff --git a/docs/docs-redirect.html b/docs/docs-redirect.html index 3d2b8a0..4e0743e 100644 --- a/docs/docs-redirect.html +++ b/docs/docs-redirect.html @@ -1,8 +1,8 @@ <html>
<head>
-<meta http-equiv="refresh" content="0;url=docs/index.html">
+<meta http-equiv="refresh" content="0;url=docs/offline.html">
</head>
<body>
-<a href="docs/index.html">click here if you are not redirected</a>
+<a href="docs/offline.html">click here if you are not redirected</a>
</body>
</html>
diff --git a/docs/html/community/index.jd b/docs/html/community/index.jd index 284afe3..4dc5503 100644 --- a/docs/html/community/index.jd +++ b/docs/html/community/index.jd @@ -4,53 +4,115 @@ page.title=Community <div id="mainBodyFluid"> <h1>Community</h1> - <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> - <ol> - <li><a href="{@docRoot}guide/appendix/faq/index.html">Read the FAQs</a> The most common questions are addressed in this frequently updated list.</li> - <li><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> - <li><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.</li> - </ol> - <p>For a great guide to phrasing your questions, please read: <a href="#">How to Ask Questions The Smart Way</a>.</p> - -<h2>Subscribe to a Group</h2> -<p>You can subscribe to these groups in one of two ways:</p> - <ul> - <li>Follow the web access link (in the first column below) and then click "Join this group" on the right-side of the Groups page. If you'd rather read posts via email, sign in to Groups and click "edit my membership" on the right hand side. Select "email" under "How do you want to read this group?".</li> - <li>Or simply subscribe via email by clicking the subscribe link (in the last column below).</li> - </ul> - -<h3 class="green">Available Groups</h3> - <table class="groupTable"> - <tr> - <th>Group - Web Access</th> - <th>Description</th> - <th>Subscribe by email</th> - </tr> - <tr class="oddRow"> - <td><a href="http://groups.google.com/group/android-beginners">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="mailto:android-beginners-subscribe@googlegroups.com">android-beginners-subscribe@googlegroups.com</a></td> - </tr> - <tr class="evenRow"> - <td><a href="http://groups.google.com/group/android-developers">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="mailto:android-developers-subscribe@googlegroups.com">android-developers-subscribe@googlegroups.com</a></td> - </tr> - <tr class="oddRow"> - <td><a href="http://groups.google.com/group/android-discuss">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="mailto:android-discuss-subscribe@googlegroups.com">android-discuss-subscribe@googlegroups.com</a></td> - </tr> - <tr class="evenRow"> - <td><a href="http://groups.google.com/group/android-security-discuss">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="mailto:android-security-discuss-subscribe@googlegroups.com">android-security-discuss-subscribe@googlegroups.com</a></td> - </tr> - <tr class="oddRow"> - <td><nobr><a href="http://groups.google.com/group/android-security-announce">android-security-announce</a></nobr></td> - <td>A low-volume group for security-related announcements by the Android Security Team.</td> - <td><a href="mailto:android-security-announce-subscribe@googlegroups.com">android-security-announce-subscribe@googlegroups.com</a></td> - </tr> - </table> + <p>Welcome to the Android developers 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 class="note"><strong>Note:</strong> If you are seeking discussion about Android source code (not application development), +then please refer to the <a href="http://source.android.com/discuss">Open Source Project Mailing lists</a>.</p> + +<p style="margin-bottom".5em"><strong>Contents</strong></p> +<ol class="toc"> + <li><a href="#BeforeYouPost">Before you post</a></li> + <li><a href="#ApplicationDeveloperLists">Application developer mailing lists</a></li> + <li><a href="#UsingEmail">Using email with the mailing lists</a></li> + <li><a href="#UsingIRC">Using IRC</a></li> +</ol> + +<h2 id="BeforeYouPost">Before you post</h2> +<p>Before writing a post, please try the following:</p> + +<ol> +<li><a href="{@docRoot}guide/appendix/faq/index.html">Read the FAQs</a> The most common questions about developing Android applications are addressed in this frequently updated list.</li> +<li><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> +<li><b>Search the mailing list archives</b> to see whether your questions have already been discussed. + </li> +</ol> + +<p>If you can't find your answer, then we encourage you to address the community. +As you write your post, please do the following: +<ol> +<li><b>Read +the <a href="http://sites.google.com/a/android.com/opensource/discuss/android-discussion-groups-charter">mailing list charter</a></b> that covers the community guidelines. +</li> +<li><b>Select the most appropriate mailing list for your question</b>. There are several different lists for +developers, described below.</li> +<li> + <b>Be very clear</b> 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.</li> +<li><b>Give plenty of details</b> in your post to +help others understand your problem. Code or log snippets, as well as +pointers to screenshots, may also be helpful. For a great guide to +phrasing your questions, read <a href="http://www.catb.org/%7Eesr/faqs/smart-questions.html">How To Ask Questions The Smart Way</a>. + </li> +</ol> + + +<h3 id="ApplicationDeveloperLists">Application developer mailing lists</h3> +<ul> +<li><b>Android beginners</b> - You're new to Android application development. You want to figure out how to get started with the Android SDK and the basic Android APIs? Start here. This list is open to any discussion around beginner-type questions for developers using the SDK; this is a great way to get up and running with your new application on the Android platform. Ask about getting your development environment set up, get help with the first steps of Android development (your first User Interface, your first permission, your first file on the Android filesystem, your first app on the Android Market...). Be sure to check the archives first before asking new questions. Please avoid advanced subjects, which belong on android-developers, and user questions, which will get a better reception on android-discuss. +<ul> +<li>Subscribe using Google Groups: <a href="http://groups.google.com/group/android-beginners">android-beginners</a></li> +<li>Subscribe via email: <a href="mailto:android-beginners-subscribe@googlegroups.com">android-beginners-subscribe@googlegroups.com</a><a href="mailto:android-platform-subscribe@googlegroups.com"> +</a></li> +</ul> +</li> + +<li><b>Android developers</b> - You're now an experienced Android application developer. You've grasped the basics of Android app development, you're comfortable using the SDK, now you want to move to advanced topics. Get help here with troubleshooting applications, advice on implementation, and strategies for improving your application's performance and user experience. This is the not the right place to discuss user issues (use android-discuss for that) or beginner questions with the Android SDK (use android-beginners for that). +<ul> +<li>Subscribe using Google Groups: <a href="http://groups.google.com/group/android-developers">android-developers</a></li> +<li>Subscribe via email: <a href="mailto:android-developers-subscribe@googlegroups.com">android-developers-subscribe@googlegroups.com</a><a href="mailto:android-platform-subscribe@googlegroups.com"> +</a></li> +</ul> +</li> + +<li><b>Android discuss</b> - The "water cooler" of Android discussion. You can discuss just about anything Android-related here, ideas for the Android platform, announcements about your applications, discussions about Android devices, community resources... As long as your discussion is related to Android, it's on-topic here. However, if you have a discussion here that could belong on another list, you are probably not reaching all of your target audience here and may want to consider shifting to a more targeted list. +<ul> +<li>Subscribe using Google Groups: <a href="http://groups.google.com/group/android-discuss">android-discuss</a></li> +<li>Subscribe via email: <a href="mailto:android-discuss-subscribe@googlegroups.com">android-discuss-subscribe@googlegroups.com</a><a href="mailto:android-platform-subscribe@googlegroups.com"> + </a></li> +</ul> +</li> + +<li><b>Android security discuss</b> - A place for open discussion on secure development, emerging security concerns, and best practices for and by android developers. Please don't disclose vulnerabilities directly on this list, you'd be putting all Android users at risk. +<ul> +<li>Subscribe using Google Groups: <a href="http://groups.google.com/group/android-security-discuss">android-security-discuss</a></li> +<li>Subscribe via email: <a href="mailto:android-security-discuss@googlegroups.com">android-secuirty-discuss@googlegroups.com</a><a href="mailto:android-platform-subscribe@googlegroups.com"> + </a></li> +</ul> +</li> + +<li><b>Android security announce</b> - A low-volume group for security-related announcements by the Android Security Team. +<ul> +<li>Subscribe using Google Groups: <a href="http://groups.google.com/group/android-security-announce">android-security-announce</a></li> +<li>Subscribe via email: <a href="mailto:android-security-announce-subscribe@googlegroups.com">android-security-announce-subscribe@googlegroups.com</a> +<a href="mailto:android-platform-subscribe@googlegroups.com"> </a></li> +</ul> +</li> +</ul> + + + +<h2 id="UsingEmail">Using email with the mailing lists</h2> +<p>Instead of using the <a href="http://groups.google.com/">Google Groups</a> site, you can use your email client of choice to participate in the mailing lists.</p> +<p>To subscribe to a group without using the Google Groups site, use the link under "subscribe via email" in the lists above.</p> +<p>To set up how you receive mailing list postings by email:</p> + +<ol><li>Sign into the group via the Google Groups site. For example, for the android-framework group you would visit <a href="http://groups.google.com/group/android-framework">http://groups.google.com/group/android-framework</a>.</li> +<li>Click "Edit +my membership" on the right side.</li> +<li>Under "How do +you want to read this group?" select one of the email options. </li> +</ol> + +<h2 id="UsingIRC">Using IRC</h2> +<p>The Android community is using the #android channel on the irc.freenode.net server. +</p> + + + + + + + </div>
\ No newline at end of file diff --git a/docs/html/favicon.ico b/docs/html/favicon.ico Binary files differnew file mode 100644 index 0000000..d8884b7 --- /dev/null +++ b/docs/html/favicon.ico diff --git a/docs/html/guide/appendix/faq/commontasks.jd b/docs/html/guide/appendix/faq/commontasks.jd index 69fddd3..9c79bdd 100644 --- a/docs/html/guide/appendix/faq/commontasks.jd +++ b/docs/html/guide/appendix/faq/commontasks.jd @@ -1,4 +1,6 @@ page.title=Common Tasks and How to Do Them in Android +parent.title=FAQs, Tips, and How-to +parent.link=index.html @jd:body <ul> @@ -81,7 +83,7 @@ want to look at the sample code included with the Android SDK, in the 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}guide/topics/views/index.html">Implementing a UI</a> for + href="{@docRoot}guide/topics/ui/index.html">User Interface</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 @@ -200,7 +202,7 @@ startActivity(myIntent); </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}guide/topics/manifest/manifest.html">The AndroidManifest.xml + tag description in <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</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> @@ -267,7 +269,7 @@ protected void onActivityResult(int requestCode, int resultCode, Intent data){ {@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}guide/topics/views/ui-events.html">Handling UI Events</a> on the UI Design page.</p> +<p>Button click and other UI event capturing are covered in <a href="{@docRoot}guide/topics/ui/ui-events.html">Handling UI Events</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 @@ -527,174 +529,8 @@ focus to the notification before they can interact with it.</p> 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; -} +<p>See <a href="{@docRoot}guide/topics/ui/menus.html">Creating Menus</a>.</p> -// 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> @@ -878,7 +714,7 @@ If the latitudeSpan, longitudeSpan, and zoomLevel attributes are not consistent, 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}guide/topics/manifest/manifest.html">The AndroidManifest.xml File</a>.</td> + information. Syntax details for this file are described in <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a>.</td> </tr> <tr> <td valign="top"> src/<br /> @@ -922,7 +758,7 @@ If the latitudeSpan, longitudeSpan, and zoomLevel attributes are not consistent, <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}guide/topics/views/index.html">Views and Layout</a> for more information about designing screens, and <a href="{@docRoot}guide/topics/resources/available-resources.html#layoutresources">Available Resource Types</a> for the syntax of these files.</td> + to an HTML file that describes the screen layout and components. See <a href="{@docRoot}guide/topics/ui/index.html">User Interface</a> for more information about designing screens, and <a href="{@docRoot}guide/topics/resources/available-resources.html#layoutresources">Available Resource Types</a> for the syntax of these files.</td> </tr> <tr> <td valign="top"> values/<br /> diff --git a/docs/html/guide/appendix/faq/framework.jd b/docs/html/guide/appendix/faq/framework.jd index c5cfcf1..76a19c5 100644 --- a/docs/html/guide/appendix/faq/framework.jd +++ b/docs/html/guide/appendix/faq/framework.jd @@ -1,4 +1,6 @@ page.title=Android Application Framework FAQ +parent.title=FAQs, Tips, and How-to +parent.link=index.html @jd:body <ul> diff --git a/docs/html/guide/appendix/faq/licensingandoss.jd b/docs/html/guide/appendix/faq/licensingandoss.jd index 98be91c..c267fe8 100644 --- a/docs/html/guide/appendix/faq/licensingandoss.jd +++ b/docs/html/guide/appendix/faq/licensingandoss.jd @@ -1,4 +1,6 @@ page.title=Android Open Source Licensing FAQ +parent.title=FAQs, Tips, and How-to +parent.link=index.html @jd:body <ul> diff --git a/docs/html/guide/appendix/faq/security.jd b/docs/html/guide/appendix/faq/security.jd index 1c66f95..b0d832b 100644 --- a/docs/html/guide/appendix/faq/security.jd +++ b/docs/html/guide/appendix/faq/security.jd @@ -1,4 +1,6 @@ page.title=Android Security FAQ +parent.title=FAQs, Tips, and How-to +parent.link=index.html @jd:body <ul> diff --git a/docs/html/guide/appendix/faq/troubleshooting.jd b/docs/html/guide/appendix/faq/troubleshooting.jd index e10f661..7c703e6 100644 --- a/docs/html/guide/appendix/faq/troubleshooting.jd +++ b/docs/html/guide/appendix/faq/troubleshooting.jd @@ -1,4 +1,6 @@ page.title=Troubleshooting +parent.title=FAQs, Tips, and How-to +parent.link=index.html @jd:body @@ -28,9 +30,14 @@ page.title=Troubleshooting <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> +required Eclipse components and then try the ADT installation again. Follow the steps below to install the required components for the +Android Editors feature, based on the version of Eclipse that you are using.</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>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> @@ -41,6 +48,19 @@ 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> +</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> + </p> <a name="nodevice"></a><h2>ADB reports "no device" when an emulator is running</h2> diff --git a/docs/html/guide/appendix/glossary.jd b/docs/html/guide/appendix/glossary.jd index 7059643..ef81631 100644 --- a/docs/html/guide/appendix/glossary.jd +++ b/docs/html/guide/appendix/glossary.jd @@ -168,7 +168,7 @@ page.title=Glossary application's package name, version, components (activities, intent filters, services), imported libraries, and describes the various activies, and so on. See <a - href="{@docRoot}guide/topics/manifest/manifest.html">The + href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a> for complete information.</dd> <dt id="ninepatch">Nine-patch / 9-patch / Ninepatch image</dt> diff --git a/docs/html/guide/appendix/media-formats.jd b/docs/html/guide/appendix/media-formats.jd index 41dfd63..5419ad6 100644 --- a/docs/html/guide/appendix/media-formats.jd +++ b/docs/html/guide/appendix/media-formats.jd @@ -20,7 +20,7 @@ page.title=Android Supported Media Formats </tr> <tr> -<td rowspan="8">Audio</td> +<td rowspan="9">Audio</td> <td>AAC LC/LTP</td> <td> </td> <td style="text-align: center;">X</td> @@ -83,6 +83,14 @@ page.title=Android Supported Media Formats </tr> <tr> +<td>PCM/WAVE</td> +<td> </td> +<td style="text-align: center;">X</td> +<td>8- and 16-bit linear PCM (rates up to limit of hardware)</td> +<td>WAVE (.wav)</td> +</tr> + +<tr> <td rowspan="4">Image</td> <td>JPEG</td> <td style="text-align: center;">X</td> diff --git a/docs/html/guide/basics/anatomy.jd b/docs/html/guide/basics/anatomy.jd deleted file mode 100755 index f4b2ad0..0000000 --- a/docs/html/guide/basics/anatomy.jd +++ /dev/null @@ -1,134 +0,0 @@ -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/android-sdk.jd b/docs/html/guide/basics/android-sdk.jd deleted file mode 100644 index d1f3437..0000000 --- a/docs/html/guide/basics/android-sdk.jd +++ /dev/null @@ -1,11 +0,0 @@ -page.title=The Android SDK -@jd:body - -<p>FIXME</p> - -<p>The downloadable Android SDK includes the Android API libraries, sample code, documentation, -and a collection of Android development tools, like the emulator and debugger.</p> - -<p>The SDK supports developing on Linux, Mac OS X, and Windows (XP and Vista).</p> - -<p>The Java Development Kit is required.</p>
\ No newline at end of file diff --git a/docs/html/guide/basics/app-framework.jd b/docs/html/guide/basics/app-framework.jd deleted file mode 100644 index 8513884..0000000 --- a/docs/html/guide/basics/app-framework.jd +++ /dev/null @@ -1,4 +0,0 @@ -page.title=The Application Framework -@jd:body - -TODO
\ No newline at end of file diff --git a/docs/html/guide/basics/what-is-android.jd b/docs/html/guide/basics/what-is-android.jd index 9e2801a..b75321b 100644 --- a/docs/html/guide/basics/what-is-android.jd +++ b/docs/html/guide/basics/what-is-android.jd @@ -2,7 +2,7 @@ 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 +system, middleware and key applications. 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> diff --git a/docs/html/guide/developing/debug-tasks.jd b/docs/html/guide/developing/debug-tasks.jd index a604df2..6b7c27a 100644 --- a/docs/html/guide/developing/debug-tasks.jd +++ b/docs/html/guide/developing/debug-tasks.jd @@ -53,7 +53,7 @@ D/ActivityManager( 763): Stopping: HistoryRecord{409dbb20 com.android.home.AllAp graphical reader called Traceview. See the linked topic for more information. </li> </ul> <ul> - <li><a href="#developingwitheclipse"><strong>Eclipse plugin</strong></a> - The ADT Plugin + <li><a href="{@docRoot}guide/developing/eclipse-adt.html"><strong>Eclipse plugin</strong></a> - The ADT Plugin for Eclipse integrates 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 diff --git a/docs/html/guide/developing/device.jd b/docs/html/guide/developing/device.jd index b723797..034f707 100644 --- a/docs/html/guide/developing/device.jd +++ b/docs/html/guide/developing/device.jd @@ -7,8 +7,8 @@ page.title=Developing on a Device <ol> <li><a href="#devices">Available Devices</a> <ol> - <li><a href="g1">T-Mobile G1</a></li> - <li><a href="dev-phone-1">Android Dev Phone 1</a></li> + <li><a href="#g1">T-Mobile G1</a></li> + <li><a href="#dev-phone-1">Android Dev Phone 1</a></li> </ol> </li> <li><a href="#setting-up">Setting up a Device for Development</a></li> @@ -41,8 +41,9 @@ href="http://www.t-mobileg1.com">T-Mobile G1 site</a>. </p> <h3 id="dev-phone-1">Android Dev Phone 1</h3> +<div class="sidebox-wrapper"> <div class="sidebox"> -<p>Selected specs for Android Dev Phone 1: </p> +<p>Selected specs for Android Dev Phone 1:</p> <ul> <li>Touch screen</li> <li>Trackball</li> @@ -58,7 +59,7 @@ href="http://www.t-mobileg1.com">T-Mobile G1 site</a>. </p> <li>Includes 1GB MicroSD card (can be replaced with up to 16GB card)</li> </ul> </div> - +</div> <p>The Android Dev Phone 1 is a SIM-unlocked and hardware-unlocked device that is designed for advanced developers. The device ships with a system image that is fully compatible with Android 1.0, so you can rely on it when developing your @@ -71,19 +72,19 @@ who live outside of T-Mobile geographies. </p> <p>To purchase an Android Dev Phone 1 device, you must first register as an Android developer on the Android Market site, if you haven't done so already. Once you've logged into your developer account on Android Market, you can -purchase the device by clicking the "Purchase" link. To accommodate demand, +purchase the device by following the link to "Development phones." To accommodate demand, there is a limit of 1 device per developer account, for now.</p> <p>The device currently costs $399 (USD) (including free shipping in the US), -and will be available for purchase in 18 international markets, including the +and is available for purchase in 18 international markets, including the US, UK, Germany, Japan, India, Canada, France, Taiwan, Spain, Australia, Singapore, Switzerland, Netherlands, Austria, Sweden, Finland, Poland, and Hungary. We will continue to expand this program into new geographies over time. Check this page for updated information.</p> <p>Note that Android Dev Phone 1 devices are <em>not</em> intended for -non-developer end users. Since the devices can be configured with system -software not provided by or supported by Google or any other company, end users +non-developer end-users. Because the device can be configured with system +software not provided by or supported by Google or any other company, end-users operate these devices at their own risk.</p> <p>For full device specs and more information about obtaining an Android Dev @@ -109,17 +110,28 @@ would on the emulator. There are just a few things to do before you can start.</ </li> <li>Setup your system to detect your device. <ul> - <li>If you're developing on Windows (32-bit only), you need to install the USB driver for adb: + <li>If you're developing on 32-bit Windows, you need to install the 32-bit USB driver for adb. + The USB driver is included in the SDK package. To install it, follow these steps:</p> <ol> - <li>Download the driver ZIP file - (<a href="http://dl.google.com/android/android_usb_windows.zip">android_usb_windows.zip</a>) - and unzip it.</li> - <li>Connect your Android device via USB. When the <em>Found New Hardware Wizard</em> appears, you'll be asked if you'd like Windows Update to search for software, select <em>No, not this time</em> and click <b>Next</b>.</li> + <li>Connect your Android device via USB. When the <em>Found New Hardware Wizard</em> appears, + you'll be asked if you'd like Windows Update to search for software. Select <em>No, not this + time</em> and click <b>Next</b>.</li> <li>Select <em>Install from a list or specified location</em> and click <b>Next</b>.</li> - <li>Select <em>Search for the best driver in these locations</em>. Browse and select the unzipped file.</li> - <li>Click <b>Finish</b>. You're all set.</li> + <li>Select <em>Search for the best driver in these locations</em>. Browse to the <code>usb_driver/x86</code> in the SDK package (<code><sdk>\usb_driver\x86</code>).</li> + <li>Click <b>Finish</b>. The system should install the driver files as necessary. Your machine may require a reboot.</li> + </ol> + </li> + <li>If you're developing on 64-bit Windows Vista, you need to install the 64-bit USB driver for adb. + The USB driver is included in the SDK package. To install it, follow these steps:</p> + <ol> + <li>Connect your Android device via USB. When the <em>Found New Hardware Wizard</em> appears, + you'll be asked if you'd like Windows Update to search for software. Select <em>No, not this + time</em> and click <b>Next</b>.</li> + <li>Select <em>Install from a list or specified location</em> and click <b>Next</b>.</li> + <li>Select <em>Search for the best driver in these locations</em>. Browse to the <code>usb_driver/amd64</code> in the SDK package (<code><sdk>\usb_driver\amd64</code>).</li> + <li>Click <b>Finish</b>. The system should install the driver files as necessary. Your machine may require a reboot.</li> </ol> </li> <li>If you're developing on Mac OS X, it just works. Skip this step.</li> diff --git a/docs/html/guide/developing/eclipse-adt.jd b/docs/html/guide/developing/eclipse-adt.jd index 7177395..8c482ee 100644 --- a/docs/html/guide/developing/eclipse-adt.jd +++ b/docs/html/guide/developing/eclipse-adt.jd @@ -1,17 +1,28 @@ 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 +<p>The Android Development Tools (ADT) plugin for Eclipse adds powerful extensions to the Eclipse integrated development environment. It allows you to create and debug Android applications easier and faster. If you use Eclipse, the ADT plugin gives you an incredible boost in developing Android applications:</p> + +<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: take screenshots, manage port-forwarding, set breakpoints, and view thread and process informationd irectly from Eclipse.</li> + <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>To begin developing Android applications in the Eclipse IDE with ADT, you first need to download the Eclipse IDE and then download and install the ADT plugin. To do so, follow the steps given in <a href="{@docRoot}sdk/1.1_r1/installing.html#installingplugin">Installing the ADT Plugin</a>, in the installation documentation included with your SDK package. </p> + +<p>Once you've installed the ADT plugin, you begin by creating 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. For complete information, see the installation documentation included in your SDK package. </p> +before using the instructions below. </p> <a name="creatingaproject" id="creatingaproject"></a> -<h3>Creating an Android Project</h3> +<h2>Creating an Android Project</h2> <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> @@ -49,7 +60,7 @@ Eclipse project for new or existing code. To create the project, follow these st <a name="launchconfig" id="launchconfig"></a> -<h3>Creating a Launch Configuration </h3> +<h2>Creating a Launch Configuration </h2> <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> @@ -78,9 +89,45 @@ Eclipse project for new or existing code. To create the project, follow these st </ol> + +<h2 id="sign_in_adt">Setting Up Application Signing</h2> + +<p>As you begin developing Android applications, you should understand that all +Android applications must be digitally signed before the system will install +them on the emulator or an actual device. </p> + +<p>The ADT plugin helps you get started quickly by signing your .apk files with +a debug key, prior to installing them on the emulator. This means that you can +compile your application and install it on the emulator without having to +generate your own private key. However, please note that if you intend to +publish your application, you <em>must</em> sign the application with your own +private key, rather than the debug key generated by the SDK tools. </p> + +<p>To sign your applications, the ADT plugin requires the Keytool utility +included in the JDK. To set up your development environment for +signing, you need to make sure that Keytool is available on your +machine that the ADT plugin knows how to find it. </p> + +<p>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>In all cases, please read and understand <a +href="{@docRoot}guide/publishing/app-signing.html">Signing Your +Applications</a>, which provides an overview of application signing on Android +and what it means to you as an Android application developer. </p> + + <a name="installingrunningdebugging" id="installingrunningdebugging"></a> -<h3>Running and Debugging an Application</h3> +<h2>Running and Debugging an Application</h2> <p>Once you've set up the project and launch configuration for your application, you can run or debug it as described below.</p> @@ -98,7 +145,8 @@ From the Eclipse main menu, select <strong>Run</strong> > <strong>Run</strong </ul> - <h2 id="tips">Eclipse Tips </h2> + +<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 diff --git a/docs/html/guide/developing/instrumentation/index.jd b/docs/html/guide/developing/instrumentation/index.jd deleted file mode 100644 index 7ebd72e..0000000 --- a/docs/html/guide/developing/instrumentation/index.jd +++ /dev/null @@ -1,54 +0,0 @@ -page.title=Instrumentation -@jd:body - -<dl> - <dt><a href="inst-framework.html">Instrumentation Framework</a></dt> - <dt><a href="inst-testing.html">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/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 deleted file mode 100644 index 17eea61..0000000 --- a/docs/html/guide/developing/instrumentation/inst-framework.jd +++ /dev/null @@ -1,139 +0,0 @@ -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="inst-testing.html">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> - diff --git a/docs/html/guide/developing/instrumentation/inst-testing.jd b/docs/html/guide/developing/instrumentation/inst-testing.jd index 6f69344..2dc4daa 100644 --- a/docs/html/guide/developing/instrumentation/inst-testing.jd +++ b/docs/html/guide/developing/instrumentation/inst-testing.jd @@ -142,8 +142,6 @@ public class FrameworkInstrumentationTestRunner extends InstrumentationTestRunne <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" /> diff --git a/docs/html/guide/developing/other-ide.jd b/docs/html/guide/developing/other-ide.jd index 78871c5..7bcb509 100644 --- a/docs/html/guide/developing/other-ide.jd +++ b/docs/html/guide/developing/other-ide.jd @@ -2,9 +2,9 @@ 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> + <a href="{@docRoot}guide/developing/eclipse-adt.html">Eclipse with the Android + Development Tools (ADT) plugin</a>, provided in the SDK. The ADT 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 @@ -82,6 +82,45 @@ activity_name: ActivityName latest version of the application for you to deploy.</li> </ol> +<h2 id="sign_in_other">Setting Up Application Signing</h2> + +<p>As you begin developing Android applications, you should understand that all +Android applications must be digitally signed before the system will install +them on the emulator or an actual device. </p> + +<p>The Android build tools help you get started quickly by signing your .apk +files with a debug key, prior to installing them on the emulator. This means +that you can compile your application and install it on the emulator without +having to generate your own private key. However, please note that if you intend +to publish your application, you <em>must</em> sign the application with your +own private key, rather than the debug key generated by the SDK tools. </p> + +<p>To sign your applications, the ADT plugin requires the Keytool utility +included in the JDK. To set up your development environment for +signing, all you need to do is make sure that Keytool is available on your +machine that the build tools know how to find it. </p> + +<p>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>In all cases, please read and understand <a +href="{@docRoot}guide/publishing/app-signing.html">Signing Your +Applications</a>, which provides an overview of application signing on Android +and what it means to you as an Android application developer. </p> + + <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 @@ -122,7 +161,7 @@ activity_name: ActivityName 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> + include information on <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port"> + how to set up Eclipse to debug your project</a>. </li> </ol> diff --git a/docs/html/guide/developing/tools/adb.jd b/docs/html/guide/developing/tools/adb.jd index 50fb024..b111047 100644 --- a/docs/html/guide/developing/tools/adb.jd +++ b/docs/html/guide/developing/tools/adb.jd @@ -104,7 +104,7 @@ Emulator 2, adb: 5557 ... <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> +<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> diff --git a/docs/html/guide/developing/tools/adt.jd b/docs/html/guide/developing/tools/adt.jd index c3bd255..f28b24c 100644 --- a/docs/html/guide/developing/tools/adt.jd +++ b/docs/html/guide/developing/tools/adt.jd @@ -90,7 +90,7 @@ If you are having trouble downloading the ADT plugin after following the steps a 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="adt_download.html">Download the ADT zip file</a> (do not unpack it). +<li><a href="{@docRoot}sdk/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> diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 3e01172..ee56ebb 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -3,9 +3,9 @@ <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 style="color:gray;">The Android SDK</a></li> -<li><a style="color:gray;">Walkthrough for Developers</a></li> - <!-- quick overview of what it's like to develop on Android --> +<!-- <li><a style="color:gray;">The Android SDK</a></li> --> +<!-- <li><a style="color:gray;">Walkthrough for Developers</a></li> --> + <!-- quick overview of what it's like to develop on Android --> </ul> </li> @@ -15,15 +15,16 @@ </ul> <ul> <li class="toggle-list"> - <div><a href="<?cs var:toroot ?>guide/topics/views/index.html">Views and Layout</a></div> + <div><a href="<?cs var:toroot ?>guide/topics/ui/index.html">User Interface</a></div> <ul> - <li><a href="<?cs var:toroot ?>guide/topics/views/layout.html">Common Layout Objects</a></li> - <li><a href="<?cs var:toroot ?>guide/topics/views/declaring-layout.html">Declaring Layout</a></li> - <li><a href="<?cs var:toroot ?>guide/topics/views/binding.html">Binding to Data with AdapterView</a></li> - <li><a href="<?cs var:toroot ?>guide/topics/views/ui-events.html">Handling UI Events</a></li> - <li><a href="<?cs var:toroot ?>guide/topics/views/themes.html">Applying Styles and Themes</a></li> - <li><a href="<?cs var:toroot ?>guide/topics/views/custom-components.html">Building Custom Components</a></li> - <li><a href="<?cs var:toroot ?>guide/topics/views/how-android-draws.html">How Android Draws Views</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/ui/declaring-layout.html">Declaring Layout</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/ui/menus.html">Creating Menus</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/ui/layout-objects.html">Common Layout Objects</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/ui/binding.html">Binding to Data with AdapterView</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/ui/ui-events.html">Handling UI Events</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/ui/themes.html">Applying Styles and Themes</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/ui/custom-components.html">Building Custom Components</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/ui/how-android-draws.html">How Android Draws Views</a></li> </ul> </li> <li class="toggle-list"> @@ -36,11 +37,35 @@ <li><a href="<?cs var:toroot ?>guide/topics/intents/intents-filters.html">Intents and Intent Filtering</a></li> <li><a href="<?cs var:toroot ?>guide/topics/data/data-storage.html">Data Storage</a></li> <li><a href="<?cs var:toroot ?>guide/topics/providers/content-providers.html">Content Providers</a></li> - <li><a style="color:gray;">Notifications</a></li> +<!-- <li><a style="color:gray;">Notifications</a></li> --> <li><a href="<?cs var:toroot ?>guide/topics/security/security.html">Security and Permissions</a></li> <!-- <li><a style="color:gray;">Processes and Threads</a></li> --> <!-- <li><a style="color:gray;">Interprocess Communication</a></li> --> - <li><a href="<?cs var:toroot ?>guide/topics/manifest/manifest.html">The Manifest File</a></li> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a></div> + <ul> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/action-element.html"><action></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/activity-element.html"><activity></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/activity-alias-element.html"><activity-alias></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/application-element.html"><application></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/category-element.html"><category></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/data-element.html"><data></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/instrumentation-element.html"><instrumentation></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/intent-filter-element.html"><intent-filter></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/manifest-element.html"><manifest></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/meta-data-element.html"><meta-data></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/permission-element.html"><permission></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/permission-group-element.html"><permission-group></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/permission-tree-element.html"><permission-tree></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/provider-element.html"><provider></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/receiver-element.html"><receiver></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/service-element.html"><service></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/uses-library-element.html"><uses-library></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/uses-permission-element.html"><uses-permission></a></li> + <li><a href="<?cs var:toroot ?>guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></li> + </ul> + </li> </ul> <ul> <li class="toggle-list"> @@ -51,22 +76,22 @@ </ul> </li> <li><a href="<?cs var:toroot ?>guide/topics/media/index.html">Audio and Video</a></li> - <li class="toggle-list"> - <div><a href="<?cs var:toroot ?>guide/topics/sensors/index.html">Sensors</a></div> +<!-- <li class="toggle-list"> + <div><a style="color:gray;">Sensors</a></div> <ul> - <li><a href="<?cs var:toroot ?>guide/topics/sensors/camera.html">Camera</a></li> - <li><a href="<?cs var:toroot ?>guide/topics/sensors/compass.html">Compass</a></li> - <li><a href="<?cs var:toroot ?>guide/topics/sensors/accelerometer.html">Accelerometer</a></li> + <li><a style="color:gray;">Camera</a></li> + <li><a style="color:gray;">Compass</a></li> + <li><a style="color:gray;">Accelerometer</a></li> </ul> - </li> + </li> --> <li><a href="<?cs var:toroot ?>guide/topics/location/index.html">Location</a></li> - <li class="toggle-list"> - <div><a href="<?cs var:toroot ?>guide/topics/wireless/index.html">Wireless Controls</a></div> +<!-- <li class="toggle-list"> + <div><a style="color:gray;">Wireless Controls</a></div> <ul> - <li><a href="<?cs var:toroot ?>guide/topics/wireless/wifi.html">Wi-Fi</a></li> - <li><a href="<?cs var:toroot ?>guide/topics/wireless/bluetooth.html">Bluetooth</a></li> + <li><a style="color:gray;">Wi-Fi</a></li> + <li><a style="color:gray;">Bluetooth</a></li> </ul> - </li> + </li> --> <!-- <li><a style="color:gray;">Localization</a></li> --> </ul> </li> @@ -86,7 +111,7 @@ <li><a href="<?cs var:toroot ?>guide/developing/tools/aapt.html">aapt</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/adb.html">adb</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/othertools.html#activitycreator">activitycreator</a></li> - <li><a href="<?cs var:toroot ?>guide/developing/tools/adt.html">ADT Plugin</a></li> +<!-- <li><a href="<?cs var:toroot ?>guide/developing/tools/adt.html">ADT Plugin</a></li>--> <li><a href="<?cs var:toroot ?>guide/developing/tools/aidl.html" >aidl</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/ddms.html" >ddms</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/othertools.html#dx">dx</a></li> @@ -98,8 +123,8 @@ <li><a href="<?cs var:toroot ?>guide/developing/tools/adb.html#sqlite">sqlite3</a></li> <li><a href="<?cs var:toroot ?>guide/developing/tools/traceview.html" >Traceview</a></li> </ul></li> - <li><a href="<?cs var:toroot ?>guide/developing/instrumentation/index.html">Instrumentation</a></li> - <li><a style="color:gray;">JUnit</a></li> +<!-- <li><a href="<?cs var:toroot ?>guide/developing/instrumentation/index.html">Instrumentation</a></li> + <li><a style="color:gray;">JUnit</a></li> --> </ul> </li> @@ -118,18 +143,9 @@ <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/index.html">Design Goals</a></li> - <li><a style="color:gray;">User Interface Guidelines</a></li> +<!-- <li><a style="color:gray;">User Interface Guidelines</a></li> --> </ul> </li> ---> <li><h2>Tutorials</h2> <ul> @@ -155,4 +171,4 @@ <!-- buildToggleLists(); //--> -</script>
\ No newline at end of file +</script> diff --git a/docs/html/guide/index.jd b/docs/html/guide/index.jd index e723235..ecbf97b 100644 --- a/docs/html/guide/index.jd +++ b/docs/html/guide/index.jd @@ -1,62 +1,84 @@ -page.title=Get Started +page.title=The Developer's Guide @jd:body -<p>Welcome to the Android Developer Guide! The <strong>Dev Guide</strong> is your conceptual and practical -introduction to developing applications for Android. With this guide, you're free to explore -which ever topics interest you, based on your goals and experience.</p> - -<p>If you're new to Android, you're probably wondering what it takes to -write a "Hello, World" application. So here it is:</p> - -<pre> -package com.example.hello; - -import android.app.Activity; -import android.os.Bundle; -import android.widget.TextView; - -public class HelloWorld extends Activity { - - public void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - TextView tv = new TextView(this); - tv.setText("Hello, World"); - setContentView(tv); - } - -} -</pre> - -<p>That's the only code you need to write!</p> - -<h2 class="small-header">Not convinced?</h2> -<p>If you're still shouting "Show me the code!" then take a look at -more Android code in the <a href="{@docRoot}guide/tutorials/hello-world/index.html">Hello World Samples</a>.</p> - -<h2 class="small-header">Ready to start?</h2> -<p>If you're already convinced you want to develop on Android, -then we'll teach you how to build and run this "Hello, World" application in the -<a href="{@docRoot}guide/tutorials/hello-world.html">Hello World Introduction</a>.</p> - -<h2 class="small-header">Ready for more?</h2> -<p>Once you've got your feet wet (or just want to skip to the heart of Android), the following -sections of the Dev Guide will educate you on the Android ins, outs, idioms and techniques:</p> -<ul> - <li><em>Android Basics</em>: - Learn more about what Android is, what it offers, and how your application fits in.</li> - <li><em>Framework Topics</em>: - Become well versed in the practical matters of developing on Android — from drawing a UI, to storing data, - to drawing 3D graphics, and much more.</li> - <li><em>Developing</em>: - Learn more about developing with IDEs, using Android develop/debug tools, and testing.</li> - <li><em>Publishing</em>: - Learn how to get you application out there, for the world to enjoy!</li> - <li><em>Best Practices</em>: - Get some recommendations on preferred techniques to write the best applications.</li> - <li><em>Tutorials</em>: - Get help doing some of the basics, step by step.</li> - <li><em>Appendix</em>: - Flotsam and jetsam. Find some of those spare nuggets of information.</li> -</ul> - -<p>For more help, you should consider joining one or more of the Android discussion groups. See the <a href="{@docRoot}community/index.html">Community</a> for more information.</p> +<p> +Welcome to the <i>Android Dev Guide</i>! The Dev Guide is +a practical introduction to developing applications for Android. +It explores the concepts behind Android, the framework for +constructing an application, and the tools for developing, +testing, and publishing software for the platform. +</p> + +<p> +The Dev Guide holds most of the documentation for the Android +platform, except for reference material on the framework API. +For API specifications, go to the +<a href="{@docRoot}reference/packages.html">Reference</a> tab above. +</p> + +<p> +As you can see in the panel on the left, the Dev Guide is +divided into a handful of sections. They are: +<p> + +<dl> +<dt><b>Android Basics</b></dt> +<dd>An initial orientation to Android — what it is, +what it offers, and how your application fits in.</dd> + +<dt><b>Framework Topics</b></dt> +<dd>Discussions of particular parts of the Android framework +and API. For an overview of the framework, begin with +<a href="{@docRoot}guide/topics/fundamentals.html">Application +Fundamentals</a>. Then explore other topics — from +designing a user interface and setting up resources to storing +data and using permissions — as needed.</dd> + +<dt><b>Developing</b></dt> +<dd>Directions for using Android's development and debugging tools, +and for testing the results.</dd> + +<dt><b>Publishing</b></dt> +<dd>Instructions on how to prepare your application for deployment +and how to publish it when it's ready.</dd> + +<dt><b>Best Practices</b></dt> +<dd>Recommendations on preferred techniques for writing +applications that perform efficiently and work well for the +user.</dd> + +<dt><b>Tutorials and Samples</b></dt> +<dd>Step-by-step tutorials and sample code demonstrating how +an Android application is constructed.</dd> + +<dt><b>Appendix</b></dt> +<dd>Reference information and specifications, as well as FAQs, +a glossary of terms, and other information.</dd> +</dl> + +<p> +The first step in programming for Android is downloading the SDK +(software development kit). For instructions and information about +the kit, go to the <a href="{@docRoot}sdk/index.html">SDK</a> tab above. +</p> + +<p> +After you have the SDK, begin by looking over the Dev Guide. +If you want to start by getting a quick look at the code, the short +<a href="{@docRoot}guide/tutorials/hello-world.html">Hello World</a> +tutorial walks you through a standard "Hello, World" application as +it would be written for the Android platform. The +<a href="{@docRoot}guide/topics/fundamentals.html">Application +Fundamentals</a> document is a good place to start for an +understanding of the application framework. +</p> + + +<p> +For additional help, consider joining one or more of the Android +discussion groups. Go to the +<a href="{@docRoot}community/index.html">Community</a> tab above +for more information. +</p> + +<p>To return to this page later, just click the "Dev Guide" tab while any Dev Guide page is loaded. </p>
\ No newline at end of file diff --git a/docs/html/guide/practices/design/seamlessness.jd b/docs/html/guide/practices/design/seamlessness.jd index caf0d6a..a6c1641 100644 --- a/docs/html/guide/practices/design/seamlessness.jd +++ b/docs/html/guide/practices/design/seamlessness.jd @@ -164,7 +164,7 @@ 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, read <a href="{@docRoot}guide/topics/views/themes.html">Applying Styles and Themes</a>.</p> +the details, read <a href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p> <h2 id="flexui">Design Your UI to Work with Multiple Screen Resolutions</h2> @@ -208,7 +208,6 @@ 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 @@ -220,8 +219,6 @@ 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 diff --git a/docs/html/guide/publishing/preparing.jd b/docs/html/guide/publishing/preparing.jd index 1f3c624..267cba2 100644 --- a/docs/html/guide/publishing/preparing.jd +++ b/docs/html/guide/publishing/preparing.jd @@ -175,7 +175,7 @@ MapView elements</h3> <div class="sidebox" style="margin-bottom:.5em;"><p>For complete information about getting a Maps API Key, see <a -href="{@docRoot}guide/developing/mapkey.html">Obtaining a Maps API +href="{@docRoot}guide/topics/location/geo/mapkey.html">Obtaining a Maps API Key</a>.<br></p></div> <p>If your application uses one or more diff --git a/docs/html/guide/publishing/publishing.jd b/docs/html/guide/publishing/publishing.jd index 1a022dd..aed244e 100644 --- a/docs/html/guide/publishing/publishing.jd +++ b/docs/html/guide/publishing/publishing.jd @@ -21,10 +21,10 @@ page.title=Publishing Your Applications <li><a href="#marketupgrade">Publishing Upgrades on Android Market</a> <li><a href="#marketintent">Using Intents to Launch the Market Application</a></li> </ol></li> - +<!-- <li><span style="color:ccc">Publishing on Other Hosted Services</a></li> <li><span style="color:ccc">Publishing through a Web Server</a></li> - +--> </ol> <h2>See also</h2> diff --git a/docs/html/guide/publishing/versioning.jd b/docs/html/guide/publishing/versioning.jd index 1f4df0b..d106266 100644 --- a/docs/html/guide/publishing/versioning.jd +++ b/docs/html/guide/publishing/versioning.jd @@ -13,12 +13,20 @@ page.title=Versioning Your Applications <li>Determine your versioning strategy early in the development process, including considerations for future releases.</li> </ul> +<h2>In this document</h2> + +<ol> +<li><a href="#appversion">Setting Application Version</a></li> +<li><a href="#minsdkversion">Specifying Minimum System API Version</a> +</ol> + + <h2>See also</h2> <ol> <li><a href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish Your Application</a></li> <li><a href="{@docRoot}guide/publishing/publishing.html#market">Publishing On Android Market</a></li> -<li><a href="{@docRoot}guide/topics/manifest/manifest.html">The Manifest File</a></li> +<li><a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a></li> </ol> </div> @@ -40,11 +48,17 @@ users. A publishing service may also need to check the application version to determine compatibility and establish upgrade/downgrade relationships.</li> </ul> -<p>The Android system itself <em>does not ever</em> check the version +<p>The Android system itself <em>does not ever</em> check the application version information for an application, such as to enforce restrictions on upgrades, compatibility, and so on. Instead, only users or applications themselves are -responsible for enforcing any version restrictions. </p> +responsible for enforcing any version restrictions for applications themselves. </p> +<p>The Android system <em>does</em> check any system version compatibility expressed +by an application in its manifest, in the <code>minSdkVersion</code> attribute. This +allows an application to specify the minimum system API with which is compatible. +For more information see <a href="#minsdkversion">Specifying Minimum System API Version</a>. + +<h2 id="appversioning">Setting Application Version</h2> <p>To define the version information for your application, you set attributes in the application's manifest file. Two attributes are available, and you should always define values for both of them: </p> @@ -111,8 +125,15 @@ applications use the {@link android.content.pm.PackageManager#getPackageInfo(java.lang.String, int)} method of {@link android.content.pm.PackageManager PackageManager}. </p> +<h2 id="#minsdkversion">Specifying Minimum System API Version</h2>. + <p>If your application requires a specific minimum version of the Android -platform, you can also specify that in the manifest file: </p> +platform, you can specify that version as an API Level identifier +in the application's manifest file. Doing so ensures that your +application can only be installed on devices that +are running a compatible version of the Android system. </p> + +<p>To specify the minimum system version in the manifest, use this attribute: </p> <ul> <li><code>android:minSdkVersion</code> — An integer value corresponding to @@ -129,7 +150,6 @@ that your application is compatible with all platform versions.</p></li> <p>To specify a minimum platform version for your application, add a <code><uses-sdk></code> element as a child of <code><manifest></code>, then define the -<code>android:minSdkVersion</code> as an attribute. Currently, only one platform -version has been released for mobile devices — that version is "1". For -this reason, you do not need to define this attribute in your application and, -at this point, defining it is <em>not recommended</em>.</p>
\ No newline at end of file +<code>android:minSdkVersion</code> as an attribute. </p> + +<p>For more information, also see the <a href="{@docRoot}sdk/android-1.1.html">Android System Image 1.1 Version Notes</a>.</p>
\ No newline at end of file diff --git a/docs/html/guide/topics/fundamentals.jd b/docs/html/guide/topics/fundamentals.jd index 7118ceb..3e1501c 100644 --- a/docs/html/guide/topics/fundamentals.jd +++ b/docs/html/guide/topics/fundamentals.jd @@ -17,6 +17,7 @@ page.title=Application Fundamentals <li><a href="#appcomp">Application Components</a> <ol> <li><a href="#actcomp">Activating components: intents</a></li> + <li><a href="#endcomp">Shutting down components</a></li> <li><a href="#manfile">The manifest file</a></li> <li><a href="#ifilters">Intent filters</a></li> </ol></li> @@ -27,8 +28,14 @@ page.title=Application Fundamentals <li><a href="#clearstack">Clearing the stack</a></li> <li><a href="#starttask">Starting tasks</a></li> </ol></li> -<li><a href="#procthread">Processes and Threads</a></li> -<li><a href="#lcycles">Lifecycles</a> +<li><a href="#procthread">Processes and Threads</a> + <ol> + <li><a href="#procs">Processes</a></li> + <li><a href="#threads">Threads</a></li> + <li><a href="#rpc">Remote procedure calls</a></li> + <li><a href="#tsafe">Thread-safe methods</a></li> + </ol></li> +<li><a href="#lcycles">Component Lifecycles</a> <ol> <li><a href="#actlife">Activity lifecycle</a></li> <li><a href="#servlife">Service lifecycle</a></li> @@ -40,13 +47,14 @@ page.title=Application Fundamentals <p> Android applications are written in the Java programming language. -The compiled Java code — along with data and -resource files required by the application and a manifest describing the -application — is bundled by the aapt tool into an <i>Android package</i>, -an archive file marked by an {@code .apk} suffix. This file is the vehicle -for distributing the application and installing it on mobile devices; it's -the file users download to their devices. All the code in a single -{@code .apk} file is considered to be one <i>application</i>. +The compiled Java code — along with any data and resource +files required by the application — is bundled by the +<a href="{@docRoot}guide/developing/tools/aapt.html"><code>aapt</code> +tool</a> into an <i>Android package</i>, an archive file +marked by an {@code .apk} suffix. This file is the vehicle +for distributing the application and installing it on mobile devices; +it's the file users download to their devices. All the code in a +single {@code .apk} file is considered to be one <i>application</i>. </p> <p> @@ -76,7 +84,7 @@ in the same Linux process, sharing the same VM. </p> -<h2><a name="appcomp"></a>Application Components</h2> +<h2 id="appcomp">Application Components</h2> <p> A central feature of Android is that one application can make use of elements @@ -125,24 +133,31 @@ current activity start the next one. Each activity is given a default window to draw in. Typically, the window fills the screen, but it might be smaller than the screen and float on top of other windows. An activity can also make use of additional windows — -for example, a window that presents users with vital information when they -select a particular item on-screen, or a pop-up dialog that calls for a user -response in the midst of the activity. +for example, a pop-up dialog that calls for a user response in the midst of +the activity, or a window that presents users with vital information when they +select a particular item on-screen. </p> <p> The visual content of the window is provided by a hierarchy of views — objects derived from the base {@link android.view.View} class. Each view -draws in a particular rectangular space within the window and responds to user -actions directed at that space. Android has a number of ready-made views that -you can use — including buttons, text fields, scroll bars, menu items, -check boxes, and more. A view hierarchy is placed within the activity's -window by the <code>{@link android.app.Activity#setContentView -Activity.setContentView()}</code> method. The <i>content view</i> -is the View object at the root of the hierarchy. -(See <a href="{@docRoot}guide/topics/views/index.html">Views and Layout</a> -for more information on views and the heirarchy.) -</p></dd> +controls a particular rectangular space within the window. Parent views +contain and organize the layout of their children. Leaf views (those at the +bottom of the hierarchy) draw in the rectangles they control and respond to +user actions directed at that space. Thus, views are where the activity's +interaction with the user takes place. For example, a view might display +a small image and initiate an action when the user taps that image. Android +has a number of ready-made views that you can use — including buttons, +text fields, scroll bars, menu items, check boxes, and more. +</p> + +<p> +A view hierarchy is placed within an activity's window by the +<code>{@link android.app.Activity#setContentView Activity.setContentView()}</code> +method. The <i>content view</i> is the View object at the root of the hierarchy. +(See the separate <a href="{@docRoot}guide/topics/ui/index.html">User Interface</a> +document for more information on views and the hierarchy.) +</p> <p><dt><b>Services</b></dt> <dd>A <i>service</i> doesn't have a visual user interface, but rather runs in @@ -152,13 +167,13 @@ data over the network or calculate something and provide the result to activitie that need it. Each service extends the {@link android.app.Service} base class. <p> -A good example is a media player playing songs from a play list. The player +A prime example is a media player playing songs from a play list. The player application would probably have one or more activities that allow the user to choose songs and start playing them. However, the music playback itself would not be handled by an activity because users will expect the music to keep playing even after they leave the player and begin something different. To keep the music going, the media player activity could start a service to run -in the background. The system will then keep the music playback service running +in the background. The system would then keep the music playback service running even after the activity that started it leaves the screen. </p> @@ -180,8 +195,10 @@ user interface, they often spawn another thread for time-consuming tasks <dd>A <i>broadcast receiver</i> is a component that does nothing but receive and react to broadcast announcements. Many broadcasts originate in system code — for example, announcements that the timezone has changed, -that the battery is low, that the keyboard has been exposed, or that the user -changed a language preference. +that the battery is low, that a picture has been taken, or that the user +changed a language preference. Applications can also initiate broadcasts +— for example, to let other applications know that some data has been +downloaded to the device and is available for them to use. <p> An application can have any number of broadcast receivers to respond to any @@ -227,19 +244,19 @@ is available, creating the instance if necessary. </p> -<h3><a name="actcomp"></a>Activating components: intents</h3> +<h3 id="actcomp">Activating components: intents</h3> <p> Content providers are activated when they're targeted by a request from a ContentResolver. The other three components — activities, services, and broadcast receivers — are activated by asynchronous messages called <i>intents</i>. An intent is an {@link android.content.Intent} -object that holds the content of the message. Among other things, it names -the action an activity or service is being requested to take and specifies -the URI of the data to act on. For broadcast receivers, it names the -action being announced. For example, it might convey a request for +object that holds the content of the message. For activities and services, +it names the action being requested and specifies the URI of the data to +act on, among other things. For example, it might convey a request for an activity to present an image to the user or let the user edit some -text. Or it might announce to interested broadcast receivers that the +text. For broadcast receivers, the Intent object names the action being +announced. For example, it might announce to interested parties that the camera button has been pressed. </p> @@ -281,13 +298,19 @@ onStart()}</code> method and passes it the Intent object.</p> Similarly, an intent can be passed to <code>{@link android.content.Context#bindService Context.bindService()}</code> to establish an ongoing connection between the calling component and a -target service. It initiates the service if it's not already running. -The service receives the Intent object in +target service. The service receives the Intent object in an <code>{@link android.app.Service#onBind onBind()}</code> call. -For example, an activity might establish a connection with the music -playback service mentioned earlier so that it could provide the user -with an interface for controlling the playback. The activity would -call {@code bindService()} to set up that connection. +(If the service is not already running, {@code bindService()} can +optionally start it.) For example, an activity might establish a connection +with the music playback service mentioned earlier so that it can provide +the user with the means (a user interface) for controlling the playback. +The activity would call {@code bindService()} to set up that connection, +and then call methods defined by the service to affect the playback. +</p> + +<p> +A later section, <a href="#rpc">Remote procedure calls</a>, has more details +about binding to a service. </p> </li> @@ -304,12 +327,49 @@ android.content.BroadcastReceiver#onReceive onReceive()}</code> methods.</p></li </ul> <p> -For more on intent messages, see the separate article, <a -href="{@docRoot}guide/topics/intents/intents-filters.html">Intents +For more on intent messages, see the separate article, +<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a>. +</p> -<h3><a name="manfile"></a>The manifest file</h3> +<h3 id="endcomp">Shutting down components</h3> + +<p> +A content provider is active only while it's responding to a request from +a ContentResolver. And a broadcast receiver is active only while it's +responding to a broadcast message. So there's no need to explicitly shut +down these components. +</p> + +<p> +Activities, on the other hand, provide the user interface. They're +in a long-running conversation with the user and may remain active, +even when idle, as long as the conversation continues. Similarly, services +may also remain running for a long time. So Android has methods to shut +down activities and services in an orderly way: +</p> + +<ul> +<li>An activity can be shut down by calling its +<code>{@link android.app.Activity#finish finish()}</code> method. One activity can +shut down another activity (one it started with {@code startActivityForResult()}) by +calling <code>{@link android.app.Activity#finishActivity finishActivity()}</code>.</li> + +<li>A service can be stopped by calling its +<code>{@link android.app.Service#stopSelf stopSelf()}</code> method, or by calling +<code>{@link android.content.Context#stopService Context.stopService()}</code>.</li> +</ul> + +<p> +Components might also be shut down by the system when they are no longer being +used or when Android must reclaim memory for more active components. A later +section, <a href="#lcycles">Component Lifecycles</a>, discusses this +possibility and its ramifications in more detail. +</p> + + +<h3 id="manfile">The manifest file</h3> <p> Before Android can start an application component, it must learn that @@ -344,8 +404,9 @@ components. For example, an activity might be declared as follows: </manifest></pre> <p> -The {@code name} attribute of the {@code <activity>} element -names the {@link android.app.Activity} subclass that implements the +The {@code name} attribute of the +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> +element names the {@link android.app.Activity} subclass that implements the activity. The {@code icon} and {@code label} attributes point to resource files containing an icon and label that can be displayed to users to represent the activity. @@ -353,24 +414,28 @@ to users to represent the activity. <p> The other components are declared in a similar way — -{@code <service>} elements for services, {@code <receiver>} -elements for broadcast receivers, and {@code <provider>} elements -for content providers. Activities, services, and content providers that -are not declared in the manifest are not visible to the system and are -consequently never run. Broadcast receivers can be declared in the -manifest, or they can be created dynamically in code (as -{@link android.content.BroadcastReceiver} objects) -and registered with the system by calling <code>{@link -android.content.Context#registerReceiver Context.registerReceiver()}</code>. +<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> +elements for services, +<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> +elements for broadcast receivers, and +<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> +elements for content providers. Activities, services, and content providers +that are not declared in the manifest are not visible to the system and are +consequently never run. However, broadcast receivers can either be +declared in the manifest, or they can be created dynamically in code +(as {@link android.content.BroadcastReceiver} objects) +and registered with the system by calling +<code>{@link android.content.Context#registerReceiver Context.registerReceiver()}</code>. </p> <p> For more on how to structure a manifest file for your application, see -<a href="{@docRoot}guide/topics/manifest/manifest.html">The Manifest File</a>. +<a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The +AndroidManifest.xml File</a>. </p> -<h3><a name="ifilters"></a>Intent filters</h3> +<h3 id="ifilters">Intent filters</h3> <p> An Intent object can explicitly name a target component. If it does, @@ -442,7 +507,7 @@ and Intent Filters</a>. </p> -<h2><a name="acttask"></a>Activities and Tasks</h2> +<h2 id="acttask">Activities and Tasks</h2> <p> As noted earlier, one activity can start another, including one defined @@ -467,14 +532,14 @@ the one that is the focus for user actions. When one activity starts another, the new activity is pushed on the stack; it becomes the running activity. The previous activity remains in the stack. When the user presses the BACK key, the current activity is popped from the stack, and the previous one resumes as -the running activity. Activities in the stack are never rearranged, only -pushed and popped. +the running activity. </p> <p> The stack contains objects, so if a task has more than one instance of the same Activity subclass open — multiple map viewers, for example — the -stack has a separate entry for each instance. +stack has a separate entry for each instance. Activities in the stack are never +rearranged, only pushed and popped. </p> <p> @@ -505,7 +570,8 @@ The behavior just described is the default behavior for activities and tasks. But there are ways to modify almost all aspects of it. The association of activities with tasks, and the behavior of an activity within a task, is controlled by the interaction between flags set in the Intent object that -started the activity and attributes set in the activity's {@code <activity>} +started the activity and attributes set in the activity's +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element in the manifest. Both requester and respondent have a say in what happens. </p> @@ -529,19 +595,19 @@ The principal {@code <activity>} attributes are: <p> The following sections describe what some of these flags and attributes do, -and how they interact. +how they interact, and what considerations should govern their use. </p> -<h3><a name="afftask"></a>Affinities and new tasks</h3> +<h3 id="afftask">Affinities and new tasks</h3> <p> By default, all the activities in an application have an <i>affinity</i> for each other — that is, there's a preference for them all to belong to the same task. However, an individual affinity can be set for each activity -with the {@code taskAffinity} attribute. Activities defined in different -applications can share an affinity, or activities defined in the same -application can be assigned different affinities. +with the {@code taskAffinity} attribute of the {@code <activity>} element. +Activities defined in different applications can share an affinity, or activities +defined in the same application can be assigned different affinities. The affinity comes into play in two circumstances: When the Intent object that launches an activity contains the {@code FLAG_ACTIVITY_NEW_TASK} flag, and when an activity has its {@code allowTaskReparenting} attribute set @@ -550,26 +616,28 @@ to "{@code true}". <dl> <dt>The <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> flag</dt> -<dd>As mentioned earlier, a new activity is, by default, launched into +<dd>As described earlier, a new activity is, by default, launched into the task of the activity that called {@code startActivity()}. It's pushed onto the same stack as the caller. However, if the Intent object passed to {@code startActivity()} contains the {@code FLAG_ACTIVITY_NEW_TASK} flag, the system looks for a different task to house the new activity. Often, as the name of the flag implies, it's a new task. However, it -doesn't have to be. If there's an existing task with the same affinity -as the new activity, the activity is launched into that task. If not, -it begins a new task.</dd> - -<dt>The {@code allowTaskReparenting} attribute</dt> -<dd>If an activity has its {@code allowTaskReparenting} attribute is -set to "{@code true}", it can move from the task it starts in to the task +doesn't have to be. If there's already an existing task with the same +affinity as the new activity, the activity is launched into that task. If +not, it begins a new task.</dd> + +<dt>The <code><a +href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> +attribute</dt> +<dd>If an activity has its {@code allowTaskReparenting} attribute set +to "{@code true}", it can move from the task it starts in to the task it has an affinity for when that task comes to the fore. For example, suppose that an activity that reports weather conditions in selected cities is defined as part of a travel application. It has the same affinity as other activities in the same application (the default affinity) and it allows reparenting. One of your activities starts the weather reporter, so it initially belongs to the same task as -your activity. However, when the travel application, next comes forward, +your activity. However, when the travel application next comes forward, the weather reporter will be reassigned to and displayed with that task.</dd> </dl> @@ -580,65 +648,116 @@ affinities to the activities associated with each of them. </p> -<h3><a name="lmodes"></a>Launch modes</h3> +<h3 id="lmodes">Launch modes</h3> <p> There are four different launch modes that can be assigned to an {@code -<activity>} element's {@code launchMode} attribute: +<activity>} element's +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">launchMode</a></code> +attribute: </p> -<p style="margin-left: 2em">"{@code standard}" (the default value) +<p style="margin-left: 2em">"{@code standard}" (the default mode) <br>"{@code singleTop}" <br>"{@code singleTask}" <br>"{@code singleInstance}"</p> <p> -The launch mode determines three things: +The modes differ from each other on these four points: </p> <ul> -<li>Whether the activity can belong to a task that includes other -activities. The answer is yes for all the modes except -"{@code singleInstance}". A "{@code singleInstance}" activity is always -the only activity in its task. If it tries to launch another activity, -that activity is assigned to a different task — as if {@code -FLAG_ACTIVITY_NEW_TASK} was in the intent.</li> - -<li><p>Whether the activity always begins a task. For "{@code singleTask}" -and "{@code singleInstance}" the answer is yes. They mark activities that -can only be the root activities of a task; they define a task. In contrast, -"{@code standard}" and "{@code singleTop}" activities can belong to any task. + +<li><b>Which task will hold the activity that responds to the intent</b>. +For the "{@code standard}" and "{@code singleTop}" modes, it's the task that +originated the intent (and called +<code>{@link android.content.Context#startActivity startActivity()}</code>) +— unless the Intent object contains the +<code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> flag. +In that case, a different task is chosen as described in the previous +section, <a href="#afftask">Affinities and new tasks</a>. + +<p> +In contrast, the "{@code singleTask}" and "{@code singleInstance}" modes mark +activities that are always at the root of a task. They define a task; they're +never launched into another task. +</p> + +<li><p><b>Whether there can be multiple instances of the activity</b>. +A "{@code standard}" or "{@code singleTop}" activity can be instantiated +many times. They can belong to multiple tasks, and a given task can have +multiple instances of the same activity. +</p> + +<p> +In contrast, "{@code singleTask}" and "{@code singleInstance}" activities +are limited to just one instance. Since these activities are at the root +of a task, this limitation means that there is never more than a single +instance of the task on the device at one time. +</p> + +<li><p><b>Whether the instance can have other activities in its task</b>. +A "{@code singleInstance}" activity stands alone as the only activity in its +task. If it starts another activity, that activity will be launched into a +different task regardless of its launch mode — as if {@code +FLAG_ACTIVITY_NEW_TASK} was in the intent. In all other respects, the +"{@code singleInstance}" mode is identical to "{@code singleTask}".</p> + +<p> +The other three modes permit multiple activities to belong to the task. +A "{@code singleTask}" activity will always be the root activity of the task, +but it can start other activities that will be assigned to its +task. Instances of "{@code standard}" and "{@code singleTop}" +activities can appear anywhere in a stack. </p></li> -<li><p>Whether an existing instance of the activity can handle new -intents. The answer is yes for all the modes except "{@code standard}". -Existing "{@code singleTask}" and "{@code singleInstance}" activities -handle all new intents that come their way; a new instance is never -created. In the case of "{@code singleTask}", all other activities in -the task are popped from the stack, so that the root "{@code singleTask}" -activity is at the top and in position to respond to the intent. +<li><b>Whether a new instance of the class will be launched +to handle a new intent</b>. For the default "{@code standard}" mode, a +new instance is created to respond to every new intent. Each instance +handles just one intent. For the "{@code singleTop}" mode, an existing +instance of the class is re-used to handle a new intent if it resides +at the top of the activity stack of the target task. If it does not +reside at the top, it is not re-used. Instead, a new instance +is created for the new intent and pushed on the stack. + +<p> +For example, suppose a task's activity stack consists of root activity A with +activities B, C, and D on top in that order, so the stack is A-B-C-D. An intent +arrives for an activity of type D. If D has the default "{@code standard}" launch +mode, a new instance of the class is launched and the stack becomes A-B-C-D-D. +However, if D's launch mode is "{@code singleTop}", the existing instance is +expected to handle the new intent (since it's at the top of the stack) and the +stack remains A-B-C-D. </p> <p> -If a "{@code singleTop}" activity is at the -top of its stack, that object is expected to handle any new intents. -However, if it's farther down the stack, a new instance is created for -the intent and pushed on the stack. +If, on the other hand, the arriving intent is for an activity of type B, a new +instance of B would be launched no matter whether B's mode is "{@code standard}" +or "{@code singleTop}" (since B is not at the top of the stack), so the resulting +stack would be A-B-C-D-B. </p> <p> -In contrast, a new instance of a "{@code standard}" activity is always -created for each new intent. +As noted above, there's never more than one instance of a "{@code singleTask}" +or "{@code singleInstance}" activity, so that instance is expected to handle +all new intents. A "{@code singleInstance}" activity is always at the top of +the stack (since it is the only activity in the task), so it is always in +position to handle the intent. However, a "{@code singleTask}" activity may +or may not have other activities above it in the stack. If it does, it is not +in position to handle the intent, and the intent is dropped. (Even though the +intent is dropped, its arrival would have caused the task to come to the +foreground, where it would remain.) </p> </li> + </ul> <p> When an existing activity is asked to handle a new intent, the Intent -object is passed to the activity in an <code>{@link android.app.Activity#onNewIntent -onNewIntent()}</code> call. (The intent object that originally started the -activity can be retrieved by calling -<code>{@link android.app.Activity#getIntent getIntent()}</code>.) +object is passed to the activity in an +<code>{@link android.app.Activity#onNewIntent onNewIntent()}</code> call. +(The intent object that originally started the activity can be retrieved by +calling <code>{@link android.app.Activity#getIntent getIntent()}</code>.) </p> <p> @@ -651,12 +770,12 @@ return to what that instance was doing before the new intent arrived. <p> For more on launch modes, see -<a href="{@docRoot}guide/topics/manifest/manifest.html">The +<a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a> </p> -<h3><a name="clearstack"></a>Clearing the stack</h3> +<h3 id="clearstack">Clearing the stack</h3> <p> If the user leaves a task for a long time, the system clears the task of all @@ -676,7 +795,7 @@ control this behavior and modify it: <dt>The {@code alwaysRetainTaskState} attribute</dt> <dd>If this attribute is set to "{@code true}" in the root activity of a task, the default behavior just described does not happen. -Activities are retained in the stack even after a long period.</dd> +The task retains all activities in its stack even after a long period.</dd> <dt>The {@code clearTaskOnLaunch} attribute</dt> <dd>If this attribute is set to "{@code true}" in the root activity of a task, @@ -690,7 +809,7 @@ initial state, even after a momentary absence.</dd> single activity, not an entire task. And it can cause any activity to go away, including the root activity. When it's set to "{@code true}", the activity remains part of the task only for the current session. If the user -leaves and then relaunches the task, it no longer is present.</dd> +leaves and then returns to the task, it no longer is present.</dd> </dl> <p> @@ -700,7 +819,11 @@ android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP FLAG_ACTIVITY_CLEAR_TOP}</code> flag, and the target task already has an instance of the type of activity that should handle the intent in its stack, all activities above that instance are cleared away so that it stands at the top of the stack and can respond -to the intent. +to the intent. +If the launch mode of the designated activity is "{@code standard}", it too +will be removed from the stack, and a new instance will be launched to handle +the incoming intent. That's because a new instance is always created for +a new intent when the launch mode is "{@code standard}". </p> <p> @@ -711,7 +834,7 @@ a position where it can respond to the intent. </p> -<h3><a name="starttask"></a>Starting tasks</h3> +<h3 id="starttask">Starting tasks</h3> <p> An activity is set up as the entry point for a task by giving it @@ -731,7 +854,7 @@ and then come back to it later. For this reason, the two launch modes that mark activities as always initiating a task, "{@code singleTask}" and "{@code singleInstance}", should be used only when the activity has a {@code MAIN} and {@code LAUNCHER} filter. -Imagine, for example, what could happen if the filter is missing. +Imagine, for example, what could happen if the filter is missing: An intent launches a "{@code singleTask}" activity, initiating a new task, and the user spends some time working in that task. The user then presses the HOME key. The task is now ordered behind and obscured by the home @@ -760,7 +883,7 @@ See <a href="#clearstack">Clearing the stack</a>, earlier. </p> -<h2><a name="procthread"></a>Processes and Threads</h2> +<h2 id="procthread">Processes and Threads</h2> <p> When the first of an application's components needs to be run, Android @@ -769,12 +892,15 @@ all components of the application run in that process and thread. </p> <p> -However, you can arrange for components to run in other processes as well as -spawn additional threads: +However, you can arrange for components to run in other processes, and you +can spawn additional threads for any process. </p> -<ul> -<li>The process where a component runs is controlled by the manifest file. + +<h3 id="procs">Processes</h3> + +<p> +The process where a component runs is controlled by the manifest file. The component elements — {@code <activity>}, {@code <service>}, {@code <receiver>}, and {@code <provider>} — each have a {@code process} attribute that can specify a process @@ -784,26 +910,27 @@ while others do not. They can also be set so that components of different applications run in the same process — provided that the applications share the same Linux user ID and are signed by the same authorities. The {@code <application>} element also has a {@code process} attribute, -for setting a default value that applies to all components.</li> - -<li><p>Threads are created in code using standard Java {@link java.lang.Thread} -objects. Android provides a number of convenience classes for managing threads -— {@link android.os.Looper} for running a message loop within a thread, -{@link android.os.Handler} for processing messages, and -{@link android.os.HandlerThread} for setting up a thread with a message loop.</p> +for setting a default value that applies to all components. +</p> <p> -Even though you may confine your application to a single process, there may be -times when you will need to spawn a thread to do some background work. Since the -user interface must always be quick to respond to user actions, the -thread that hosts an activity should not also host time-consuming operations like -network downloads, or anything else that may not be completed quickly. -</p></li> -</ul> +All components are instantiated in the main thread of the specified +process, and system calls to the component are dispatched from that +thread. Separate threads are not created for each instance. Consequently, +methods that respond to those calls — methods like +<code>{@link android.view.View#onKeyDown View.onKeyDown()}</code> that report +user actions and the lifecycle notifications discussed later in the +<a href="#lcycles">Component Lifecycles</a> section — always run in the +main thread of the process. This means +that no component should perform long or blocking operations (such as networking +operations or computation loops) when called by the system, since this will block +any other components also in the process. You can spawn separate threads for +long operations, as discussed under <a href="#threads">Threads</a>, next. +</p> <p> Android may decide to shut down a process at some point, when memory is -low and required by other applications that are more immediately serving +low and required by other processes that are more immediately serving the user. Application components running in the process are consequently destroyed. A process is restarted for those components when there's again work for them to do. @@ -816,17 +943,176 @@ with activities that are no longer visible on screen than a process with visible activities. The decision whether to terminate a process, therefore, depends on the state of the components running in that process. Those states are the subject of -the next section, <a href="#lcycles">Lifecycles</a>. +a later section, <a href="#lcycles">Component Lifecycles</a>. +</p> + + +<h3 id="threads">Threads</h3> + +<p> +Even though you may confine your application to a single process, there will +likely be times when you will need to spawn a thread to do some background +work. Since the user interface must always be quick to respond to user actions, +the thread that hosts an activity should not also host time-consuming operations +like network downloads. Anything that may not be completed quickly should be +assigned to a different thread. +</p> + +<p> +Threads are created in code using standard Java {@link java.lang.Thread} +objects. Android provides a number of convenience classes for managing +threads — {@link android.os.Looper} for running a message loop within +a thread, {@link android.os.Handler} for processing messages, and +{@link android.os.HandlerThread} for setting up a thread with a message loop. </p> -<h2><a name="lcycles"></a>Lifecycles</h2> +<h3 id="rpc">Remote procedure calls</h3> + +<p> +Android has a lightweight mechanism for remote procedure calls (RPCs) +— where a method is called locally, but executed remotely (in another +process), with any result returned back to the caller. +This entails decomposing the method call and all its attendant data to a +level the operating system can understand, transmitting it from the local +process and address space to the remote process and address space, and +reassembling and reenacting the call there. Return values have to be +transmitted in the opposite direction. Android provides all the code +to do that work, so that you can concentrate on defining and implementing +the RPC interface itself. +</p> + +<p> +An RPC interface can include only methods. +All methods are executed synchronously (the local method blocks until the +remote method finishes), even if there is no return value. +</p> + +<p> +In brief, the mechanism works as follows: You'd begin by declaring the +RPC interface you want to implement using a simple IDL (interface definition +language). From that declaration, the +<code><a href="{@docRoot}guide/developing/tools/aidl.html">aidl</a></code> +tool generates a Java interface definition that must be made available to +both the local and the remote process. It contains two inner class, as shown +in the following diagram: +</p> + +<p style="margin-left: 2em"> +<img src="{@docRoot}images/binder_rpc.png" alt="RPC mechanism." border="0" /> +</p> + +<p> +The inner classes have all the code needed to administer remote procedure +calls for the interface you declared with the IDL. +Both inner classes implement the {@link android.os.IBinder} +interface. One of them is used locally and internally by the system; +the code you write can ignore it. +The other, called Stub, extends the {@link android.os.Binder} +class. In addition to internal code for effectuating the IPC calls, it +contains declarations for the methods in the RPC interface you declared. +You would subclass Stub to implement those methods, as indicated in the +diagram. +</p> + +<p> +Typically, the remote process would be managed by a service (because a +service can inform the system about the process and its connections to +other processes). It would have both the interface file generated by +the {@code aidl} tool and the Stub subclass implementing the +RPC methods. Clients of the service would have only the interface file +generated by the {@code aidl} tool. +</p> + +<p> +Here's how a connection between a service and its clients is set up: +</p> + +<ul> +<li>Clients of the service (on the local side) would implement +<code>{@link android.content.ServiceConnection#onServiceConnected +onServiceConnected()}</code> and +<code>{@link android.content.ServiceConnection#onServiceDisconnected +onServiceDisconnected()}</code> methods so they can be notified +when a successful connection to the remote service is established, and +when it goes away. They would then call +<code>{@link android.content.Context#bindService bindService()}</code> +to set up the connection. +</li> + +<li> +The service's <code>{@link android.app.Service#onBind onBind()}</code> +method would be implemented to either accept or reject the connection, +depending on the intent it receives (the intent passed to +{@code bindService()}). If the connection is accepted, it returns +an instance of the Stub subclass. +</li> + +<li>If the service accepts the connection, Android calls the +client's {@code onServiceConnected()} method and passes it an IBinder +object, a proxy for the Stub subclass managed by the service. Through +the proxy, the client can make calls on the remote service. +</li> +</ul> + +<p> +This brief description omits some details of the RPC mechanism. For more +information, see +<a href="{@docRoot}guide/developing/tools/aidl.html">Designing a Remote +Interface Using AIDL</a> and the {@link android.os.IBinder IBinder} class +description. +</p> + + +<h3 id="tsafe">Thread-safe methods</h3> + +<p> +In a few contexts, the methods you implement may be called from more +than one thread, and therefore must be written to be thread-safe. +</p> + +<p> +This is primarily true for methods that can be called remotely — +as in the RPC mechanism discussed in the previous section. +When a call on a method implemented in an IBinder object originates +in the same process as the IBinder, the method is executed in the +caller's thread. However, when the call originates in another process, +the method is executed in a thread chosen from a pool of threads that +Android maintains in the same process as the IBinder; it's not executed +in the main thread of the process. For example, whereas a service's +{@code onBind()} method would be called from the main thread of the +service's process, methods implemented in the object that {@code onBind()} +returns (for example, a Stub subclass that implements RPC methods) would +be called from threads in the pool. +Since services can have more than one client, more than one pool thread +can engage the same IBinder method at the same time. IBinder methods +must, therefore, be implemented to be thread-safe. +</p> + +<p> +Similarly, a content provider can receive data requests that originate in +other processes. Although the ContentResolver and ContentProvider classes +hide the details of how the interprocess communication is managed, +ContentProvider methods that respond to those requests — the methods +<code>{@link android.content.ContentProvider#query query()}</code>, +<code>{@link android.content.ContentProvider#insert insert()}</code>, +<code>{@link android.content.ContentProvider#delete delete()}</code>, +<code>{@link android.content.ContentProvider#update update()}</code>, and +<code>{@link android.content.ContentProvider#getType getType()}</code> +— are called from a pool of threads in the content provider's +process, not the main thread of the process. Since these methods +may be called from any number of threads at the same time, they too must +be implemented to be thread-safe. +</p> + + +<h2 id="lcycles">Component Lifecycles</h2> <p> Application components have a lifecycle — a beginning when Android instantiates them to respond to intents through to an end when the instances are destroyed. In between, they may sometimes be active -or inactive, or, in the case of activities, visible to the user or +or inactive,or, in the case of activities, visible to the user or invisible. This section discusses the lifecycles of activities, services, and broadcast receivers — including the states that they can be in during their lifetimes, the methods that notify you of transitions @@ -835,7 +1121,7 @@ the process hosting them might be terminated and the instances destroyed. </p> -<h3><a name="actlife"></a>Activity lifecycle</h3> +<h3 id="actlife">Activity lifecycle</h3> <p>An activity has essentially three states:</p> @@ -864,12 +1150,10 @@ method), or simply killing its process. When it is displayed again to the user, it must be completely restarted and restored to its previous state. </p> - -<h4>Lifecycle methods</h4> - <p> As an activity transitions from state to state, it is notified of the change by calls to the following protected methods: +</p> <p style="margin-left: 2em">{@code void onCreate(Bundle <i>savedInstanceState</i>)} <br/>{@code void onStart()} @@ -881,9 +1165,9 @@ by calls to the following protected methods: <p> All of these methods are hooks that you can override to do appropriate work -when the state changes. -All activities must implement <code>{@link android.app.Activity#onCreate -onCreate()}</code> to do initial setup when the activity is first instantiated. +when the state changes. All activities must implement +<code>{@link android.app.Activity#onCreate onCreate()}</code> to do the +initial setup when the object is first instantiated. Many will also implement <code>{@link android.app.Activity#onPause onPause()}</code> to commit data changes and otherwise prepare to stop interacting with the user. </p> @@ -950,7 +1234,7 @@ can be in. The square rectangles represent the callback methods you can impleme to perform operations when the activity transitions between states. <p> -<p><img src="{@docRoot}images/activity_lifecycle.png" +<p style="margin-left: 2em"><img src="{@docRoot}images/activity_lifecycle.png" alt="State diagram for an Android activity lifecycle." border="0" /></p> <p> @@ -1084,7 +1368,7 @@ extreme and dire circumstances when there is no other recourse. </p> -<h4><a name="actstate"></a>Saving activity state</h4> +<h4 id="actstate">Saving activity state</h4> <p> When the system, rather than the user, shuts down an activity to conserve @@ -1118,14 +1402,38 @@ return to the activity, so there's no reason to save its state. </p> <p> -Because {@code onSaveInstanceState()} is not always called, you -should use it only to record the transient state of the activity, -not to store persistent data. Use {@code onPause()} for that purpose -instead. +Because {@code onSaveInstanceState()} is not always called, you should +use it only to record the transient state of the activity, not to store +persistent data. Use {@code onPause()} for that purpose instead. +</p> + + +<h4 id="coordact">Coordinating activities</h4> + +<p> +When one activity starts another, they both experience lifecycle +transitions. One pauses and may stop, while the other starts up. +On occasion, you may need to coordinate these activities, one with +the other. +</p> + +<p> +The order of lifecycle callbacks is well defined, +particularly when the two activities are in the same process: </p> +<ol> +<li>The current activity's {@code onPause()} method is called.</li> + +<li>Next, the starting activity's {@code onCreate()}, {@code onStart()}, +and {@code onResume()} methods are called in sequence.</li> + +<li>Then, if the starting activity is no longer visible +on screen, its {@code onStop()} method is called.</li> +</ol> + -<h3><a name="servlife"></a>Service lifecycle</h3> +<h3 id="servlife">Service lifecycle</h3> <p> A service can be used in two ways: @@ -1243,11 +1551,11 @@ no matter how it's started, can potentially allow clients to bind to it, so any service may receive {@code onBind()} and {@code onUnbind()} calls. </p> -<p><img src="{@docRoot}images/service_lifecycle.png" +<p style="margin-left: 2em"><img src="{@docRoot}images/service_lifecycle.png" alt="State diagram for Service callbacks." border="0" /></p> -<h3><a name="broadlife"></a>Broadcast receiver lifecycle</h3> +<h3 id="broadlife">Broadcast receiver lifecycle</h3> <p> A broadcast receiver has single callback method: @@ -1286,15 +1594,16 @@ The next section has more on the vulnerability of processes to being killed. </p> -<h3><a name="proclife"></a>Processes and lifecycles</h3> +<h3 id="proclife">Processes and lifecycles</h3> <p>The Android system tries to maintain an application process for as long as possible, but eventually it will need to remove old processes when memory runs low. To determine which processes to keep and which to kill, Android places each process into an "importance hierarchy" based on the -components running in it and the state of those components. There are -five levels in the hierarchy. The following list presents them in order -of importance: +components running in it and the state of those components. Processes +with the lowest importance are eliminated first, then those with the next +lowest, and so on. There are five levels in the hierarchy. The following +list presents them in order of importance: </p> <ol> @@ -1348,16 +1657,15 @@ A visible process is considered extremely important and will not be killed unless doing so is required to keep all foreground processes running. </p></li> -<li><p>A <b>service process</b> is one that is running a service that has -been started with the +<li><p>A <b>service process</b> is one that is running a service that +has been started with the <code>{@link android.content.Context#startService startService()}</code> -method. Although service processes are not directly tied to anything the +method and that does not fall into either of the two higher categories. +Although service processes are not directly tied to anything the user sees, they are generally doing things that the user cares about (such as playing an mp3 in the background or downloading data on the network), so the system keeps them running unless there's not enough -memory to retain them along with all foreground and visible processes. -(Note that a service can be ranked higher than this by virtue of being -bound to a visible or foreground activity). +memory to retain them along with all foreground and visible processes. </p></li> <li><p>A <b>background process</b> is one holding an activity @@ -1365,8 +1673,8 @@ that's not currently visible to the user (the Activity object's <code>{@link android.app.Activity#onStop onStop()}</code> method has been called). These processes have no direct impact on the user experience, and can be killed at any time to reclaim memory for a foreground, visible, or service process. -Usually there are many background processes running, -so they are kept in an LRU list to ensure that the process with the activity that +Usually there are many background processes running, so they are kept in an +LRU (least recently used) list to ensure that the process with the activity that was most recently seen by the user is the last to be killed. If an activity implements its lifecycle methods correctly, and captures its current state, killing its process will not have a deleterious effect on the user experience. diff --git a/docs/html/guide/topics/graphics/2d-graphics.jd b/docs/html/guide/topics/graphics/2d-graphics.jd index 822c66f..a72962e 100644 --- a/docs/html/guide/topics/graphics/2d-graphics.jd +++ b/docs/html/guide/topics/graphics/2d-graphics.jd @@ -87,6 +87,13 @@ protected void onCreate(Bundle savedInstanceState) { To do so, create a Drawable from the resource like so: <pre>Drawable myImage = Resources.getDrawable(R.drawable.my_image);</pre> +<p class="caution"><strong>Caution:</strong> Each unique resource in your project can maintain only one +state, no matter how many different objects you may instantiate for it. For example, if you instantiate two +Drawable objects from the same image resource, then change a property (such as the alpha) for one of the +Drawables, then it will also affect the other. So when dealing with multiple instances of an image resource, +instead of directly transforming the Drawable, you should perform a <a href="#tween-animation">tween animation</a>.</p> + + <h4>Example XML</h4> <p>The XML snippet below shows how to add a resource Drawable to an {@link android.widget.ImageView} in the XML layout (with some red tint just for fun). @@ -103,8 +110,8 @@ To do so, create a Drawable from the resource like so: <h3 id="drawables-from-xml">Creating from resource XML</h3> -<p>By now, you should be familiar with Android's principles of -<a href="{@docRoot}guide/topics/views/index.html">Views and Layout</a>. Hence, you understand the power +<p>By now, you should be familiar with Android's principles of developing a +<a href="{@docRoot}guide/topics/ui/index.html">User Interface</a>. Hence, you understand the power and flexibility inherent in defining objects in XML. This philosophy caries over from Views to Drawables. If there is a Drawable object that you'd like to create, which is not initially dependent on variables defined by your applicaton code or user interaction, then defining the Drawable in XML is a good option. @@ -309,15 +316,28 @@ stretches to accommodate it. <h2 id="tween-animation">Tween Animation</h2> -<p>A tweened animation can perform a series of simple transformations (position, size, rotation, and transparency) on +<p>A tween animation can perform a series of simple transformations (position, size, rotation, and transparency) on the contents of a View object. So, if you have a TextView object, you can move, rotate, grow, or shrink the text. -If it has a background image, the background image will be transformed along with the text.</p> +If it has a background image, the background image will be transformed along with the text. +The {@link android.view.animation animation package} provides all the classes used in a tween animation.</p> -<p>The animation is achieved with a sequence of animation instructions, defined in either XML or code. +<p>A sequence of animation instructions defines the twen animation, defined by either XML or Android code. Like defining a layout, an XML file is recommended because it's more readable, reusable, and swappable -than hard-coding it. In the example below, we use XML. (To define an animation in code, refer to the +than hard-coding the animation. In the example below, we use XML. (To learn more about defining an animation +in your application code, instead of XML, refer to the {@link android.view.animation.AnimationSet} class and other {@link android.view.animation.Animation} subclasses.)</p> +<p>The animation instructions define the transformations that you want to occur, when they will occur, +and how long they should take to apply. Transformations can be sequential or simultaneous — +for example, you can have the contents of a TextView move from left to right, and then +rotate 180 degrees, or you can have the text move and rotate simultaneously. Each transformation +takes a set of parameters specific for that transformation (starting size and ending size +for size change, starting angle and ending angle for rotation, and so on), and +also a set of common parameters (for instance, start time and duration). To make +several transformations happen simultaneously, give them the same start time; +to make them sequential, calculate the start time plus the duration of the preceding transformation. +</p> + <p>The animation XML file belongs in the <code>res/anim/</code> directory of your Android project. 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, @@ -389,22 +409,23 @@ spaceshipImage.startAnimation(hyperspaceJumpAnimation); <p>As an alternative to <code>startAnimation()</code>, you can define a starting time for the animation with <code>{@link android.view.animation.Animation#setStartTime(long) Animation.setStartTime()}</code>, then assign the animation to the View with -<code>{@link android.view.View#setAnimation(android.view.animation.Animation) View.setAnimation()}</code>.</p> +<code>{@link android.view.View#setAnimation(android.view.animation.Animation) View.setAnimation()}</code>. +</p> <p>For more information on the XML syntax, available tags and attributes, see the discussion on animation in the <a href="{@docRoot}guide/topics/resources/available-resources.html#animation">Available Resources</a>.</p> -<p class="note"><strong>Note:</strong> Animations are drawn in the area designated for the View at the start of -the animation; this area does not change to accommodate size or movement, so if your animation moves or expands -outside the original boundaries of your object, it will be clipped to the size of the original View, even if -the object's LayoutParams are set to WRAP_CONTENT (the object will not resize to accommodate moving or -expanding/shrinking animations).</p> +<p class="note"><strong>Note:</strong> Regardless of how your animation may move or resize, the bounds of the +View that holds your animation will not automatically adjust to accomodate it. Even so, the animation will still +be drawn beyond the bounds of its View and will not be clipped. However, clipping <em>will occur</em> +if the animation exceeds the bounds of the parent View.</p> <h2 id="frame-animation">Frame Animation</h2> <p>This is a traditional animation in the sense that it is created with a sequence of different -images, played in order, like a roll of film.</p> +images, played in order, like a roll of film. The {@link android.graphics.drawable.AnimationDrawable} +class is the basis for frame animations.</p> <p>While you can define the frames of an animation in your code, using the {@link android.graphics.drawable.AnimationDrawable} class API, it's more simply accomplished with a single XML @@ -454,6 +475,6 @@ called during the <code>onCreate()</code> method of your Activity, because the A to the window. If you want to play the animation immediately, without requiring interaction, then you might want to call it from the <code>{@link android.app.Activity#onWindowFocusChanged(boolean) onWindowFocusChanged()}</code> method in -your Activity, which will get called when Android brings your window into focus.</p> +your Activity, which will get called when Android brings your window into focus.</p> diff --git a/docs/html/guide/topics/graphics/index.jd b/docs/html/guide/topics/graphics/index.jd index 388acc9..bc2a8bf 100644 --- a/docs/html/guide/topics/graphics/index.jd +++ b/docs/html/guide/topics/graphics/index.jd @@ -1,21 +1,203 @@ -page.title=2D and 3D Graphics +page.title=Graphics @jd:body - +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#options">Consider your Options</a></li> + <li><a href="#draw-to-view">Simple Graphics Inside a View</a></li> + <li><a href="#draw-with-canvas">Draw with a Canvas</a> + <ol> + <li><a href="#on-view">On a View</a></li> + <li><a href="#on-surfaceview">On a SurfaceView</a></li> + </ol> + </li> + </ol> + </div> +</div> <p>Android graphics are powered by a custom 2D graphics library and OpenGL ES 1.0 -for 3D graphics.</p> - -<h2>2D Graphics</h2> -<p>Android offers a custom 2D graphics library for drawing shapes and images.</p> -<p>The {@link android.graphics} and {@link android.graphics.drawable} -packages are where you'll find the classes used for drawing in two-dimensions. -For common drawing tasks, though, the {@link android.graphics.drawable} package -is where you'll find what you need.</p> -<p>For an introduction to drawing shapes and images, read the -<a href="2d-graphics.html">2D Graphics</a> document.</p> - - -<h2>3D with OpenGL</h2> -<p>High performance 3D graphic utilities are provided on Android with the OpenGL ES API. -You'll find the OpenGL APIs in the {@link android.opengl} package. -Read more about <a href="opengl.html">3D with OpenGL</a>.</p>
\ No newline at end of file +for high performance 3D graphics. The most common 2D graphics APIs can be found in the +{@link android.graphics.drawable drawable package}. OpenGL APIs are available +from the Khronos {@link javax.microedition.khronos.opengles OpenGL ES package}, +plus some Android {@link android.opengl OpenGL utilities}.</p> + +<p>When starting a project, it's important to consider exactly what your graphical demands will be. +Varying graphical tasks are best accomplished with varying techniques. For example, graphics and animations +for a rather static application should be implemented much differently than graphics and animations +for an interactive game or 3D rendering.</p> + +<p>Here, we'll discuss a few of the options you have for drawing graphics on Android, +and which tasks they're best suited for.</p> + +<p>If you're specifically looking for information on drawing 3D graphics, this page won't +help a lot. However, the information below, on <a href="#drawing-with-canvas">Drawing with a Canvas</a> +(and the section on SurfaceView), +will give you a quick idea of how you should draw to the View hierarchy. For more information +on Android's 3D graphic utilities (provided by the OpenGL ES API), +read <a href="opengl.html">3D with OpenGL</a> and refer to other OpenGL documentation.</p> + + +<h2 id="options">Consider your Options</h2> + +<p>When drawing 2D graphics, you'll typically do so in one of two ways:</p> +<ol type="a"> + <li>Draw your graphics or animations into a View object from your layout. In this manner, + the drawing (and any animation) of your graphics is handled by the system's + normal View hierarchy drawing process — you simply define the graphics to go inside the View.</li> + <li>Draw your graphics directly to a Canvas. This way, you personally call the appropriate class's + <code>draw()</code> method (passing it your Canvas), or one of the Canvas <code>draw...()</code> methods (like + <code>{@link android.graphics.Canvas#drawPicture(Picture,Rect) drawPicture()}</code>). In doing so, you are also in + control of any animation.</li> +</ol> + +<p>Option "a," drawing to a View, is your best choice when you want to draw simple graphics that do not +need to change dynamically and are not part of a performance-intensive game. For example, you should +draw your graphics into a View when you want to display a static graphic or predefined animation, within +an otherwise static application. Read <a href="#draw-to-view">Simple Graphics Inside a View</a>.</li> + +<p>Option "b," drawing to a Canvas, is better when you're application needs to regularly re-draw itself. +Basically, any video game should be drawing to the Canvas on its own. However, there's more than +one way to do this: </p> +<ul> + <li>In the same thread as your UI Activity, wherein you create a custom View component in + your layout, call <code>{@link android.view.View#invalidate()}</code> and then handle the + <code>{@link android.view.View#onDraw(Canvas) onDraw()}</code> callback..</li> + <li>Or, in a separate thread, wherein you manage a {@link android.view.SurfaceView} and + perform draws to the Canvas as fast as your thread is capable + (you do not need to request <code>invalidate()</code>).</li> +</ul> +<p>...Begin by reading <a href="#draw-with-canvas">Draw with a Canvas</a>.</p> + +<h2 id="draw-to-view">Simple Graphics Inside a View</h2> + +<p>If you'll be drawing some simple graphics (images, shapes, colors, pre-defined animations, etc.), +then you should probably just draw to the background of a View or +to the content of an {@link android.widget.ImageView} in your layout. +In this case, you can skip the rest of this document and learn how to +draw graphics and animations in the <a href="2d-graphics.html">2D Graphics</a> document. +</p> + + +<h2 id="draw-with-canvas">Draw with a Canvas</h2> + +<p>When you're writing an application in which you would like to perform specialized drawing +and/or control the animation of graphics, +you should do so by drawing through a {@link android.graphics.Canvas}. A Canvas works for you as +a pretense, or interface, to the actual surface upon which your graphics will be drawn — it +holds all of your "draw" calls. Via the Canvas, your drawing is actually performed upon an +underlying {@link android.graphics.Bitmap}, which is placed into the window.</p> + +<p>In the event that you're drawing within the <code>{@link android.view.View#onDraw(Canvas) onDraw()}</code> +callback method, the Canvas is provided for you and you need only place your drawing calls upon it. +You can also acquire a Canvas from <code>{@link android.view.SurfaceHolder#lockCanvas() SurfaceHolder.lockCanvas()}</code>, +when dealing with a SurfaceView object. (Both of these scenarios are discussed in the following sections.) +However, if you need to create a new Canvas, then you must define the {@link android.graphics.Bitmap} +upon which drawing will actually be performed. The Bitmap is always required for a Canvas. You can set up +a new Canvas like this:</p> +<pre> +Bitmap b = Bitmap.createBitmap(100, 100, Bitmap.Config.ARGB_8888); +Canvas c = new Canvas(b); +</pre> + +<p>Now your Canvas will draw onto the defined Bitmap. After drawing upon it with the Canvas, you can then carry your +Bitmap to another Canvas with one of the <code>{@link android.graphics.Canvas#drawBitmap(Bitmap,Matrix,Paint) +Canvas.drawBitmap(Bitmap,...)}</code> methods. It's recommended that you ultimately draw your final +graphics through a Canvas offered to you +by <code>{@link android.view.View#onDraw(Canvas) View.onDraw()}</code> or +<code>{@link android.view.SurfaceHolder#lockCanvas() SurfaceHolder.lockCanvas()}</code> (see the following sections).</p> + +<p>The {@link android.graphics.Canvas} class has its own set of drawing methods that you can use, +like <code>drawBitmap(...)</code>, <code>drawRect(...)</code>, <code>drawText(...)</code>, and many more. +Other classes that you might use also have <code>draw()</code> methods. For example, you'll probably +have some {@link android.graphics.drawable.Drawable} objects that you want to put on the Canvas. Drawable +has its own <code>{@link android.graphics.drawable.Drawable#draw(Canvas) draw()}</code> method +that takes your Canvas as an arguement.</p> + + +<h3 id="on-view">On a View</h3> + +<p>If you're application does not require a significant amount of processing or +frame-rate speed (perhaps for a chess game, a snake game, +or another slowly-animated application), then you should consider creating a custom View component +and drawing with a Canvas in <code>{@link android.view.View#onDraw(Canvas) View.onDraw()}</code>. +The most convenient aspect of doing so is that the Android framework will +provide you with a pre-defined Canvas to which you will place your drawing calls.</p> + +<p>To start, extend the {@link android.view.View} class (or descendent thereof) and define +the <code>{@link android.view.View#onDraw(Canvas) onDraw()}</code> callback method. This method will be called by the Android +framework to request that your View draw itself. This is where you will perform all your calls +to draw through the {@link android.graphics.Canvas}, which is passed to you through the <code>onDraw()</code> callback.</p> + +<p>The Android framework will only call <code>onDraw()</code> as necessary. Each time that +your application is prepared to be drawn, you must request your View be invalidated by calling +<code>{@link android.view.View#invalidate()}</code>. This indicates that you'd like your View to be drawn and +Android will then call your <code>onDraw()</code> method (though is not guaranteed that the callback will +be instantaneous). </p> + +<p>Inside your View component's <code>onDraw()</code>, use the Canvas given to you for all your drawing, +using various <code>Canvas.draw...()</code> methods, or other class <code>draw()</code> methods that +take your Canvas as an argument. Once your <code>onDraw()</code> is complete, the Android framework will +use your Canvas to draw a Bitmap handled by the system.</p> + +<p class="note"><strong>Note: </strong> In order to request an invalidate from a thread other than your main +Activity's thread, you must call <code>{@link android.view.View#postInvalidate()}</code>.</p> + +<p>Also read <a href="{@docRoot}guide/topics/ui/custom-components.html">Building Custom Components</a> +for a guide to extending a View class, and <a href="2d-graphics.html">2D Graphics: Drawables</a> for +information on using Drawable objects like images from your resources and other primitive shapes.</p> + +<p>For a sample application, see the Snake game, in the SDK samples folder: +<code><your-sdk-directory>/samples/Snake/</code>.</p> + +<h3 id="on-surfaceview">On a SurfaceView</h3> + +<p>The {@link android.view.SurfaceView} is a special subclass of View that offers a dedicated +drawing surface within the View hierarchy. The aim is to offer this drawing surface to +an application's secondary thread, so that the application isn't required +to wait until the system's View hierarchy is ready to draw. Instead, a secondary thread +that has reference to a SurfaceView can draw to its own Canvas at its own pace.</p> + +<p>To begin, you need to create a new class that extends {@link android.view.SurfaceView}. The class should also +implement {@link android.view.SurfaceHolder.Callback}. This subclass is an interface that will notify you +with information about the underlying {@link android.view.Surface}, such as when it is created, changed, or destroyed. +These events are important so that you know when you can start drawing, whether you need +to make adjustments based on new surface properties, and when to stop drawing and potentially +kill some tasks. Inside your SurfaceView class is also a good place to define your secondary Thread class, which will +perform all the drawing procedures to your Canvas.</p> + +<p>Instead of handling the Surface object directly, you should handle it via +a {@link android.view.SurfaceHolder}. So, when your SurfaceView is initialized, get the SurfaceHolder by calling +<code>{@link android.view.SurfaceView#getHolder()}</code>. You should then notify the SurfaceHolder that you'd +like to receive SurfaceHolder callbacks (from {@link android.view.SurfaceHolder.Callback}) by calling +{@link android.view.SurfaceHolder#addCallback(SurfaceHolder.Callback) addCallback()} +(pass it <var>this</var>). Then override each of the +{@link android.view.SurfaceHolder.Callback} methods inside your SurfaceView class.</p> + +<p>In order to draw to the Surface Canvas from within your second thread, you must pass the thread your SurfaceHandler +and retrieve the Canvas with <code>{@link android.view.SurfaceHolder#lockCanvas() lockCanvas()}</code>. +You can now take the Canvas given to you by the SurfaceHolder and do your necessary drawing upon it. +Once you're done drawing with the Canvas, call +<code>{@link android.view.SurfaceHolder#unlockCanvasAndPost(Canvas) unlockCanvasAndPost()}</code>, passing it +your Canvas object. The Surface will now draw the Canvas as you left it. Perform this sequence of locking and +unlocking the canvas each time you want to redraw.</p> + +<p class="note"><strong>Note:</strong> On each pass you retrieve the Canvas from the SurfaceHolder, +the previous state of the Canvas will be retained. In order to properly animate your graphics, you must re-paint the +entire surface. For example, you can clear the previous state of the Canvas by filling in a color +with <code>{@link android.graphics.Canvas#drawColor(int) drawColor()}</code> or setting a background image +with <code>{@link android.graphics.Canvas#drawBitmap(Bitmap,Rect,RectF,Paint) drawBitmap()}</code>. Otherwise, +you will see traces of the drawings you previously performed.</p> + + +<p>For a sample application, see the Lunar Landar game, in the SDK samples folder: +<code><your-sdk-directory>/samples/LunarLander/</code>. Or, +browse the source in the <a href="{@docRoot}guide/samples/index.html">Sample Code</a> section.</p> + + + + + + + + diff --git a/docs/html/guide/topics/location/geo/mapkey.jd b/docs/html/guide/topics/location/geo/mapkey.jd index 110876f..9aa824c 100644 --- a/docs/html/guide/topics/location/geo/mapkey.jd +++ b/docs/html/guide/topics/location/geo/mapkey.jd @@ -1,28 +1,210 @@ -page.title=Obtaining a MapView API Key +page.title=Obtaining a Maps API Key @jd:body -<p>{@link-fixme com.google.android.maps.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> +<div class="sidebox"><p>To register for a Maps API Key, read this document and then go to the <a href="http://code.google.com/android/maps-api-signup.html">Android Maps API Key Signup</a> page.</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> +</div> -<p>Registering your application is simple, and has two parts: </p> +<p>com.google.android.maps.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 of Maps tiles, 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 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 for a Maps API Key is simple, free, 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> +<li>Registering the MD5 fingerprint of the certificate that you will use to sign your application. The Maps registration service then provides you a Maps API Key that is associated with your application's signer certificate. </li> +<li>Adding a reference to the Maps API Key in each MapView, whether declared in XML or instantiated directly from code. You can use the same Maps API Key for any MapView in any Android application, provided that the application 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> +<p>During registration, you also need to agree to the Maps API Terms of Service, which describe how your application can use the Maps data. In general, the terms of service are permissive and place few restrictions on how you can use the data. For example, the terms allow you to build "friend finder" type applications. </p> + +<p>The sections below describe how to obtain your Maps API Key and how to reference it from your MapView elements. </p> + +<ul> +<li><a href="#overview">Overview</a></li> +<li><a href="#getfingerprint">Getting the MD5 Fingerprint of Your Signing Certificate</a></li> +<li><a href="#getdebugfingerprint">Getting the MD5 Fingerprint of the SDK Debug Certificate</a></li> +<li><a href="#registering">Registering the Certificate Fingerprint with the Google Maps Service</a></li> +<li><a href="#addingkey">Adding the Maps API Key to your Application</a></li> +<li><a href="#finalsteps">Final Steps to Enable MapView Elements</a></li> +</ul> + +<h2 id="overview">Overview</h2> + +<p>MapView objects are views that display Maps tiles downloaded from the Google Maps service. To ensure that applications use Maps data in an appropriate manner, the Google Maps service requires application developers to register with the service, agreeing to the Terms of Service and supplying an MD5 fingerprint of the certificate(s) that they will use to sign applications. For each registered certificate fingerprint, the service then provides the developer with a Maps API Key — an alphanumeric string that uniquely identifies the certificate and developer registered with the service. </p> + +<p>The Google Maps service also requires that each MapView identify itself to the service using a Maps API Key. Before providing Maps tiles to a MapView, the service checks the Maps API Key supplied by the MapView to ensure that it:</p> +<ul> +<li>References a certificate/developer registered with the service, and </li> +<li>References a certificate that matches the certificate with which the application (containing the MapView) was signed. </li> +</ul> + +<p>Unless both conditions are met, the service does not provide Maps tiles to the MapView. </p> + +<p>Each MapView object in your application must reference a Maps API Key. Since the Key is associated with a certificate, all Mapview elements in an application should reference the same Key. Going a step further, all MapView elements in all applications that you sign with the same certificate should reference the same Key. </p> + +<p>On the other hand, you can register for multiple Maps API Keys, each being associated with a specific certificate. You would want to do this if, for example, you were developing several independent applications that you will sign using different certificates. In this case, note that all MapView elements in a given application can reference the same Maps API Key, but <em>must</em> reference the Key that is associated with the certificate used to sign the application. </p> + +<p>Because MapView elements must refer to a Maps API Key, you need to register your certificate and receive a Key before you can make use of MapView elements in your application. To make it easier for you to get started using MapView elements, you are welcome to register the debug certificate generated by the SDK tools and receive a temporary Maps API Key. The details of how to do that are given below. </p> + +<p>When you are preparing to release your application, however, note that you <em>must</em> sign your application with a suitable cryptographic key, rather than the SDK debug key. That means that you will also need to register your application's release certificate with the Google Maps service. After you've done so, you will receive a new Maps API Key that is uniquely associated with your release certificate. To enable the MapView elements in your application to work after release, you must remember to change the Maps API Key for all MapViews in your application so that they refer to the Key associated with your release certificate (rather than your debug certificate). </p> + +<p>To summarize, the important points to understand about MapViews and the Maps API Key are: </p> + +<ul> +<li>To display Maps data in a MapView, you need to register for a Maps API Key</li> +<li>Each Maps API Key is uniquely associated with a specific certificate, based on an MD5 fingerprint of the certificate </li> +<li>Each MapView must reference a Maps API Key, and the Key referenced must be registered to the certificate used to sign the application</li> +<li>All MapView elements in an application can reference the same Maps API Key</li> +<li>You can register multiple certificates under your developer identity</li> +<li>You can get a temporary Maps API Key based on your debug certificate, but before you publish your application, you must register for a new Key based on your release certificate and update references in your MapViews accordingly</li> +</ul> + +<h2 id="getfingerprint">Getting the MD5 Fingerprint of Your Signing Certificate</h2> + +<div class="sidebox"> +For more information about using Keytool and Jarsigner to sign your application, see <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>. +</div> + +<p>To register for a Maps API Key, you need to provide an MD5 fingerprint of the certificate that you will use to sign your application. </p> + +<p>Before you visit the registration page, use Keytool to generate the fingerprint of the appropriate certificate. + +<p>First, determine which key you will use to sign your application at release and make sure of the path to the keystore that contains it.</p> + +<p>Next, run Keytool with the <code>-list</code> option, against the target keystore and key alias. The table below lists the options you should use.</p> + +<table> +<tr> +<th>Keytool Option</th> +<th>Description</th> +</tr> +<tr> +<td><code>-list</code></td><td>Print an MD5 fingerprint of a certificate.</td> +</tr> +<tr> +<td><code>-keystore <keystore-name>.keystore</code></td><td>The name of the keystore containing the target 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>The alias for the key for which to generate the MD5 certificate fingerprint.</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 an MD5 certificate fingerprint for the key <code>alias_name</code> in the keystore <code>my-release-key.keystore</code>:</p> + +<pre>$ keytool -list -alias alias_name -keystore my-release-key.keystore</pre> + +<p>Keytool will prompt you to enter passwords for the keystore and key. As output of the command, Keytool prints the fingerprint to the shell. For example:</p> + +<pre>Certificate fingerprint (MD5): 94:1E:43:49:87:73:BB:E6:A6:88:D7:20:F1:8E:B5:98</pre> + +<p>Note that, if you happen to forget your Maps API Key, you can repeat the process described above and register the fingerprint again. The server will give you the same key for the specified certificate fingerprint.</p> + +<p>Once you have the fingerprint, you can go to the Maps API registration site, described next.</p> + +<h2 id="getdebugfingerprint">Getting the MD5 Fingerprint of the SDK Debug Certificate</h2> -<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>While you are developing and debugging your application, you will likely be +sigining your application in debug mode — that is, the SDK build tools +will automatically sign your application using the debug certificate. To let +your MapView elements properly display Maps data during this period, you should +obtain a temporary Maps API Key registered to the debug certificate. To do so, +you first need to get the MD5 fingerprint of the debug certificate. When +you are ready to release your application, you must register your release +certificate with the Google Maps service and obtain a new Maps API Key. You must +then change the MapView elements in your application to reference the new 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>To generate an MD5 fingerprint of the debug certificate, first locate the debug keystore. The location at which the SDK tools create the default debug keystore varies by platform: </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> +<ul> +<li>Windows Vista: <code>C:\Users\<user>\AppData\Local\Android\debug.keystore</code></li> +<li>Windows XP: <code>C:\Documents and Settings\<user>\Local Settings\Application Data\Android\debug.keystore</code></li> +<li>OS X and Linux: <code>~/.android/debug.keystore</code></li> +</ul> + +<p>If you are using Eclipse/ADT and are unsure where the debug keystore is located, you can select <strong>Windows</strong> > <strong>Prefs</strong> > <strong>Android</strong> > <strong>Build</strong> to check the full path, which you can then paste into a file explorer to locate the directory containing the keystore.</p> + +<p>Once you have located the keystore, use this Keytool command to get the MD5 fingerprint of the debug certificate:</p> + +<pre>$ keytool -list -alias androiddebugkey \ +-keystore <path_to_debug_keystore>.keystore \ +-storepass android -keypass android</pre> + +<h2 id="registering">Registering the Certificate Fingerprint with the Google Maps Service</h2> + +<p>When you are ready to register for a Maps API Key, load this page in a browser: </p> + +<p><a href="http://code.google.com/android/maps-api-signup.html">http://code.google.com/android/maps-api-signup.html</a></p> + +<p>To register for a Maps API Key, follow these steps:</p> + +<ol> +<li>If you don't have a Google account, use the link on the page to set one up. </li> +<li>Read the Android Maps API Terms of Service carefully. If you agree to the terms, indicate so using the checkbox on the screen. </li> +<li>Paste the MD5 certificate fingerprint of the certificate that you are registering into the appropriate form field.</li> +<li>Click "Generate API Key"</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> +<p>The server will handle your request, associating the fingerprint with your developer identity and generating a unique Maps API Key, then returning a results page that gives you your Key string. </p> + +<p>To use the Maps API Key string, copy and paste it into your code as described in the next section.</p> + +<h2 id="addingkey">Adding the Maps API Key to your Application</h2> + +<p>Once you've registered with the Google Maps service and have obtained a Maps API Key, you must add it to your application's MapView objects, so that the Maps server will allow them to download Maps tiles. </p> + +<p>For <code><MapView></code> elements declared in XML layout files, add the Maps API Key as the value of a special attribute — <code>android:apiKey</code>. For example: </li> + +<pre><com.google.android.maps.MapView + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:enabled="true" + android:clickable="true" + android:apiKey="example_Maps_ApiKey_String" + /></pre> +</li> + +<p>For MapView objects instantiated directly from code, pass the Maps API Key string as a parameter in the constructor. For example: </p> + +<pre>mMapView = new MapView(this, "example_Maps_ApiKey_String");</pre> + +<p>For more information about MapView, see the MapView class Documentation. </p> + +<h2 id="finalsteps">Final Steps to Enable MapView Elements</h2> + +<p>If you've added the Maps API Key to the MapViews in your application, here are the final steps to enable the MapView elements to run properly:</p> + +<ul> +<li>Make sure that you added a <code><uses-library></code> element referencing the external <code>com.google.android.maps</code> library. The element must be a child of the <code><application></code> element in the application's manifest. For example: + +<p><pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.example.package.name"> + ... + <application android:name="MyApplication" > + <uses-library android:name="com.google.android.maps" /> + ... + </application></pre></p></li> + +<li>Sign your application with the certificate that corresponds to the Maps API Key referenced in your MapView elements. </li> + +</ul> + +<div class="special"><p>Note that, when you are ready to publish your application, you must get a Maps API Key that is based on the certificate that you will use to sign the application for release. You must then change the Maps API Key string referenced by all of your MapView elements, so that they reference the new Key. </p></div> + + + diff --git a/docs/html/guide/topics/location/index.jd b/docs/html/guide/topics/location/index.jd index eeaab39..53f1d29 100644 --- a/docs/html/guide/topics/location/index.jd +++ b/docs/html/guide/topics/location/index.jd @@ -95,7 +95,7 @@ MapView must extend {@link-fixme com.google.android.maps.MapActivity}. </p> <p>Also note that you must obtain a MapView API Key from the Google Maps service, before your MapView can load maps data. For more information, see -<a href="{@docRoot}guide/developing/mapkey.html">Obtaining a MapView API Key</a>.</p> +<a href="{@docRoot}guide/topics/location/geo/mapkey.html">Obtaining a MapView API Key</a>.</p> <p>Once you've created a MapView, you'll probably want to use {@link-fixme com.google.android.maps.MapView#getController()} to diff --git a/docs/html/guide/topics/resources/available-resources.jd b/docs/html/guide/topics/resources/available-resources.jd index 7ba9e52..2a6a6ac 100644 --- a/docs/html/guide/topics/resources/available-resources.jd +++ b/docs/html/guide/topics/resources/available-resources.jd @@ -853,7 +853,7 @@ of an <code><item></code> (to create a Sub Menu).</p> </dl> <p>For more discussion on how to create menus in XML and inflate them in your application, -read <a href="{@docRoot}guide/topics/views/menus.html">Creating Menus</a>.</p> +read <a href="{@docRoot}guide/topics/ui/menus.html">Creating Menus</a>.</p> @@ -877,7 +877,7 @@ the Android namespace "http://schemas.android.com/apk/res/android" defined in the root element.</p> <p>For a complete discussion on creating layouts, see the -<a href="{@docRoot}guide/topics/views/index.html">Views and Layout</a> topic.</p> +<a href="{@docRoot}guide/topics/ui/index.html">User Interface</a> topic.</p> <p> <strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> @@ -971,7 +971,7 @@ res/layout/<em>some_file</em>.xml.</p> <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}guide/topics/views/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: + <strong>Attributes of the object's {@link android.view.ViewGroup.LayoutParams} subclass.</strong> All View objects support a LayoutParams member (see <a href="{@docRoot}guide/topics/ui/declaring-layout.html#layout-params">Declaring Layout</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> @@ -1032,7 +1032,7 @@ setContentView(R.layout.main_screen); However, layout elements can also represent repeating elements used as templates. </p> -<p>Also see <a href="{@docRoot}guide/topics/views/index.html">Views and Layout</a> for more information on layouts.</p> +<p>Also see <a href="{@docRoot}guide/topics/ui/index.html">User Interface</a> for more information on layouts.</p> @@ -1078,7 +1078,7 @@ setContentView(R.layout.main_screen); </p> <p>For a complete discussion on styles and themes, read -<a href="{@docRoot}guide/topics/views/themes.html">Applying Styles and Themes</a>.</p> +<a href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</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. @@ -1132,4 +1132,4 @@ setContentView(R.layout.main_screen); </dl> <p>For examples of how to declare and apply styles and themes, read -<a href="{@docRoot}guide/topics/views/themes.html">Applying Styles and Themes</a>.</p> +<a href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p> diff --git a/docs/html/guide/topics/resources/resources-i18n.jd b/docs/html/guide/topics/resources/resources-i18n.jd index 8a9bd43..b1da4cd 100644 --- a/docs/html/guide/topics/resources/resources-i18n.jd +++ b/docs/html/guide/topics/resources/resources-i18n.jd @@ -120,7 +120,7 @@ the containing file.</p> <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}guide/topics/views/declaring-layout.html">Declaring Layout</a></td> + See <a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout</a></td> </tr> <tr> <td><code>res/values/</code></td> diff --git a/docs/html/guide/topics/views/binding.jd b/docs/html/guide/topics/ui/binding.jd index ce57ac4..f9afbc5 100644 --- a/docs/html/guide/topics/views/binding.jd +++ b/docs/html/guide/topics/ui/binding.jd @@ -1,5 +1,5 @@ page.title=Binding to Data with AdapterView -parent.title=Views and Layout +parent.title=User Interface parent.link=index.html @jd:body diff --git a/docs/html/guide/topics/views/custom-components.jd b/docs/html/guide/topics/ui/custom-components.jd index 9e7943b..eccc2ca 100644 --- a/docs/html/guide/topics/views/custom-components.jd +++ b/docs/html/guide/topics/ui/custom-components.jd @@ -1,5 +1,5 @@ page.title=Building Custom Components -parent.title=Views and Layout +parent.title=User Interface parent.link=index.html @jd:body @@ -35,7 +35,7 @@ that you can use to construct your UI.</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.html">Common Layout Objects</a>.</p> +and others. For more examples, see <a href="layout-objects.html">Common Layout Objects</a>.</p> <p>If none of the prebuilt widgets or layouts meets your needs, you can create your own View subclass. If you only need to make small adjustments to an existing widget or layout, you can simply subclass diff --git a/docs/html/guide/topics/ui/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd new file mode 100644 index 0000000..dd0b7de --- /dev/null +++ b/docs/html/guide/topics/ui/declaring-layout.jd @@ -0,0 +1,269 @@ +page.title=Declaring Layout +parent.title=User Interface +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#write">Write the XML</a></li> + <li><a href="#load">Load the XML Resource</a></li> + <li><a href="#attributes">Attributes</a> + <ol> + <li><a href="#id">ID</a></li> + <li><a href="#layout-params">Layout Parameters</a></li> + </ol> + </li> + <li><a href="#Position">Position</a></li> + <li><a href="#SizePaddingMargin">Size, Padding and Margins</a></li> + <li><a href="#example">Example Layout</a></li> + </ol> +</div> +</div> + +<p>Your layout is the architecture for the user interface in an Activity. +It defines the layout structure and holds all the elements that appear to the user. +You can declare your layout in two ways:</p> +<ul> +<li><strong>Declare UI elements in XML</strong>. Android provides a straightforward XML +vocabulary that corresponds to the View classes and subclasses, such as those for widgets and layouts.</li> +<li><strong>Instantiate layout elements at runtime</strong>. Your +application can create View and ViewGroup objects (and manipulate their properties) programmatically. </li> +</ul> + +<p>The Android framework gives you the flexibility to use either or both of these methods for 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> + +<div class="sidebox"> + <p>The <a href="{@docRoot}guide/developing/tools/adt.html">Android Development Tools</a> + (ADT) plugin for Eclipse offers a layout preview of your XML — + with the XML file opened, select the <strong>Layout</strong> tab.</p> + <p>You should also try the + <a href="{@docRoot}guide/developing/tools/hierarchy-viewer.html">Hierarchy Viewer</a> tool, + for debugging layouts — it reveals layout property values, + draws wireframes with padding/margin indicators, and full rendered views while + you debug on the emulator or device.</p> +</div> + +<p>The advantage to declaring your UI in XML is that it enables you to better separate the presentation of your application from the code that controls its behavior. Your UI descriptions are 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, different device screen sizes, and different languages. Additionally, declaring the layout in XML makes it easier to visualize the structure of your UI, so it's easier to debug problems. As such, this document focuses on teaching you how to declare your layout in XML. If you're +interested in instantiating View objects at runtime, refer to the {@link android.view.ViewGroup} and +{@link android.view.View} class references.</p> + +<p>In general, the XML vocabulary for declaring UI elements closely follows the structure and naming of the 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. However, note that not all vocabulary is identical. In some cases, there are slight naming differences. For +example, the EditText element has a <code>text</code> attribute that corresponds to +<code>EditText.setText()</code>. </p> + +<p class="note"><strong>Tip:</strong> Learn more about different layout types in <a href="{@docRoot}guide/topics/ui/layout-objects.html">Common +Layout Objects</a>. There are also a collection of tutorials on building various layouts in the +<a href="{@docRoot}guide/tutorials/views/index.html">Hello Views</a> tutorial guide.</p> + +<h2 id="write">Write the XML</h2> + +<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}guide/topics/resources/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 web pages in HTML — with a series of nested elements. </p> + +<p>Each layout file must contain exactly one root element, which must be a View or ViewGroup object. Once you've defined the root element, you can add additional layout objects or widgets as child elements to gradually build a View hierarchy that defines your layout. For example, here's an XML layout that uses a vertical {@link android.widget.LinearLayout} +to hold a {@link android.widget.TextView} and a {@link android.widget.Button}:</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:orientation="vertical" > + <TextView android:id="@+id/text" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="Hello, I am a TextView" /> + <Button android:id="@+id/button" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="Hello, I am a Button" /> +</LinearLayout> +</pre> + +<p>After you've declared your layout in XML, save the file with the <code>.xml</code> extension, +in your Android project's <code>res/layout/</code> directory, so it will properly compile. </p> + +<p>We'll discuss each of the attributes shown here a little later.</p> + +<h2 id="load">Load the XML Resource</h2> + +<p>When you compile your application, each XML layout file is compiled into a +{@link android.view.View} resource. You should load the layout resource from your application code, in your +{@link android.app.Activity#onCreate(android.os.Bundle) Activity.onCreate()} callback implementation. +Do so by calling <code>{@link android.app.Activity#setContentView(int) setContentView()}</code>, +passing it the reference to your layout resource in the form of: +<code>R.layout.<em>layout_file_name</em></code> +For example, if your XML layout is saved as <code>main_layout.xml</code>, you would load it +for your Activity like so:</p> +<pre> +public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView.(R.layout.main_layout); +} +</pre> + +<p>The <code>onCreate()</code> callback method in your Activity is called by the Android framework when +your Activity is launched (see the discussion on Lifecycles, in the +<a href="{@docRoot}guide/topics/fundamentals.html#lcycles">Application Fundamantals</a>, for more on this).</p> + + +<h2 id="attributes">Attributes</h2> + +<p>Every View and ViewGroup object supports their own variety of XML attributes. +Some attributes are specific to a View object (for example, TextView supports the <code>textSize</code> +attribute), but these attributes are also inherited by any View objects that may extend this class. +Some are common to all View objects, because they are inherited from the root View class (like +the <code>id</code> attribute). And, other attributes are considered "layout parameters," which are +attributes that describe certain layout orientations of the View object, as defined by that object's +parent ViewGroup object.</p> + +<h3 id="id">ID</h3> + +<p>Any View object may have an integer ID associated with it, to uniquely identify the View within the tree. +When the application is compiled, this ID is referenced as an integer, but the ID is typically +assigned in the layout XML file as a string, in the <code>id</code> attribute. +This is an XML attribute common to all View objects +(defined by the {@link android.view.View} class) and you will use it very often. +The syntax for an ID, inside an XML tag is:</p> +<pre>android:id="@+id/my_button"</pre> + +<p>The at-symbol (@) at the beginning of the string indicates that the XML parser should parse and expand the rest +of the ID string and identify it as an ID resource. The plus-symbol (+) means that this is a new resource name that must +be created and added to our resources (in the <code>R.java</code> file). There are a number of other ID resources that +are offered by the Android framework. When referencing an Android resource ID, you do not need the plus-symbol, +but must add the <code>android</code> package namespace, like so:</p> +<pre>android:id="@android:id/empty"</pre> +<p>With the <code>android</code> package namespace in place, we're now referencing an ID from the <code>android.R</code> +resources class, rather than the local resources class.</p> + +<p>In order to create views and reference them from the application, a common pattern is to:</p> +<ol> + <li>Define a view/widget in the layout file and assign it a unique ID: +<pre> +<Button android:id="@+id/my_button" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@string/my_button_text"/> +</pre> + </li> + <li>Then create an instance of the view object and capture it from the layout +(typically in the <code>{@link android.app.Activity#onCreate(Bundle) onCreate()}</code> method): +<pre> +Button myButton = (Button) findViewById(R.id.my_button); +</pre> + </li> +</ol> +<p>Defining IDs for view objects is important when creating a {@link android.widget.RelativeLayout}. +In a relative layout, sibling views can define their layout relative to another sibling view, +which is referenced by the unique ID.</p> +<p>An ID need not be unique throughout the entire tree, but it should be +unique within the part of the tree you are searching (which may often be the entire tree, so it's best +to be completely unique when possible).</p> + + +<h3 id="layout-params">Layout Parameters</h3> + +<p>XML layout attributes named <code>layout_<em>something</em></code> define +layout parameters for the View that are appropriate for the ViewGroup in which it resides.</p> + +<p>Every ViewGroup class implements a nested class that extends {@link +android.view.ViewGroup.LayoutParams}. This subclass +contains property types that define the size and position for each child view, as +appropriate for the view group. As you can see in the figure below, the parent +view group defines layout parameters for each child view (including the child view group).</p> + +<img src="{@docRoot}images/layoutparams.png" alt="" height="300" 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, +though it may also define different LayoutParams for its own children. </p> + +<p>All view groups include a width and height (<code>layout_width</code> and <code>layout_height</code>), +and each view is required to define them. +Many LayoutParams also include optional margins and +borders. You can specify width and height with exact measurements, though you probably won't want +to do this often. More often, you will tell your view to size itself either to +the dimensions required by its content, or to become as big as its parent view group +will allow (with the <var>wrap_content</var> and <var>fill_parent</var> values, respectively). +The accepted measurement types are defined in the +<a href="{@docRoot}guide/topics/resources/available-resources.html#dimension">Available Resources</a> document.</p> + + +<h2 id="Position">Layout Position</h2> + <p> + The geometry of a view is that of a rectangle. A view has a location, + expressed as a pair of <em>left</em> and <em>top</em> coordinates, and + two dimensions, expressed as a width and a height. The unit for location + and dimensions is the pixel. + </p> + + <p> + It is possible to retrieve the location of a view by invoking the methods + {@link android.view.View#getLeft()} and {@link android.view.View#getTop()}. The former returns the left, or X, + coordinate of the rectangle representing the view. The latter returns the + top, or Y, coordinate of the rectangle representing the view. These methods + both return the location of the view relative to its parent. For instance, + when getLeft() returns 20, that means the view is located 20 pixels to the + right of the left edge of its direct parent. + </p> + + <p> + In addition, several convenience methods are offered to avoid unnecessary + computations, namely {@link android.view.View#getRight()} and {@link android.view.View#getBottom()}. + These methods return the coordinates of the right and bottom edges of the + rectangle representing the view. For instance, calling {@link android.view.View#getRight()} + is similar to the following computation: <code>getLeft() + getWidth()</code>. + </p> + + +<h2 id="SizePaddingMargins">Size, Padding and Margins</h2> + <p> + The size of a view is expressed with a width and a height. A view actually + possess two pairs of width and height values. + </p> + + <p> + The first pair is known as <em>measured width</em> and + <em>measured height</em>. These dimensions define how big a view wants to be + within its parent. The + measured dimensions can be obtained by calling {@link android.view.View#getMeasuredWidth()} + and {@link android.view.View#getMeasuredHeight()}. + </p> + + <p> + The second pair is simply known as <em>width</em> and <em>height</em>, or + sometimes <em>drawing width</em> and <em>drawing height</em>. These + dimensions define the actual size of the view on screen, at drawing time and + after layout. These values may, but do not have to, be different from the + measured width and height. The width and height can be obtained by calling + {@link android.view.View#getWidth()} and {@link android.view.View#getHeight()}. + </p> + + <p> + To measure its dimensions, a view takes into account its padding. The padding + is expressed in pixels for the left, top, right and bottom parts of the view. + Padding can be used to offset the content of the view by a specific amount of + pixels. For instance, a left padding of 2 will push the view's content by + 2 pixels to the right of the left edge. Padding can be set using the + {@link android.view.View#setPadding(int, int, int, int)} method and queried by calling + {@link android.view.View#getPaddingLeft()}, {@link android.view.View#getPaddingTop()}, + {@link android.view.View#getPaddingRight()} and {@link android.view.View#getPaddingBottom()}. + </p> + + <p> + Even though a view can define a padding, it does not provide any support for + margins. However, view groups provide such a support. Refer to + {@link android.view.ViewGroup} and + {@link android.view.ViewGroup.MarginLayoutParams} for further information. + </p> + +<p>For more information about dimensions, see <a href="{@docRoot}guide/topics/resources/available-resources.html#dimension">Dimension Values</a>.</p> + + + + diff --git a/docs/html/guide/topics/ui/how-android-draws.jd b/docs/html/guide/topics/ui/how-android-draws.jd new file mode 100644 index 0000000..a511005 --- /dev/null +++ b/docs/html/guide/topics/ui/how-android-draws.jd @@ -0,0 +1,94 @@ +page.title=How Android Draws Views +parent.title=User Interface +parent.link=index.html +@jd:body + + +<p>When an Activity receives focus, it will be requested to draw its layout. +The Android framework will handle the procedure for drawing, but the Activity must provide +the root node of its layout hierarchy.</p> + +<p>Drawing begins with the root node of the layout. It is requested to measure and +draw the layout tree. Drawing is handled by walking the tree and rendering each View that + intersects the invalid region. In turn, each View group is responsible for requesting +each of its children to be drawn (with the <code>{@link android.view.View#draw(Canvas) draw()}</code> method) +and each View is responsible for drawing itself. + Because the tree is traversed in-order, + this means that parents will be drawn before (i.e., behind) their children, with + siblings drawn in the order they appear in the tree. + </p> + +<div class="sidebox"> + <p>The framework will not draw Views that are not in the invalid region, and also + will take care of drawing the Views background for you.</p> + <p>You can force a View to draw, by calling <code>{@link android.view.View#invalidate()}</code>. + </p> +</div> + +<p> + Drawing the layout is a two pass process: a measure pass and a layout pass. The measuring + pass is implemented in <code>{@link android.view.View#measure(int, int)}</code> and is a top-down traversal + of the View tree. Each View pushes dimension specifications down the tree + during the recursion. At the end of the measure pass, every View has stored + its measurements. The second pass happens in + <code>{@link android.view.View#layout(int,int,int,int)}</code> and is also top-down. During + this pass each parent is responsible for positioning all of its children + using the sizes computed in the measure pass. + </p> + + <p> + When a View's <code>measure()</code> method returns, its <code>{@link android.view.View#getMeasuredWidth()}</code> and + <code>{@link android.view.View#getMeasuredHeight()}</code> values must be set, along with those for all of + that View's descendants. A View's measured width and measured height values + must respect the constraints imposed by the View's parents. This guarantees + that at the end of the measure pass, all parents accept all of their + children's measurements. A parent View may call <code>measure()</code> more than once on + its children. For example, the parent may measure each child once with + unspecified dimensions to find out how big they want to be, then call + <code>measure()</code> on them again with actual numbers if the sum of all the children's + unconstrained sizes is too big or too small (i.e., if the children don't agree among themselves + as to how much space they each get, the parent will intervene and set the rules on the second pass). + </p> + + <div class="sidebox"><p> + To intiate a layout, call <code>{@link android.view.View#requestLayout}</code>. This method is typically + called by a View on itself when it believes that is can no longer fit within + its current bounds.</p> + </div> + + <p> + The measure pass uses two classes to communicate dimensions. The + {@link android.view.View.MeasureSpec} class is used by Views to tell their parents how they + want to be measured and positioned. The base LayoutParams class just + describes how big the View wants to be for both width and height. For each + dimension, it can specify one of:</p> + <ul> + <li> an exact number + <li><var>FILL_PARENT</var>, which means the View wants to be as big as its parent + (minus padding)</li> + <li><var>WRAP_CONTENT</var>, which means that the View wants to be just big enough to + enclose its content (plus padding).</li> + </ul> + <p>There are subclasses of LayoutParams for different subclasses of ViewGroup. + For example, AbsoluteLayout has its own subclass of LayoutParams which adds + an X and Y value. + </p> + + <p> + MeasureSpecs are used to push requirements down the tree from parent to + child. A MeasureSpec can be in one of three modes:</p> + <ul> + <li><var>UNSPECIFIED</var>: This is used by a parent to determine the desired dimension + of a child View. For example, a LinearLayout may call <code>measure()</code> on its child + with the height set to <var>UNSPECIFIED</var> and a width of <var>EXACTLY</var> 240 to find out how + tall the child View wants to be given a width of 240 pixels.</li> + <li><var>EXACTLY</var>: This is used by the parent to impose an exact size on the + child. The child must use this size, and guarantee that all of its + descendants will fit within this size.</li> + <li><var>AT_MOST</var>: This is used by the parent to impose a maximum size on the + child. The child must gurantee that it and all of its descendants will fit + within this size.</li> + </ul> + + + diff --git a/docs/html/guide/topics/ui/index.jd b/docs/html/guide/topics/ui/index.jd new file mode 100644 index 0000000..ccc8ff6 --- /dev/null +++ b/docs/html/guide/topics/ui/index.jd @@ -0,0 +1,235 @@ +page.title=User Interface +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Key classes and packages</h2> + <ol> + <li>{@link android.view.View}</li> + <li>{@link android.view.ViewGroup}</li> + <li>{@link android.widget}</li> + </ol> + + <h2>In this document</h2> + <ol> + <li><a href="#ViewHierarchy">View Hierarchy</a></li> + <li><a href="#Layout">Layout</a></li> + <li><a href="#Widgets">Widgets</a></li> + <li><a href="#Events">UI Events</a></li> + <li><a href="#Menus">Menus</a></li> + <li><a href="#Advanced">Advanced Topics</a> + <ol> + <li><a href="#Adapters">Adapters</a></li> + <li><a href="#StylesAndThemes">Styles and Themes</a></li> + </ol> + </li> + </ol> +</div> +</div> + +<p>In an Android application, the user interface is built using {@link android.view.View} and +{@link android.view.ViewGroup} objects. There are many types of views and view groups, each of which +is a descendant of the {@link android.view.View} class.</p> + +<p>View objects are the basic units of user interface expression on the Android platform. +The View class serves as the base for subclasses called "widgets," which offer fully implemented +UI objects, like text fields and buttons. The ViewGroup class serves as the base for subclasses called "layouts," +which offer different kinds of layout architecture, like linear, tabular and relative.</p> + +<p>A View object is a data structure whose properties store the layout parameters and content for a specific +rectangular area of the screen. A View object handles its own measurement, layout, drawing, focus change, +scrolling, and key/gesture interactions for the rectangular area of the screen in which it resides. As an +object in the user interface, a View is also a point of interaction for the user and the receiver +of the interaction events.</p> + + +<h2 id="ViewHierarchy">View Hierarchy</h2> + +<p>On the Android platform, you define an Activity's UI using a hierarchy of View and ViewGroup nodes, +as shown in the diagram below. This hierarchy tree can be as simple or complex as you need it to be, and you +can build it up using Android's set of predefined widgets and layouts, or with custom Views that you +create yourself.</p> + +<img src="{@docRoot}images/viewgroup.png" alt="" width="312" height="211" align="center"/> + +<p> +In order to attach the view hierarchy tree to the screen for rendering, your Activity must call the +<code>{@link android.app.Activity#setContentView(int) setContentView()}</code> +method and pass a reference to the root node object. The Android system +receives this reference and uses it to invalidate, measure, and draw the tree. The root node of the hierarchy requests +that its child nodes draw themselves — in turn, each view group node is responsible for calling +upon each of its own child views to draw themselves. +The children may request a size and location within the parent, but the parent object has the final +decision on where how big each child can be. Android parses +the elements of your layout in-order (from the top of the hierarchy tree), instantiating the Views and +adding them to their parent(s). Because these are drawn in-order, if there are elements that +overlap positions, the last one to be drawn will lie on top of others previously drawn to that space.</p> + +<p>For a more detailed discussion on how view hierarchies are measured +and drawn, read <a href="how-android-draws.html">How Android Draws Views</a>.</p> + + +<h2 id="Layout">Layout</h2> + +<p>The most common way to define your layout and express the view hierarchy is with an XML layout file. +XML offers a human-readable structure for the layout, much like HTML. Each element in XML is +either a View or ViewGroup object (or descendent thereof). View objects are leaves in the tree, +ViewGroup objects are branches in the tree (see the View Hierarchy figure above).</p> +<p>The name of an XML element +is respective to the Java class that it represents. So a <code><TextView></code> element creates +a {@link android.widget.TextView} in your UI, and a <code><LinearLayout></code> element creates +a {@link android.widget.LinearLayout} view group. When you load a layout resource, +the Android system initializes these run-time objects, corresponding to the elements in your layout.</p> + +<p>For example, a simple vertical layout with a text view and a button 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="fill_parent" + android:layout_height="fill_parent" + android:orientation="vertical" > + <TextView android:id="@+id/text" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="Hello, I am a TextView" /> + <Button android:id="@+id/button" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="Hello, I am a Button" /> +</LinearLayout> +</pre> + +<p>Notice that the LinearLayout element contains both the TextView and the Button. You can nest +another LinearLayout (or other type of view group) inside here, to lengthen the view hierarchy and create a more +complex layout.</p> + +<p>For more on building a UI layout, read <a href="declaring-layout.html">Declaring Layout</a>. + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <p><b>Tip:</b> You can also draw View and ViewGroups objects in Java code, + using the <code>{@link android.view.ViewGroup#addView(View)}</code> methods + to dynamically insert new View and ViewGroup objects.</p> +</div> +</div> + +<p>There are a variety of ways in which you can layout your views. Using more and different kinds of view groups, +you can structure child views and view groups in an infinite number of ways. +Some pre-defined view groups offered by Android (called layouts) include LinearLayout, RelativeLayout, AbsoluteLayout, +TableLayout, GridLayout and others. Each offers a unique set of layout parameters that are used to define the +positions of child views and layout structure.</p> +<p>To learn about some of the different kinds of view groups used for a layout, +read <a href="layout-objects.html">Common Layout Objects</a>.</p> + + +<h2 id="Widgets">Widgets</h2> + +<p>A widget is a View object that serves as an interface for interaction with the user. +Android provides a set of fully implemented +widgets, like buttons, checkboxes, and text-entry fields, so you can quickly build your UI. +Some widgets provided by Android are more complex, like a date picker, a clock, and zoom controls. +But you're not limited to the kinds of widgets provided by the Android platform. If you'd +like to do something more customized and create your own actionable elements, you can, by defining your own +View object or by extending and combining existing widgets.</p> +<p>Read more in <a href="custom-components.html">Building Custom Components</a>.</p> + +<p>For a list of the widgets provided by Android, see the {@link android.widget} package.</p> + + +<h2 id="Events">UI Events</h2> + +<p>Once you've added some Views/widgets to the UI, you probably want to know about the +user's interaction with them, so you can perform actions. To be informed of UI events, you need to +do one of two things:</p> +<ul> + <li><strong>Define an event listener and register it with the View.</strong> More often than not, +this is how you'll listen for events. The View class contains a collection of nested interfaces named +On<em><something></em>Listener, each with a callback method called <code>On<em><something></em>()</code>. +For example, {@link android.view.View.OnClickListener} (for handling "clicks" on a View), +{@link android.view.View.OnTouchListener} (for handling touch screen events in a View), and +{@link android.view.View.OnKeyListener} (for handling device key presses within a View). So if you want your View +to be notified when it is "clicked" (such as when a button is selected), implement OnClickListener and define +its <code>onClick()</code> callback method (where you perform the action upon click), and register it +to the View with <code>{@link android.view.View#setOnClickListener(View.OnClickListener) setOnClickListener()}</code>. +</li> + <li><strong>Override an existing callback method for the View.</strong> This is +what you should do when you've implemented your own View class and want to listen for specific events +that occur within it. Example events you can handle include when the +screen is touched (<code>{@link android.view.View#onTouchEvent(MotionEvent) onTouchEvent()}</code>), when +the trackball is moved (<code>{@link android.view.View#onTrackballEvent(MotionEvent) onTrackballEvent()}</code>), +or when a key on the device is pressed (<code>{@link android.view.View#onKeyDown(int, KeyEvent) +onKeyDown()}</code>). This allows you to define the default behavior for each event inside your custom View and determine +whether the event should be passed on to some other child View. Again, these are callbacks to the View class, +so your only chance to define them is when you +<a href="{@docRoot}guide/topics/ui/custom-components.html">build a custom component</a>. +</li> +</ul> + +<p>Continue reading about handling user interaction with Views in the <a href="ui-events.html">Handling UI Events</a> +document.</p> + + +<h2 id="Menus">Menus</h2> + +<p>Application menus are another important part of an application's UI. Menus offers a reliable interface that reveals +application functions and settings. The most common application menu is revealed by pressing +the MENU key on the device. However, you can also add Context Menus, which may be revealed when the user presses +and holds down on an item.</p> + +<p>Menus are also structured using a View hierarchy, but you don't define this structure yourself. Instead, +you define the <code>{@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()}</code> or +<code>{@link android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenu.ContextMenuInfo) onCreateContextMenu()}</code> +callback methods for your Activity and declare the items that you want to include in your menu. +At the appropriate time, Android will automatically create the necessary View hierarchy for the menu and +draw each of your menu items in it.</p> + +<p>Menus also handle their own events, so there's no need to register event listeners on the items in your menu. +When an item in your menu is selected, the <code>{@link android.app.Activity#onOptionsItemSelected(MenuItem) +onOptionsItemSelected()}</code> or +<code>{@link android.app.Activity#onContextItemSelected(MenuItem) onContextItemSelected()}</code> +method will be called by the framework.</p> + +<p>And just like your application layout, you have the option to declare the items for you menu in an XML file.</p> + +<p>Read <a href="{@docRoot}guide/topics/ui/menus.html">Creating Menus</a> to learn more.</p> + + +<h2 id="Advanced">Advanced Topics</h2> + +<p>Once you've grappled the fundamentals of creating a user interface, you can explore +some advanced features for creating a more complex application interface.</p> + +<h3 id="Adapters">Adapters</h3> + +<p>Sometimes you'll want to populate a view group with some information that can't be hard-coded, instead, +you want to bind your view to an external source of data. To do this, you use an AdapterView as +your view group and each child View is initialized and populated with data from the Adapter.</p> +<p>The AdapterView object is an implementation of ViewGroup that determines its child views +based on a given Adapter object. The Adapter acts like a courier between your data source (perhaps an +array of external strings) and the AdapterView, which displays it. There are several implementations +of the Adapter class, for specific tasks, such as the CursorAdapter for reading database data from a Cursor, +or an ArrayAdapter for reading from an arbitrary array.</p> +<p>To learn more about using an Adapter to populate your views, read +<a href="binding.html">Binding to Data with AdapterView</a>.</p> + + +<h3 id="StylesAndThemes">Styles and Themes</h3> + +<p>Perhaps you're not satisfied with the look of the standard widgets. To revise them, you can create some +of your own styles and themes.</p> + +<ul> + <li>A style is a set of one or more formatting attributes that you can apply as a unit to individual elements +in your layout. For example, you could define a style that specifies a certain text size and color, then +apply it to only specific View elements.</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 just a single activity. For example, you could define a theme that sets specific colors for +the window frame and the panel background, and sets text sizes and colors for menus. This theme can then be +applied to specific activities or the entire application.</li> +</ul> + +<p>Styles and themes are resources. Android provides some default style and theme resources that you can use, +or you can declare your own custom style and theme resources.</p> +<p>Learn more about using styles and themes in the +<a href="themes.html">Applying Styles and Themes</a> document.</p> diff --git a/docs/html/guide/topics/views/layout.jd b/docs/html/guide/topics/ui/layout-objects.jd index a6fec35..cf85fd6 100644 --- a/docs/html/guide/topics/views/layout.jd +++ b/docs/html/guide/topics/ui/layout-objects.jd @@ -1,5 +1,5 @@ page.title=Common Layout Objects -parent.title=Views and Layout +parent.title=User Interface parent.link=index.html @jd:body @@ -20,6 +20,8 @@ parent.link=index.html <p>This section describes some of the more common types of layout objects to use in your applications. Like all layouts, they are subclasses of {@link android.view.ViewGroup ViewGroup}.</p> +<p>Also see the <a href="{@docRoot}guide/tutorials/views/index.html">Hello Views</a> tutorials for +some guidance on using more Android View layouts.</p> <h2 id="framelayout">FrameLayout</h2> <p>{@link android.widget.FrameLayout FrameLayout} is the simplest type of layout @@ -95,9 +97,42 @@ cells empty, but cells cannot span columns, as they can in HTML.</p> Each row has zero or more cells, each of which is defined by any kind of other View. So, the cells of a row may be composed of a variety of View objects, like ImageView or TextView objects. A cell may also be a ViewGroup object (for example, you can nest another TableLayout as a cell).</p> -<p>The following image shows a table layout, with the invisible cell borders displayed as dotted lines. </p> +<p>The following sample layout has two rows and two cells in each. The accompanying screenshot shows the +result, with cell borders displayed as dotted lines (added for visual effect). </p> -<img src="{@docRoot}images/table_layout.png" alt="" /> +<table class="columns"> + <tr> + <td> + <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:text="@string/table_layout_4_open" + android:padding="3dip" /> + <TextView + android:text="@string/table_layout_4_open_shortcut" + android:gravity="right" + android:padding="3dip" /> + </TableRow> + + <TableRow> + <TextView + android:text="@string/table_layout_4_save" + android:padding="3dip" /> + <TextView + android:text="@string/table_layout_4_save_shortcut" + android:gravity="right" + android:padding="3dip" /> + </TableRow> +</TableLayout> +</pre></td> + <td><img src="{@docRoot}images/table_layout.png" alt="" style="margin:0" /></td> + </tr> +</table> <p>Columns can be hidden, marked to stretch and fill the available screen space, or can be marked as shrinkable to force the column to shrink until the table @@ -127,13 +162,54 @@ TableLayout</a> tutorial.</p> will be aligned relative to screen center. Also, because of this ordering, if using XML to specify this layout, the element that you will reference (in order to position other view objects) must be listed in the XML file before you refer to it from the other views via its reference ID. </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>The example below shows an XML file and the resulting screen in the UI. +Note that the attributes that refer to relative elements (e.g., <var>layout_toLeft</var>) +refer to the ID using the syntax of a relative resource +(<var>@id/<em>id</em></var>). </p> + +<table class="columns"> + <tr> + <td> + <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="wrap_content" + android:background="@drawable/blue" + android:padding="10px" > + + <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="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="" style="margin:0" /></td> + </tr> +</table> -<img src="{@docRoot}images/designing_ui_relative_layout.png" alt="" /> -<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 +<p>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 defined RelativeLayout parameters are: <code>width</code>, <code>height</code>, diff --git a/docs/html/guide/topics/views/menus.jd b/docs/html/guide/topics/ui/menus.jd index 489cd07..ed796ee 100644 --- a/docs/html/guide/topics/views/menus.jd +++ b/docs/html/guide/topics/ui/menus.jd @@ -9,7 +9,7 @@ parent.link=index.html <ol> <li><a href="#options-menu">Options Menu</a></li> <li><a href="#context-menu">Context Menu</a></li> - <li><a href="#sub-menu">Sub Menu</a></li> + <li><a href="#submenu">Submenu</a></li> <li><a href="#xml">Define Menus in XML</a></li> <li><a href="#features">Menu Features</a> <ol> @@ -20,6 +20,12 @@ parent.link=index.html </ol> </li> </ol> + <h2>Key classes</h2> + <ol> + <li>{@link android.view.Menu}</li> + <li>{@link android.view.ContextMenu}</li> + <li>{@link android.view.SubMenu}</li> + </ol> </div> </div> @@ -47,9 +53,9 @@ for developers to provide standardized application menus for various situations. <dt><strong>Context Menu</strong></dt> <dd>This is a floating list of menu items that may appear when you perform a long-press on a View (such as a list item). </dd> - <dt><strong>Sub Menu</strong></dt> + <dt><strong>Submenu</strong></dt> <dd>This is a floating list of menu items that is revealed by an item in the Options Menu - or a Context Menu. A Sub Menu item cannot support nested Sub Menus. </dd> + or a Context Menu. A Submenu item cannot support nested Submenus. </dd> </dl> @@ -63,7 +69,7 @@ is automatically added when there are more than six items.</p> <p>The Options Menu is where you should include basic application functions and any necessary navigation items (e.g., to a home screen or application settings). -You can also add <a href="#sub-menu">Sub Menus</a> for organizing topics +You can also add <a href="#submenu">Submenus</a> for organizing topics and including extra menu functionality.</p> <p>When this menu is opened for the first time, @@ -127,7 +133,7 @@ and we recommend you do it that way for easier localization).</p> <p class="note"><strong>Tip:</strong> If you have several menu items that can be grouped together with a title, -consider organizing them into a <a href="#sub-menu">Sub Menu</a>.</p> +consider organizing them into a <a href="#submenu">Submenu</a>.</p> <h3>Adding icons</h3> <p>Icons can also be added to items that appears in the Icon Menu with @@ -136,8 +142,8 @@ consider organizing them into a <a href="#sub-menu">Sub Menu</a>.</p> menu.add(0, MENU_QUIT, 0, "Quit") .setIcon(R.drawable.menu_quit_icon);</pre> -<h3>Modifying the options menu</h3> -<p>If you want to sometimes re-write the options menu as it is opened, override the +<h3>Modifying the menu</h3> +<p>If you want to sometimes re-write the Options Menu as it is opened, override the <code>{@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()}</code> method, which is called each time the menu is opened. This will pass you the Menu object, just like the <code>onCreateOptionsMenu()</code> callback. This is useful if you'd like to add or remove @@ -225,7 +231,7 @@ in the list is registered to this context menu.</p> -<h2 id="sub-menu">Sub Menus</h2> +<h2 id="submenu">Submenus</h2> <p>A sub menu can be added within any menu, except another sub menu. These are very useful when your application has a lot of functions that may be organized in topics, like the items in a PC application's menu bar (File, Edit, View, etc.).</p> @@ -254,7 +260,7 @@ public boolean onCreateOptionsMenu(Menu menu) { <p>Callbacks for items selected in a sub menu are made to the parent menu's callback method. For the example above, selections in the sub menu will be handled by the <code>onOptionsItemSelected()</code> callback.</p> -<p>You can also add Sub Menus when you <a href="#xml">define the parent menu in XML</a>.</p> +<p>You can also add Submenus when you <a href="#xml">define the parent menu in XML</a>.</p> <h2 id="xml">Define Menus in XML</h2> @@ -269,7 +275,7 @@ This is where you should keep all XML files that define your application menus.< three valid elements: <code><menu></code>, <code><group></code> and <code><item></code>. The <code>item</code> and <code>group</code> elements must be children of a <code>menu</code>, but <code>item</code> elements may also be the children of a <code>group</code>, and another <code>menu</code> element may be the child -of an <code>item</code> (to create a Sub Menu). Of course, the root node of any file +of an <code>item</code> (to create a Submenu). Of course, the root node of any file must be a <code>menu</code> element.</p> <p>As an example, we'll define the same menu created in the <a href="#options-menu">Options Menu</a> section, @@ -302,7 +308,7 @@ passing it a pointer to our menu resource and the Menu object given by the callb and it keeps your application code clean.</p> <p>You can define <a href="#groups">menu groups</a> by wrapping <code>item</code> elements in a <code>group</code> -element, and create Sub Menus by nesting another <code>menu</code> inside an <code>item</code>. +element, and create Submenus by nesting another <code>menu</code> inside an <code>item</code>. Each element also supports all the necessary attributes to control features like shortcut keys, checkboxes, icons, and more. To learn about these attributes and more about the XML syntax, see the Menus topic in the <a href="{@docRoot}guide/topics/resources/available-resources.html#menus">Available @@ -367,7 +373,7 @@ assign the same group ID to each menu item and call <code>{@link android.view.Menu#setGroupCheckable(int,boolean,boolean) setGroupCheckable()}</code>. In this case, you don't need to call <code>setCheckable()</code> on each menu items, because the group as a whole is set checkable. Here's an example of -two mutually exclusive options in a sub-menu:</p> +two mutually exclusive options in a Submenu:</p> <pre> SubMenu subMenu = menu.addSubMenu("Color"); subMenu.add(COLOR_MENU_GROUP, COLOR_RED_ID, 0, "Red"); diff --git a/docs/html/guide/topics/views/themes.jd b/docs/html/guide/topics/ui/themes.jd index a206a4b..d684512 100644 --- a/docs/html/guide/topics/views/themes.jd +++ b/docs/html/guide/topics/ui/themes.jd @@ -1,5 +1,5 @@ page.title=Applying Styles and Themes -parent.title=Views and Layout +parent.title=User Interface parent.link=index.html @jd:body diff --git a/docs/html/guide/topics/ui/ui-events.jd b/docs/html/guide/topics/ui/ui-events.jd new file mode 100644 index 0000000..f4d114a --- /dev/null +++ b/docs/html/guide/topics/ui/ui-events.jd @@ -0,0 +1,283 @@ +page.title=Handling UI Events +parent.title=User Interface +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#EventListeners">Event Listeners</a></li> + <li><a href="#EventHandlers">Event Handlers</a></li> + <li><a href="#TouchMode">Touch Mode</a></li> + <li><a href="#HandlingFocus">Handling Focus</a></li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}guide/tutorials/views/hello-formstuff.html">Hello Form Stuff tutorial</a></li> + </ol> +</div> +</div> + +<p>On Android, there's more than one way to intercept the events from a user's interaction with your application. +When considering events within your user interface, the approach is to capture the events from +the specific View object that the user interacts with. The View class provides the means to do so.</p> + +<p>Within the various View classes that you'll use to compose your layout, you may notice several public callback +methods that look useful for UI events. These methods are called by the Android framework when the +respective action occurs on that object. For instance, when a View (such as a Button) is touched, +the <code>onTouchEvent()</code> method is called on that object. However, in order to intercept this, you must extend +the class and override the method. Obviously, extending every View object +you want to use (just to handle an event) would be obsurd. This is why the View class also contains +a collection of nested interfaces with callbacks that you can much more easily define. These interfaces, +called <a href="#EventListeners">event listeners</a>, are your ticket to capturing the user interaction with your UI.</p> + +<p>While you will more commonly use the event listeners to listen for user interaction, there may +come a time when you do want to extend a View class, in order to build a custom component. +Perhaps you want to extend the {@link android.widget.Button} +class to make something more fancy. In this case, you'll be able to define the default event behaviors for your +class using the class <a href="#EventHandlers">event handlers</a>.</p> + + +<h2 id="EventListeners">Event Listeners</h2> + +<p>An event listener is an interface in the {@link android.view.View} class that contains a single +callback method. These methods will be called by the Android framework when the View to which the listener has +been registered is triggered by user interaction with the item in the UI.</p> + +<p>Included in the event listener interfaces are the following callback methods:</p> + +<dl> + <dt><code>onClick()</code></dt> + <dd>From {@link android.view.View.OnClickListener}. + This is called when the user either touches the item + (when in touch mode), or focuses upon the item with the navigation-keys or trackball and + presses the suitable "enter" key or presses down on the trackball.</dd> + <dt><code>onLongClick()</code></dt> + <dd>From {@link android.view.View.OnLongClickListener}. + This is called when the user either touches and holds the item (when in touch mode), or + focuses upon the item with the navigation-keys or trackball and + presses and holds the suitable "enter" key or presses and holds down on the trackball (for one second).</dd> + <dt><code>onFocusChange()</code></dt> + <dd>From {@link android.view.View.OnFocusChangeListener}. + This is called when the user navigates onto or away from the item, using the navigation-keys or trackball.</dd> + <dt><code>onKey()</code></dt> + <dd>From {@link android.view.View.OnKeyListener}. + This is called when the user is focused on the item and presses or releases a key on the device.</dd> + <dt><code>onTouch()</code></dt> + <dd>From {@link android.view.View.OnTouchListener}. + This is called when the user performs an action qualified as a touch event, including a press, a release, + or any movement gesture on the screen (within the bounds of the item).</dd> + <dt><code>onCreateContextMenu()</code></dt> + <dd>From {@link android.view.View.OnCreateContextMenuListener}. + This is called when a Context Menu is being built (as the result of a sustained "long click"). See the discussion + on context menus in <a href="{@docRoot}guide/topics/ui/menus.html#context-menu">Creating Menus</a> for more information.</dd> +</dl> + +<p>These methods are the sole inhabitants of their respective interface. To define one of these methods +and handle your events, implement the nested interface in your Activity or define it as an anonymous class. +Then, pass an instance of your implementation +to the respective <code>View.set...Listener()</code> method. (E.g., call +<code>{@link android.view.View#setOnClickListener(View.OnClickListener) setOnClickListener()}</code> +and pass it your implementation of the {@link android.view.View.OnClickListener OnClickListener}.)</p> + +<p>The example below shows how to register an on-click listener for a Button. </p> + +<pre> +// Create an anonymous implementation of OnClickListener +private OnClickListener mCorkyListener = new OnClickListener() { + public void onClick(View v) { + // do something when the button is clicked + } +}; + +protected void onCreate(Bundle savedValues) { + ... + // Capture our button from layout + Button button = (Button)findViewById(R.id.corky); + // Register the onClick listener with the implementation above + button.setOnClickListener(mCorkyListener); + ... +} +</pre> + +<p>You may also find it more conventient to implement OnClickListener as a part of your Activity. +This will avoid the extra class load and object allocation. For example:</p> +<pre> +public class ExampleActivity extends Activity implements OnClickListener { + protected void onCreate(Bundle savedValues) { + ... + Button button = (Button)findViewById(R.id.corky); + button.setOnClickListener(this); + } + + // Implement the OnClickListener callback + public void onClick(View v) { + // do something when the button is clicked + } + ... +} +</pre> + +<p>Notice that the <code>onClick()</code> callback in the above example has +no return value, but some other event listener methods must return a boolean. The reason +depends on the event. For the few that do, here's why:</p> +<ul> + <li><code>{@link android.view.View.OnLongClickListener#onLongClick(View) onLongClick()}</code> - + This returns a boolean to indicate whether you have consumed the event and it should not be carried further. + That is, return <em>true</em> to indicate that you have handled the event and it should stop here; + return <em>false</em> if you have not handled it and/or the event should continue to any other + on-click listeners.</li> + <li><code>{@link android.view.View.OnKeyListener#onKey(View,int,KeyEvent) onKey()}</code> - + This returns a boolean to indicate whether you have consumed the event and it should not be carried further. + That is, return <em>true</em> to indicate that you have handled the event and it should stop here; + return <em>false</em> if you have not handled it and/or the event should continue to any other + on-key listeners.</li> + <li><code>{@link android.view.View.OnTouchListener#onTouch(View,MotionEvent) onTouch()}</code> - + This returns a boolean to indicate whether your listener consumes this event. The important thing is that + this event can have multiple actions that follow each other. So, if you return <em>false</em> when the + down action event is received, you indicate that you have not consumed the event and are also + not interested in subsequent actions from this event. Thus, you will not be called for any other actions + within the event, such as a fingure gesture, or the eventual up action event.</li> +</ul> + +<p>Remember that key events are always delivered to the View currently in focus. They are dispatched starting from the top +of the View hierarchy, and then down, until they reach the appropriate destination. If your View (or a child of your View) +currently has focus, then you can see the event travel through the <code>{@link android.view.View#dispatchKeyEvent(KeyEvent) +dispatchKeyEvent()}</code> method. As an alternative to capturing key events through your View, you can also receive +all of the events inside your Activity with <code>{@link android.app.Activity#onKeyDown(int,KeyEvent) onKeyDown()}</code> +and <code>{@link android.app.Activity#onKeyUp(int,KeyEvent) onKeyUp()}</code>.</p> + +<p class="note"><strong>Note:</strong> Android will call event handlers first and then the appropriate default +handlers from the class definition second. As such, returning <em>true</em> from these event listeners will stop +the propagation of the event to other event listeners and will also block the callback to the +default event handler in the View. So be certain that you want to terminate the event when you return <em>true</em>.</p> + + +<h2 id="EventHandlers">Event Handlers</h2> + +<p>If you're building a custom component from View, then you'll be able to define several callback methods +used as default event handlers. +In the document on <a href="{@docRoot}guide/topics/ui/custom-components.html">Building Custom Components</a>, +you'll learn see some of the common callbacks used for event handling, including:</p> +<ul> + <li><code>{@link android.view.View#onKeyDown}</code> - Called when a new key event occurs.</li> + <li><code>{@link android.view.View#onKeyUp}</code> - Called when a key up event occurs.</li> + <li><code>{@link android.view.View#onTrackballEvent}</code> - Called when a trackball motion event occurs.</li> + <li><code>{@link android.view.View#onTouchEvent}</code> - Called when a touch screen motion event occurs.</li> + <li><code>{@link android.view.View#onFocusChanged}</code> - Called when the view gains or loses focus.</li> +</ul> +<p>There are some other methods that you should be awere of, which are not part of the View class, +but can directly impact the way you're able to handle events. So, when managing more complex events inside +a layout, consider these other methods:</p> +<ul> + <li><code>{@link android.app.Activity#dispatchTouchEvent(MotionEvent) + Activity.dispatchTouchEvent(MotionEvent)}</code> - This allows your {@link + android.app.Activity} to intercept all touch events before they are dispatched to the window.</li> + <li><code>{@link android.view.ViewGroup#onInterceptTouchEvent(MotionEvent) + ViewGroup.onInterceptTouchEvent(MotionEvent)}</code> - This allows a {@link + android.view.ViewGroup} to watch events as they are dispatched to child Views.</li> + <li><code>{@link android.view.ViewParent#requestDisallowInterceptTouchEvent(boolean) + ViewParent.requestDisallowInterceptTouchEvent(boolean)}</code> - Call this + upon a parent View to indicate that it should not intercept touch events with <code>{@link + android.view.ViewGroup#onInterceptTouchEvent(MotionEvent)}</code>.</li> +</ul> + +<h2 id="TouchMode">Touch Mode</h2> +<p> +When a user is navigating a user interface with directional keys or a trackball, it is +necessary to give focus to actionable items (like buttons) so the user can see +what will accept input. If the device has touch capabilities, however, and the user +begins interacting with the interface by touching it, then it is no longer necessary to +highlight items, or give focus to a particular View. Thus, there is a mode +for interaction named "touch mode." +</p> +<p> +For a touch-capable device, once the user touches the screen, the device +will enter touch mode. From this point onward, only Views for which +{@link android.view.View#isFocusableInTouchMode} is true will be focusable, such as text editing widgets. +Other Views that are touchable, like buttons, will not take focus when touched; they will +simply fire their on-click listeners when pressed. +</p> +<p> +Any time a user hits a directional key or scrolls with a trackball, the device will +exit touch mode, and find a view to take focus. Now, the user may resume interacting +with the user interface without touching the screen. +</p> +<p> +The touch mode state is maintained throughout the entire system (all windows and activities). +To query the current state, you can call +{@link android.view.View#isInTouchMode} to see whether the device is currently in touch mode. +</p> + + +<h2 id="HandlingFocus">Handling Focus</h2> + +<p>The framework will handle routine focus movement in response to user input. +This includes changing the focus as Views are removed or hidden, or as new +Views become available. Views indicate their willingness to take focus +through the <code>{@link android.view.View#isFocusable()}</code> method. To change whether a View can take +focus, call <code>{@link android.view.View#setFocusable(boolean) setFocusable()}</code>. When in touch mode, +you may query whether a View allows focus with <code>{@link android.view.View#isFocusableInTouchMode()}</code>. +You can change this with <code>{@link android.view.View#setFocusableInTouchMode(boolean) setFocusableInTouchMode()}</code>. +</p> + +<p>Focus movement is based on an algorithm which finds the nearest neighbor in a +given direction. In rare cases, the default algorithm may not match the +intended behavior of the developer. In these situations, you can provide +explicit overrides with the following XML attributes in the layout file: +<var>nextFocusDown</var>, <var>nextFocusLeft</var>, <var>nextFocusRight</var>, and +<var>nextFocusUp</var>. Add one of these attributes to the View <em>from</em> which +the focus is leaving. Define the value of the attribute to be the id of the View +<em>to</em> which focus should be given. For example:</p> +<pre> +<LinearLayout + android:orientation="vertical" + ... > + <Button android:id="@+id/top" + android:nextFocusUp="@+id/bottom" + ... /> + <Button android:id="@+id/bottom" + android:nextFocusDown="@+id/top" + ... /> +</LinearLayout> +</pre> + +<p>Ordinarily, in this vertical layout, navigating up from the first Button would not go +anywhere, nor would navigating down from the second Button. Now that the top Button has +defined the bottom one as the <var>nextFocusUp</var> (and vice versa), the navigation focus will +cycle from top-to-bottom and bottom-to-top.</p> + +<p>If you'd like to declare a View as focusable in your UI (when it is traditionally not), +add the <code>android:focusable</code> XML attribute to the View, in your layout declaration. +Set the value <var>true</var>. You can also declare a View +as focusable while in Touch Mode with <code>android:focusableInTouchMode</code>.</p> +<p>To request a particular View to take focus, call <code>{@link android.view.View#requestFocus()}</code>.</p> +<p>To listen for focus events (be notified when a View receives or looses focus), use +<code>{@link android.view.View.OnFocusChangeListener#onFocusChange(View,boolean) onFocusChange()}</code>, +as discussed in the <a href="#EventListeners">Event Listeners</a> section, above.</p> + + + +<!-- +<h2 is="EventCycle">Event Cycle</h2> + <p>The basic cycle of a View is as follows:</p> + <ol> + <li>An event comes in and is dispatched to the appropriate View. The View + handles the event and notifies any listeners.</li> + <li>If, in the course of processing the event, the View's bounds may need + to be changed, the View will call {@link android.view.View#requestLayout()}.</li> + <li>Similarly, if in the course of processing the event the View's appearance + may need to be changed, the View will call {@link android.view.View#invalidate()}.</li> + <li>If either {@link android.view.View#requestLayout()} or {@link android.view.View#invalidate()} were called, + the framework will take care of measuring, laying out, and drawing the tree + as appropriate.</li> + </ol> + + <p class="note"><strong>Note:</strong> The entire View tree is single threaded. You must always be on + the UI thread when calling any method on any View. + If you are doing work on other threads and want to update the state of a View + from that thread, you should use a {@link android.os.Handler}. + </p> +--> diff --git a/docs/html/guide/topics/views/declaring-layout.jd b/docs/html/guide/topics/views/declaring-layout.jd deleted file mode 100644 index 43afdf7..0000000 --- a/docs/html/guide/topics/views/declaring-layout.jd +++ /dev/null @@ -1,228 +0,0 @@ -page.title=Declaring Layout -parent.title=Views and Layout -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#LoadingTheResource">Loading the XML Resource</a></li> - <li><a href="#Position">Position</a></li> - <li><a href="#SizePaddingMargin">Size, Padding and Margins</a></li> - </ol> -</div> -</div> - -<p>You can create your application's user interface in two ways: -<ul> -<li><strong>Declare UI elements statically, in XML</strong>. Android provides a straightforward XML -vocabulary that corresponds to the View classes and subclasses, such as those for widgets and layouts. </li> -<li><strong>Instantiate screen elements at runtime</strong>. 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> - -<div class="sidebox"> - <p>The <a href="{@docRoot}guide/developing/tools/adt.html">Android Development Tools</a> - (ADT) plugin for Eclipse offers a layout preview of your XML — - with the XML file opened, select the <strong>Layout</strong> tab.</p> - <p>You should also try the - <a href="{@docRoot}guide/developing/tools/hierarchy-viewer.html">Hierarchy Viewer</a> tool, - for debugging layouts — it reveals layout property values, - draws wireframes with padding/margin indicators, and full rendered views while - you debug on the emulator or device.</p> -</div> - -<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 -<code>EditText.setText()</code>. </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}guide/topics/resources/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 your application's <code>res/layout/</code> directory, so it will properly compile. </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). -See <a href="how-android-draws.html">How Android Draws Views</a> for more information.</p> - -<p>Attributes named <code>layout_<em>something</em></code> apply to that -object's LayoutParams member. <a href="{@docRoot}guide/topics/resources/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}guide/topics/resources/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> - - -<h2 id="LoadingTheResource">Loading the XML Resource</h2> -<p>Loading the compiled layout resource is very easy, and done with a single -call in the activity's <code>onCreate()</code> method, as shown here:</p> - -<pre> -protected void onCreate(Bundle savedInstanceState) -{ - // Be sure to call the super class. - super.onCreate(savedInstanceState); - - // 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(savedInstanceState); -} </pre> - -<h2 id="Position">Position</h2> - <p> - The geometry of a view is that of a rectangle. A view has a location, - expressed as a pair of <em>left</em> and <em>top</em> coordinates, and - two dimensions, expressed as a width and a height. The unit for location - and dimensions is the pixel. - </p> - - <p> - It is possible to retrieve the location of a view by invoking the methods - {@link android.view.View#getLeft()} and {@link android.view.View#getTop()}. The former returns the left, or X, - coordinate of the rectangle representing the view. The latter returns the - top, or Y, coordinate of the rectangle representing the view. These methods - both return the location of the view relative to its parent. For instance, - when getLeft() returns 20, that means the view is located 20 pixels to the - right of the left edge of its direct parent. - </p> - - <p> - In addition, several convenience methods are offered to avoid unnecessary - computations, namely {@link android.view.View#getRight()} and {@link android.view.View#getBottom()}. - These methods return the coordinates of the right and bottom edges of the - rectangle representing the view. For instance, calling {@link android.view.View#getRight()} - is similar to the following computation: <code>getLeft() + getWidth()</code>. - </p> - - -<h2 id="SizePaddingMargins">Size, Padding and Margins</h2> - <p> - The size of a view is expressed with a width and a height. A view actually - possess two pairs of width and height values. - </p> - - <p> - The first pair is known as <em>measured width</em> and - <em>measured height</em>. These dimensions define how big a view wants to be - within its parent. The - measured dimensions can be obtained by calling {@link android.view.View#getMeasuredWidth()} - and {@link android.view.View#getMeasuredHeight()}. - </p> - - <p> - The second pair is simply known as <em>width</em> and <em>height</em>, or - sometimes <em>drawing width</em> and <em>drawing height</em>. These - dimensions define the actual size of the view on screen, at drawing time and - after layout. These values may, but do not have to, be different from the - measured width and height. The width and height can be obtained by calling - {@link android.view.View#getWidth()} and {@link android.view.View#getHeight()}. - </p> - - <p> - To measure its dimensions, a view takes into account its padding. The padding - is expressed in pixels for the left, top, right and bottom parts of the view. - Padding can be used to offset the content of the view by a specific amount of - pixels. For instance, a left padding of 2 will push the view's content by - 2 pixels to the right of the left edge. Padding can be set using the - {@link android.view.View#setPadding(int, int, int, int)} method and queried by calling - {@link android.view.View#getPaddingLeft()}, {@link android.view.View#getPaddingTop()}, - {@link android.view.View#getPaddingRight()} and {@link android.view.View#getPaddingBottom()}. - </p> - - <p> - Even though a view can define a padding, it does not provide any support for - margins. However, view groups provide such a support. Refer to - {@link android.view.ViewGroup} and - {@link android.view.ViewGroup.MarginLayoutParams} for further information. - </p> -
\ No newline at end of file diff --git a/docs/html/guide/topics/views/how-android-draws.jd b/docs/html/guide/topics/views/how-android-draws.jd deleted file mode 100644 index f497db7..0000000 --- a/docs/html/guide/topics/views/how-android-draws.jd +++ /dev/null @@ -1,90 +0,0 @@ -page.title=How Android Draws Views -parent.title=Views and Layout -parent.link=index.html -@jd:body - - -<p>As mentioned in the introduction to <a href="index.html">Views and Layout</a>, -drawing begins when the Activity requests the root node of the layout to measure and -draw the layout tree. Drawing is handled by walking the tree and rendering each view that - intersects the invalid region. In turn, each view group is responsible for requesting -each of its children to be drawn and each view is responsible for drawing itself. - Because the tree is traversed in-order, - this means that parents will be drawn before (i.e., behind) their children, with - siblings drawn in the order they appear in the tree. - </p> - -<div class="sidebox"> - <p>The framework will not draw views that are not in the invalid region, and also - will take care of drawing the views background for you.</p> - <p>You can force a view to draw, by calling {@link android.view.View#invalidate()}. - </p> -</div> - -<p> - Drawing the layout is a two pass process: a measure pass and a layout pass. The measuring - pass is implemented in {@link android.view.View#measure(int, int)} and is a top-down traversal - of the view tree. Each view pushes dimension specifications down the tree - during the recursion. At the end of the measure pass, every view has stored - its measurements. The second pass happens in - {@link android.view.View#layout(int,int,int,int)} and is also top-down. During - this pass each parent is responsible for positioning all of its children - using the sizes computed in the measure pass. - </p> - - <p> - When a view's measure() method returns, its {@link android.view.View#getMeasuredWidth()} and - {@link android.view.View#getMeasuredHeight()} values must be set, along with those for all of - that view's descendants. A view's measured width and measured height values - must respect the constraints imposed by the view's parents. This guarantees - that at the end of the measure pass, all parents accept all of their - children's measurements. A parent view may call measure() more than once on - its children. For example, the parent may measure each child once with - unspecified dimensions to find out how big they want to be, then call - measure() on them again with actual numbers if the sum of all the children's - unconstrained sizes is too big or too small (i.e., if the children don't agree among themselves - as to how much space they each get, the parent will intervene and set the rules on the second pass). - </p> - - <div class="sidebox"><p> - To intiate a layout, call {@link android.view.View#requestLayout}. This method is typically - called by a view on itself when it believes that is can no longer fit within - its current bounds.</p> - </div> - - <p> - The measure pass uses two classes to communicate dimensions. The - {@link android.view.View.MeasureSpec} class is used by views to tell their parents how they - want to be measured and positioned. The base LayoutParams class just - describes how big the view wants to be for both width and height. For each - dimension, it can specify one of:</p> - <ul> - <li> an exact number - <li>FILL_PARENT, which means the view wants to be as big as its parent - (minus padding)</li> - <li> WRAP_CONTENT, which means that the view wants to be just big enough to - enclose its content (plus padding).</li> - </ul> - <p>There are subclasses of LayoutParams for different subclasses of ViewGroup. - For example, AbsoluteLayout has its own subclass of LayoutParams which adds - an X and Y value. - </p> - - <p> - MeasureSpecs are used to push requirements down the tree from parent to - child. A MeasureSpec can be in one of three modes:</p> - <ul> - <li>UNSPECIFIED: This is used by a parent to determine the desired dimension - of a child view. For example, a LinearLayout may call measure() on its child - with the height set to UNSPECIFIED and a width of EXACTLY 240 to find out how - tall the child view wants to be given a width of 240 pixels.</li> - <li>EXACTLY: This is used by the parent to impose an exact size on the - child. The child must use this size, and guarantee that all of its - descendants will fit within this size.</li> - <li>AT_MOST: This is used by the parent to impose a maximum size on the - child. The child must gurantee that it and all of its descendants will fit - within this size.</li> - </ul> - - - diff --git a/docs/html/guide/topics/views/index.jd b/docs/html/guide/topics/views/index.jd deleted file mode 100644 index a246ba1..0000000 --- a/docs/html/guide/topics/views/index.jd +++ /dev/null @@ -1,216 +0,0 @@ -page.title=Views and Layout -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>Key classes and packages</h2> - <ol> - <li>{@link android.view.View}</li> - <li>{@link android.view.ViewGroup}</li> - <li>{@link android.widget}</li> - </ol> - - <h2>In this document</h2> - <ol> - <li><a href="#ViewHierarchy">View Hierarchy</a></li> - <li><a href="#Layout">Layout</a></li> - <li><a href="#Widgets">Widgets</a></li> - <li><a href="#Events">Events</a></li> - <li><a href="#Adapters">Adapters</a></li> - <li><a href="#StylesAndThemes">Styles and Themes</a></li> - </ol> -</div> -</div> - -<p>In an Android application, a user interface is built using {@link android.view.View} and -{@link android.view.ViewGroup} objects. There are many types of views and view groups, each of which -is a descendant of the {@link android.view.View} class.</p> - -<p>View objects are the basic units of user interface expression on the Android platform. -The View class serves as the base for subclasses called "widgets," which offer fully implemented -UI objects, like text fields and buttons. The ViewGroup class serves as the base for subclasses called "layouts," -which offer different kinds of layout architecture, like linear, tabular and relative.</p> - -<p>A View object is a data structure whose properties store the layout properties and content for a specific -rectangular area of the screen. A View object handles its own measurement, layout, drawing, focus change, -scrolling, and key/gesture interactions for the rectangular screen area it represents. </p> - - -<h2 id="ViewHierarchy">View Hierarchy</h2> - -<p>On the Android platform, you will define an Activity's UI using a hierarchy of view and view group nodes, -as shown in the diagram below. This hierarchy tree can be as simple or complex as you need it to be, and you -can build it up using Android's set of predefined widgets and layouts, or with custom view types that you -create yourself.</p> - -<img src="{@docRoot}images/viewgroup.png" alt="" width="312" height="211" align="center"/> - -<p>The Android system will notify your Activity when it becomes active and receives focus. -In order to attach the view hierarchy tree to the screen for rendering, your Activity must call its -<code>setContentView()</code> method and pass a reference to the root node object. The Android system -receives this reference so that it can invalidate, measure, and draw the tree. The root node requests -that its child nodes draw themselves — in turn, each view group node is responsible for -calling <code>Draw()</code> on each of its own child views, so that each child view can render itself. -The children may request a size and location within the parent, but the parent object has the final -decision on where how big each child can be. To learn more about how a view group and its children are measured -and drawn, read <a href="how-android-draws.html">How Android Draws Views</a>.</p> - - -<h2 id="Layout">Layout</h2> - -<p>The most common way to define your layout and express the view hierarchy is with an XML layout file. -XML offers a human-readable structure for the layout, much like HTML. Each element in XML is -(usually a descendant of) either a View or ViewGroup object. View objects are leaves in the tree, -ViewGroup objects are branches in the tree. The name of an XML element -is the respective class object name. So a <code><TextView></code> element creates -a {@link android.widget.TextView} widget in your UI, and a <code><LinearLayout></code> element creates -a {@link android.widget.LinearLayout} layout branch in the tree. To learn more about how to write your layout in XML, -read <a href="declaring-layout.html">Declaring and Querying Layout</a>. - -<div class="sidebox-wrapper"> -<div class="sidebox"> - <p><b>Tip:</b> You can also draw new views and view groups from within your code, - by adding new View and ViewGroup objects to an - existing ViewGroup (specifically, you'll use the <code>addView()</code> methods to dynamically insert new views). - To see how to add views in your code, see the {@link android.view.ViewGroup} reference.</p> -</div> -</div> - -<p>There are a variety of ways in which you can layout your views, using different view groups. -Some pre-defined view groups offered by Android (called layouts) include LinearLayout, RelativeLayout, AbsoluteLayout, -TableLayout, GridLayout and others. Each offers a different mechanisms for arranging child views -among each other. -To learn more about how to use some of these view groups for your layout, -read <a href="layout.html">Common Layout Objects</a>. - -<h3 id="IDs">IDs</h3> - -<p>Views may have an integer ID associated with them. The ID is written as a string, but once the application is -compiled, it will be referenced as an integer. -These IDs are typically assigned in the layout XML file as an attribute of the view, -and are used to uniquely identify a view within the tree. The usual syntax for an ID, inside an XML tag is:</p> -<pre>id="@+id/my_button"</pre> -<p>The at-symbol (@) at the beginning of the string indicates that the XML parser should parse and expand the rest -of the ID string and identify it as an ID resource. The plus-symbol (+) means that this is a new resource name that must -be created and added to our resources (in the <code>R.java</code> file). There are a number of other ID resources that -are offered by the Android framework. When referencing an Android resource ID, you do not need the plus-symbol, -but must add the <code>android</code> package namespace, like so:</p> -<pre>id="@android:id/empty"</pre> -<p>With the <code>android</code> package namespace in place, we're now referencing an ID from the <code>android.R</code> -resources class, rather than the local resources class.</p> - -<p>In order to create views and reference them from the application, a common pattern is to:</p> -<ol> - <li>Define a view/widget in the layout file and assign it a unique ID. E.g.: -<pre> -<Button id="@+id/my_button" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:text="@string/my_button_text"/> -</pre> - </li> - <li>Then create an instance of the view object and capture it from the layout -(typically in the <code>onCreate()</code> method). -<pre> -Button myButton = (Button) findViewById(R.id.my_button); -</pre> - </li> -</ol> -<p>Defining IDs for view objects is important when creating a {@link android.widget.RelativeLayout}. -In a relative layout, sibling views can define their layout relative to another sibling view, -which is referenced by the unique ID.</p> -<p>An ID need not be unique throughout the entire tree, but it should be -unique within the part of the tree you are searching (which may often be the entire tree, so it's best -to be completely unique when possible).</p> - - -<h3>Layout Parameters</h3> - -<p>Every ViewGroup class implements a nested class that extends {@link -android.view.ViewGroup.LayoutParams}. This subclass -contains property types that define each child view's size and position, as -appropriate for that type of view group. As you can see in the figure below, the parent -view group defines layout parameters for each child view (including the child view group).</p> - -<img src="{@docRoot}images/layoutparams.png" alt="" height="300" 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, -though it may also define different LayoutParams for its own children. </p> - -<p>All view groups include a width and height, and each view is required to define them. -Many LayoutParams also include optional margins and -borders. You can specify width and height with exact measurements, though you probably won't want -to do this often. More often, you will tell your view to size itself either to -the dimensions required by its content, or to become as big as its parent view group -will allow (with the <var>wrap_content</var> and <var>fill_parent</var> values, respectively). -The accepted measurement types are defined in the -<a href="{@docRoot}guide/topics/resources/available-resources.html#dimension">Available Resources</a> document.</p> - -<h2 id="Widgets">Widgets</h2> - - -<p>The View class also serves as a base class for <em>widgets</em> — a set of fully implemented -View subclasses that draw interactive screen elements, so you can quickly build your UI. -Android provides a vast collection of widgets for special actions. -Some of them are basic interaction elements like buttons and text fields, while others are more complex, -like a date picker or zoom controls.</p> -<p>For a list of all built-in widgets, see the {@link android.widget widget}.</p> - -<p>You're not limited to the kinds of views, layouts and widgets provided by the Android platform. If you'd -like to do something more customized, create your own widget or layout, you can. -Read more in <a href="custom-components.html">Building Custom Components</a>. - - -<h2 id="Events">Events</h2> - -<p>Once you've designed and built your UI layout, you need to handle the user interaction with it. -Obviously, the views that you've implemented in the layout are the -receptors for such interaction events. Because the View class is built to listen for most interaction events, -receiving and handling them is pretty straigh-forward. When you want to perform an action upon an event, -you need to do one of two things:</p> -<ul> - <li>Override an existing callback method for the view you've implemented, which will be called when something -like a touch or focus event occurs.</li> - <li>Define a listener interface, like {@link android.view.View.OnClickListener} (for handling "clicks" on a View). -You must then define the listener for your view with the respective <code>set...Listener()</code> -method (such as {@link android.view.View#setOnClickListener(android.view.View.OnClickListener) setOnCLickListener()}).</li> -</ul> - -<p>To learn more about handling events and writing your own listeners, -read <a href="ui-events.html">Handling UI Events</a>.</p> - - -<h2 id="Adapters">Adapters</h2> - -<p>Sometimes you'll want to populate a view group with some information that can't be hard-coded, instead, -you want to bind your view to an external source of data. To do this, you use an AdapterView as -your view group and each child View is initialized and populated with data from the Adapter.</p> -<p>The AdapterView object is an implementation of ViewGroup that determines its child views -based on a given Adapter object. The Adapter acts like a courier between your data source (perhaps an -array of external strings) and the AdapterView, which displays it. There are several implementations -of the Adapter class, for specific tasks, such as the CursorAdapter for reading database data from a Cursor, -or an ArrayAdapter for reading from an arbitrary array.</p> -<p>To learn more about using an Adapter to populate your views, read -<a href="binding.html">Binding to Data with AdapterView</a>.</p> - - -<h2 id="StylesAndThemes">Styles and Themes</h2> - -<p>Perhaps you're not satisfied with the look of the standard widgets. To revise them, you can create some -of your own styles and themes.</p> - -<ul> - <li>A style is a set of one or more formatting attributes that you can apply as a unit to individual elements -in your layout. For example, you could define a style that specifies a certain text size and color, then -apply it to only specific View elements.</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 just a single activity. For example, you could define a theme that sets specific colors for -the window frame and the panel background, and sets text sizes and colors for menus. This theme can then be -applied to specific activities or the entire application.</li> -</ul> - -<p>Styles and themes are resources. Android provides some default style and theme resources that you can use, -or you can declare your own custom style and theme resources. Learn more about using styles and themes in the -<a href="themes.html">Applying Styles and Themes</a> document.</p> diff --git a/docs/html/guide/topics/views/ui-events.jd b/docs/html/guide/topics/views/ui-events.jd deleted file mode 100644 index 96136f8..0000000 --- a/docs/html/guide/topics/views/ui-events.jd +++ /dev/null @@ -1,113 +0,0 @@ -page.title=Handling UI Events -parent.title=Views and Layout -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#TouchMode">Touch Mode</a></li> - <li><a href="#Scrolling">Scrolling</a></li> - <li><a href="#EventCycle">Event Cycle</a></li> - </ol> - - <h2>See also</h2> - <ol> - <li><a href="{@docRoot}guide/tutorials/views/hello-formstuff.html">Hello Form Stuff tutorial</a></li> - </ol> -</div> -</div> - -<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 <code>onKeyDown()</code> and <code>onKeyUp()</code> and {@link android.widget.TextView TextView} -provides <code>onFocusChanged()</code>. </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} does not declare an <code>onClick()</code> handler method. So, to handle a click event, -you need to create an anonymous class to act as a listener for the event, then register the listener with the -target class object (via the appropriate <code>set...Listener()</code> method). 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) - { - ... - - // Capture our button from layout and listen for 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) - { - //do something when the button is clicked - } - }; -} -</pre> - - -<h2 id="TouchMode">Touch Mode</h2> - <p> - When a user is navigating a user interface via directional keys such as a D-pad, it is - necessary to give focus to actionable items such as buttons so the user can see - what will take input. If the device has touch capabilities, however, and the user - begins interacting with the interface by touching it, it is no longer necessary to - always highlight, or give focus to, a particular view. Thus, there is a mode - for interaction named "touch mode." - </p> - <p> - For a touch-capable device, once the user touches the screen, the device - will enter touch mode. From this point onward, only views for which - {@link android.view.View#isFocusableInTouchMode} is true will be focusable, such as text editing widgets. - Other views that are touchable, like buttons, will not take focus when touched; they will - simply fire their on-click listeners when pressed. - </p> - <p> - Any time a user hits a directional key, such as a D-pad direction, the view device will - exit touch mode, and find a view to take focus, so that the user may resume interacting - with the user interface without touching the screen. - </p> - <p> - The touch mode state is maintained across {@link android.app.Activity}s. To query the current state, you can call - {@link android.view.View#isInTouchMode} to see whether the device is currently in touch mode. - </p> - - -<h2 id="Scrolling">Scrolling</h2> - <p> - The framework provides basic support for views that wish to internally - scroll their content. This includes keeping track of the X and Y scroll - offset as well as mechanisms for drawing scrollbars. See - {@link android.view.View#scrollBy(int, int)}, {@link android.view.View#scrollTo(int, int)} for more details. - </p> - -<h2 is="EventCycle">Event Cycle</h2> - <p>The basic cycle of a view is as follows:</p> - <ol> - <li>An event comes in and is dispatched to the appropriate view. The view - handles the event and notifies any listeners.</li> - <li>If, in the course of processing the event, the view's bounds may need - to be changed, the view will call {@link android.view.View#requestLayout()}.</li> - <li>Similarly, if in the course of processing the event the view's appearance - may need to be changed, the view will call {@link android.view.View#invalidate()}.</li> - <li>If either {@link android.view.View#requestLayout()} or {@link android.view.View#invalidate()} were called, - the framework will take care of measuring, laying out, and drawing the tree - as appropriate.</li> - </ol> - - <p class="note"><strong>Note:</strong> The entire view tree is single threaded. You must always be on - the UI thread when calling any method on any view. - If you are doing work on other threads and want to update the state of a view - from that thread, you should use a {@link android.os.Handler}. - </p>
\ No newline at end of file diff --git a/docs/html/guide/tutorials/hello-world.jd b/docs/html/guide/tutorials/hello-world.jd index c993048..bbc4f77 100644 --- a/docs/html/guide/tutorials/hello-world.jd +++ b/docs/html/guide/tutorials/hello-world.jd @@ -330,7 +330,7 @@ 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}guide/topics/views/index.html">Views and Layout</a> documentation for more +here. Read the <a href="{@docRoot}guide/topics/ui/index.html">User Interface</a> documentation for more information on creating layouts.</p> <div class="special"> diff --git a/docs/html/guide/tutorials/notepad/codelab/NotepadCodeLab.zip b/docs/html/guide/tutorials/notepad/codelab/NotepadCodeLab.zip Binary files differindex 86f5e9d..c7dd989 100755..100644 --- a/docs/html/guide/tutorials/notepad/codelab/NotepadCodeLab.zip +++ 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 index 45ed97e..b7f42bf 100644 --- a/docs/html/guide/tutorials/notepad/notepad-ex1.jd +++ b/docs/html/guide/tutorials/notepad/notepad-ex1.jd @@ -1,4 +1,6 @@ page.title=Notepad Exercise 1 +parent.title=Notepad Tutorial +parent.link=index.html @jd:body @@ -584,5 +586,4 @@ the zip file to compare with your own.</p> <p>Once you are ready, move on to <a href="notepad-ex2.html">Tutorial Exercise 2</a> to add the ability to create, edit and delete notes.</p> -<p><a href="index.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 index b4608fb..3b8fa0b 100644 --- a/docs/html/guide/tutorials/notepad/notepad-ex2.jd +++ b/docs/html/guide/tutorials/notepad/notepad-ex2.jd @@ -1,9 +1,12 @@ page.title=Notepad Exercise 2 +parent.title=Notepad Tutorial +parent.link=index.html @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 +create and edit notes. You will also allow the user to delete existing notes through a context menu. +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> @@ -11,6 +14,7 @@ demonstrates:</em></p> <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> +<li><em>How to create a context menu</em></li> </ul> <div style="float:right;white-space:nowrap"> @@ -51,7 +55,8 @@ Tools</strong> > <strong>Fix Project Properties</strong>.</p> </li> <li> There are also a couple of new overridden methods - (<code>onListItemClick()</code> and <code>onActivityResult()</code>) + (<code>onCreateContextMenu()</code>, <code>onContextItemSelected()</code>, + <code>onListItemClick()</code> and <code>onActivityResult()</code>) which we will be filling in below. </li> </ul> @@ -59,59 +64,62 @@ Tools</strong> > <strong>Fix Project Properties</strong>.</p> <h2>Step 2</h2> - <p>Add an entry to the menu for deleting a note:</p> +<div class="sidebox"> +<p>Context menus should always be used when performing actions upon specific elements in the UI. +When you register a View to a context menu, the context menu is revealed by performing a "long-click" +on the UI component (press and hold the touchscreen or highlight and hold down the selection key for about two seconds).</p> +</div> + +<p>First, let's create the context menu that will allow users to delete individual notes. +Open the Notepadv2 class.</p> + <ol> + <li>In order for each list item in the ListView to register for the context menu, we call + <code>registerForContextMenu()</code> and pass it our ListView. So, at the very end of + the <code>onCreate()</code> method add this line: + <pre>registerForContextMenu(getListView());</pre> + <p>Because our Activity extends the ListActivity class, <code>getListView()</code> will return us + the local ListView object for the Activity. Now, each list item in this ListView will activate the + context menu. <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> + Now fill in the <code>onCreateContextMenu()</code> method. This callback is similar to the other + menu callback used for the options menu. Here, we add just one line, which will add a menu item + to delete a note. Call <code>menu.add()</code> like so: <pre> -@Override -public boolean onCreateOptionsMenu(Menu menu) { - super.onCreateOptionsMenu(menu); - menu.add(0, INSERT_ID, 0, R.string.menu_insert); +public boolean onCreateContextMenu(Menu menu, View v + ContextMenuInfo menuInfo) { + super.onCreateContextMenu(menu, v, menuInfo); menu.add(0, DELETE_ID, 0, R.string.menu_delete); - return true; }</pre> + <p>The <code>onCreateContextMenu()</code> callback some passes other information in addition to the Menu object, + such as the View that has been triggered for the menu and + an extra object that may contain additional information about the object selected. However, we don't care about + these here, because we only have one kind of object in the Activity that uses context menus. In the next + step, we'll handle the menu item selection.</p> </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) { + <p>Now that the we've registered our ListView for a context menu and defined our context menu item, we need + to handle the callback when it is selected. For this, we need to identify the list ID of the + selected item, then delete it. So fill in the + <code>onContextItemSelected()</code> method like this:</p> +<pre> +public boolean onContextItemSelected(MenuItem item) { switch(item.getItemId()) { - case INSERT_ID: - createNote(); - return true; case DELETE_ID: - mDbHelper.deleteNote(getListView().getSelectedItemId()); + AdapterContextMenuInfo info = (AdapterContextMenuInfo) item.getMenuInfo(); + mDbHelper.deleteNote(info.id); fillData(); return true; } - - return super.onMenuItemSelected(featureId, item); + return super.onContextItemSelected(item); }</pre> +<p>Here, we retrieve the {@link android.widget.AdapterView.AdapterContextMenuInfo AdapterContextMenuInfo} +with {@link android.view.MenuItem#getMenuInfo()}. The <var>id</var> field of this object tells us +the position of the item in the ListView. We then pass this to the <code>deleteNote()</code> +method of our NotesDbAdapter and the note is deleted. That's it for the context menu — notes +can now be deleted.</p> <h2 style="clear:right;">Step 4</h2> <div class="sidebox" style="border:2px solid #FFFFDD;float:right; @@ -294,8 +302,8 @@ case ACTIVITY_EDIT: 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}guide/topics/views/declaring-layout.html">Android layout</a> is an essential part of creating + good UI is part art and part science, and the rest is work. Mastery of <a + href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring 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 @@ -570,7 +578,7 @@ protected void onCreate(Bundle savedInstanceState) { 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}guide/topics/manifest/manifest.html">AndroidManifest.xml</a></p> + <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a></p> </div> <p>Finally, the new Activity has to be defined in the manifest file:</p> @@ -636,5 +644,4 @@ Once you are ready, move on to <a href="notepad-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="index.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 index a2eaa48..8737280 100644 --- a/docs/html/guide/tutorials/notepad/notepad-ex3.jd +++ b/docs/html/guide/tutorials/notepad/notepad-ex3.jd @@ -1,4 +1,6 @@ page.title=Notepad Exercise 3 +parent.title=Notepad Tutorial +parent.link=index.html @jd:body @@ -354,4 +356,3 @@ the zip file to compare with your own.</p> When you are ready, move on to the <a href="notepad-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="index.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 index f64e90e..0d59b56 100644 --- a/docs/html/guide/tutorials/notepad/notepad-extra-credit.jd +++ b/docs/html/guide/tutorials/notepad/notepad-extra-credit.jd @@ -1,4 +1,6 @@ -page.title=Tutorial: Extra Credit +page.title=Notepad Extra Credit +parent.title=Notepad Tutorial +parent.link=index.html @jd:body @@ -65,6 +67,4 @@ when.</p> your application development, but also superb profiling support. You can also try using <a href="{@docRoot}guide/developing/tools/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="index.html">Back to the Tutorial main -page...</a></p> diff --git a/docs/html/guide/tutorials/views/hello-mapview.jd b/docs/html/guide/tutorials/views/hello-mapview.jd index fcdf056..b0f59de 100644 --- a/docs/html/guide/tutorials/views/hello-mapview.jd +++ b/docs/html/guide/tutorials/views/hello-mapview.jd @@ -43,7 +43,7 @@ First, we'll create a simple Activity that can view and navigate a map. Then we The API key is generated using the MD5 fingerprint of your application certificate. For the purposes of this exercise, you should use the fingerprint of your debug certificate (which cannot be used to release your application for Android devices, but will work while developing). See how to - <a href="{@docRoot}guide/topics/geo/mapkey.html#getdebugfingerprint">generate a fingerprint from your + <a href="{@docRoot}guide/topics/location/geo/mapkey.html#getdebugfingerprint">generate a fingerprint from your debug certificate</a>, then <a href="http://code.google.com/android/maps-api-signup.html">register the certificate</a> to retieve an API key. Insert the API key as the value of the <code>apiKey</code> attribute. If you do not insert a valid diff --git a/docs/html/guide/tutorials/views/index.jd b/docs/html/guide/tutorials/views/index.jd index 6a6ac4b..2248c68 100644 --- a/docs/html/guide/tutorials/views/index.jd +++ b/docs/html/guide/tutorials/views/index.jd @@ -30,67 +30,67 @@ your strings.xml file.</p> <div> <div class="view"> -<a href="hello-linearlayout.html">LinearLayout<br/> -<img src="images/hello-linearlayout.png" height="285" width="200" /></a> +<a href="hello-linearlayout.html">LinearLayout</a><br/> +<a href="hello-linearlayout.html"><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> +<a href="hello-relativelayout.html">RelativeLayout</a><br/> +<a href="hello-relativelayout.html"><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> +<a href="hello-tablelayout.html">TableLayout</a><br/> +<a href="hello-tablelayout.html"><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> +<a href="hello-datepicker.html">DatePicker</a><br/> +<a href="hello-datepicker.html"><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> +<a href="hello-timepicker.html">TimePicker</a><br/> +<a href="hello-timepicker.html"><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> +<a href="hello-formstuff.html">Form Stuff</a><br/> +<a href="hello-formstuff.html"><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> +<a href="hello-spinner.html">Spinner</a><br/> +<a href="hello-spinner.html"><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> +<a href="hello-autocomplete.html">AutoComplete</a><br/> +<a href="hello-autocomplete.html"><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> +<a href="hello-listview.html">ListView</a><br/> +<a href="hello-listview.html"><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> +<a href="hello-gridview.html">GridView</a><br/> +<a href="hello-gridview.html"><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> +<a href="hello-gallery.html">Gallery</a><br/> +<a href="hello-gallery.html"><img src="images/hello-gallery.png" height="285" width="200" /></a> </div> <div class="view"> -<a href="hello-tabwidget.html">TabWidget<br/> -<img src="images/hello-tabwidget.png" height="285" width="200" /></a> +<a href="hello-tabwidget.html">TabWidget</a><br/> +<a href="hello-tabwidget.html"><img src="images/hello-tabwidget.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> +<a href="hello-mapview.html">MapView</a><br/> +<a href="hello-mapview.html"><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> +<a href="hello-webview.html">WebView</a><br/> +<a href="hello-webview.html"><img src="images/hello-webview.png" height="285" width="200" /></a> </div> <!-- diff --git a/docs/html/images/adc1r1_deck.pdf b/docs/html/images/adc1r1_deck.pdf Binary files differdeleted file mode 100644 index e76a554..0000000 --- a/docs/html/images/adc1r1_deck.pdf +++ /dev/null diff --git a/docs/html/images/binder_rpc.png b/docs/html/images/binder_rpc.png Binary files differnew file mode 100644 index 0000000..1021109 --- /dev/null +++ b/docs/html/images/binder_rpc.png diff --git a/docs/html/images/options_menu.png b/docs/html/images/options_menu.png Binary files differnew file mode 100755 index 0000000..ecb9394 --- /dev/null +++ b/docs/html/images/options_menu.png diff --git a/docs/html/images/radio_buttons.png b/docs/html/images/radio_buttons.png Binary files differnew file mode 100755 index 0000000..b755e42 --- /dev/null +++ b/docs/html/images/radio_buttons.png diff --git a/docs/html/images/table_layout.png b/docs/html/images/table_layout.png Binary files differindex bc1a47c..e7fae2d 100644 --- a/docs/html/images/table_layout.png +++ b/docs/html/images/table_layout.png diff --git a/docs/html/index.jd b/docs/html/index.jd index 05ab987..8db339d 100644 --- a/docs/html/index.jd +++ b/docs/html/index.jd @@ -7,14 +7,16 @@ page.title=Home <div id="mainBodyLeft"> <div id="homeMiddle"> <div id="homeTitle"> - <div style="float:left;"> - <h2>T-Mobile G1 Now Available!</h2> - </div> - <div style="float:right;" align="center"> - <a href="http://www.t-mobileg1.com">Learn more »</a><br /> - <!-- <img src="{@docRoot}assets/images/icon_robot.jpg" style="margin:8px 10px 0 10px; clear:both;" /> --> - </div> + <h2>Developer Announcements</h2> </div><!-- end homeTitle --> + <div id="announcement-block"> + <!-- total max width is 520px --> + <img src="{@docRoot}assets/images/home/IO-logo.png" alt="Google I/O Developer Conference 2009" width="242px" /> + <div id="announcement" style="width:270px"> + <p>Google I/O is a two-day developer event that will take place May 27-28 at Moscone Center, San Francisco.</p> + <p><a href="http://code.google.com/events/io/">Learn more »</a></p> + </div> <!-- end annoucement --> + </div> <!-- end annoucement-block --> <div id="carouselMain"> <div id="bulletinImg"></div> <div id="bulletinDesc"></div> @@ -27,51 +29,32 @@ page.title=Home <!-- populated by buildCarousel() --> </div> </div><!-- end list-clip --> - <a href="javascript:{}" id="arrow-right" onclick="" class="arrow-right-off"></a> + <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" style="padding:0" /></td> + <td class="imageCell"><a href="{@docRoot}sdk/index.html"><img src="{@docRoot}assets/images/icon_download.jpg" style="padding:0" /></a></td> <td> <h2 class="green">Download</h2> - <p>Latest SDK</p> - <p><a href="{@docRoot}sdk/index.html">Download now</a></p> + <p>The Android SDK has the tools, sample code, and docs you need to create great apps. </p> + <p><a href="{@docRoot}sdk/1.1_r1/index.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_market.jpg" style="padding:0" /></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> + <td class="imageCell"><a href="http://www.android.com/market.html"><img src="{@docRoot}assets/images/icon_market.jpg" style="padding:0" /></a></td> + <td> + <h2 class="green">Publish</h2> + <p>Android Market is an open service that lets you distribute your apps to handsets.</p> <p><a href="http://www.android.com/market.html">Learn more »</a></p> </td> </tr> @@ -79,16 +62,25 @@ page.title=Home <td colspan="2"><div class="seperator"> </div></td> </tr> <tr> - <td class="imageCell"><img src="{@docRoot}assets/images/icon_contribute.jpg" style="padding:0" /></td> + <td class="imageCell"><a href="http://source.android.com"><img src="{@docRoot}assets/images/icon_contribute.jpg" style="padding:0" /></a></td> <td> <h2 class="green">Contribute</h2> - <p>Create using our open source codebase and help us keep this project growing.</p> + <p>Android Open Source Project gives you access to the entire platform source.</p> <p><a href="http://source.android.com">Learn more »</a></p> </td> </tr> <tr> <td colspan="2"><div class="seperator"> </div></td> </tr> + <tr> + <td class="imageCell"><a href="http://www.youtube.com/user/androiddevelopers"><img src="{@docRoot}assets/images/video-droid.png" style="padding:0" /></a></td> + <td> + <h2 class="green">Watch</h2> + <object width="150" height="140"><param name="movie" value="http://www.youtube.com/v/x1ZZ-R3p_w8&hl=en&fs=1"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/x1ZZ-R3p_w8&hl=en&fs=1" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="150" height="140"></embed></object> + <p style="margin-top:1em"><a href="http://www.youtube.com/user/androiddevelopers">More Android videos »</a></p> + </td> + </tr> + </table> </div> </div> @@ -125,10 +117,10 @@ page.title=Home 'sdk': { 'layout':"imgLeft", 'icon':"sdk-small.png", - 'name':"SDK 1.0 r1", + 'name':"SDK 1.1 r1", 'img':"sdk-large.png", - 'title':"Android 1.0 SDK r1", - 'desc': "<p>The first Android 1.0 SDK is available for download. This is the first release guaranteed to operate on the first Android devices. If you want to release an application for Android, you should be developing with this SDK.</p><p><a href='{@docRoot}sdk/index.html'>Download Android 1.0 SDK r1</a></p>" + 'title':"Android 1.1 SDK r1", + 'desc': "<p>A new Android SDK is available for download. The new SDK includes minor API changes, new UI localizations, bug fixes and some new application features.</p><p><a href='{@docRoot}sdk/1.1_r1/index.html'>Download Android 1.1 SDK r1</a></p>" }, 'mapskey': { @@ -137,7 +129,7 @@ page.title=Home 'name':"Maps API Key", 'img':"maps-large.png", 'title':"Maps API Key", - 'desc':"<p>If you're writing an Android application that uses Google Maps (with MapView), you must register your application to obtain a Maps API Key. Without the key, your maps application will not work on Android devices. Obtaining a key requires just a couple of steps.</p><p><a href='{@docRoot}guide/topics/geo/mapkey.html'>Learn how to get a Maps API Key</a></p>" + 'desc':"<p>If you're writing an Android application that uses Google Maps (with MapView), you must register your application to obtain a Maps API Key. Without the key, your maps application will not work on Android devices. Obtaining a key requires just a couple of steps.</p><p><a href='{@docRoot}guide/topics/location/geo/mapkey.html'>Learn how to get a Maps API Key</a></p>" }, 'market': { @@ -147,6 +139,15 @@ page.title=Home 'img':"market-large.png", 'title':"", 'desc': "<p>Android Market helps you get your applications into the hands of users. The beta version of Market is now open and you can begin sharing your applications with users of the first Android-powered phone, the T-Mobile G1.</p><p><a href='http://market.android.com/publish/'>Publish your Android app on Market »</a></p>" + }, + + 'devphone': { + 'layout':"imgLeft", + 'icon':"devphone-small.png", + 'name':"Dev Phone 1", + 'img':"devphone-large.png", + 'title':"Android Dev Phone 1", + 'desc': "<p>Run and debug your Android applications directly on this device. Modify and rebuild the Android operating system, and flash it onto the phone. The Android Dev Phone 1 is carrier independent, and available for purchase by any developer registered with <a href='http://market.android.com/publish'>Android Market</a>.</p><p><a href='/guide/developing/device.html#dev-phone-1'>Learn more about the Android Dev Phone 1 »</a></p>" } } diff --git a/docs/html/license.jd b/docs/html/license.jd new file mode 100644 index 0000000..39fb3a0 --- /dev/null +++ b/docs/html/license.jd @@ -0,0 +1,142 @@ +page.title=Content License +@jd:body + +<div id="mainBodyFluid"> +<h1>Content License</h1> + +<p>For the purposes of licensing, the content of this site is divided +into two categories:</p> +<ul> + <li>Documentation content, found under the "Dev Guide" and "Reference" + tabs, including both static content and content extracted from source + code modules, as well as sample code, and </li> +<li>All other site content</li> +</ul> + +<p>The documentation content on this site is made available to +you as part of the <a href="http://source.android.com">Android Open +Source Project</a>. This documentation, including any code shown in it, +is licensed under the <a +href="http://www.apache.org/licenses/LICENSE-2.0">Apache 2.0 +license</a>, the preferred license for all parts of the of the Android +Open Source Project.</p> + +<p>Apache 2.0 is a commercial and open-source-friendly software +license. The majority of the Android platform and documentation is +licensed under the Apache 2.0 license. While the project strives to +adhere to the preferred license, there may be exceptions, such as for +documentation (code comments) extracted from a source code module that +is licensed under GPLv2 or other license. In those cases, the license +covering the source code module will apply to the documentation +extracted from it. </p> + +<p>All other content on this site, except as otherwise noted, +is licensed under the <a +href="http://creativecommons.org/licenses/by/2.5/">Creative Commons +Attribution 2.5</a> license. </p> + +<p>You may use the content of this site in any way that is consistent +with the specific license that applies to the content, as described +above. For content licensed under Creative Commons Attribution 2.5, we +ask that you give proper <a href="#attribution">attribution</a>. </p> + + +<h3 id="terms">Terms of Use</h3> + +<p>We are pleased to license the Android documentation and sample code under +terms that encourage you to take, modify, reuse, re-purpose, and remix the +content as you see fit. Except as noted in the Restrictions section below, you +are free to use the documentation content in your own creations. For example, +you could quote the text in a book, cut-and-paste sections to your blog, record +it as an audiobook for the visually impaired, or even translate it. </p> + + +<h3 id="restrictions">Restrictions</h3> + +<ul> +<li>While the documentation itself is available to you under the Apache 2.0 +license, note that proprietary trademarks and brand features are not +included in that license.</li> + +<li>Google's trademarks and other brand features (including the +ANDROID stylized typeface logo) are not included in the license. +Please see <a href="http://www.google.com/permissions/guidelines.html"> +Guidelines for Third Party Use of Google Brand Features</a> for +information about this usage. </li> + +<li>In some cases, a page may include content, such as an image, that is not +covered by the license. In that case, we will label the content that is not licensed. </li> + +<li>In addition, content linked from a page on this site is not covered +by the license unless specifically noted. For example, pages may link to videos or +slide decks that are not covered.</li> + +<li>The use of sample source code provided in the SDK or shown in this +documentation is subject to the conditions detailed in the <a +href="{@docRoot}sdk/terms.html">SDK Terms and Conditions</a>.</li> +</ul> +</h3> + +<h3 id="attribution">Attribution</h3> +<p> +Proper attribution is required when you reuse or create modified +versions of content that appears on a page made available under the +terms of the Creative Commons Attribution license. On this site, the +requirement for attribution applies only to the non-documentation +content, as described earlier in this document. The complete +requirements for attribution can be found in section 4b of the +<a href="http://creativecommons.org/licenses/by/2.5/legalcode"> +Creative Commons legal code</a>. +</p> +<p> + In practice we ask that you provide attribution to the Android Open + Source project to the best of the ability of the medium in which you + are producing the work. There are several typical ways in which this + might apply: +</p> +<h4>Exact Reproductions</h4> +<p> + If your online work <em>exactly reproduces</em> text or images from this + site, in whole or in part, please include a paragraph at the bottom + of your page that reads: +</p> +<blockquote> + Portions of this page are reproduced from work created and <a + href="http://code.google.com/policies.html">shared by the Android Open Source Project</a> + and used according to terms described in the <a + href="http://creativecommons.org/licenses/by/2.5/">Creative Commons + 2.5 Attribution License</a>. + +</blockquote> +<p> + Also, please link back to the original source page so that readers can + refer there for more information. +</p> +<h4>Modified Versions</h4> +<p> + If your online work shows <em>modified</em> text or images based on + the content from this site, please include a paragraph at the bottom of + your page that reads: +</p> +<blockquote> + Portions of this page are modifications based on work created and <a + href="http://code.google.com/policies.html">shared by the Android Open + Source Project</a> and used according to terms described in the <a + href="http://creativecommons.org/licenses/by/2.5/">Creative Commons + 2.5 Attribution License</a>. +</blockquote> +<p> + Again, please link back to the original source page so that readers can + refer there for more information. This is even more important when + the content has been modified. +</p> +<h4>Other Media</h4> +<p> + If you produce non-hypertext works, such as books, audio, or + video, we ask that you make a best effort to include a spoken or + written attribution in the spirit of the messages above. +</p> + +</div> + + diff --git a/docs/html/offline.jd b/docs/html/offline.jd new file mode 100644 index 0000000..07c20d6 --- /dev/null +++ b/docs/html/offline.jd @@ -0,0 +1,28 @@ +home=true +page.title=Welcome +@jd:body + +<div id="mainBodyFluid"> + +<h1>Welcome to the Android SDK!</h1> + +<img src="{@docRoot}images/android_icon_125.png" style="float:right; margin:1em 6em 6em;" /> + +<p>If you've just downloaded the SDK, then continue with the +<a href="{@docRoot}sdk/1.1_r1/installing.html">Installing</a> guide.</p> + +<p>If you're upgrading from a previously installed version, then refer to the +<a href="{@docRoot}sdk/1.1_r1/upgrading.html">Upgrading</a> guide.</p> + +<p>Once you've completed the SDK installation, you can start learning about development on the Android framework +by reading the <em><a href="{@docRoot}guide/index.html">Dev Guide</a></em>. And don't forget that the SDK comes packaged with +a wide variety of very helpful code <a href="{@docRoot}samples/index.html">samples</a>.</p> + +<p>Please note that you are currently viewing a local, offline version of the Android developer documentation. +The offline documentation will behave just like the online documentation, except searches in the above +search bar will not work. However, the search bar is still able to provide auto-completion for package and class names, +which can help you quickly find reference documentation for specific classes that you remember. +If you'd like fully searchable documentation, please visit +<a href="http://developer.android.com/index.html">http://developer.android.com</a>.</p> + +</div>
\ No newline at end of file diff --git a/docs/html/resources/bootcamp.pdf b/docs/html/resources/bootcamp.pdf Binary files differdeleted file mode 100644 index a817b96..0000000 --- a/docs/html/resources/bootcamp.pdf +++ /dev/null diff --git a/docs/html/samples/index.jd b/docs/html/samples/index.jd index 6219f9a..c5c0b71 100644 --- a/docs/html/samples/index.jd +++ b/docs/html/samples/index.jd @@ -17,7 +17,7 @@ page.onlyfortemplate=codesite </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 +href="{@docRoot}guide/developing/eclipse-adt.html#creatingaproject">import them into +Eclipse</a> or <a href="{@docRoot}guide/developing/other-ide.html">use activitycreator.py</a>, as described in the <a -href="{@docRoot}intro/installing.html">Installing the SDK</a>.</p> +href="{@docRoot}sdk/1.1_r1/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 deleted file mode 100644 index c6a38bb..0000000 --- a/docs/html/sdk/1.0_r1/RELEASENOTES.jd +++ /dev/null @@ -1,100 +0,0 @@ -page.title=Release Notes, 1.0 r1 -@jd:body - - -<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> - <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> - diff --git a/docs/html/sdk/1.0_r1/index.jd b/docs/html/sdk/1.0_r1/index.jd index 7ad4e88..d236844 100644 --- a/docs/html/sdk/1.0_r1/index.jd +++ b/docs/html/sdk/1.0_r1/index.jd @@ -1,6 +1,8 @@ -page.title=Download 1.0r1 +page.title=Android 1.0 SDK, release 1 -sdk.version=Android 1.0 SDK, release 1 +sdk.not_latest_version=true + +sdk.version=1.0_r1 sdk.date=September 23, 2008 sdk.win_download=android-sdk-windows-1.0_r1.zip @@ -15,4 +17,48 @@ sdk.linux_download=android-sdk-linux_x86-1.0_r1.zip sdk.linux_bytes=87.8 MB sdk.linux_checksum=2660b4029039b7d714e59827e9a9a11d + @jd:body + +<h2>Included in this SDK</h2> + +<p>This SDK includes some awesome stuff.</p> + + +<h2>System and Software Requirements</h2> + +<p>The following systems and development environments are supported by this SDK.</p> + +<h4>Supported Operating Systems:</h4> +<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> + +<h4>Supported Development Environments:</h4> +<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>
\ 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 deleted file mode 100644 index 5c6e6fc..0000000 --- a/docs/html/sdk/1.0_r1/terms.jd +++ /dev/null @@ -1,7 +0,0 @@ -page.title=Terms and Conditions -@jd:body - -<?cs include:"terms_body.html" ?> - - - diff --git a/docs/html/sdk/1.0_r2/index.jd b/docs/html/sdk/1.0_r2/index.jd new file mode 100644 index 0000000..6fbca6d --- /dev/null +++ b/docs/html/sdk/1.0_r2/index.jd @@ -0,0 +1,64 @@ +page.title=Android 1.0 SDK, release 2 + +sdk.not_latest_version=true + +sdk.version=1.0_r2 +sdk.date=November 2008 + +sdk.win_download=android-sdk-windows-1.0_r2.zip +sdk.win_bytes=98360564 +sdk.win_checksum=a5e1af8ac145946b4a9627516ad4a711 + +sdk.mac_download=android-sdk-mac_x86-1.0_r2.zip +sdk.mac_bytes=93771410 +sdk.mac_checksum=87b99d5e9f59b78363a63200c11498e8 + +sdk.linux_download=android-sdk-linux_x86-1.0_r2.zip +sdk.linux_bytes=94186463 +sdk.linux_checksum=a1f3b6d854596f850f5008856d0f380e + + +@jd:body + +<h2>Included in this SDK</h2> + +<p>This SDK includes some awesome stuff.</p> + + +<h2>System and Software Requirements</h2> + +<p>The following systems and development environments are supported by this SDK.</p> + +<h4>Supported Operating Systems:</h4> +<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> + +<h4>Supported Development Environments:</h4> +<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>
\ No newline at end of file diff --git a/docs/html/sdk/1.0_r2/installing.jd b/docs/html/sdk/1.0_r2/installing.jd new file mode 100644 index 0000000..0f15396 --- /dev/null +++ b/docs/html/sdk/1.0_r2/installing.jd @@ -0,0 +1,124 @@ +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, follow the link below.</p> + +<div class="linkbox"><a href="http://developer.android.com/sdk/">Download the SDK</a></div> + +<p>Before you begin, be sure that you're development environment meets the SDK +<a href="requirements.html">System and Software Requirements</a>.</p> + +<div class="special"> +<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="upgrading.html">Upgrading the SDK</a></b> document. +</p> +</div> + + +<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}guide/developing/tools/index.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> + +<h3>Setting up Eclipse</h3> +<p>If you'll be developing with the Eclipse IDE, follow the following procedure to setup the IDE +to use the Android SDK.</p> +<p>Basically, you just need to update your Eclipse preferences to point to the Android 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> +<p>Done! We now recommend that you install the ADT Eclipse plugin, which will provide some much-appreciated assistance in developing Android apps with Eclipse...</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. This plugin is highly recommended for Eclipse users.</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><strong>Follow this guide to install the ADT Plugin</strong></p> + +<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 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_r2/upgrading.jd b/docs/html/sdk/1.0_r2/upgrading.jd new file mode 100644 index 0000000..168f1be --- /dev/null +++ b/docs/html/sdk/1.0_r2/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="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="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="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}guide/publishing/app-signing.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 Android 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="migrating/changes-overview.html">Overview of Changes</a> +and <a href="migrating/changes.html">API Diffs Report</a>.</p> + +<p>If you have additional trouble updating your code, visit the +<a href="http://groups.google.com/group/android-developers">Android Developers Group</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}guide/appendix/faq/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/1.1_r1/index.jd b/docs/html/sdk/1.1_r1/index.jd new file mode 100644 index 0000000..b516acb --- /dev/null +++ b/docs/html/sdk/1.1_r1/index.jd @@ -0,0 +1,62 @@ +page.title=Download Android 1.1 SDK, Release 1 + +sdk.version=1.1_r1 +sdk.date=February 2009 + +sdk.win_download=android-sdk-windows-1.1_r1.zip +sdk.win_bytes=unknown +sdk.win_checksum=unknown + +sdk.mac_download=android-sdk-mac_x86-1.1_r1.zip +sdk.mac_bytes=unknown +sdk.mac_checksum=unknown + +sdk.linux_download=android-sdk-linux_x86-1.1_r1.zip +sdk.linux_bytes=unknown +sdk.linux_checksum=unknown + + +@jd:body + +<h2>SDK Contents</h2> + +<h4>Development tools</h4> + +<p>The SDK includes a variety of tools for developing and debugging application code and designing an application UI. You can read about the tools in the +<a href="{@docRoot}guide/developing/tools/index.html">Dev Guide</a> and access them in the <code><sdk>/tools/</code> directory. + +<p>The tools package included in this SDK is the same as that included in the Android 1.0, Release 2 SDK. </p> + +<h4 id="system_images">System Images</h4> + +<p>The Android system images listed below are included in this SDK. For more information about a system image — features, applications included, localizations, API changes, and so on — see its Version Notes. </p> + +<table style="margin-right:1em;" width="80%"> +<tr> +<th><nobr>System Image</nobr></th><th><nobr>API Level</nobr></th><th>Notes</th><th>Description</th> +</tr> + +<tr> +<td width="5%"><nobr>Android 1.1</nobr></td> +<td width="5%">2</td> +<td width="5%"><nobr><a href="{@docRoot}sdk/android-1.1.html">Version Notes</a></nobr></td> +<td>Includes com.google.android.maps external library and a set of standard development applications. </td> + +</tr> + +</table> + +<h4>Sample Code and Applications</h4> + +<p>You can look at a variety of tutorials and samples in the <a href="{@docRoot}guide/samples/index.html">Dev Guide</a> and access the sample code itself +in the <code><sdk>/samples/</code> directory of the SDK package.</p> + +<h4>Documentation</h4> + +<p>The SDK package includes a full set of local documentation. To view it, open the <code><sdk>/documentation.html</code> file in a web browser. If you are developing in an IDE such as Eclipse, you can also view the reference documentation directly in the IDE. </p> + +<p>The most current documentation is always available on the Android Developers site:</p> + +<p style="margin-left:2em;"><a href="ttp://developer.android.com/index.html">http://developer.android.com/</a></p> + + diff --git a/docs/html/sdk/1.1_r1/installing.jd b/docs/html/sdk/1.1_r1/installing.jd new file mode 100644 index 0000000..1319237 --- /dev/null +++ b/docs/html/sdk/1.1_r1/installing.jd @@ -0,0 +1,216 @@ +page.title=Installing the Android SDK +sdk.version=1.1_r1 + +@jd:body + + +<p>This page describes how to install the Android 1.1 SDK, Release 1, and set up your development environment. +If you haven't downloaded the SDK yet, you can so so from the <a href="{@docRoot}sdk/1.1_r1/index.html">Download</a> page.</p> + +<p>Before you begin, be sure that your development environment meets the SDK +<a href="{@docRoot}sdk/1.1_r1/requirements.html">System Requirements</a>.</p> + +<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 +<a href="{@docRoot}sdk/1.1_r1/upgrading.html"><strong>Upgrading the SDK</strong></a></b> document instead. +</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}guide/developing/tools/index.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> + +<h2>Setting up Eclipse</h2> +<p>If you'll be developing with the Eclipse IDE, follow the following procedure to setup the IDE +to use the Android SDK.</p> +<p>Basically, you just need to update your Eclipse preferences to point to the Android 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> +<p>Done! We now recommend that you install the ADT Eclipse plugin, which will provide some much-appreciated assistance in developing Android apps with Eclipse...</p> + + +<h2 id="installingplugin">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. Developing in ADT/Eclipse is highly recommended for Eclipse users and those new to Android.</p> + +<p>If you <em>will not</em> be using the Eclipse IDE, you do not need to download or install the ADT plugin. You can still develop Android applications using other tools. </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="45%"> +<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> + <p>Alternatively, you can use http in the Location URL, if you are having + trouble with https (https is preferred for security reasons).</p> + <pre>http://dl-ssl.google.com/android/eclipse/</pre> + <p>Click <strong>OK</strong>.</p> </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. 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> + <p>Alternatively, you can use http in the Location URL, if you are having + trouble with https (https is preferred for security reasons).</p> + <pre>http://dl-ssl.google.com/android/eclipse/</pre> + <p>Click <strong>OK</strong>.</p></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. Click <strong>Next</strong>. + </li> + <li>Accept the license agreement and click <strong>Finish</strong>.</li> + <li>Restart Eclipse. </li> +</ol> + +</td> +</tr> +</table> + +<h3 id="troubleshooting">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>If Eclipse can not find the remote update site containing the ADT plugin, try changing the remote site URL to use http, rather than https. That is, set the Location for the remote site to: + <pre>http://dl-ssl.google.com/android/eclipse/</pre></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 as a remote update site, you can download the ADT files to your local machine using a browser and the install the files in Eclipse from there: +</p> +<ol> +<li><a href="{@docRoot}sdk/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}guide/appendix/faq/troubleshooting.html#installeclipsecomponents">ADT Installation Error: "requires plug-in org.eclipse.wst.sse.ui"</a>.</p> + +<h4>For Linux users</h4> +<p>If you encounter this error when installing the ADT Plugin for Eclipse: +<pre> +An error occurred during provisioning. +Cannot connect to keystore. +JKS</pre> +<p> +...then your development machine lacks a suitable Java VM. Installing Sun +Java 6 will resolve this issue and you can then reinstall the ADT +Plugin.</p> + +<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 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> + + diff --git a/docs/html/sdk/1.0_r1/requirements.jd b/docs/html/sdk/1.1_r1/requirements.jd index 6af3900..95b658b 100644 --- a/docs/html/sdk/1.0_r1/requirements.jd +++ b/docs/html/sdk/1.1_r1/requirements.jd @@ -1,18 +1,20 @@ -page.title=System and Software Requirements -@jd:body +page.title=System Requirements + +sdk.version=1.1_r1 +sdk.date=February 2009 +@jd:body -<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>The sections below describe the system and software requirements for developing Android applications using the Android SDK tools included in Android 1.1 SDK, Release 1. </p> -<p><strong>Supported Operating Systems:</strong></p> +<h3>Supported Operating Systems</h3> <ul> - <li>Windows XP or Vista</li> + <li>Windows XP (32-bit) or Vista (32- or 64-bit)</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> +<h3>Supported Development Environments</h3> <ul> <li>Eclipse IDE <ul> diff --git a/docs/html/sdk/1.1_r1/upgrading.jd b/docs/html/sdk/1.1_r1/upgrading.jd new file mode 100644 index 0000000..aa7c3a5 --- /dev/null +++ b/docs/html/sdk/1.1_r1/upgrading.jd @@ -0,0 +1,185 @@ +page.title=Upgrading the SDK +sdk.version=1.1_r1 +@jd:body + +<!-- +<div class="sidebox-wrapper"> + <div class="sidebox-inner"> + + <h2>Useful Links</h2> + + <ul class="noindent"> + <li><a href="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="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="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> +--> + +<p>This document describes how to move your devlopment environment and existing +Android applications from an Android 1.0 SDK to the Android 1.1, Release 1 SDK. +If you are migrating applications from an earlier SDK, please read the upgrading +document available in the Android 1.0 SDK package. +</p> + +<p>To ensure that your applications are compliant with the Android 1.1 system available +on mobile devices, you need to install the Android 1.1 SDK and port your existing Android +applications to it. The sections below guide you through the process.</p> + +<h2 id="install-new">Installing the Latest SDK</h2> + +<p><a href="{@docRoot}sdk/1.1_r1/index.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>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. For example, 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> + <li>If (and only if) you are developing using Ant, you will also need to modify + your build.xml properties to point to the new SDK. + <p>Open the <code>default.properties</code> file associated with your build.xml + file (typically located in the same directory). In the default.properties + file, update the <code>sdk-folder</code> property with the full path to + the new SDK directory.</p></li> +</ul> + +<a name="Updating_the_ADT_plugin" id="Updating_the_ADT_plugin"></a> +<h2 id="update-plugin">Update your ADT Eclipse Plugin</h2> + +<p>If you develop on Eclipse and are migrating from an Android 1.0 +SDK, no update of the ADT plugin is needed. </p> + +<p>If you are migrating from an earlier version of the SDK, you will +need to update the ADT plugin. <p>You may also want to upgrade your +ADT plugin when a new version becomes available for your existing version +of the SDK.</p> + +<p>The steps below describe how to update the ADT plugin to the latest +version available. </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> +<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> + <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}guide/publishing/app-signing.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 (and only 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, if Necessary</h2> + +<p>If (and only if) you have written apps in an SDK released previous to +the Android 1.0 SDK, you will need to migrate your applications. After +installing the new SDK and updating the ADT Plugin (if applicable), you +may encounter breakages in your application code, due to +framework and API changes. You'll need to update your code to match the +latest 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 +specific API changes in the Android 1.0 APIs in the +<a href="http://code.google.com/android/migrating/changes-overview.html"> +Overview of Changes</a> and <a href="http://code.google.com/android/migrating/changes.html"> +API Diffs Report</a>.</p> + +<p>If you have additional trouble updating your code, visit the +<a href="http://groups.google.com/group/android-developers">Android Developers Group</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}guide/appendix/faq/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/RELEASENOTES.jd b/docs/html/sdk/RELEASENOTES.jd new file mode 100644 index 0000000..6e0716c --- /dev/null +++ b/docs/html/sdk/RELEASENOTES.jd @@ -0,0 +1,138 @@ +page.title=SDK Release Notes +sdk.version=1.1_r1 +@jd:body + +<p>This document provides version-specific information about Android SDK releases. For the latest known issues, please ensure that you're viewing this page at: <a href="http://developer.android.com/sdk/RELEASENOTES.html">http://developer.android.com/sdk/RELEASENOTES.html</a>.</p> + +<h2>Android 1.1 SDK, Release 1</h2> + +<p>This SDK provides the development tools and Android system image you need to create applications for Android-powered devices. Applications developed on this SDK will be compatible with mobile devices running the Android 1.1 platform. </p> + +<p>This release provides an updated system image (Android 1.1), updated documentation, and the same set of development tools provided in the Android 1.0 r2 SDK. The updated system image includes bug fixes and some smaller features, as well as a few minor API changes from the 1.0 version. </p> + +<p>For details about the Android 1.1 system image included in the SDK — including bug fixes, features, and API changes — please read the <a href="{@docRoot}sdk/android-1.1.html">Android 1.1 Version Notes</a>.</p> + +<h3>App Versioning for Android 1.1</h3> + +<p>If you are using this SDK to build an application that is compatible <em>only</em> with Android-powered devices running the Android 1.1 platform, please note that you <strong>must</strong> set the the <code>android:minSdkVersion</code> attribute in the application's manifest to the API Level of Android 1.1 — "2".</p> + +<p>Specifically, you specify the <code>android:minSdkVersion</code> attribute in a <code><uses-sdk></code> element as a child of <code><manifest></code> in the manifest file. When set, the attribute looks like this: </p> + +<pre><code><manifest> + ... + <uses-sdk minSdkVersion="2"> + ... +</manifest></code> +</pre> + +<p>By setting <code>android:minSdkVersion</code> in this way, you ensure that users will only be able to install your application if their devices are running the Android 1.1 platform. In turn, this ensures that your application will function properly on their devices, especially if it uses APIs introduced in Android 1.1. </p> + +<p>If your application uses APIs introduced in Android 1.1 but does not declare <code><uses-sdk minSdkVersion="2"></code>, then it will run properly on Android 1.1 devices but <em>not</em> on Android 1.0 devices. </p> + +<p>If your application does not use any new APIs introduced in Android 1.1, you can indicate Android 1.0 compatibility by removing <code>minSdkVersion</code> or setting the attribute to "1". However, before publishing your application, you must make sure to compile your application against the Android 1.0 system image (available in the Android 1.0 SDK), to ensure that it builds and functions properly for Android 1.0 devices. You should test the application against system images corresponding to the API Levels that the application is designed to be compatible with.</p> + +<p>If you are sure your application is not using Android 1.1 APIs and has no need to use them, you might find it easier to keep working in the Android 1.0 SDK, rather than migrating to the Android 1.1 SDK and having to do additional testing.</p> + + +<h3>ADT Plugin Compatibility</h3> + +<p>For this version of the SDK — Android 1.1 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}sdk/1.1_r1/upgrading.html#update-plugin">Upgrading +the SDK</a>.</p> + +<h3>Installation and Upgrade Notes</h3> + +<p>If you've been developing an application using an Android 1.0 SDK no +changes to your application are needed. You may want to wipe application +user data (emulator option <code>-wipe-data</code>) when running your +application on the Android 1.1 emulator for the first time.</p> + +<p>If you're installing the Android SDK for the first time, please see +the instructions in <a +href="{@docRoot}sdk/1.1_r1/installing.html">Installing the SDK</a>. + +<h3>Other Notes</h3> + +<p><strong>MapView API Key</strong></p> + +<p>com.google.android.maps.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>Developers should note that the registration service for MapView is now +active and Google Maps is actively enforcing the Maps API Key requirement. +For information about how to register for a Maps API Key, see +<a href="{@docRoot}guide/topics/location/geo/mapkey.html"> +Obtaining a Maps API Key</a>.</p> + +<p><strong>USB Drivers for Windows</strong></p> + +<p>If you using Windows and want to develop or test your application on an +Android-powered device (such as the T-Mobile G1), you need an appropriate USB +driver. For your convenience, the Windows version of the Android SDK includes +these USB drivers that you can install, to let you develop on the device:</p> + +<ul> +<li>USB driver for 32-bit XP and Vista</li> +<li>USB driver for 64-bit Vista only</li> +</ul> + +<p>The USB driver files are located in the +<code><SDK>/usb_driver</code> directory. For details and +installation instructions, see <a +href="{@docRoot}guide/developing/device.html#setting-up">Setting Up a +Device for Development</a>.</p> +</p> + +<h3>Resolved Issues, Changes</h3> + +<p><strong>Emulator</strong></p> +<ul> +<li>Emulator now saves the user image in <android>/SDK1.1/</code></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}guide/appendix/faq/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.1 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> + diff --git a/docs/html/guide/developing/tools/adt_download.jd b/docs/html/sdk/adt_download.jd index f03cc46..6e9eec4 100644 --- a/docs/html/guide/developing/tools/adt_download.jd +++ b/docs/html/sdk/adt_download.jd @@ -29,8 +29,8 @@ page</a>. <td style="background-color:#ffcccc;">0.8.0</td> <td style="background-color:#ffcccc;"><a href="http://dl-ssl.google.com/android/ADT-0.8.0.zip">ADT-0.8.0.zip</a></td> <td style="background-color:#ffcccc;">23 September 2008</td> - <td style="background-color:#ffcccc;">Android 1.0 SDK, Release 1</td> - <td style="background-color:#ffcccc;">Required for users of Android 1.0 SDK, Release 1. </td> + <td style="background-color:#ffcccc;">Android 1.1 SDK, Release 1<br />Android 1.0 SDK, Release 1<br /></td> + <td style="background-color:#ffcccc;">Required for users of Android 1.1 SDK, Release 1 and Android 1.0 SDK, Release 1<br /> </td> </tr> <tr> <td>0.7.1</td> diff --git a/docs/html/sdk/android-1.1.jd b/docs/html/sdk/android-1.1.jd new file mode 100644 index 0000000..8e63ba3 --- /dev/null +++ b/docs/html/sdk/android-1.1.jd @@ -0,0 +1,250 @@ +page.title=Android 1.1 Version Notes +sdk.version=1.1_r1 +sys.date=February 2009 +@jd:body + +<p> +<em>Date:</em> February 2009<br /> +<em>API Level:</em> <strong>2</strong></p> + + +<p>This document provides version notes for the Android 1.1 system image included in the SDK. + +<ul> +<li><a href="#overview">Overview</a> +<li><a href="#overview">External Libraries</a> +<li><a href="#comp">Device Compatibility</a> +<li><a href="#apps">Built-in Applications</a> +<li><a href="#locs">UI Localizations</a> +<li><a href="#resolved-issues">Resolved Issues</a> +<li><a href="#features">New Features</a> +<li><a href="#api-changes">API Changes</a> +</ul></p> + +<h2 id="overview">Overview</h2> + +<p>The Android 1.1 system image delivered in the SDK is the development +counterpart to the Android 1.1 production system image, deployable to +Android-powered handsets starting in February 2009. </p> + +<p>The Android 1.1 system image delivers an updated version of the framework +API. As with the Android 1.0 API, the Android 1.1 API +is assigned an integer identifier — <strong>2</strong> — that is +stored in the system itself. This identifier, called the "API Level", allows the +system to correctly determine whether an application is compatible with +the system, prior to installing the application.</p> + +<p>Applications can reference a specific API Level value in their +manifest files, to indicate the minimum version of the Android system +required to run the app. To reference a minimum API Level, applications +can add a <code>minSdkVersion</code> attribute in their manifest files. +The value of the attribute is an integer corresponding to an API Level +identifier. Prior to installing an application, the system then checks the value of +<code>minSdkVersion</code> and allows the install only +if the referenced integer is less than or equal to the API Level integer stored +in the system itself. </p> + +<p>If you use the Android 1.1 system image to build an application +compatible with Android-powered devices running the Android 1.1 +platform, please note that you <strong><span +style="color:red;">must</span></strong> set the the +<code>android:minSdkVersion</code> attribute in the application's +manifest to "2", which is the API strictly associated with Android 1.1. +</p> + +<p>Specifically, you specify the <code>android:minSdkVersion</code> +attribute in a <code><uses-sdk></code> element as a child of +<code><manifest></code> in the manifest file. When set, the +attribute looks like this: </p> + +<pre><code><manifest> + ... + <uses-sdk minSdkVersion="2"> + ... +</manifest></code> +</pre> + +<p>By setting <code>android:minSdkVersion</code> in this way, you ensure +that users will only be able to install your application if their +devices are running the Android 1.1 platform. In turn, this ensures that +your application will function properly on their devices, especially if +it uses <a href="#apichange">APIs introduced in Android 1.1</a>. </p> + +<p>If your application uses APIs introduced in Android 1.1 but does not +declare <code><uses-sdk minSdkVersion="2"></code>, then it will +run properly on Android 1.1 devices but <em>not</em> on Android 1.0 +devices. In the latter case, the application will crash at runtime when +it tries to use the Android 1.1 APIs.</p> + +<p>If your application does not use any new APIs introduced in Android +1.1, you can indicate Android 1.0 compatibility by removing +<code>minSdkVersion</code> or setting the attribute to "1". However, +before publishing your application, you must make sure to compile your +application against the Android 1.0 system image (available in the +Android 1.0 SDK), to ensure that it builds and functions properly for +Android 1.0 devices. You should test the application against system +images corresponding to the API Levels that the application is designed +to be compatible with.</p> + +<p>If you are sure your application is not using Android 1.1 APIs and +has no need to use them, you might find it easier to keep working in the +Android 1.0 SDK, rather than migrating to the Android 1.1 SDK and having +to do additional testing.</p> + + +<h2 id="extlibs">External Libraries</h2> + +<p>The system image includes these external libraries, which you can +access from your application by adding a <a +href="{@docRoot}guide/topics/manifest/uses-library-element.html"> +<uses-library></a>.</p> + <ul> + <li>com.google.android.maps — gives your +application access to Google Maps data. Note that, to use Google Maps +data, a Maps API Key is required.</li> + </ul> + +<h2 id="comp">Device Compatibility</h2> + +<p>The Android 1.1 system image was tested for compatability with the +Android-powered devices listed below:</p> + <ul> + <li><a href="http://www.t-mobileg1.com">T-Mobile G1</a></li> + </ul> + +<h2 id="apps">Built-in Applications</h2> + +<p>The system image includes these built-in applications:</p> + <ul> + <li>Alarm Clock</li> + <li>API Demos</li> + <li>Browser</li> + <li>Calculator</li> + <li>Camera</li> + <li>Contacts</li> + <li>Dev Tools</li> + <li>Dialer</li> + <li>Email</li> + <li>Maps (and StreetView)</li> + <li>Messaging</li> + <li>Music</li> + <li>Pictures</li> + <li>Settings</li> + </ul> + +<h2 id="locs">UI Localizations</h2> + +<p>The system image provides localized UI strings for the languages +listed below.</p> + <ul> + <li>English, US (en_US)</li> + <li>German (de) </li> + </ul> + +<p>Localized UI strings match the locales that are displayable in +the emulator, accessible through the device Settings application.</p> + +<h2 id="resolved-issues">Resolved Issues</h2> +<ul> +<li>AlarmClock alert now plays audio/vibe directly, rather than through +AlarmManager. AlarmClock alert starts playing audio/vibe in its +IntentReceiver, rather than on activity start. These changes should +prevent alarms from being blocked by modal dialogs.</li> +<li>Fixes to device sleep. </li> +<li>Single tap no longer opens the in-call dialpad; users now need to +touch and drag it. </li> +<li>Fixes a bug causing approximately 1 in 25 outbound messages to +freeze up the IMAP connection (to a Gmail based server) when transferred +to the Sent folder.</li> +<li>Removes automatic account setup entries that were broken or not +testable. Adds minor fixes to a few of the remaining entries. Makes +improvements to warning dialogs used for a few special cases. </li> +<li>Changes default mail checking interval to every 15 minutes (instead +of defaulting to "never").</li> +<li>Fixes password-quoting bugs in IMAP, so that users can include +special characters in passwords (e.g. spaces).</li> +<li>Fixes various errors in auto and manual account setup </li> +<li>Improves reporting for various connection errors, making it easier +for the user to diagnose failed account setups.</li> +<li>Fixes new-mail notifications for POP3 accounts.</li> +<li>Ensures proper auto-checking of accounts marked as "never +check".</li> +<li>Now displays date and time using user preference (e.g. 24 hr vs. +AM/PM).</li> +<li>Now shows cc: in message view.</li> +<li>Improves recovery from POP3 connection failures.</li> +<li>POP3 parser rules loosened, so the application can work with +non-compliant email servers.</li> +<li>Removes green CALL button as a shortcut for "add a new call".</li> +</ul> + +<h2 id="features">New Features</h2> + +<ul> +<li>Maps: Adds details and reviews when a user does a search on Maps and +clicks on a business to view it's details.</li> +<li>Dialer: In-call screen timeout default is now longer when using the +speakerphone.</li> +<li>Dialer: Adds a "Show dialpad" / "Hide dialpad" item to the in-call +menu, to make it easier to discover the DTMF dialpad. </li> +<li>Adds support for saving attachments from MMS</li> +<li>Adds support for marquee in layouts.</li> +</ul> + +<h2 id="api-changes">API Changes</h2> + +<h3>Overview</strong></h3> + +<ul> +<li>Adds annotations for test systems, no actual (non-test) API +changes.</li> +<li>Adds a method to allow a process to easily determine its UID. +<li>Adds support for marquee in layouts.</li> +<li>Adds new methods for determining padding in views. Useful if you are +writing your own +subclasses of {@link android.view.View View}.</li> +<li>Adds new permissions that allow an application to broadcast an SMS +or WAP Push message. </li> +<li>API cleanup: removes protected constructor from +SDK-bound system images. </li> +</ul> + +<h3>API Change Details</h3> + +<table> +<tr> +<th>Module or Feature</th><th>Change Description</th> +</tr> +<tr><td rowspan="4">Annotations for test systems</td></tr> + <tr><td>Added class {@link android.test.suitebuilder.annotation.LargeTest LargeTest} to package {@link android.test.suitebuilder.annotation}</td></tr> + <tr><td>Added class {@link android.test.suitebuilder.annotation.MediumTest MediumTest} to package {@link android.test.suitebuilder.annotation}</td></tr> + <tr><td>Added class {@link android.test.suitebuilder.annotation.SmallTest SmallTest} to package {@link android.test.suitebuilder.annotation}</td></tr> + +<tr><td rowspan="2">Allow a process to easily know its UID.</td></tr> + <tr><td>Added public method {@link android.os.Process#myUid} to class {@link android.os.Process android.os.Process}</td></tr> + +<tr><td rowspan="6">Padding in views</td></tr> + <tr><td>Added public method {@link android.view.View#getBottomPaddingOffset} to class {@link android.view.View android.view.View}.</td></tr> + <tr><td>Added public method {@link android.view.View#getLeftPaddingOffset} to class {@link android.view.View android.view.View}.</td></tr> + <tr><td>Added public method {@link android.view.View#getRightPaddingOffset} to class {@link android.view.View android.view.View}.</td></tr> + <tr><td>Added public method {@link android.view.View#getTopPaddingOffset} to class {@link android.view.View android.view.View}.</td></tr> + <tr><td>Added public method {@link android.view.View#isPaddingOffsetRequired} to class {@link android.view.View android.view.View}.</td></tr> + +<tr><td rowspan="3">Marquee support</td></tr> + <tr><td>Added public method {@link android.widget.TextView#setMarqueeRepeatLimit} to class {@link android.widget.TextView}</td></tr> + <tr><td>Added public field {@link android.R.attr#marqueeRepeatLimit android.R.attr.marqueeRepeatLimit}</td></tr> + +<tr><td rowspan="3">New permissions</td></tr> + <tr><td>Added public field {@link android.Manifest.permission#BROADCAST_SMS android.Manifest.permission.BROADCAST_SMS}</td></tr> + <tr><td>Added public field {@link android.Manifest.permission#BROADCAST_WAP_PUSH android.Manifest.permission.BROADCAST_WAP_PUSH}</td></tr> + +<tr><td rowspan="2">API cleanup</td></tr> + <tr><td>Removed protected constructor java.net.ServerSocket.ServerSocket(java.net.SocketImpl).</td></tr> + +</table> + + + + + + diff --git a/docs/html/sdk/download.jd b/docs/html/sdk/download.jd new file mode 100644 index 0000000..d64b781 --- /dev/null +++ b/docs/html/sdk/download.jd @@ -0,0 +1,76 @@ +page.title=Download the Android SDK +@jd:body + +<p>Please carefully review the Android SDK License Agreement before downloading the SDK. +The License Agreement constitutes a contract between you and Google with respect to your use of the SDK.</p> + +<iframe style="border:1px solid #888;margin:0 0 1em;height:400px;width:95%;" src="terms_body.html"> +</iframe> + +<script language="javascript"> + function verify() { + document.getElementById('download_button').disabled = !document.getElementById('checkbox').checked; + } + function submit() { + var location = window.location.href; + if (location.indexOf('?v=') != -1) { + var filename = location.substring(location.indexOf('=')+1,location.length); + if (document.getElementById('checkbox').checked) { + document.location = "http://dl.google.com/android/" + filename; + } + document.getElementById('click_download').setAttribute("href", "http://dl.google.com/android/" + filename); + document.getElementById('next_steps').style.display = "block"; + } else { + alert("You have not selected an SDK version. Please return to the Download page"); + } + } +</script> + + <p> + <input type="checkbox" id="checkbox" onclick="verify()" /> + <label for="checkbox">I agree to the terms of the Android SDK License Agreement.</label> + </p> + <p> + <input type="submit" value="Download" id="download_button" disabled="disabled" onclick="submit()" /> + </p> + <p> + <script language="javascript"> + var loc = window.location.href; + if (loc.indexOf('?v=') != -1) { + var filename = loc.substring(loc.indexOf('=')+1,loc.length); + document.write("File: " + filename); + } + </script> + </p> + +<noscript> + <p><strong>Please enable Javascript in your browser in order to agree to the terms and download the SDK.</strong></p> +</noscript> + +<div class="special" id="next_steps" style="display:none"> + <p>Your download should be underway. If not, <a id="click_download">click here to download</a>.</p> + <p>Continue your setup with one the following documents:</p> + <ul style="margin-top:.5em"> + <li><a href="installing.html" class="addVersionPath">Installing</a> - If you are + installing the Android SDK for the first time.</li> + <li><a href="upgrading.html" class="addVersionPath">Upgrading</a> - If you are + upgrading from a previously installed version of the Android SDK.</li> + </ul> +</div> + +<script language="javascript"> + var loc = window.location.href; + var filename = loc.substring(loc.indexOf('=')+1,loc.length); + version = filename.substring(filename.indexOf('.')-1,filename.lastIndexOf('.')); + $(".addVersionPath").each(function(i) { + var oldHref = $(this).attr("href"); + $(this).attr({href: "/sdk/" + version + "/" + oldHref}); + }); +</script> + + + + + + + diff --git a/docs/html/sdk/index.html b/docs/html/sdk/index.html deleted file mode 100644 index c5468dd..0000000 --- a/docs/html/sdk/index.html +++ /dev/null @@ -1,6 +0,0 @@ -<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/index.jd b/docs/html/sdk/index.jd new file mode 100644 index 0000000..38db6f8 --- /dev/null +++ b/docs/html/sdk/index.jd @@ -0,0 +1,5 @@ +sdk.redirect=1.1_r1 +@jd:body + + + diff --git a/docs/html/sdk/sdk_toc.cs b/docs/html/sdk/sdk_toc.cs index 11d3086..f617302 100644 --- a/docs/html/sdk/sdk_toc.cs +++ b/docs/html/sdk/sdk_toc.cs @@ -1,37 +1,20 @@ -<ul> - <li><h2>Android 1.0</h2> +<ul> + <li><h2>Latest SDK Release</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/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/RELEASENOTES.html">Release Notes</a></li> - </ul> - </li> - + <li><a href="<?cs var:toroot ?>sdk/1.1_r1/index.html">Download</a></li> + <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/requirements.html">System Requirements</a></li> + <li><a href="<?cs var:toroot ?>sdk/RELEASENOTES.html">SDK Release Notes</a></li> </ul> - </li> -<!-- just a template - <li><h2>Android 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/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/RELEASENOTES.html">Release Notes</a></li> - </ul> - </li> + <li><a href="<?cs var:toroot ?>sdk/android-1.1.html">Android 1.1 Version Notes</a></li> </ul> </li> ---> - <li><a href="<?cs var:toroot ?>sdk/terms.html">Terms and Conditions</a></li> +</ul> +<ul> + <li><a href="<?cs var:toroot ?>sdk/terms.html">SDK Terms and Conditions</a></li> + <li><a href="http://code.google.com/android/download_list.html">Previous SDK Releases</a></li> </ul> diff --git a/docs/html/sdk/terms.jd b/docs/html/sdk/terms.jd index 5599fa6..72e5bd0 100644 --- a/docs/html/sdk/terms.jd +++ b/docs/html/sdk/terms.jd @@ -1,4 +1,5 @@ page.title=Terms and Conditions +sdk.version=1.1_r1 @jd:body <p>This is the Android Software Development Kit License Agreement.</p> diff --git a/docs/html/sdk/terms_body.html b/docs/html/sdk/terms_body.html new file mode 100644 index 0000000..e8fdc3c --- /dev/null +++ b/docs/html/sdk/terms_body.html @@ -0,0 +1,216 @@ + +<p>This is the Android Software Development Kit License Agreement.</p> + +<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/search.jd b/docs/html/search.jd index 9269d2c..979964b 100755..100644 --- a/docs/html/search.jd +++ b/docs/html/search.jd @@ -5,73 +5,53 @@ page.title=Search Results <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);
+ function OnLoad() {
+ document.getElementById("search_autocomplete").style.color = "#000";
- // bind clear and submit functions
- this.searchForm.setOnSubmitCallback(this, cse.prototype.onSubmit);
- this.searchForm.setOnClearCallback(this, cse.prototype.onClear);
+ // create search control
+ searchControl = new google.search.SearchControl();
- // set up for small result sets
- this.leftControl.setResultSetSize(google.search.Search.LARGE_RESULTSET);
+ // use our existing search form and use tabs when multiple searchers are used
+ drawOptions = new google.search.DrawOptions();
+ drawOptions.setDrawMode(google.search.SearchControl.DRAW_MODE_TABBED);
+ drawOptions.setInput(document.getElementById("search_autocomplete"));
- var searcher;
- var options;
+ // configure search result options
+ searchOptions = new google.search.SearcherOptions();
+ searchOptions.setExpandMode(GSearchControl.EXPAND_MODE_OPEN);
+ searchOptions.setRoot(document.getElementById("leftSearchControl"));
- // configure left control
- // Site Restrict to CSE ID for reviews
+ // configure searcher options
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 + "\"";
+ searcher.setUserDefinedLabel("Android Developers");
+ searcher.setSiteRestriction("001283715400630100512:ggqrtvkztwm");
+
+ searchControl.addSearcher(searcher, searchOptions);
+ searchControl.setResultSetSize(google.search.Search.LARGE_RESULTSET);
+ searchControl.setLinkTarget(google.search.Search.LINK_TARGET_SELF);
+ searchControl.setNoResultsString(google.search.SearchControl.NO_RESULTS_DEFAULT_STRING);
+
+ // upon ajax search, refresh the url and search title
+ searchControl.setSearchStartingCallback(this, function(control, searcher, query) {
+ temp = location.href.split('#');
+ url = temp ? temp[0] : location.href;
+ location.href = url + '#q=' + query;
+ document.getElementById("searchTitle").innerHTML = "search results for <em>" + query + "</em>"
+ });
+
+ searchControl.draw(null, drawOptions);
+
+ // execute a search upon page load, from url hash query
+ if (location.href.indexOf("#q=") != -1) {
+ url = location.href.split("#q=");
+ searchControl.execute(decodeURI(url[1]));
}
- 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" style="width:auto; margin:20px">
<h2 id="searchTitle">search results</h2>
<img src="{@docRoot}assets/images/hr_gray_main.jpg" />
|
