diff options
| author | Jean-Baptiste Queru <jbq@google.com> | 2009-05-20 11:28:04 -0700 |
|---|---|---|
| committer | Jean-Baptiste Queru <jbq@google.com> | 2009-05-20 11:28:04 -0700 |
| commit | 843ef36f7b96cc19ea7d2996b7c8661b41ec3452 (patch) | |
| tree | 560e1648c99a93986f8b7deef851ef8bb8029db7 /docs/html/guide | |
| parent | 358d23017d0d6c4636eb7599ae7a9b48108899a3 (diff) | |
| download | frameworks_base-843ef36f7b96cc19ea7d2996b7c8661b41ec3452.zip frameworks_base-843ef36f7b96cc19ea7d2996b7c8661b41ec3452.tar.gz frameworks_base-843ef36f7b96cc19ea7d2996b7c8661b41ec3452.tar.bz2 | |
donut snapshot
Diffstat (limited to 'docs/html/guide')
45 files changed, 5195 insertions, 1707 deletions
diff --git a/docs/html/guide/appendix/faq/commontasks.jd b/docs/html/guide/appendix/faq/commontasks.jd index 9c79bdd..0f89e75 100644 --- a/docs/html/guide/appendix/faq/commontasks.jd +++ b/docs/html/guide/appendix/faq/commontasks.jd @@ -701,8 +701,8 @@ If the latitudeSpan, longitudeSpan, and zoomLevel attributes are not consistent, <a name="filelist" id="filelist"></a><h2>List of Files for an Android Application</h2> <p>The following list describes the structure and files of an Android application. - Many of these files can be built for you (or stubbed out) by the activitycreator - application shipped in the tools/ menu of the SDK. </p> + Many of these files can be built for you (or stubbed out) by the android tool + shipped in the tools/ menu of the SDK. </p> <table width="100%" border="0"> <tr> <td width="28%" valign="top">MyApp/<br /></td> diff --git a/docs/html/guide/appendix/faq/framework.jd b/docs/html/guide/appendix/faq/framework.jd index 76a19c5..33b69ac 100644 --- a/docs/html/guide/appendix/faq/framework.jd +++ b/docs/html/guide/appendix/faq/framework.jd @@ -12,7 +12,7 @@ parent.link=index.html from one Activity/Service to another?</a></li> <li><a href="#4">How can I check if an Activity is already running before starting it?</a></li> - <li><a href="#5">If an Activity starts a remote service,is + <li><a href="#5">If an Activity starts a remote service, is there any way for the Service to pass a message back to the Activity?</a></li> <li><a href="#6">How to avoid getting the Application not responding dialog?</a></li> @@ -20,7 +20,6 @@ parent.link=index.html added or removed?</a></li> </ul> -<!-- ------------------------------------------------------------------ --> <a name="1" id="1"></a> @@ -32,7 +31,7 @@ default. If needed, you can declare an <code>android:process</code> attribute in your manifest file, to explicitly place a component (Activity/Service) in another process.</p> -<!-- ------------------------------------------------------------------ --> + <a name="2" id="2"></a> @@ -47,7 +46,7 @@ separate pool of transaction threads in each process to dispatch all incoming IPC calls. The developer should create separate threads for any long-running code, to avoid blocking the main UI thread.</p> -<!-- ------------------------------------------------------------------ --> + <a name="3" id="3"></a> @@ -128,7 +127,7 @@ the <a href="{@docRoot}guide/topics/data/data-storage.html">Data Storage</a> for further details on how to use these components.</p> -<!-- ------------------------------------------------------------------ --> + <a name="4" id="4"></a> @@ -140,7 +139,7 @@ or to bring the activity stack to the front if is already running in the background— is the to use the NEW_TASK_LAUNCH flag in the startActivity() call.</p> -<!-- ------------------------------------------------------------------ --> + <a name="5" id="5"></a> @@ -156,7 +155,7 @@ messages.</p> <p>The sample code for remote service callbacks is given in <a href="{@docRoot}guide/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.html">ApiDemos/RemoteService</a></p> -<!-- ------------------------------------------------------------------ --> + <a name="6" id="6"></a> @@ -166,7 +165,7 @@ href="{@docRoot}guide/samples/ApiDemos/src/com/example/android/apis/app/RemoteSe document.</p> -<!-- ------------------------------------------------------------------ --> + <a name="7" id="7"></a> @@ -194,5 +193,5 @@ removed. </p> -<!-- ------------------------------------------------------------------ --> + diff --git a/docs/html/guide/appendix/faq/troubleshooting.jd b/docs/html/guide/appendix/faq/troubleshooting.jd index 7c703e6..0cf1ab0 100644 --- a/docs/html/guide/appendix/faq/troubleshooting.jd +++ b/docs/html/guide/appendix/faq/troubleshooting.jd @@ -23,7 +23,6 @@ parent.link=index.html <li><a href="#majorminor">When I go to preferences in Eclipse and select "Android", I get the following error message: Unsupported major.minor version 49.0.</a></li> <li><a href="#apidemosreinstall">I can't install ApiDemos apps in my IDE because of a signing error</a></li> <li><a href="#signingcalendar">I can't compile my app because the build tools generated an expired debug certificate</a></li> - <li><a href="#addjunit">I can't run a JUnit test class in Eclipse/ADT</a></li> </ul> <a name="installeclipsecomponents" id="installeclipsecomponents"></a><h2>ADT Installation Error: "requires plug-in org.eclipse.wst.sse.ui".</h2> @@ -245,8 +244,8 @@ documentation.</p> <ol> <li>First, delete the debug keystore/key already generated by the Android build tools. Specifically, delete the <code>debug.keystore</code> file. On Linux/Mac OSX, the file is stored in <code>~/.android</code>. On Windows XP, the file is stored in <code> -C:\Documents and Settings\<user>\Local Settings\Application Data\Android</code>. On Windows Vista, the file is stored in <code> -C:\Users\<user>\AppData\Local\Android</code></li> +C:\Documents and Settings\<user>\.android</code>. On Windows Vista, the file is stored in <code> +C:\Users\<user>\.android</code></li> <li>Next, you can either <ul> <li>Temporarily change your development machine's locale (date and time) to one that uses a Gregorian calendar, for example, United States. Once the locale is changed, use the Android build tools to compile and install your app. The build tools will regenerate a new keystore and debug key with valid dates. Once the new debug key is generated, you can reset your development machine to the original locale. </li> @@ -260,46 +259,3 @@ C:\Users\<user>\AppData\Local\Android</code></li> <p>For general information about signing Android applications, see <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>. </p> -<h2 id="addjunit">I can't run a JUnit test class in Eclipse/ADT</h2> - -<p>If you are developing on Eclipse/ADT, you can add JUnit test classes to your application. However, you may get an error when trying to run such a class as a JUnit test:</p> - -<pre>Error occurred during initialization of VM -java/lang/NoClassDefFoundError: java/lang/ref/FinalReference</pre> - -<p>This error occurs because android.jar does not include complete Junit.* class implementations, but includes stub classes only. </p> - -<p>To add a JUnit class, you have to set up a JUnit configuration:. - -<ol> -<li>In the Package Explorer view, select your project. </li> -<li>Open the launch configuration manager. - <ul> - <li>In Eclipse 3.3 (Europa), select <strong>Run </strong>> - <strong>Open Run Dialog... </strong>or <strong>Run </strong>> - <strong>Open Debug Dialog... </strong>. - </li> - - <li>In Eclipse 3.4 (Ganymede), select <strong>Run </strong>> - <strong>Run Configurations... </strong>or <strong>Run </strong>> - <strong>Debug Configurations... </strong>. - </li> - </ul> - </li> -<li>In the configuration manager, right-click the "JUnit" configuration type and select <strong>New</strong></li> -<li>In the new configuration's <strong>Test</strong> tab, specify the project and test class, as well as any options for running the test. </li> -<li>In the new configuration's <strong>Classpath</strong> tab, find "Android Library" under Bootstrap Entries and remove it. </li> -<li>Still in the <strong>Classpath</strong> tab, select Bootstrap Entries and click the Advanced button. </li> -<ol type="a"> -<li>Choose Add Library and click OK.</li> -<li>Select JRE System Library and click Next. </li> -<li>Select Workspace Default JRE and click Finish.</li> -</ol> -<li>Select Bootstrap Entries again and click Advanced.</li> -<ol type="a"> -<li>Choose Add Library and click OK.</li> -<li>Select JUnit 3 and click Finish. </li> -</ol> -</ol> -<p>When configured in this way, your JUnit test class should now run properly.</p> - diff --git a/docs/html/guide/developing/app-signing.jd b/docs/html/guide/developing/app-signing.jd deleted file mode 100644 index 582dfb2..0000000 --- a/docs/html/guide/developing/app-signing.jd +++ /dev/null @@ -1,428 +0,0 @@ -page.title=Signing Your Applications -@jd:body - -<p>The Android system requires that all installed applications be digitally -signed with a certificate whose private key is held by the application's -developer. The system uses the certificate as a means of identifying the author of -an application and establishing trust relationships between applications, rather -than for controlling which applications the user can install. The certificate -does not need to be signed by a certificate authority: it is perfectly -allowable, and typical, for Android applications to use self-signed -certificates.</p> - -<p>The important points to understand about signing Android applications are:</p> - -<ul> - <li>All applications <em>must</em> be signed. The system will not install an application -that is not signed.</li> - <li>You can use self-signed certificates to sign your applications. No certificate authority -is needed.</li> - <li>When you are ready to publish your application, you must sign it with a suitable private -key. You can not publish an application that is signed with the default key generated -by the SDK tools. - </li> - <li>The system tests a signer certificate's expiration date only at install time. If an -application's signer certificate expires after the application is installed, the application -will continue to function normally.</li> - <li>You can use standard tools — Keytool and Jarsigner — to generate keys and -sign your application .apk files.</li> -</ul> - -<p>The Android system will not install or run an application that is not signed appropriately. This -applies wherever the Android system is run, whether on an actual device or on the emulator. -For this reason, you must set up signing for your application before you will be able to -run or debug it on an emulator or device.</p> - -<p>The Android SDK tools assist you in signing your applications when debugging. Both the ADT Plugin -for Eclipse and the Ant build tool offer two signing modes — debug mode and release mode. - -<ul> -<li>In debug mode, the build tools use the Keytool utility, included in the JDK, to create -a keystore and key with a known alias and password. At each compilation, the tools then use -the debug key to sign the application .apk file. Because the password is known, the tools -don't need to prompt you for the keystore/key password each time you compile.</li> - -<li>When your application is ready for release, you compile it in release signing mode. -In this mode, the tools compile your .apk <em>without</em> signing it. You must then sign -the .apk manually — <span style="color:red">with your private key</span> — -using Jarsigner (or similar tool). If you do not have a suitable private key already, -you can run Keytool manually to generate your own keystore/key and then sign your -application with Jarsigner.</li> -</ul> - -<h2>Signing Strategies</h2> - -<p>Some aspects of application signing may affect how you approach the development -of your application, especially if you are planning to release multiple -applications. </p> - -<p>In general, the recommended strategy for all developers is to sign -all of your applications with the same certificate, throughout the expected -lifespan of your applications. There are several reasons why you should do so: </p> - -<ul> -<li>Application upgrade — As you release upgrades to your -application, you will want to sign the upgrades with the same certificate, if you -want users to upgrade seamlessly to the new version. When the system is -installing an update to an application, if any of the certificates in the -new version match any of the certificates in the old version, then the -system allows the update. If you sign the version without using a matching -certificate, you will also need to assign a different package name to the -application — in this case, the user installs the new version as a -completely new application. - -<li>Application modularity — The Android system allows applications that -are signed by the same certificate to run in the same process, if the -applications so request, so that the system treats them as a single application. -In this way you can deploy your application in modules, and users can update -each of the modules independently if needed.</li> - -<li>Code/data sharing through permissions — The Android system provides -signature-based permissions enforcement, so that an application can expose -functionality to another application that is signed with a specified -certificate. By signing multiple applications with the same certificate and -using signature-based permissions checks, your applications can share code and -data in a secure manner. </li> - -</li> - -</ul> - -<p>Another important consideration in determining your signing strategy is -how to set the validity period of the key that you will use to sign your -applications.</p> - -<ul> -<li>If you plan to support upgrades for a single application, you should ensure -that your key has a validity period that exceeds the expected lifespan of -that application. A validity period of 25 years or more is recommended. -When your key's validity period expires, users will no longer be -able to seamlessly upgrade to new versions of your application.</li> - -<li>If you will sign multiple distinct applications with the same key, -you should ensure that your key's validity period exceeds the expected -lifespan of <em>all versions of all of the applications</em>, including -dependent applications that may be added to the suite in the future. </li> - -<li>If you plan to publish your application(s) on Android Market, the -key you use to sign the application(s) must have a validity period -ending after 22 October 2033. The Market server enforces this requirement -to ensure that users can seamlessly upgrade Market applications when -new versions are available. </li> -</ul> - -<p>As you design your application, keep these points in mind and make sure to -use a <a href="#cert">suitable certificate</a> to sign your applications. </p> - -<h2 id="setup">Basic Setup for Signing</h2> - -<p>To support the generation of a keystore and debug key, you should first make sure that -Keytool is available to the SDK build -tools. In most cases, you can tell the SDK build tools how to find Keytool by making sure -that your JAVA_HOME environment variable is set and that it references a suitable JDK. -Alternatively, you can add the JDK version of Keytool to your PATH variable.</p> - -<p>If you are developing on a version of Linux that originally came with GNU Compiler for -Java, make sure that the system is using the JDK version of Keytool, rather than the gcj -version. If Keytool is already in your PATH, it might be pointing to a symlink at -/usr/bin/keytool. In this case, check the symlink target to make sure that it points -to the Keytool in the JDK.</p> - -<p>If you will release your application to the public, you will also need to have -the Jarsigner tool available on your machine. Both Jarsigner and Keytool are included -in the JDK. </p> - -<h2>Signing in Debug Mode</h2> - -<p>The Android build tools provide a debug signing mode that makes it easier for you -to develop and debug your application, while still meeting the Android system -requirement for signing your .apk when it is installed in the emulator or a device. </p> - -<p>If you are developing in Eclipse/ADT and have set up Keytool as described -above, signing in debug mode is enabled by default. When you run or debug your -application, ADT signs the .apk for you and installs it on the emulator. No -specific action on your part is needed, provided ADT has access to Keytool.</p> - -<p>If you use Ant to build your .apk files, debug signing mode -is enabled by default, assuming that you are using a build.xml file generated by the -activitycreator tool included in the latest SDK. When you run Ant against build.xml to -compile your app, the build script generates a keystore/key and signs the .apk for you. -No specific action on your part is needed.</p> - -<p>Note that you can not release your application to the public if it is signed only with -the debug key. </p> - -<h2>Signing for Public Release</h2> - -<p>When your application is ready for release to other users, you must:</p> -<ol> -<li>Compile the application in release mode</li> -<li>Obtain a suitable private key, and then</li> -<li>Sign the application with your private key</li> -<li>Secure your private key</li> -</ol> - -<p>The sections below provide information about these steps. </p> - -<h3>Compiling for Release</h3> - -<p>To prepare your application for release, you must first compile it in release mode. -In release mode, the Android build tools compile your application as usual, -but without signing it with the debug key. </p> - -<p>If you are developing in Eclipse/ADT, right-click the project in the Package -pane and select <strong>Android Tools</strong> > <strong>Export Application -Package</strong>. You can then specify the file location for the unsigned .apk. -Alternatively, you can follow the "Exporting the unsigned .apk" -link in the Manifest Editor overview page. </p> - -<p>If you are using Ant, all you need to do is specify the build target -"release" in the Ant command. For example, if you are running Ant from the -directory containing your build.xml file, the command would look like this:</p> - -<pre>$ ant release</pre> - -<p>The build script compiles the application .apk without signing it. - -<p>Note that you can not release your application unsigned, or signed with the debug key.</p> - -<h3 id="cert">Obtaining a Suitable Private Key</h3> - -<p>In preparation for signing your application, you must first ensure that -you have a suitable private key with which to sign. A suitable private -key is one that:</p> - -<ul> -<li>Is in your possession</li> -<li>Represents the personal, corporate, or organizational entity to be identified -with the application</li> -<li>Has a validity period that exceeds the expected lifespan of the application -or application suite. A validity period of more than 25 years is recommended. -<p>If you plan to publish your application(s) on Android Market, note that a -validity period ending after 22 October 2033 is a requirement. You can not upload an -application if it is signed with a key whose validity expires before that date. -</p></li> -<li>Is not the debug key generated by the Android SDK tools. </li> -</ul> - -<p>The key may be self-signed. If you do not have a suitable key, you must -generate one using Keytool. Make sure that you have Keytool available, as described -in <a href="#setup">Basic Setup</a>.</p> - -<p>To generate a self-signed key with Keytool, use the <code>keytool</code> -command and pass any of the options listed below (and any others, as -needed). </p> - -<p class="warning">Before you run Keytool, make sure to read <a -href="#secure-key">Securing Your Key</a> for a discussion of how to keep your -key secure and why doing so is critically important to you and to users. In -particular, when you are generating your key, you should select strong -passwords for both the keystore and key.</p> - -<table> -<tr> -<th>Keytool Option</th> -<th>Description</th> -</tr> -<tr> -<td><code>-genkey</code></td><td>Generate a key pair (public and private -keys)</td> -</tr> -<tr> -<td><code>-v</code></td><td>Enable verbose output.</td> -</tr> -<tr> -<td><code>-keystore <keystore-name>.keystore</code></td><td>A name -for the keystore containing the private key.</td> -</tr> -<tr> -<td><code>-storepass <password></code></td><td><p>A password for the -keystore.</p><p>As a security precaution, do not include this option -in your command line unless you are working at a secure computer. -If not supplied, Keytool prompts you to enter the password. In this -way, your password is not stored in your shell history.</p></td> -</tr> -<tr> -<td><code>-alias <alias_name></code></td><td>An alias for the key.</td> -</tr> -<tr> -<td><code>-keyalg <alg></code></td><td>The encryption algorithm to use -when generating the key.</td> -</tr> -<tr> -<td><code>-dname <name></code></td><td><p>A Distinguished Name that describes -who created the key. The value is used as the issuer and subject fields in the -self-signed certificate. </p><p>Note that you do not need to specify this option -in the command line. If not supplied, Jarsigner prompts you to enter each -of the Distinguished Name fields (CN, OU, and so on).</p></td> -</tr> -<tr> -<td><code>-validity <valdays></code></td><td><p>The validity period for the -key, in days. </p><p><strong>Note:</strong> A value of 9500 or greater is recommended.</p></td> -</tr> -<tr> -<td><code>-keypass <password></code></td><td><p>The password for the key.</p> -<p>As a security precaution, do not include this option -in your command line unless you are working at a secure computer. -If not supplied, Keytool prompts you to enter the password. In this -way, your password is not stored in your shell history.</p></td> -</tr> -</table> - - -<p>Here's an example of a Keytool command that generates a private key:</p> - -<pre>$ keytool -genkey -v -keystore my-release-key.keystore --alias alias_name -keyalg RSA -validity 9500</pre> - -<p>Running the example command above, Keytool prompts you to provide -passwords for the keystore and key, and to provide the Distinguished -Name fields for your key. It then generates the keystore as a file called -<code>my-release-key.keystore</code>. The keystore and key are -protected by the passwords you entered. The keystore contains -a single key, valid for 9500 days. The alias is a name that you — -will use later, to refer to this keystore when signing your application. </p> - -<p>For more information about Keytool, see the documentation at -<a -href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> -http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> - -<h3>Signing Your Application</h3> - -<p>When you are ready to actually sign your .apk for release, you can do so -using the Jarsigner tool. Make sure that you have Jarsigner available on your -machine, as described in <a href="#setup">Basic Setup</a>. Also, make sure that -the keystore containing your private key is available.</p> - -<p>To sign your application, you run Jarsigner, referencing both the -application's .apk and the keystore containing the private key with which to -sign the .apk. The table below shows the options you could use. <p> - -<table> -<tr> -<th>Jarsigner Option</th> -<th>Description</th> -</tr> -<tr> -<td><code>-keystore <keystore-name>.keystore</code></td><td>The name of -the keystore containing your private key.</td> -</tr> -<tr> -<td><code>-verbose</code></td><td>Enable verbose output.</td> -</tr> -<tr> -<td><code>-storepass <password></code></td><td><p>The password for the -keystore. </p><p>As a security precaution, do not include this option -in your command line unless you are working at a secure computer. -If not supplied, Jarsigner prompts you to enter the password. In this -way, your password is not stored in your shell history.</p></td> -</tr> -<tr> -<td><code>-keypass <password></code></td><td><p>The password for the private -key. </p><p>As a security precaution, do not include this option -in your command line unless you are working at a secure computer. -If not supplied, Jarsigner prompts you to enter the password. In this -way, your password is not stored in your shell history.</p></td> -</tr> -</table> - -<p>Here's how you would use Jarsigner to sign an application package called -<code>my_application.apk</code>, using the example keystore created above. -</p> - -<pre>$ jarsigner -verbose -keystore my-release-key.keystore -my_application.apk alias_name</pre> - -<p>Running the example command above, Jarsigner prompts you to provide -passwords for the keystore and key. It then modifies the APK -in-place, meaning the .apk is now signed. Note that you can sign an -APK multiple times with different keys.</p> - -<p>To verify that your .apk is signed, you can use a command like this:</p> - -<pre>$ jarsigner -verify my_signed.apk</pre> - -<p>If the .apk is signed properly, Jarsigner prints "jar verified". -If you want more details, you can try one of these commands:</p> - -<pre>$ jarsigner -verify -verbose my_application.apk</pre> - -<p>or</p> - -<pre>$ jarsigner -verify -verbose -certs my_application.apk</pre> - -<p>The command above, with the <code>-certs</code> option added, will show you the -"CN=" line that describes who created the key.</p> - -<p class="note">Note: if you see "CN=Android Debug", this means the .apk was -signed with the debug key generated by the Android SDK. If you intend to release -your application, you must sign it with your private key instead of the debug -key.</p> - -<p>For more information about Jarsigner, see the documentation at -<a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> -http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> - -<h3 id="secure-key">Securing Your Private Key</h3> - -<p>Maintaining the security of your private key is of critical importance, both -to you and to the user. If you allow someone to use your key, or if you leave -your keystore and passwords in an unsecured location such that a third-party -could find and use them, your authoring identity and the trust of the user -are compromised. </p> - -<p>If a third party should manage to take your key without your knowledge or -permission, that person could sign and distribute applications that maliciously -replace your authentic applications or corrupt them. Such a person could also -sign and distribute applications under your identity that attack other -applications or the system itself, or corrupt or steal user data. </p> - -<p>Your reputation as a developer entity depends on your securing your private -key properly, at all times, until the key is expired. Here are some tips for -keeping your key secure: </p> - -<ul> -<li>Select strong passwords for the keystore and key.</li> -<li>When you generate your key with Keytool, <em>do not</em> supply the -<code>-storepass</code> and <code>-keypass</code> options at the command line. -If you do so, your passwords will be available in your shell history, -which any user on your computer could access.</li> -<li>Similarly, when signing your applications with Jarsigner, -<em>do not</em> supply the <code>-storepass</code> and <code>-keypass</code> -options at the command line. </li> -<li>Do not give or lend anyone your private key, and do not let unauthorized -persons know your keystore and key passwords.</li> -</ul> - -<p>In general, if you follow common-sense precautions when generating, using, -and storing your key, it will remain secure. </p> - -<h2>Expiry of the Debug Certificate</h2> - -<p>The self-signed certificate used to sign your application in debug mode (the default on -Eclipse/ADT and Ant builds) will have an expiration date of 365 days from its creation date.</p> - -<p>When the certificate expires, you will get a build error. On Ant builds, the error -looks like this:</p> - -<pre>debug: -[echo] Packaging bin/samples-debug.apk, and signing it with a debug key... -[exec] Debug Certificate expired on 8/4/08 3:43 PM</pre> - -<p>In Eclipse/ADT, you will see a similar error in the Android console.</p> - -<p>To fix this problem, simply delete the <code>debug.keystore</code> file. On Linux/Mac OSX, -the file is stored in <code>~/.android</code>. OOn Windows XP, the file is stored in <code> -C:\Documents and Settings\<user>\Local Settings\Application Data\Android</code>. -On Windows Vista, the file is stored in <code> -C:\Users\<user>\AppData\Local\Android</code>.</p> - -<p>The next time you build, the build tools will regenerate a new keystore and debug key.</p> - -<p>Note that, if your development machine is using a non-Gregorian locale, the build -tools may erroneously generate an already-expired debug certificate, so that you get an -error when trying to compile your application. For workaround information, see the -troubleshooting topic <a href="{@docRoot}kb/troubleshooting.html#signingcalendar"> -I can't compile my app because the build tools generated an expired debug -certificate</a>. </p>
\ No newline at end of file diff --git a/docs/html/guide/developing/eclipse-adt.jd b/docs/html/guide/developing/eclipse-adt.jd index 8c482ee..75f3d78 100644 --- a/docs/html/guide/developing/eclipse-adt.jd +++ b/docs/html/guide/developing/eclipse-adt.jd @@ -1,193 +1,393 @@ -page.title=In Eclipse, with ADT +page.title=Developing In Eclipse, with ADT @jd:body -<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> +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#CreatingAProject">Creating an Android Project</a></li> + <li><a href="#Running">Running Your Application</a> + <ol> + <li><a href="#CreatingAnAvd">Creating an AVD</a></li> + <li><a href="#RunningAnApplication">Running an application</a></li> + </ol> + </li> + <li><a href="#RunConfig">Creating a Custom Run Configuration</a></li> + <li><a href="#Signing">Setting Up Application Signing</a></li> + <li><a href="#Tips">Eclipse Tips</a></li> + </div> +</div> + + +<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 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> + <li>It provides an Android code editor that helps you write valid XML for your Android +manifest and resource files.</li> + <li>It will even export your project into a signed APK, which can be distributed to users.</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>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.5_r1/installing.html#installingplugin">Installing +the ADT Plugin</a>.</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. </p> +<p>If you are already developing applications using a version of ADT earlier than 0.9, make +sure to upgrade to the latest version before continuing. See the guide to +<a href="{@docRoot}sdk/1.5_r1/upgrading.html#UpdateAdt">Update Your Eclipse ADT Plugin</a>.</p> -<a name="creatingaproject" id="creatingaproject"></a> +<p class="note"><strong>Note:</strong> This guide assumes you are using the latest version of +the ADT plugin (0.9). While most of the information covered also applies to previous +versions, if you are using an older version, you may want to consult this document from +the set of documentation included in your SDK package (instead of the online version).</p> -<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> +<h2 id="CreatingAProject">Creating an Android Project</h2> -<a name="existingcode"></a> +<p>The ADT plugin provides a New Project Wizard that you can use to quickly create a new +Android project (or a project from existing code). To create a new project:</p> <ol> - <li>Select <strong>File</strong> > <strong>New</strong> > <strong>Project</strong></li> - <li>Select <strong>Android</strong> > <strong>Android Project</strong>, and press <strong>Next</strong></li> - <li>Select the contents for the project: - <ul> - <li>Select <strong>Create new project in workspace</strong> to start a project for new code. - <p>Enter the project name, the base package name, the name of a single Activity class to create as a stub .java file, and a name to use for your application.</p></li> - <li>Select <strong>Create project from existing source</strong> to start a project from existing code. Use this option if you want to build and run any of the sample applications included with the SDK. The sample applications are located in the samples/ directory in the SDK. - <p>Browse to the directory containing the existing source code and click OK. If the directory contains a valid Android manifest file, the ADT plugin fills in the package, activity, and application names for you.</p> - </li> - </ul> - </li> - <li>Press <strong>Finish</strong>.</li> -</ol> - -<p>The ADT plugin creates the these folders and - files for you as appropriate for the type of project:</p> - + <li>Select <strong>File</strong> > <strong>New</strong> > <strong>Project</strong>.</li> + <li>Select <strong>Android</strong> > <strong>Android Project</strong>, and click + <strong>Next</strong>.</li> + <li>Select the contents for the project: + <ul> + <li>Enter a <em>Project Name</em>. This will be the name of the folder where your + project is created.</li> + <li>Under Contents, select <strong>Create new project in workspace</strong>. + Select your project workspace location.</li> + <li>Under Target, select an Android target to be used as the project's Build Target. + The Build Target + specifies which Android platform you'd like your application built against. + <p>Unless you know that you'll be using new APIs introduced in the latest SDK, you should + select a target with the lowest platform version possible, such as Android 1.1.</p> + <p class="note"><strong>Note:</strong> You can change your the Build Target for your + project at any time: Right-click the project in the Package Explorer, select + <strong>Properties</strong>, select <strong>Android</strong> and then check + the desired Project Target.</p> + </li> + <li>Under Properties, fill in all necessary fields. <ul> - <li>src/ A - folder that includes your stub .java Activity file.</li> - <li>res/ A folder for your - resources.</li> - <li>AndroidManifest.xml The - manifest for your project. </li> + <li>Enter an <em>Application name</em>. This is the human-readable title for your + application — the name that will appear on the Android device.</li> + <li>Enter a <em>Package name</em>. This is the package namespace (following the same rules + as for packages in the Java programming language) where all your source code + will reside.</li> + <li>Select <em>Create Activity</em> (optional, of course, but common) and enter a name + for your main Activity class.</li> + <li>Enter a <em>Min SDK Version</em>. This is an integer that indicates + the minimum API Level required to properly run your application. + Entering this here automatically sets the <code>minSdkVersion</code> attribute in the + <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a> + of your Android Manifest file. If you're unsure of the appropriate API Level to use, + copy the API Level listed for the Build Target you selected in the Target tab.</li> </ul> - + </li> + </ul> + </li> + <li>Click <strong>Finish</strong>.</li> </ol> -<a name="launchconfig" id="launchconfig"></a> +<p class="note"><strong>Tip:</strong> +You can also start the New Project Wizard from the <em>New</em> icon in the toolbar.</p> + +<p>Once you complete the New Project Wizard, ADT creates the following +folders and files in your new project:</p> + <dl> + <dt><code>src/</code></dt> + <dd>Includes your stub Activity Java file. All other Java files for your application + go here.</dd> + <dt><code><em><Android Version></em>/</code> (e.g., <code>Android 1.1/</code>)</dt> + <dd>Includes the <code>android.jar</code> file that your application will build against. + This is determined by the build target that you have chosen in the <em>New Project + Wizard</em>.</dd> + <dt><code>gen/</code></dt> + <dd>This contains the Java files generated by ADT, such as your <code>R.java</code> file + and interfaces created from AIDL files.</dd> + <dt><code>assets/</code></dt> + <dd>This is empty. You can use it to store raw asset files. See + <a href="{@docRoot}guide/topics/resources/index.html">Resources and Assets</a>.</dd> + <dt><code>res/</code></dt> + <dd>A folder for your application resources, such as drawable files, layout files, string + values, etc. See + <a href="{@docRoot}guide/topics/resources/index.html">Resources and Assets</a>.</dd> + <dt><code>AndroidManifest.xml</code></dt> + <dd>The Android Manifest for your project. See + <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml + File</a>.</dd> + <dt><code>default.properties</code></dt> + <dd>This file contains project settings, such as the build target. This files is integral + to the project, as such, it should be maintained in a Source Revision Control system. + It should never be edited manually — to edit project properties, + right-click the project folder and select "Properties".</dd> + </dl> + + +<h2 id="Running">Running Your Application</h2> + +<p><em>Wait!</em> Before you can run your application on the Android Emulator, +you <strong>must</strong> create an Android Virtual Device (AVD). +An AVD is a configuration that specifies the Android platform to be used on the emulator. +You can read more about AVDs in the <a href="{@docRoot}guide/developing/index.html#avd">Developing +Overview</a>, but if you just want to get started, follow the simple guide below to create +an AVD.</p> + +<p>If you will be running your applications only on actual device hardware, you do not +need an AVD — see +<a href="{@docRoot}guide/developing/device.html">Developing On a Device</a> for information +on running your applicaiton.</p> + +<h3 id="CreatingAnAvd">Creating an AVD</h3> + +<p>To avoid some explanation that's beyond the scope of this document, here's the +basic procedure to create an AVD:</p> -<h2>Creating a Launch Configuration </h2> +<ol> + <li>Open a command-line (e.g.,"Command Prompt" application on Windows, or "Terminal" + on Mac/Linux) and navigate to your SDK package's + <code>tools/</code> directory.</li> + <li>First, you need to select a Deployment Target. To view available targets, execute: + <pre>android list targets</pre> + <p>This will output a list of available Android targets, such as:</p> +<pre> +id:1 + Name: Android 1.1 + Type: platform + API level: 2 + Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P +id:2 + Name: Android 1.5 + Type: platform + API level: 3 + Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P +</pre> + <p>Find the target that matches the Android platform upon which you'd like + to run your application. Note the integer value of the <code>id</code> — + you'll use this in the next step.</p> + </li> + <li>Create a new AVD using your selected Deployment Target. Execute: + <pre>android create avd --name <em><your_avd_name></em> --target <em><targetID></em></pre> + <li>Next, you'll be asked whether you'd like to create a custom hardware profile. + If you respond "yes," you'll be presented with a series of prompts to define various aspects of the + device hardware (leave entries blank to use default values, which are shown in brackets). Otherwise, + press return to use all default values ("no" is the default).</li> + </li> +</ol> -<p>Before you can run and debug your application in Eclipse, you must create a launch configuration for it. A launch configuration specifies the project to launch, the Activity to start, the emulator options to use, and so on. </p> +<p>That's it; your AVD is ready. In the next section, you'll see how the AVD is used +when launching your application on an emulator.</p> -<p>To create a launch configuration for the application, follow these steps as appropriate for your Eclipse version:</p> +<p>To learn more about creating and managing AVDs, please read the +<a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a> +documentation.</p> -<ol> - <li>Open the launch configuration manager. - <ul> - <li>In Eclipse 3.3 (Europa), select <strong>Run </strong>> - <strong>Open Run Dialog... </strong>or <strong>Run </strong>> - <strong>Open Debug Dialog... </strong>as appropriate. - </li> - <li>In Eclipse 3.4 (Ganymede), select <strong>Run </strong>> - <strong>Run Configurations... </strong>or <strong>Run </strong>> - <strong>Debug Configurations... </strong>as appropriate. - </li> - </ul> - </li> - <li>In the project type list on the left, locate the <strong> Android Application</strong> item and double-click it (or right-click > <strong>New</strong>), to create a new launch configuration.</li> - <li>Enter a name for your configuration.</li> - <li>On the Android tab, browse for the project and Activity to start.</li> - <li>On the Target tab, set the desired screen and network properties, as well as any other <a href="{@docRoot}guide/developing/tools/emulator.html#startup-options">emulator startup options</a>.</li> - <li>You can set additional options on the Common tab as desired.</li> - <li>Press <strong>Apply</strong> to save the launch configuration, or press <strong>Run</strong> or <strong>Debug</strong> (as appropriate).</li> +<h3 id="RunningYourApplication">Running your application</h3> -</ol> +<p class="note"><strong>Note:</strong> Before you can run your application, be sure that +you have created an AVD with a target that satisfies your application's Build Target. +If an AVD cannot be found that meets the requirements of your Build Target, you will see +a console error telling you so and the launch will be aborted.</p> +<p>To run (or debug) your application, select <strong>Run</strong> > <strong>Run</strong> (or +<strong>Run</strong> > <strong>Debug</strong>) from the Eclipse main menu. The ADT plugin +will automatically create a default launch configuration for the project.</p> -<h2 id="sign_in_adt">Setting Up Application Signing</h2> +<p>When you choose to run or debug your application, Eclipse will perform the following:</p> -<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> +<ol> + <li>Compile the project (if there have been changes since the last build).</li> + <li>Create a default launch configuration (if one does not already exist for the project).</li> + <li>Install and start the application on an emulator or device (based on the Deployment Target + defined by the run configuration). + <p>By default, Android application run configurations use an "automatic target" mode for + selecting a device target. For information on how automatic target mode selects a + deployment target, see <a href="#AutoAndManualTargetModes">Automatic and manual + target modes</a> below.</p> + </li> +</ol> -<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>If debugging, the application will start in the "Waiting For Debugger" mode. Once the +debugger is attached, Eclipse will open the Debug perspective.</p> + +<p>To set or change the launch configuration used for your project, use the launch configuration manager. +See <a href="#launchconfig">Creating a Launch Configuration</a> for information.</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> +<h2 id="RunConfig">Creating a Run Configuration</h2> -<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>The run configuration specifies the project to run, the Activity +to start, the emulator options to use, and so on. When you first run a project +as an <em>Android Application</em>, ADT will automatically create a run configuration. +The default run configuration will +launch the default project Activity and use automatic target mode for device selection +(with no preferred AVD). If the default setting don't suit your project, you can +customize the launch configuration or even create a new.</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> +<p>To create or modify a launch configuration, follow these steps as appropriate +for your Eclipse version:</p> +<ol> + <li>Open the run configuration manager. + <ul> + <li>In Eclipse 3.3 (Europa), select <strong>Run</strong> > + <strong>Open Run Dialog</strong> (or <strong>Open Debug Dialog</strong>) + </li> + <li>In Eclipse 3.4 (Ganymede), select <strong>Run </strong>> + <strong>Run Configurations</strong> (or + <strong>Debug Configurations</strong>) + </li> + </ul> + </li> + <li>Expand the <strong>Android Application</strong> item and create a new + configuration or open an existing one. + <ul> + <li>To create a new configuration: + <ol> + <li>Select <strong>Android Application</strong> and click the <em>New launch configuration</em> + icon above the list (or, right-click <strong>Android Application</strong> and click + <strong>New</strong>).</li> + <li>Enter a Name for your configuration.</li> + <li>In the Android tab, browse and select the project you'd like to run with the + configuration.</li> + </ol> + <li>To open an existing configuration, select the configuration name from the list + nested below <strong>Android Application</strong>.</li> + </ul> + </li> + <li>Adjust your desired launch configuration settings. + <p>In the Target tab, consider whether you'd like to use Manual or Automatic mode + when selecting an AVD to run your application. + See the following section on <a href=#AutoAndManualModes">Automatic and manual target + modes</a>).</p> + </li> +</ol> -<a name="installingrunningdebugging" id="installingrunningdebugging"></a> -<h2>Running and Debugging an Application</h2> +<h3 id="AutoAndManualTargetModes">Automatic and manual target modes</h3> -<p>Once you've set up the project and launch configuration for your application, you can run or debug it as described below.</p> +<p>By default, a run configuration uses the <strong>automatic</strong> target mode in order to select +an AVD. In this mode, ADT will select an AVD for the application in the following manner:</p> -From the Eclipse main menu, select <strong>Run</strong> > <strong>Run</strong> or <strong>Run</strong> > <strong>Debug</strong> as appropriate, to run or debug the active launch configuration. </li> +<ol> + <li>If there's a device or emulator already running and its AVD configuration + meets the requirements of the application's build target, the application is installed + and run upon it.</li> + <li>If there's more than one device or emulator running, each of which meets the requirements + of the build target, a "device chooser" is shown to let you select which device to use.</li> + <li>If there are no devices or emulators running that meet the requirements of the build target, + ADT looks at the available AVDs. If one meets the requirements of the build target, + the AVD is used to launch a new emulator, upon which the application is installed and run.</li> + <li>If all else fails, the application will not be run and you will see a console error warning + you that there is no existing AVD that meets the build target requirements.</li> +</ol> -<p>Note that the active launch configuration is the one most recently selected in the Run configuration manager. It does not necessarily correspond to the application that is selected in the Eclipse Navigation pane (if any).</p> +<p>However, if a "preferred AVD" is selected in the run configuration, then the application +will <em>always</em> be deployed to that AVD. If it's not already running, then a new emulator +will be launched.</p> -<p>To set or change the active launch configuration, use the launch configuration manager. See <a href="#launchconfig">Creating a Launch Configuration</a> for information about how to access the launch configuration manager.</strong>.</p> +<p>If your run configuration uses <strong>manual</strong> mode, then the "device chooser" +is presented every time that your application is run, so that you can select which AVD to use.</p> -<p>Running or debugging the application triggers these actions:</p> -<ul><li>Starts the emulator, if it is not already running. </li> - <li>Compiles the project, if there have been changes since the last build, and installs the application on the emulator. </li> - <li><strong>Run</strong> starts the application. </li> - <li><strong>Debug</strong> starts the application in "Wait for debugger" mode, then opens the Debug perspective and attaches the Eclipse Java debugger to the application.</li> - </ul> +<h2 id="Signing">Signing your Applications</h2> +<p>As you begin developing Android applications, understand that all +Android applications must be digitally signed before the system will install +them on an emulator or an actual device. There are two ways to do this: +with a debug key (for immediate testing on an emulator or development device) +or with a private key (for application distribution).</p> -<h2 id="tips">Eclipse Tips </h2> - <h3>Executing arbitrary Java expressions in Eclipse<a name="arbitraryexpressions" id="arbitraryexpressions"></a></h3> - <p>You can execute arbitrary code when paused at a breakpoint in Eclipse. For example, - when in a function with a String argument called "zip", you can get - information about packages and call class methods. You can also invoke arbitrary - static methods: for example, entering <code>android.os.Debug.startMethodTracing()</code> will - start dmTrace. </p> - <p>Open a code execution window, select <strong>Window</strong>><strong>Show - View</strong>><strong>Display</strong> from the main menu to open the - Display window, a simple text editor. Type your expression, highlight the - text, and click the 'J' icon (or CTRL + SHIFT + D) to run your - code. The code runs in the context of the selected thread, which must be - stopped at a breakpoint or single-step point. (If you suspend the thread - manually, you have to single-step once; this doesn't work if the thread is - in Object.wait().)</p> - <p>If you are currently paused on a breakpoint, you can simply highlight and execute - a piece of source code by pressing CTRL + SHIFT + D. </p> - <p>You can highlight a block of text within the same scope by pressing ALT +SHIFT - + UP ARROW to select larger and larger enclosing blocks, or DOWN ARROW to select - smaller blocks. </p> - <p>Here are a few sample inputs and responses in Eclipse using the Display window.</p> - <table width="100%" border="1"> - <tr> - <th scope="col">Input</th> - <th scope="col">Response</th> - </tr> - <tr> - <td><code>zip</code></td> - <td><code>(java.lang.String) /work/device/out/linux-x86-debug/android/app/android_sdk.zip</code></td> - </tr> - <tr> - <td><code>zip.endsWith(".zip")</code></td> - <td><code>(boolean) true</code></td> - </tr> - <tr> - <td><code>zip.endsWith(".jar")</code></td> - <td><code>(boolean) false</code></td> - </tr> - </table> - <p>You can also execute arbitrary code when not debugging by using a scrapbook page. - Search the Eclipse documentation for "scrapbook".</p> - - <h3>Running DDMS Manually</h3> - - <p>Although the recommended way to debug is to use the ADT plugin, you can manually run DDMS and configure Eclipse to debug on port 8700. (<strong>Note: </strong>Be sure that you have first started <a href="{@docRoot}guide/developing/tools/ddms.html">DDMS</a>). </p> +<p>The ADT plugin helps you get started quickly by signing your .apk files with +a debug key, prior to installing them on an emulator or development device. This means that you can +quickly run your application from Eclipse without having to +generate your own private key. No specific action on your part is needed, +provided ADT has access to Keytool.However, please note that if you intend +to publish your application, you <strong>must</strong> sign the application with your +own private key, rather than the debug key generated by the SDK tools.</p> + +<p>Please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your +Applications</a>, which provides a thorough guide to application signing on Android +and what it means to you as an Android application developer. The document also includes +a guide to exporting and signing your application with the ADT's Export Wizard.</p> + + +<h2 id="Tips">Eclipse Tips </h2> + +<h3 id="arbitraryexpressions">Executing arbitrary Java expressions in Eclipse</h3> + +<p>You can execute arbitrary code when paused at a breakpoint in Eclipse. For example, + when in a function with a String argument called "zip", you can get + information about packages and call class methods. You can also invoke arbitrary + static methods: for example, entering <code>android.os.Debug.startMethodTracing()</code> will + start dmTrace. </p> +<p>Open a code execution window, select <strong>Window</strong>><strong>Show + View</strong>><strong>Display</strong> from the main menu to open the + Display window, a simple text editor. Type your expression, highlight the + text, and click the 'J' icon (or CTRL + SHIFT + D) to run your + code. The code runs in the context of the selected thread, which must be + stopped at a breakpoint or single-step point. (If you suspend the thread + manually, you have to single-step once; this doesn't work if the thread is + in Object.wait().)</p> +<p>If you are currently paused on a breakpoint, you can simply highlight and execute + a piece of source code by pressing CTRL + SHIFT + D. </p> +<p>You can highlight a block of text within the same scope by pressing ALT +SHIFT + + UP ARROW to select larger and larger enclosing blocks, or DOWN ARROW to select + smaller blocks. </p> +<p>Here are a few sample inputs and responses in Eclipse using the Display window.</p> + +<table width="100%" border="1"> + <tr> + <th scope="col">Input</th> + <th scope="col">Response</th> + </tr> + <tr> + <td><code>zip</code></td> + <td><code>(java.lang.String) + /work/device/out/linux-x86-debug/android/app/android_sdk.zip</code></td> + </tr> + <tr> + <td><code>zip.endsWith(".zip")</code></td> + <td><code>(boolean) true</code></td> + </tr> + <tr> + <td><code>zip.endsWith(".jar")</code></td> + <td><code>(boolean) false</code></td> + </tr> +</table> +<p>You can also execute arbitrary code when not debugging by using a scrapbook page. + Search the Eclipse documentation for "scrapbook".</p> + + +<h3>Running DDMS Manually</h3> + +<p>Although the recommended way to debug is to use the ADT plugin, you can manually run +DDMS and configure Eclipse to debug on port 8700. (<strong>Note: </strong>Be sure that you +have first started <a href="{@docRoot}guide/developing/tools/ddms.html">DDMS</a>). </p> + + +<!-- TODO: clean this up and expand it to cover more wizards and features +<h3>ADT Wizards</h3> + +<p>Notice that the "New Android Project" wizard has been expanded to use the multi-platform +capabilities of the new SDK.</p> + +<p>There is now a "New XML File" wizard that lets you create skeleton XML resource +files for your Android projects. This makes it easier to create a new layout, a new menu, a +new strings file, etc.</p> + +<p>Both wizards are available via <strong>File > New</strong> and new icons in the main +Eclipse toolbar (located to the left of the Debug and Run icons). +If you do not see the new icons, you may need to select <strong>Window > Reset +Perspective</strong> from the Java perspective.</p> +--> diff --git a/docs/html/guide/developing/other-ide.jd b/docs/html/guide/developing/other-ide.jd index 7bcb509..8cdf0b9 100644 --- a/docs/html/guide/developing/other-ide.jd +++ b/docs/html/guide/developing/other-ide.jd @@ -1,167 +1,408 @@ -page.title=In Other IDEs +page.title=Developing In Other IDEs @jd:body +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#CreatingAProject">Creating an Android Project</a></li> + <li><a href="#Signing">Preparing to Sign Your Application</a></li> + <li><a href="#Building">Building Your Application</a> + <ol> + <li><a href="#DebugMode">Building in debug mode</a></li> + <li><a href="#ReleaseMode">Building in release mode</a></li> + </ol> + </li> + <li><a href="#Running">Running Your Application</a></li> + <li><a href="#AttachingADebugger">Attaching a Debugger to Your Application</a></li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}guide/developing/tools/othertools.html#android">android Tool</a></li> + <li><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></li> + <li><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a></li> + </ol> +</div> +</div> + <p>The recommended way to develop an Android application is to use - <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> +<a href="{@docRoot}guide/developing/eclipse-adt.html">Eclipse with the ADT plugin</a>. +The ADT plugin provides editing, building, debugging, and .apk packaging and signing functionality +integrated right into the IDE.</p> -<p>However, if you'd rather develop your application in another IDE, such as IntelliJ, - or use Eclipse without the ADT plugin, you can do that instead. The SDK - provides the tools you need to set up, build, and debug your application. - </p> +<p>However, if you'd rather develop your application in another IDE, such as IntelliJ, +or in a basic editor, such as Emacs, you can do that instead. The SDK +includes all the tools you need to set up an Android project, build it, debug it and then +package it for distribution. This document is your guide to using these tools.</p> -<h2>Creating an Android Project </h2> +<h2 id="EssentialTools">Essential Tools</h2> -<p>The Android SDK includes <code>activityCreator</code>, a program that generates a number of stub files for your project, as well as a build file. You can use the program to create an Android project for new code or from existing code, such as the sample applications included in the SDK. For Linux and Mac, the SDK provides <code>activitycreator</code> and for Windows, <code>activityCreator.bat</code>, a batch script. Regardless of platform, you can use <code>activitycreator</code> in the same way. </p> +<p>When developing in IDEs or editors other than Eclipse, you'll require +familiarity with the following Android SDK tools:</p> -<p>To run <code>activityCreator</code> and create an Android project, follow these steps:</p> +<dl> + <dt><a href="{@docRoot}guide/developing/tools/othertools.html#android">android</a></dt> + <dd>To create/update Android projects and to create/move/delete AVDs.</dd> + <dt><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></dt> + <dd>To run your Android applications on an emulated Android platform.</dd> + <dt><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a></dt> + <dd>To interface with your emulator or connected device (install apps, + shell the device, issue commands, etc.). + </dd> +</dl> + +<p>In addition to the above tools, included with the SDK, you'll use the following +open source and third-party tools:</p> + +<dl> + <dt>Ant</dt> + <dd>To compile and build your Android project into an installable .apk file.</dd> + <dt>Keytool</dt> + <dd>To generate a keystore and private key, used to sign your .apk file.</dd> + <dt>Jarsigner (or similar signing tool)</dt> + <dd>To sign your .apk file with a private key generated by keytool.</dd> +</dl> + +<p>In the topics that follow, you'll be introduced to each of these tools as necessary. +For more advanced operations, please read the respective documentation for each tool.</p> + + +<h2 id="CreatingAProject">Creating an Android Project</h2> + +<p>To create an Android project, you must use the <code>android</code> tool. When you create +a new project with <code>android</code>, it will generate a project directory +with some default application files, stub files, configuration files and a build file.</p> -<ol> - <li> In the command line, change to the <code>tools/</code> directory of the SDK and create a new directory for your project files. If you are creating a project from existing code, change to the root folder of your application instead. </li> - <li><p>Run <code>activityCreator</code>. In the command, you must specify a fully-qualified class name as an argument. If you are creating a project for new code, the class represents the name of a stub class that the script will create. If you are creating a project from existing code, you must specify the name of one Activity class in the package. Command options for the script include: +<h3 id="CreatingANewProject">Creating a new Project</h3> + +<p>If you're starting a new project, use the <code>android create project</code> +command to generate all the necessary files and folders.</p> + +<p>To create a new Android project, open a command-line, +navigate to the <code>tools/</code> directory of your SDK and run:</p> +<pre> +android create project \ +--target <em><targetID></em> \ +--path <em>/path/to/your/project</em> \ +--activity <em><your_activity_name></em> \ +--package <em><your_package_namespace></em> +</pre> + <ul> - <li><code>--out <folder></code> which sets the output directory. By default, the output directory is the current directory. If you created a new directory for your project files, use this option to point to it. </li> - <li><code>--ide intellij</code>, which generates IntelliJ IDEA project files in the newly created project</li> + <li><code>target</code> is the "build target" for your application. It corresponds + to an Android platform library (including any add-ons, such as Google APIs) that you would like to + build your project against. To see a list of available targets and their corresponding IDs, + execute: <code>android list targets</code>.</li> + <li><code>path</code> is the location of your project directory. If the directory does not exist, + it will be created for you.</li> + <li><code>activity</code> is the name for your {@link android.app.Activity} class. This class file + will be created for you inside + <code><em><path_to_your_project></em>/src/<em><your_package_namespace_path></em>/</code>.</li> + <li><code>package</code> is the package namespace for your project, following the same rules as for + packages in the Java programming language.</li> </ul> -</li> -</ol> -<p>Here's an example:</p> +<p>Here's an example:</p> <pre> -~/android_linux_sdk/tools $ ./activityCreator.py --out myproject your.package.name.ActivityName -package: your.package.name -out_dir: myproject -activity_name: ActivityName -~/android_linux_sdk/tools $ </pre> +android create project \ +--target 1 \ +--path ./myProject \ +--activity MyActivity \ +--package com.example.myproject +</pre> -<p>The <code>activityCreator</code> script generates the following files and directories (but will not overwrite existing ones):</p> +<p>The tool generates the following files and directories:</p> <ul> - <li><code>AndroidManifest.xml</code> The application manifest file, synced to the specified Activity class for the project.</li> - <li><code>build.xml</code> An <code>Ant</code> file that you can use to build/package the application.</li> - <li><code>src<em>/your/package/name/ActivityName</em>.java</code> The Activity class you specified on input.</li> - <li><code><em>your_activity</em>.iml, <em>your_activity</em>.ipr, - <em>your_activity</em>.iws </code> [<em>only - with the <code>-ide intelliJ</code> flag</em>] intelliJ project - files. </li> - <li><code>res/</code> A directory to hold resources. </li> - <li><code>src/</code> The source directory. - <li><code>bin/</code> The output directory for the build script.</li> + <li><code>AndroidManifest.xml</code> - The application manifest file, + synced to the specified Activity class for the project.</li> + <li><code>build.xml</code> - Build file for Ant.</li> + <li><code>default.properties</code> - Properties for the build system. <em>Do not modify + this file</em>.</li> + <li><code>build.properties</code> - Customizable properties for the build system. You can edit this + file to overried default build settings used by Ant.</li> + <li><code>src<em>/your/package/namespace/ActivityName</em>.java</code> - The Activity class + you specified during project creation.</li> + <li><code>bin/</code> - Output directory for the build script.</li> + <li><code>gen/</code> - Holds <code>Ant</code>-generated files, such as <code>R.java</code>. </li> + <li><code>libs/</code> - Holds private libraries.</li> + <li><code>res/</code> - Holds project resources.</li> + <li><code>src/</code> - Holds source code.</li> + <li><code>tests/</code> - Holds a duplicate of all-of-the-above, for testing purposes.</li> </ul> -<p>You can now move your folder wherever you want for development, but keep in mind - that you'll have to use the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> program in the <code>tools/</code> folder to - send files to the emulator, so you'll need access between your solution and - the <code>tools/</code> folder. </p> - -<p>Also, you should refrain from moving the - location of the SDK directory, since this will break the build scripts (they - will need to be manually updated to reflect the new SDK location before they will - work again).</p> -<a name="buidingwithant"></a> -<h2 id="antbuild">Building the Application with Ant</h2> -<p>Use the Ant <code>build.xml</code> file generated by - <code>activityCreator</code> to build your application.</p> -<ol> - <li>If you don't have it, you can obtain Ant from the - <a href="http://ant.apache.org/">Apache Ant home page</a>. Install it and make - sure it is on your executable path. </li> - <li>Before calling Ant, you need to declare the JAVA_HOME environment variable to specify the path to where the JDK is installed. - <p class="note"><strong>Note:</strong> When installing JDK on Windows, the default is to install in the "Program Files" directory. This location will cause <code>ant</code> to fail, because of the space. To fix the problem, you can specify the JAVA_HOME variable like this: <code>set JAVA_HOME=c:\Prora~1\Java\<jdkdir></code>. The easiest solution, however, is to install JDK in a non-space directory, for example: <code>c:\java\jdk1.6.0_02</code>. </p> - </li> - - - <li>If you have not done so already, follow the instructions for Creating a - New Project above to set up the project.</li> - <li>You can now run the Ant build file by simply typing ant in the same folder - as the build.xml file for your project. Each time you change - a source file or resource, you should run ant again and it will package up the - latest version of the application for you to deploy.</li> -</ol> +<p>Once you've created your project, you're ready to begin development. +You can move your project folder wherever you want for development, but keep in mind +that you must use the <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> +(adb) — located in the SDK <code>tools/</code> directory — to send your application +to the emulator (discussed later). So you need access between your project solution and +the <code>tools/</code> folder.</p> + +<p class="warning"><strong>Note:</strong> You should refrain from moving the +location of the SDK directory, because this will break the build scripts. (They +will need to be manually updated to reflect the new SDK location before they will +work again.)</p> + -<h2 id="sign_in_other">Setting Up Application Signing</h2> +<h3 id="UpdatingAProject">Updating a project</h3> -<p>As you begin developing Android applications, you should understand that all +<p>If you're upgrading a project from an older version of the Android SDK or want to create +a new project from existing code, use the +<code>android update project</code> command to update the project to the new development +environment. You can also use this command to revise the build target of an existing project +(with the <code>--target</code> option). The <code>android</code> tool will generate any files and +folders (listed in the previous section) that are either missing or need to be updated, +as needed for the Android project.</p> + +<p>To update an existing Android project, open a command-line +and navigate to the <code>tools/</code> directory of your SDK. Now run:</p> +<pre> +android update project --target <em><targetID></em> --path <em>path/to/your/project/</em> +</pre> + +<ul> + <li><code>target</code> is the "build target" for your application. It corresponds to + an Android platform library (including any add-ons, such as Google APIs) that you would + like to build your project against. To see a list of available targets and their corresponding IDs, + execute: <code>android list targets</code>.</li> + <li><code>path</code> is the location of your project directory.</li> +</ul> + +<p>Here's an example:</p> +<pre> +android update project --target 2 --path ./myProject +</pre> + + +<h2 id="Signing">Preparing to Sign Your Application</h2> + +<p>As you begin developing Android applications, understand that all Android applications must be digitally signed before the system will install -them on the emulator or an actual device. </p> +them on an emulator or device. There are two ways to do this: +with a <em>debug key</em> (for immediate testing on an emulator or development device) +or with a <em>private key</em> (for application distribution).</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 +<p>The Android build tools help you get started by automatically signing your .apk +files with a debug key at build time. 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 +to publish your application, you <strong>must</strong> 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 - in the emulator using the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> tool as described here:</p> +<p>Please read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your +Applications</a>, which provides a thorough guide to application signing on Android +and what it means to you as an Android application developer.</p> + + + +<h2 id="Building">Building Your Application</h2> + +<p>There are two ways to build your application: one for testing/debugging your application +— <em>debug mode</em> — and one for building your final package for release — +<em>release mode</em>. As described in the previous +section, your application must be signed before it can be installed on an emulator +or device.</p> + +<p>Whether you're building in debug mode or release mode, you +need to use the Ant tool to compile and build your project. This will create the .apk file +that is installed onto the emulator or device. When you build in debug mode, the .apk +file is automatically signed by the SDK tools with a debug key, so it's instantly ready for installation +(but only onto an emulator or attached development device). +When you build in release mode, the .apk file is <em>unsigned</em>, so you must manually +sign it with your own private key, using Keytool and Jarsigner.</p> + +<p>It's important that you read and understand +<a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>, particularly +once you're ready to release your application and share it with end-users. That document describes +the procedure for generating a private key and then using it to sign your .apk file. +If you're just getting started, however, +you can quickly run your applications on an emulator or your own development device by building in +debug mode.</p> + +<p>If you don't have Ant, you can obtain it from the +<a href="http://ant.apache.org/">Apache Ant home page</a>. Install it and make +sure it is in your executable PATH. Before calling Ant, you need to declare the JAVA_HOME +environment variable to specify the path to where the JDK is installed.</p> + +<p class="note"><strong>Note:</strong> When installing JDK on Windows, the default is to install +in the "Program Files" directory. This location will cause <code>ant</code> to fail, because of +the space. To fix the problem, you can specify the JAVA_HOME variable like this: +<code>set JAVA_HOME=c:\Prora~1\Java\<jdkdir></code>. The easiest solution, however, is to +install JDK in a non-space directory, for example: <code>c:\java\jdk1.6.0_02</code>.</p> + + +<h3 id="DebugMode">Building in debug mode</h3> + +<p>For immediate application testing and debugging, you can build your application +in debug mode and immediately install it on an emulator. In debug mode, the build tools automatically +sign your application with a debug key. However, you can (and should) also test your +application in release mode. Debug mode simply allows you to run your application without +manually signing the application.</p> + +<p>To build in debug mode:</p> + +<ol> + <li>Open a command-line and navigate to the root of your project directory.</li> + <li>Use Ant to compile your project in debug mode: + <pre>ant debug</pre> + <p>This creates your Android application .apk file inside the project <code>bin/</code> + directory, named <code><em><your_DefaultActivity_name></em>-debug.apk</code>. The file + is already signed with the debug key.</p> + </li> +</ol> + +<p>Each time you change a source file or resource, you must run Ant +again in order to package up the latest version of the application.</p> + +<p>To install and run your application on an emulator, see the following section +about <a href="#Running">Running Your Application</a>.</p> + + +<h3 id="ReleaseMode">Building in release mode</h3> + +<p>When you're ready to release and distribute your application to end-users, you must build +your application in release mode. Once you have built in release mode, it's a good idea to perform +additional testing and debugging with the final .apk.</p> + +<p>To build in release mode:</p> + +<ol> + <li>Open a command-line and navigate to the root of your project directory.</li> + <li>Use Ant to compile your project in release mode: + <pre>ant release</pre> + <p>This creates your Android application .apk file inside the project <code>bin/</code> + directory, named <code><em><your_DefaultActivity_name></em>.apk</code>.</p> + <p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point. + You can't install it on an emulator or device until you sign it with your private key.</p> + </li> +</ol> + +<p>Because release mode builds your application unsigned, your next step is to sign +it with your private key, in order to distribute it to end-users. To complete this procedure, +read <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p> + +<p>Once you have signed your application with a private key, you can install it on an +emulator or device as discussed in the following section about +<a href="#Running">Running Your Application</a>. +You can also try installing it onto a device from a web server. +Simply upload the signed APK to a web site, then load the .apk URL in your Android web browser to +download the application and begin installation. +(On your device, be sure you have enabled <em>Settings > Applications > Unknown sources</em>.)</p> + + +<h2 id="Running">Running Your Application</h2> + +<p>Unless you'll be running your application on device hardware, +you need to launch an emulator upon which you will install your application. +An instance of the Android emulator runs a specific Android platform with specific device configuration +settings. The platform and configuration is defined with an Android Virtual Device (AVD). +So before you can launch your emulator, you must define an AVD.</p> + +<p>If you'll be running your application on device hardware, please read about +<a href="{@docRoot}guide/developing/device.html">Developing On a Device</a> instead.</p> + <ol> - <li>Start the emulator (run <code><em><your_sdk_dir></em>/tools/emulator</code> from the command line)</li> - <li>On the emulator, navigate to the home screen (it is best not to have that - application running when you reinstall it on the emulator; press the <strong>Home</strong> key - to navigate away from that application).</li> - <li>Run <code>adb install <em>myproject</em>/bin/<<em>appname</em>>.apk</code> to upload - the executable. So, for example, to install the Lunar Lander sample, navigate - in the command line to <code><em><your_sdk_dir></em>/sample/LunarLander</code> and type <code>../../tools/adb install bin/LunarLander.apk</code></li> - <li>In the emulator, open the list of available applications, and scroll down to - select and start your application. </li> + <li><strong>Create an AVD</strong> + <ol> + <li>Open a command-line and navigate to your SDK package's + <code>tools/</code> directory.</li> + <li>First, you need to select a "deployment target." To view available targets, execute: + <pre>android list targets</pre> + <p>This will output a list of available Android targets, such as:</p> +<pre> +id:1 + Name: Android 1.1 + Type: platform + API level: 2 + Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P +id:2 + Name: Android 1.5 + Type: platform + API level: 3 + Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P +</pre> + <p>Find the target that matches the Android platform upon which you'd like + to run your application. Note the integer value of the <code>id</code> — + you'll use this in the next step.</p> + </li> + <li>Create a new AVD using your selected deployment target: + <pre>android create avd --name <em><your_avd_name></em> --target <em><targetID></em></pre> + <li>Next, you'll be asked whether you'd like to create a custom hardware profile. + If you respond "yes," you'll be presented with a series of prompts to define various aspects of the + device hardware (leave entries blank to use default values, which are shown in brackets). Otherwise, + press return to use all default values ("no" is the default).</li> + </li> + </ol> + </li> + + <li><strong>Launch an emulator</strong></li> + <p>From your SDK's <code>tools/</code> directory, launch an emulator + using an existing AVD (created above): + <pre>emulator -avd <em><your_avd_name></em></pre> + <p>An instance of the emulator will now launch, running the target and configuration + defined by your AVD.</p> + </li> + + <li><strong>Install your application</strong> + <p>From your SDK's <code>tools/</code> directory, install the .apk on the emulator: + <pre>adb install <em>/path/to/your/application</em>.apk</pre> + <p>If there is more than one emulator running, you must specify the emulator upon which to install + the application, by its serial number, with the <code>-s</code> option. For example:</p> + <pre>adb -s emulator-5554 install /my/project/path/myapp.apk</pre> + </li> + <li><strong>Open your application</strong> + <p>In the emulator, open the list of available applications to find + and open your application.</p> + </li> </ol> -<p class="note"><strong>Note:</strong> When you install an Activity for the - first time, you might have to restart the emulator before it shows up in the - application launcher, or other applications can call it. This is because - the package manager usually only examines manifests completely on emulator - startup.</p> -<h2>Attaching a Debugger to Your Application</h2> +<p>If you don't see your application on the emulator. Try restarting the emulator +(with the same AVD). Sometimes when you install an Activity for the +first time, it won't show up in the application launcher or be accessible by other +applications. This is because the package manager usually examines manifests +completely only on emulator startup.</p> + +<p class="note"><strong>Tip:</strong> If you have only one emulator running, +you can build your application and install it on the emulator in one simple step. +Navigate to the root of your project directory and use Ant to compile the project +with <em>install mode</em>: +<code>ant install</code>. This will build your application, sign it with the debug key, +and install it on the currently running emulator. +If there is more than one emulator currently running +when using the <code>install</code> command, it will fail — it can't select between the +multiple emulators.</p> + +<p>For more information on the tools used above, please see the following documents:</p> +<ul> + <li><a href="{@docRoot}guide/developing/tools/othertools.html#android">android Tool</a></li> + <li><a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a></li> + <li><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (ADB)</li> +</ul> + + +<h2 id="AttachingADebugger">Attaching a Debugger to Your Application</h2> + <p>This section describes how to display debug information on the screen (such as CPU usage), as well as how to hook up your IDE to debug running applications on the emulator. </p> <p>Attaching a debugger is automated using the Eclipse plugin, but you can configure other IDEs to listen on a debugging port to receive debugging - information.</p> + information:</p> <ol> - <li><strong>Start the <a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor Server (DDMS) - tool </a>, </strong> which + <li><strong>Start the <a href="{@docRoot}guide/developing/tools/ddms.html">Dalvik Debug Monitor + Server (DDMS)</a> tool, </strong> which acts as a port forwarding service between your IDE and the emulator.</li> <li><strong>Set optional debugging configurations on - your emulator</strong>, such as blocking application startup for an activity + your emulator</strong>, such as blocking application startup for an Activity until a debugger is attached. Note that many of these debugging options can be used without DDMS, such as displaying CPU usage or screen refresh rate on the emulator.</li> - <li><strong>Configure your IDE to attach to port 8700 for debugging.</strong> We - include information on <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port"> - how to set up Eclipse to debug your project</a>. </li> - + <li><strong>Configure your IDE to attach to port 8700 for debugging.</strong> Read + about <a href="{@docRoot}guide/developing/debug-tasks.html#ide-debug-port"> + Configuring Your IDE to Attach to the Debugging Port</a>. </li> </ol> diff --git a/docs/html/guide/developing/tools/aidl.jd b/docs/html/guide/developing/tools/aidl.jd index 96e4fec..f370a80 100644 --- a/docs/html/guide/developing/tools/aidl.jd +++ b/docs/html/guide/developing/tools/aidl.jd @@ -1,6 +1,25 @@ page.title=Designing a Remote Interface Using AIDL @jd:body + +<div id="qv-wrapper"> +<div id="qv"> +<h2>In this document</h2> +<ol> + <li><a href="#implementing">Implementing IPC Using AIDL</a> + <ol> + <li><a href="#aidlsyntax">Create an .aidl File</a></li> + <li><a href="#implementtheinterface">Implementing the Interface</a></li> + <li><a href="#exposingtheinterface">Exposing Your Interface to Clients</a></li> + <li><a href="#parcelable">Pass by value Parameters using Parcelables</a></li> + </ol> + </li> + <li><a href="#calling">Calling an IPC Method</a></li> +</ol> +</div> +</div> + + <p>Since each application runs in its own process, and you can write a service that runs in a different process from your Application's UI, sometimes you need to pass objects between processes. On the Android platform, one process can not normally access the memory @@ -10,7 +29,7 @@ the operating system can understand, and "marshall" the object across that bound <p>The code to do that marshalling is tedious to write, so we provide the AIDL tool to do it for you.</p> -<p> AIDL (Android Interface Definition Language) is an <a +<p>AIDL (Android Interface Definition Language) is an <a href="http://en.wikipedia.org/wiki/Interface_description_language">IDL</a> language used to generate code that enables two processes on an Android-powered device to talk using interprocess communication (IPC). If you have code @@ -20,12 +39,9 @@ generate code to marshall the parameters.</p> <p>The AIDL IPC mechanism is interface-based, similar to COM or Corba, but lighter weight. It uses a proxy class to pass values between the client and the implementation. </p> -<p>This page includes the following main topics: </p> -<ul> - <li><a href="#implementing">Implementing IPC Using AIDL</a></li> - <li><a href="#calling">Calling an .aidl (IPC) Class </a></li> -</ul> -<h2>Implementing IPC Using AIDL <a name="implementing"></a></h2> + + +<h2 id="implementing">Implementing IPC Using AIDL</h2> <p>Follow these steps to implement an IPC service using AIDL.</p> <ol> <li><strong><a href="#aidlsyntax">Create your .aidl file</a> </strong>- This @@ -46,7 +62,8 @@ generate code to marshall the parameters.</p> Service.onBind(Intent)} to return an instance of your class that implements your interface. </li> </ol> -<h3>Create an .aidl File <a name="aidlsyntax"></a></h3> + +<h3 id="aidlsyntax">Create an .aidl File</h3> <p>AIDL is a simple syntax that lets you declare an interface with one or more methods, that can take parameters and return values. These parameters and return values can be of any type, even other AIDL-generated interfaces. <em>However, it @@ -117,7 +134,7 @@ interface IBankAccountService { int getCustomerList(in String branch, out String[] customerList); }</pre> -<h3>Implementing the Interface <a name="implementtheinterface"></a></h3> +<h3 id="implementtheinterface">Implementing the Interface</h3> <p>AIDL generates an interface file for you with the same name as your .aidl file. If you are using the Eclipse plugin, AIDL will automatically be run as part of the build process (you don't need to run AIDL first and then build your project). @@ -152,7 +169,7 @@ private final IRemoteService.Stub mBinder = new IRemoteService.Stub(){ <li>Only methods are supported; you cannot declare static fields in an AIDL interface.</li> </ul> -<h3>Exposing Your Interface to Clients<a name="exposingtheinterface" id="exposingtheinterface"></a></h3> +<h3 id="exposingtheinterface">Exposing Your Interface to Clients</h3> <p>Now that you've got your interface implementation, you need to expose it to clients. This is known as "publishing your service." To publish a service, inherit {@link android.app.Service Service} and implement {@link android.app.Service#onBind @@ -165,8 +182,8 @@ private final IRemoteService.Stub mBinder = new IRemoteService.Stub(){ exposing_a_service} }</pre> -<a name="parcelable"></a> -<h3>Pass by value Parameters using Parcelables</h3> + +<h3 id="parcelable">Pass by value Parameters using Parcelables</h3> <p>If you have a class that you would like to send from one process to another through an AIDL interface, you can do that. You must ensure that the code for your class is available @@ -181,25 +198,12 @@ current state of the object and writes it to a parcel.</li> value in a parcel into your object.</li> <li>Add a static field called <code>CREATOR</code> to your class which is an object implementing the {@link android.os.Parcelable.Creator Parcelable.Creator} interface.</li> -<li>Last but not least: -<ul> -<li>If you are developing with Eclipse/ADT, follow these steps: -<ol type="a"> -<li>In the Package Explorer view, right-click on the project.</li> -<li>Choose <strong>Android Tools</strong> > <strong>Create Aidl preprocess file -for Parcelable classes</strong>.</li> -<li>This will create a file called "project.aidl" in the root of the project. -The file will be automatically used when compiling an aidl file that uses the -parcelable classes.</li> -</ol> -</li> -<li>If you are developing with Ant or are using a custom build process, create an aidl file +<li>Last but not least, create an aidl file that declares your parcelable class (as shown below). If you are using a custom build process, do not add the aidl file to your build. Similar to a header file in C, the aidl file isn't compiled.</li> -</ul> -</li> -</ul> +</ol> + <p>AIDL will use these methods and fields in the code it generates to marshall and unmarshall your objects.</p> <p>Here is an example of how the {@link android.graphics.Rect} class implements the @@ -269,7 +273,7 @@ values for whatever the caller is trying to do. See <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> for more on how to keep your application secure from malware.</p> -<h2>Calling an IPC Method <a name="calling"></a></h2> +<h2 id="calling">Calling an IPC Method</h2> <p>Here are the steps a calling class should make to call your remote interface: </p> <ol> <li>Declare a variable of the interface type that your .aidl file defined. </li> diff --git a/docs/html/guide/developing/tools/avd.jd b/docs/html/guide/developing/tools/avd.jd new file mode 100644 index 0000000..b8f205e --- /dev/null +++ b/docs/html/guide/developing/tools/avd.jd @@ -0,0 +1,504 @@ +page.title=Android Virtual Devices +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>AVD quickview</h2> + <ul> + <li>You need to create an AVD to run any app in the Android emulator</li> + <li>Each AVD is a completely independent virtual device, with its own + hardware options, system image, and data storage. + <li>You create AVD configurations to model different device environments + in the Android emulator.</li> + </ul> + <h2>In this document</h2> + <ol> + <li><a href="#creating">Creating an AVD</a> + <ol> + <li><a href="#listingtargets">Listing targets</a></li> + <li><a href="#selectingtarget">Selecting a target</a></li> + <li><a href="#createavd">Creating the AVD</a></li> + <li><a href="#hardwareopts">Setting hardware emulation options</a></li> + <li><a href="#location">Default location of the AVD files</a></li> + </ol> + </li> + <li><a href="#managing">Managing AVDs</a> + <ol> + <li><a href="#moving">Moving an AVD</a></li> + <li><a href="#updating">Updating an AVD</a></li> + <li><a href="#deleting">Deleting an AVD</a></li> + </ol> + </li> + <li><a href="#options">Command-line options</a></li> + </ol> + <h2>See Also</h2> + <ol> + <li><a href="{@docRoot}guide/developing/tools/emulator.html">Android + Emulator</a></li> + </ol> +</div> +</div> + +<p>Android Virtual Devices (AVDs) are configurations of emulator options that let +you better model an actual device.</p> + +<p>Each AVD is made up of: </p> + +<ul> +<li>A hardware profile. You can set options to define the hardware +features of the virtual device. For example, you can define whether the device +has a camera, whether it uses a physical QWERTY keyboard or a dialing pad, how +much memory it has, and so on. </li> +<li>A mapping to a system image. You can define what version of the +Android platform will run on the virtual device. You can choose a version of the +standard Android platform or the system image packaged with an SDK add-on.</li> +<li>Other options. You can specify the emulator skin you want to use +with the AVD, which lets you control the screen dimensions, appearance, and so +on. You can also specify the emulated SD card to use with the AVD.</li> +<li>A dedicated storage area on your development machine, in which is stored the +device's user data (installed applications, settings, and so on) and emulated SD +card.</li> +</ul> + +<p>You can create as many AVDs as you need, based on the types of devices you +want to model and the Android platforms and external libraries you want to run +your application on. </p> + +<p>In addition to the options in an AVD configuration, you can also +specify emulator command-line options at launch or by using the emulator +console to change behaviors or characteristics at run time. For a complete +reference of emulator options, please see the <a +href="{@docRoot}guide/developing/tools/emulator.html">Emulator</a> +documentation. </p> + +<p>To create and manage AVDs, you use the android tool provided in the Android +SDK. For more information about how to work with AVDs from inside +your development environment, see <a +href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse with +ADT</a> or <a href="{@docRoot}guide/developing/other-ide.html">Developing in +Other IDEs</a>, as appropriate for your environment.</p> + +<h2 id="creating">Creating an AVD</h2> + +<div class="sidebox-wrapper"> +<div class="sidebox-inner"> +<p>The Android SDK does not include any preconfigured AVDs, so +you need to create an AVD before you can run any application in the emulator +(even the Hello World application).</p> +</div> +</div> + +<p>To create an AVD, you use the android tool, a command-line utility +available in the <code><sdk>/tools/</code> directory. Managing AVDs is one +of the two main function of the android tool (the other is creating and updating +Android projects). Open a terminal window and change to the +<code><sdk>/tools/</code> directory, if needed</p> + +<p>To create each AVD, you issue the command <code>android create avd</code>, +with options that specify a name for the new AVD and the system image you want +to run on the emulator when the AVD is invoked. You can specify other options on +the command line also, such as to create an emulated SD card for the new AVD, set +the emulator skin to use, or set a custom location for the AVD's files.</p> + +<p>Here's the command-line usage for creating an AVD: </p> + +<pre>android create avd -n <name> -t <targetID> [-<option> <value>] ... </pre> + +<p>You can use any name you want for the AVD, but since you are likely to be +creating multiple AVDs, you should choose a name that lets you recognize the +general characteristics offered by the AVD. </p> + +<p>As shown in the usage above, you must use the <code>-t</code> (or +<code>--target</code>) argument when creating a new AVD. The argument sets up a +mapping between the AVD and the system image that you want to use whenever the +AVD is invoked. You can specify any Android system image that is available in +your local SDK — it can be the system image of a standard Android platform +version or that of any SDK add-on. Later, when applications use the AVD, they'll +be running on the system that you specify in the <code>-t</code> argument.<p> + +<p>To specify the system image to use, you refer to its <em>target ID</em> +— an integer — as assigned by the android tool. The target ID is not +derived from the system image name, version, or API Level, or other attribute, +so you need to have the android tool list the available system images and the +target ID of each, as described in the next section. You should do this +<em>before</em> you run the <code>android create avd</code> command. +</p> + +<h3 id="listingtargets">Listing targets</h3> + +<p>To generate a list of system image targets, use this command: </p> + +<pre>android list targets</pre> + +<p>The android tool scans the <code><sdk>/platforms</code> and +<code><sdk>/add-ons</code> directories looking for valid system images and +then generates the list of targets. Here's an example of the command output: +</p> + +<pre>Available Android targets: +id:1 + Name: Android 1.1 + Type: platform + API level: 2 + Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P +id:2 + Name: Android 1.5 + Type: platform + API level: 3 + Skins: HVGA (default), HVGA-L, HVGA-P, QVGA-L, QVGA-P +id:3 + Name: Google APIs + Type: add-on + Vendor: Google Inc. + Description: Android + Google APIs + Based on Android 1.5 (API level 3) + Libraries: + * com.google.android.maps (maps.jar) + API for Google Maps + Skins: HVGA (default), HVGA-L, QVGA-P, HVGA-P, QVGA-L</pre> + +<h3 id="selectingtarget">Selecting a target</h3> + +<p>Once you have generated the list of targets available, you can look at the +characteristics of each system image — name, API Level, external +libraries, and so on — and determine which target is appropriate for the +new AVD. </p> + +<p>Keep these points in mind when you are selecting a system image target for +your AVD:</p> +<ul> +<li>The API Level of the target is important, because your application will not +be able to run on a system image whose API Level is less than that required by +your application, as specified in the <code>minSdkVersion</code> attribute of +the application's manifest file. For more information about the relationship +between system API Level and application <code>minSdkVersion</code>, see <a +href="{@docRoot}guide/publishing/versioning.html#minsdkversion">Specifying +Minimum System API Version</a>. +<li>Creating at least one AVD that uses a target whose API Level is greater than +that required by your application is strongly encouraged, because it allows you to +test the forward-compatibility of your application. Forward-compatibility +testing ensures that, when users who have downloaded your application receive a +system update, your application will continue to function normally. </li> +<li>If your application declares a <code>uses-library</code> element in its +manifest file, the application can only run on a system image in which that +external library is present. If you want your application to run on the AVD you +are creating, check the application's <code>uses-library</code> element and +select a system image target that includes that library. + +</ul> + +<h3 id="createavd">Creating the AVD</h3> + +<p>When you've selected the target you want to use and made a note of its ID, +use the <code>android create avd</code> command to create the AVD, supplying the +target ID as the <code>-t</code> argument. Here's an example that creates an +AVD with name "my_android1.5" and target ID "2" (the standard Android 1.5 +system image in the list above): </p> + +<pre>android create avd -n my_android1.5 -t 2</pre> + +<p>If the target you selected was a standard Android system image ("Type: +platform"), the android tool next asks you whether you want to create a custom +hardware profile. </p> + +<pre>Android 1.5 is a basic Android platform. +Do you wish to create a custom hardware profile [no]</pre> + +<p>If you want to set custom hardware emulation options for the AVD, enter +"yes" and set values as needed. If you want to use the default hardware +emulation options for the AVD, just press the return key (the default is "no"). +The android tool creates the AVD with name and system image mapping you +requested, with the options you specified. + +<p class="note">If you are creating an AVD whose target is an SDK add-on, +the android tool does not allow you to set hardware emulation options. It +assumes that the provider of the add-on has set emulation options appropriately +for the device that the add-on is modeling, and so prevents you from resetting +the options. </p> + +<p>For a list of options you can use in the <code>android create avd</code> +command, see the table in <a href="#options">Command-line options for AVDs</a>, +at the bottom of +this page. </p> + +<h3 id="hardwareopts">Setting hardware emulation options</h3> + +<p>When are creating a new AVD that uses a standard Android system image ("Type: +platform"), the android tool lets you set hardware emulation options for virtual +device. The table below lists the options available and the default values, as +well as the names of properties that store the emulated hardware options in the AVD's +configuration file (the config.ini file in the AVD's local directory). </p> + + +<table> +<tr> +<th>Characteristic</th> +<th>Description</th> +<th>Property</th> +</tr> + +<tr> +<td>Device ram size</td> +<td>The amount of physical RAM on the device, in megabytes. Default value is "96". +<td>hw.ramSize</td> +</tr> + +<tr> +<td>Touch-screen support</td> +<td>Whether there is a touch screen or not on the device. Default value is "yes".</td> +<td>hw.touchScreen + + +<tr> +<td>Trackball support </td> +<td>Whether there is a trackball on the device. Default value is "yes".</td> +<td>hw.trackBall</td> +</tr> + +<tr> +<td>Keyboard support</td> +<td>Whether the device has a QWERTY keyboard. Default value is "yes".</td> +<td>hw.keyboard</td> +</tr> + +<tr> +<td>DPad support</td> +<td>Whether the device has DPad keys. Default value is "yes".</td> +<td>hw.dPad</td> +</tr> + +<tr> +<td>GSM modem support</td> +<td>Whether there is a GSM modem in the device. Default value is "yes".</td> +<td>hw.gsmModem</td> +</tr> + +<tr> +<td>Camera support</td> +<td>Whether the device has a camera. Default value is "no".</td> +<td>hw.camera</td> +</tr> + +<tr> +<td>Maximum horizontal camera pixels</td> +<td>Default value is "640".</td> +<td>hw.camera.maxHorizontalPixels</td> +</tr> + +<tr> +<td>Maximum vertical camera pixels</td> +<td>Default value is "480".</td> +<td>hw.camera.maxVerticalPixels</td> +</tr> + +<tr> +<td>GPS support</td> +<td>Whether there is a GPS in the device. Default value is "yes".</td> +<td>hw.gps</td> +</tr> + +<tr> +<td>Battery support</td> +<td>Whether the device can run on a battery. Default value is "yes".</td> +<td>hw.battery</td> +</tr> + +<tr> +<td>Accelerometer</td> +<td>Whether there is an accelerometer in the device. Default value is "yes".</td> +<td>hw.accelerometer</td> +</tr> + +<tr> +<td>Audio recording support</td> +<td>Whether the device can record audio. Default value is "yes".</td> +<td>hw.audioInput</td> +</tr> + +<tr> +<td>Audio playback support</td> +<td>Whether the device can play audio. Default value is "yes".</td> +<td>hw.audioOutput</td> +</tr> + +<tr> +<td>SD Card support</td> +<td>Whether the device supports insertion/removal of virtual SD Cards. Default value is "yes".</td> +<td>hw.sdCard</td> +</tr> + +<tr> +<td>Cache partition support</td> +<td>Whether we use a /cache partition on the device. Default value is "yes".</td> +<td>disk.cachePartition</td> +</tr> + +<tr> +<td>Cache partition size</td> +<td>Default value is "66MB".</td> +<td>disk.cachePartition.size </td> +</tr> +</table> + +<h3 id="location">Default location of the AVD files</h3> + +<p>When you create an AVD, the android tool creates a dedicated directory for it +on your development computer. The directory contains the AVD configuration file, +the user data image and SD card image (if available), and any other files +associated with the device. Note that the directory does not contain a system +image — instead, the AVD configuration file contains a mapping to the +system image, which it loads when the AVD is launched. </p> + +<p>The android tool also creates a <AVD name>.ini file for the AVD at the +root of the .android/avd directory on your computer. The file specifies the +location of the AVD directory and always remains at the root the .android +directory.</p> + +<p>By default, the android tool creates the AVD directory inside +<code>~/.android/avd/</code> (on Linux/Mac), <code>C:\Documents and +Settings\<user>\.android\</code> on Windows XP, and +<code>C:\Users\<user>\.android\</code> on Windows Vista. +If you want to use a custom location for the AVD directory, you +can do so by using the <code>-p <path></code> option when +you create the AVD: </p> + +<pre>android create avd -n my_android1.5 -t 2 -p path/to/my/avd</pre> + +<p>If the .android directory is hosted on a network drive, we recommend using +the <code>-p</code> option to place the AVD directory in another location. +The AVD's .ini file remains in the .android directory on the network +drive, regardless of the location of the AVD directory. </p> + +<h2 id="managing">Managing AVDs</h2> + +<p>The sections below provide more information about how to manage AVDs once you've created them. </p> + +<h3 id="moving">Moving an AVD</h3> + +<p>If you want to move or rename an AVD, you can do so using this command:</p> + +<pre>android move avd -n <name> [-<option> <value>] ...</pre> + +<p>The options for this command are listed in <a href="#options">Command-line +options for AVDs</a> at the bottom of this page. </p> + +<h3 id="updating">Updating an AVD</h3> + +<p>If, for any reason, the platform/add-on root folder has its name changed (maybe because the user has installed an update of the platform/add-on) then the AVD will not be able to load the system image that it is mapped to. In this case, the <code>android list targets</code> command will produce this output: + +<pre>The following Android Virtual Devices could not be loaded: +Name: foo +Path: <path>/.android/avd/foo.avd +Error: Invalid value in image.sysdir. Run 'android update avd -n foo' </pre> + +<p>To fix this error, use the <code>android update avd</code> command to recompute the path to the system images.</p> + +<h3 id="deleting">Deleting an AVD</h3> + +<p>You can use the android tool to delete an AVD. Here is the command usage:</p> + +<pre>android delete avd -n <name> </pre> + +<p>When you issue the command, the android tool looks for an AVD matching the +specified name deletes the AVD's directory and files. </p> + + +<h2 id="options">Command-line options for AVDs</h2> + +<p>The table below lists the command-line options you can use with the +android tool. </p> + + +<table> +<tr> + <th width="15%">Action</th> + <th width="20%">Option</th> + <th width="30%">Description</th> + <th>Comments</th> +</tr> + + +<tr> + <td><code>list avds</code></td> + <td> </td> + <td>List all known AVDs, with name, path, target, and skin. </td> + <td> </td> +</tr> +<tr> + <td rowspan="6"><code>create avd</code></td> + <td><code>-n <name> or <br></code></td> + <td>The name for the AVD.</td> + <td>Required</td> +</tr> +<tr> + <td><code>-t <targetID></code></td> + <td>Target ID of the system image to use with the new AVD.</td> + <td>Required. To obtain a list of available targets, use <code>android list + targets</code>.</td> +</tr> +<tr> + <td><code>-c <path></code> or <br> + <code>-c <size>[K|M]</code></td> + <td>The path to the SD card image to use with this AVD or the size of a new SD + card image to create for this AVD.</td> + <td>Examples: <code>-c path/to/sdcard</code> or <code>-c 1000M</code></td> +</tr> +<tr> + <td><code>-f</code></td> + <td>Force creation of the AVD</td> + <td>By default, if the name of the AVD being created matches that of an + existing AVD, the android tool will not create the new AVD or overwrite + the existing AVD. If you specify the <code>-f</code> option, however, the + android tool will automatically overwrite any existing AVD that has the + same name as the new AVD. The files and data of the existing AVD are + deleted. </td> +</tr> + +<tr> + <td><code>-p <path></code></td> + <td>Path to the location at which to create the directory for this AVD's +files.</td> + <td> </td> +</tr> +<tr> + <td><code>-s <name></code> or <br> + <code>-s <width>-<height></code> </td> + <td>The skin to use for this AVD, identified by name or dimensions.</td> + <td>The android tool scans for a matching skin by name or dimension in the +<code>skins/</code> directory of the target referenced in the <code>-t +<targetID></code> argument. Example: <code>-s HVGA-L</code></td> +</tr> +<tr> + <td><code>delete avd</code></td> + <td><code>-n <name></code></td> + <td>Delete the specified AVD.</td> + <td>Required</td> +</tr> +<tr> + <td rowspan="3"><code>move avd</code></td> + <td><code>-n <name></code></td> + <td>The name of the AVD to move.</td> + <td>Required</td> +</tr> +<tr> + <td><code>-p <path></code></td> + <td>The path to the new location for the AVD.</td> + <td> </td> +</tr> +<tr> + <td><code>-r <new-name></code></td> + <td>Rename the AVD.</td> + <td> </td> +</tr> +<tr> + <td><code>update avds</code></td> + <td> </td> + <td>Recompute the paths to all system images.</td> + <td> </td> +</tr> + + + +</table> + diff --git a/docs/html/guide/developing/tools/emulator.jd b/docs/html/guide/developing/tools/emulator.jd index 769491b..82d3c8d 100644 --- a/docs/html/guide/developing/tools/emulator.jd +++ b/docs/html/guide/developing/tools/emulator.jd @@ -14,30 +14,31 @@ using your mouse or keyboard to generate events for your application. It also provides a screen in which your application is displayed, together with any other Android applications running. </p> -<p>To help you model and test your application, the emulator lets your application -use the services of the Android platform to invoke other applications, access the -network, play audio and video, store and retrieve data, notify the user, and render -graphical transitions and themes. </p> +<p>To let you model and test your application more easily, the emulator supports +Android Virtual Device (AVD) configurations. AVDs let you specify the Android +platform that you want to run on the emulator, as well as the hardware options +and emulator skin files tht you want to use. Once your application is running on +the emulator, it can use the services of the Android platform to invoke other +applications, access the network, play audio and video, store and retrieve data, +notify the user, and render graphical transitions and themes. </p> <p>The emulator also includes a variety of debug capabilities, such as a console from which you can log kernel output, simulate application interrupts (such as arriving SMS messages or phone calls), and simulate latency effects and dropouts on the data channel.</p> - - - <div class="inline-toc" style="whitespace:nowrap;"> <h4>In this document:</h4> <div class="g-unit g-first" style="whitespace:nowrap;width:35%;"> <ol class="toc"> <li><a href="#overview">Overview</a></li> <li><a href="#starting">Starting and Stopping the Emulator</a></li> +<li><a href="#starting">Android Virtual Devices and the Emulator</a></li> <li><a href="#controlling">Controlling the Emulator</a></li> <li><a href="#startup-options">Emulator Startup Options</a></li> <li><a href="#diskimages">Working with Emulator Disk Images</a> <ol class="toc"> - <li><a href="#systemimages">System Images</a></li> + <li><a href="#defaultimages">Default Images</a></li> <li><a href="#runtimeimages">Runtime Images: User Data and SD Card</a></li> <li><a href="#temporaryimages">Temporary Images</a></li> </ol></li> @@ -76,7 +77,8 @@ on the data channel.</p> <li><a href="#apps">Installing Applications on the Emulator</a></li> <li><a href="#sdcard">SD Card Emulation</a> <ol class="toc"> - <li><a href="#creating">Creating a Disk Image</a></li> + <li><a href="#creatinga">Creating an SD card image using the android tool</li> + <li><a href="#creatingm">Creating an SD card image using mksdcard</a></li> <li><a href="#copying">Copying Files to a Disk Image</a></li> <li><a href="#loading">Loading the Disk Image at Emulator Startup</a></li> </ol></li> @@ -92,12 +94,14 @@ on the data channel.</p> <h2>Overview</h2> <p>The Android emulator is a QEMU-based application that provides a virtual ARM -mobile device on which you can run your Android applications. It provides a full -Android system stack, down to the kernel level, and includes a set of +mobile device on which you can run your Android applications. It runs a full +Android system stack, down to the kernel level, that includes a set of preinstalled applications (such as the dialer) that you can access from your -applications. It provides a skinnable mobile device UI, customizable key -mappings, and a variety of commands and options for controlling the behaviors of -the emulated environment. </p> +applications. You can choose what version of the Android system you want to +run in the emulator by configuring AVDs, and you can also customize the +mobile device skin and key mappings. When launching the emulator and at runtime, +you can use a variety of commands and options to control the its behaviors. +</p> <p>The Android system image distributed in the SDK contains ARM machine code for the Android Linux kernel, the native libraries, the Dalvik VM, and the various @@ -132,9 +136,9 @@ it for developing Android applications.</p> <p>During development and testing of your application, you install and run your application in the Android emulator. You can launch the emulator as a standalone application, from a command line, or you can use it as part of your Eclipse -development environment. In either case, you can specify the startup options -described in this document to control the emulator. - </p> +development environment. In either case, you specify the AVD configuration to +load and any startup options you want to use, as described in this document. +</p> <p>You can run your application on a single instance of the emulator or, depending on your needs, you can start multiple emulator instances and run your @@ -146,9 +150,14 @@ Emulation</a>, <a href="#sms">SMS Emulation</a>, and <a href="#emulatornetworking">Emulator Networking</a></p> <p>To start an instance of the emulator from the command line, change to the -<code>tools/</code> folder of the SDK and enter <code>emulator</code> or -<code>./emulator</code>. This initializes the Android system and you will see -the emulator window appear on your screen. </p> +<code>tools/</code> folder of the SDK. Enter <code>emulator</code> command +like this: </p> + +<pre>emulator -avd <avd_name></pre> + +<p>This initializes the emulator and loads an AVD configuration (see the next +section for more information about AVDs). You will see the emulator window +appear on your screen. </p> <p>If you are working in Eclipse, the ADT plugin for Eclipse installs your application and starts the emulator automatically, when you run or debug @@ -163,6 +172,27 @@ on the Emulator</a> for information about how to install your application.</p> <a name="controlling"></a> +<a name="avds"></a> + +<h2>Android Virtual Devices and the Emulator</h2> + +<p>To use the emulator, you first must create one or more AVD configurations. In each +configuration, you specify an Android platform to run in the emulator and the set of hardware +options and emulator skin you want to use. Then, when you launch the emulator, you specify +the AVD configuration that you want to load. </p> + +<p>To specify the AVD you want to load when starting the emulator, you use the +<code>-avd</code> argument, as shown in the previous section. </p> + +<p>Each AVD functions as an independent device, with its own private storage for +user data, SD card, and so on. When you launch the emulator with an AVD configuration, +it automatically loads the user data and SD card data from the AVD directory. By default, +the emulator stores the user data, SD card data, and cache in the AVD directory.</p> + +<p>To create and manage AVDs you use the android tool, a command-line utility +included in the SDK. For complete information about how to set up AVDs, see <a +href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>.</p> + <h2>Controlling the Emulator</h2> <p>You can use emulator <a href="#startup-options">startup options</a> and <a @@ -279,7 +309,7 @@ the keys of your keyboard. </p> when launching the emulator, to control its appearance or behavior. Here's the command-line usage for launching the emulator with options: </p> -<pre>emulator [-<option> [<value>]] ... [-<qemu args>]</pre> +<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre> <p>The table below summarizes the available options.</p> @@ -292,7 +322,7 @@ Here's the command-line usage for launching the emulator with options: </p> </tr> <tr> - <td rowspan="8">Help</td> + <td rowspan="9">Help</td> <td><code>-help</code></td> <td>Print a list of all emulator options.</td> <td> </td> @@ -331,9 +361,22 @@ Here's the command-line usage for launching the emulator with options: </p> <td>Print help for defining a custom key mappings file.</td> <td> </td> </tr> - <tr> - <td rowspan="10">Disk Images</td> + <td><code>-help-virtual-device</code></td> + <td>Print help for Android Virtual Device usage.</td> + <td> </td> +</tr> +<tr> + <td>AVD</td> + <td><code>-avd <avd_name></code> or <br> + <code>@<avd_name></code></td> + <td><strong>Required</strong>. Specifies the AVD to load for this emulator + instance.</td> + <td>You must create an AVD configuration before launching the emulator. For + information, see <a href="{@docRoot}guide/developing/tools/avd.html">Android + Virtual Devices</a>.</td> +<tr> + <td rowspan="7">Disk Images</td> <td><code>-cache <filepath></code></td> <td>Use <filepath> as the working cache partition image. </td> <td>Optionally, you can specify a path relative to the current working directory. @@ -345,13 +388,7 @@ Here's the command-line usage for launching the emulator with options: </p> <td>Use <filepath> as the working user-data disk image. </td> <td>Optionally, you can specify a path relative to the current working directory. If <code>-data</code> is not used, the emulator looks for a file named "userdata-qemu.img" - in the directory specified in <datadir>. ~/.android/SDK-1.0 (on Linux/Mac) or - C:\Documents and Settings\<user>\Local Settings\Application Data\Android\SDK-1.0 (on Windows). - <p> If you use <code>-data <filepath></code> but the file does not exist, the emulator creates - a file at that location using the specified name. </p> - <p>See <a href="#multipleinstances">Running Multiple Emulator Instances</a> for information about how - to use <code>-data</code> to let multiple emulator instances preserve their user data across sessions.</p> - <p>For more information on disk images, use <code>-help-disk-images</code>.</p> + in the storage area of the AVD being used (see <code>-avd</code>). </td></tr> <!-- <tr> @@ -359,28 +396,32 @@ Here's the command-line usage for launching the emulator with options: </p> <td>Search for the user-data disk image specified in <code>-data</code> in <dir></td> <td><code><dir></code> is a path relative to the current working directory. -<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image in the - directory ~/.android/SDK-1.0 (on Linux/Mac) or C:\Documents and Settings\<user>\Local Settings\Application - Data\Android\SDK-1.0 (on Windows). </p><p>For more information on disk images, use <code>-help-disk-images</code>.</p> +<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image +in the storage area of the AVD being used (see <code>-avd</code>)</p><p>For more information +on disk images, use <code>-help-disk-images</code>.</p> </td></tr> --> +<!-- <tr> <td><code>-image <filepath></code></td> <td>Use <filepath> as the system image.</td> <td>Optionally, you can specify a path relative to the current working directory. Default is <system>/system.img.</td> </tr> +--> <tr> <td><code>-initdata <filepath></code></td> <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td> <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>. <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td> </tr> +<!-- <tr> <td><code>-kernel <filepath></code></td> <td>Use <filepath> as the emulated kernel.</td> <td>Optionally, you can specify a path relative to the current working directory. </td> </tr> +--> <tr> <td><code>-nocache</code></td> <td>Start the emulator without a cache partition.</td> @@ -400,12 +441,14 @@ Here's the command-line usage for launching the emulator with options: </p> <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p> </td> </tr> +<!-- <tr> <td><code>-system <dirpath></code></td> <td>Search for system, ramdisk and user data images in <dir>.</td> <td><code><dir></code> is a directory path relative to the current working directory.</td> </tr> +--> <tr> <td><code>-wipe-data</code></td> <td>Reset the current user-data disk image (that is, the file specified by <code>-datadir</code> and @@ -448,8 +491,8 @@ Here's the command-line usage for launching the emulator with options: </p> <td><code>-shell-serial <device></code></td> <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character device to use for communication with the shell.</td> - <td><device> must be a QEMU device type. See the documentation for 'serial -dev' at - <a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a> + <td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at + <a href="http://www.nongnu.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a> for a list of device types.</p> <p>Here are some examples: </p> @@ -679,7 +722,8 @@ scale in direct relationship with <delay> values.</p> <tr> <td><code>-skin <skinID></code></td> <td>Start the emulator with the specified skin. </td> - <td>The SDK includes a <a href="#skins">choice of four skins</a>:<br /> + <td>The standard Android platforms includes a <a href="#skins">choice of + four skins</a>:<br /> <li>HVGA-L (480x320, landscape)</li> <li>HVGA-P (320x480, portrait) (default) </li> <li>QVGA-L (320x240, landscape)</li> @@ -702,10 +746,16 @@ disk image containing an emulator-specific kernel, the Android system, a ramdisk image, and writeable images for user data and simulated SD card.</p> <p>To run properly, the emulator requires access to a specific set of disk image -files. The Android SDK includes default versions of the required images, stored -in predetermined locations in the SDK directory structure. At startup, the -emulator looks for and reads the image files, using their default names and -storage locations. </p> +files. By default, the Emulator always looks for the disk images in the +private storage area of the AVD in use. If no images exist there when +the Emulator is launched, it creates the images in the AVD directory based on +default versions stored in the SDK. </p> + +<p class="note"><strong>Note:</strong> The default storage location for +AVDs is in <code>~/.android/avd</code> on OS X and Linux, <code>C:\Documents and +Settings\<user>\.android\</code> on Windows XP, and +<code>C:\Users\<user>\.android\</code> +on Windows Vista.</p> <p>To let you use alternate or custom versions of the image files, the emulator provides startup options that override the default locations and filenames of @@ -713,32 +763,26 @@ the image files. When you use the options, the emulator searches for the image file under the image name or location that you specify; if it can not locate the image, it reverts to using the default names and location.</p> -<p>The emulator uses three types of image files: system image files, runtime +<p>The emulator uses three types of image files: default image files, runtime image files, and temporary image files. The sections below describe how to override the location/name of each type of file. </p> -<a name="systemimages"></a> -<h3>System Images</h3> +<a name="defaultimages"></a> +<h3>Default Images</h3> -<p>System images contain system data and default settings without which the -emulator can not run. The image files are read-only — the emulator reads -the images at startup and does not modify them during the session.</p> - -<p>All of the system image files are stored in a single directory. By default, -the system images are stored in the <code>lib/images</code>' under the -emulator's program location. </p> +<p>When the emulator launches but does not find an existing user data image in +the active AVD's storage area, it creates a new one from a default version +included in the SDK. The default user data image is read-only. The image +files are read-only.</p> <p>The emulator provides the <code>-system <dir></code> startup option to -let you override the location under which the emulator looks for the system -images files. </p> +let you override the location under which the emulator looks for the default +user data image. </p> -<p>The emulator also provides startup options that let you override the names of -the system images, as described in the table below. When you use one of the -options, the emulator looks in the default directory, or in a custom location -(if you specified <code>-system <dir></code>). Note that, if you provide -alternate system image file, it must contain the same type of data as the -default. For example, your override of the system.img file must point to a disk -image containing an Android system. </p> +<p>The emulator also provides a startup option that lets you override the name +of the default user data image, as described in the table below. When you use the +option, the emulator looks in the default directory, or in a custom location +(if you specified <code>-system <dir></code>). </p> <table> @@ -748,6 +792,7 @@ image containing an Android system. </p> <th width="40%" >Comments</th> </tr> +<!-- <tr> <td><code>kernel-qemu.img</code></td> <td>The emulator-specific Linux kernel image</td> @@ -765,7 +810,7 @@ image containing an Android system. </p> <td>The <em>initial</em> Android system image.</td> <td>Override using <code>-image <file></code></td> </tr> - +--> <tr> <td><code>userdata.img</code></td> <td>The <em>initial</em> user-data disk image</td> @@ -784,13 +829,7 @@ partition and removable storage media on actual device. </p> <p>The emulator provides a default user-data disk image. At startup, the emulator creates the default image as a copy of the system user-data image (user-data.img), -described above. The emulator stores the default image in this location on -on your development machine: </p> - -<ul> - <li>Linux and OS X: <code>~/.android/SDK-1.0</code></li> - <li>Windows: <code>C:\Documents and Settings\<user>\Local Settings\Application Data\Android\SDK-1.0</code></li> -</ul> +described above. The emulator stores the new image with the files of the active AVD.</p> <!-- <p>The emulator provides a startup option, <code>-datadir <dir></code>, @@ -801,7 +840,7 @@ image files. </p> <p>The emulator provides startup options to let you override the actual names and storage locations of the runtime images to load, as described in the table below. When you use one of these options, the emulator looks for the specified file(s) in the current working directory, -in the default directory, or in a custom location (if you specified a path with the filename. </p> +in the AVD directory, or in a custom location (if you specified a path with the filename). </p> <table> <tr> @@ -837,12 +876,12 @@ installed application data, settings, databases, and files. </p> <p>At startup, the emulator attempts to load a user-data image stored during a previous session. It looks for the file in the current working directory, -at the default location, as described above, and at the custom location/name +in the AVD directory as described above, and at the custom location/name that you specified at startup. </p> <ul> -<li>If it finds a user-data image, it mounts the image and makes it available to the system -for reading/writing of user data. </li> +<li>If it finds a user-data image, it mounts the image and makes it available +to the system for reading/writing of user data. </li> <li>If it does not find one, it creates an image by copying the system user-data image (userdata.img), described above. At device power-off, the system persists the user data to the image, so that it will be available in the next session. @@ -850,13 +889,9 @@ Note that the emulator stores the new disk image at the location/name that you specify in <code>-data</code> startup option.</li> </ul> -<p>If you are planning to run multiple emulator instances concurrently, note -that only the first emulator instance can persist user-data, if no explicit -user-data image file is specified in the startup command. When running multiple -emulator instances, you must specify a name for the image file to use (or -create), by using the <code>-data <name></code> option with a unique -<code><name></code> value. For more information, see -<a href="#multipleinstances">Running Multiple Emulator Instances</a>.</p> +<p class="note"><strong>Note:</strong> Because of the AVD configurations used in the emulator, +each emulator instance now gets its own dedicated storage. There is no need +to use the <code>-d</code> option to specify an instance-specific storage area.</p> <h4>SD Card</h4> @@ -864,6 +899,10 @@ create), by using the <code>-data <name></code> option with a unique to simulate removeable storage in an actual device. For information about how to create an emulated SD card and load it in the emulator, see <a href="#sdcard">SD Card Emulation</a></p> +<p>You can also use the android tool to automatically create an SD Card image +for you, when creating an AVD. For more information, see <a +href="{@docRoot}guide/developing/tools/avd.html#options">Command-line options for AVDs</a>. + <a name="temporaryimages"></a> <h3>Temporary Images</h3> @@ -1637,21 +1676,11 @@ kilobits/sec):</p> <h2>Running Multiple Emulator Instances</h2> -<p>You can run multiple instances of the emulator concurrently, if necessary. Each emulator instance can use a separate user-data image file and a different console port. This lets you manage each instance in isolation. </p> - -<p>However, if you will run multiple emulator instances, note that there are limitations on the capability of each instance to maintain its persistent user data — user settings and installed applications — across sessions. Specifically:</p> - -<ul> - <li>By default, only the first-launched emulator instance can preserve user data across sessions. When a session closes, - the emulator stores the user data to a user-data image file — by default, it stores the data in the file - <code>~/.android/SDK-1.0/userdata-qemu.img </code>(on Linux and Mac) or <code>C:\Documents and Settings\<user>\Local - Settings\Application Data\Android\SDK-1.0\userdata-qemu.img</code> (on Windows) in your development computer.</li> - -<li>Emulator instances that you start after the first instance (that are running concurrently) can also store user data during a session, but they <em>do not</em> preserve it for the next session, unless you have specified a unique user-data image file in which the data should be stored. </li> - -</ul> - -<p>To run multiple emulator instances and let each maintain user data across sessions, start the instances with the <code>-data</code> option (see <a href="#startup-options">Startup Options</a>) and supply the path to a user-data file. </p> +<p>Through the AVDs configurations used by the emulator, you can run multiple +instances of the emulator concurrently, each with its own AVD configuration and +storage area for user data, SD card, and so on. You no longer need to use the +<code>-d</code> option when launching the emulator, to point to an +instance-specific storage area. </p> <a name="apps"></a> @@ -1675,19 +1704,43 @@ For more information about the user-data partition and other emulator storage, see <a href="#diskimages">Working with Emulator Disk Images</a>.</p> <a name="sdcard"></a> +<a name="creating"></a> <h2>SD Card Emulation</h2> -<p>You can create a disk image and then load it to the emulator at startup, to simulate the presence of a user's SD card in the device. The sections below describe how to create the disk image, how to copy files to it, and how to load it in the emulator at startup. </p> -<p>Note that you can only load disk image at emulator startup. Similarly, you can not remove a simulated SD card from a running emulator. However, you can browse, send files to, and copy/remove files from a simulated SD card either with adb or the emulator. </p> +<p>You can create a disk image and then load it to the emulator at startup, to +simulate the presence of a user's SD card in the device. To do this, you can use +the android tool to create a new SD card image with a new AVD, or you can use +the mksdcard utility included in the SDK. </p> -<p>The emulator supports emulated SDHC cards, so you can create an SD card image of any size up to 128 gigabytes.</p> +<p>The sections below describe how to create an SD card disk image, how to copy +files to it, and how to load it in the emulator at startup. </p> -<a name="creating"></a> +<p>Note that you can only load disk image at emulator startup. Similarly, you +can not remove a simulated SD card from a running emulator. However, you can +browse, send files to, and copy/remove files from a simulated SD card either +with adb or the emulator. </p> + +<p>The emulator supports emulated SDHC cards, so you can create an SD card image +of any size up to 128 gigabytes.</p> + +<h3 id="creatinga">Creating an SD card image using the android tool</h3> -<h3>Creating a Disk Image</h3> +<p>The easiest way to create a new SD card is to use the android tool. When +creating an AVD, you simply specify the <code>-c</code> option, like this: </p> -<p>You can use the mksdcard tool, included in the SDK, to create a FAT32 disk image that you can load in the emulator at startup. You can access mksdcard in the tools/ directory of the SDK and create a disk image like this: </p> +<pre>android create avd -n <avd_name> -t <targetID> -c <size>[K|M]</pre> + +<p>You can also use the <code>-c</code> option to specify a path to an SD card +image to use in the new AVD. For more information, see <a +href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. +</p> + +<h3 id="creatingm">Creating an SD card image using mksdcard</h3> + +<p>You can use the mksdcard tool, included in the SDK, to create a FAT32 disk +image that you can load in the emulator at startup. You can access mksdcard in +the tools/ directory of the SDK and create a disk image like this: </p> <pre>mksdcard <size> <file></pre> @@ -1700,13 +1753,23 @@ see <a href="#diskimages">Working with Emulator Disk Images</a>.</p> <a name="copying"></a> <h3>Copying Files to a Disk Image</h3> -<p>Once you have created the disk image, you can copy files to it prior to loading it in the emulator. To copy files, you can mount the image as a loop device and then copy the files to it, or you can use a utility such as mtools to copy the files directly to the image. The mtools package is available for Linux, Mac, and Windows.</p> +<p>Once you have created the disk image, you can copy files to it prior to +loading it in the emulator. To copy files, you can mount the image as a loop +device and then copy the files to it, or you can use a utility such as mtools to +copy the files directly to the image. The mtools package is available for Linux, +Mac, and Windows.</p> <a name="loading"></a> <a name="step3" id="step3"></a> <h3>Loading the Disk Image at Emulator Startup</h3> -<p>To load FAT32 disk image in the emulator, start the emulator with the <code>-sdcard</code> flag and specify the name and path of your image (relative to the current working directory): </p> + +<p>By default, the emulator loads the SD card image that is stored with the active +AVD (see the <code>-avd</code> startup option).</p> + +<p>Alternatively, you ca start the emulator with the +<code>-sdcard</code> flag and specify the name and path of your image (relative +to the current working directory): </p> <pre>emulator -sdcard <filepath></pre> diff --git a/docs/html/guide/developing/tools/index.jd b/docs/html/guide/developing/tools/index.jd index b491a4f..2c9e45d 100644 --- a/docs/html/guide/developing/tools/index.jd +++ b/docs/html/guide/developing/tools/index.jd @@ -8,23 +8,29 @@ applications on the Android platform. The most important of these are the Androi Emulator and the Android Development Tools plugin for Eclipse, but the SDK also includes a variety of other tools for debugging, packaging, and installing your applications on the emulator. </p> - -<dl> - <dt><a href="emulator.html">Android Emulator</a></dt> - <dd>A virtual mobile device that runs on your computer. You use the emulator to design, - debug, and test your applications in an actual Android run-time environment. </dd> + <dl> <dt><a href="adt.html">Android Development Tools Plugin</a> (for the Eclipse IDE)</dt> <dd>The ADT plugin adds powerful extensions to the Eclipse integrated environment, making creating and debugging your Android applications easier and faster. If you use Eclipse, the ADT plugin gives you an incredible boost in developing Android applications.</dd> + <dt><a href="emulator.html">Android Emulator</a></dt> + <dd>A QEMU-based device-emulation tool that you can use to design, + debug, and test your applications in an actual Android run-time environment. </dd> - <dt><a href="hierarchy-viewer.html">Hierarchy Viewer</a></dt> - <dd>The Hierarchy Viewer tool allows you to debug and optimize your user interface. - It provides a visual representation of your layout's hierarchy of Views and a magnified inspector - of the current display with a pixel grid, so you can get your layout just right. - </dd> + <dt><a href="avd.html">Android Virtual Devices (AVDs)</a></dt> + <dd>Virtual device configurations that you create, to model device + characteristics in the Android Emulator. In each configuration, you can + specify the Android platform to run, the hardware options, and the + emulator skin to use. Each AVD functions as an independent device with + it's own storage for user data, SD card, and so on. </dd> + + <dt><a href="hierarchy-viewer.html">Hierarchy Viewer</a></dt> + <dd>The Hierarchy Viewer tool allows you to debug and optimize your user interface. + It provides a visual representation of your layout's hierarchy of Views and a magnified inspector + of the current display with a pixel grid, so you can get your layout just right. + </dd> <dt><a href="draw9patch.html">Draw 9-patch</a></dt> <dd>The Draw 9-patch tool allows you to easily create a @@ -79,10 +85,9 @@ applications on the emulator. </p> level events. You can use the Monkey to stress-test applications that you are developing, in a random yet repeatable manner.</dd> - <dt><a href="othertools.html#activitycreator">activitycreator</a></dt> - <dd>A script that generates <a + <dt><a href="othertools.html#android">android</a></dt> + <dd>A script that lets you manage AVDs and generate <a href="http://ant.apache.org/" title="Ant">Ant</a> build files that - you can use to compile your Android applications. If you are developing - on Eclipse with the ADT plugin, you won't need to use this script. </dd> + you can use to compile your Android applications. </dd> </dl> diff --git a/docs/html/guide/developing/tools/othertools.jd b/docs/html/guide/developing/tools/othertools.jd index eaa0b76..603609e 100644 --- a/docs/html/guide/developing/tools/othertools.jd +++ b/docs/html/guide/developing/tools/othertools.jd @@ -3,16 +3,32 @@ page.title=Other Tools <p>The sections below describe other tools that you can use when building Android applications. </p> -<p>All of the tools are included in the Android SDK and are accessible from the <code>tools/</code> directory.</p> +<p>All of the tools are included in the Android SDK and are accessible from the <code><sdk>/tools/</code> directory.</p> <h2>Contents</h2> <dl> + <dt><a href="#android">android</a></dd> <dt><a href="#mksdcard">mksdcard</a></dt> <dt><a href="#dx">dx</a></dt> - <dt><a href="#activitycreator">activitycreator</a></dd> </dl> +<a name="activitycreator"></a> +<h2 id="android">android</h2> + +<p>The android tool is a script that lets you create and manage Android Virtual Devices (AVDs) and, if you are developing using Ant, generate template Android projects to help you get started quickly. </p> + +<p>For information about how to use the android tool to manage AVDs, see <a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a>. </p> + +<p>For information about how to use the android tool to create or update a project, see <a href="{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>. </p> + +<p>Note that if you are developing in Eclipse with the ADT plugin, you will use the android tool to manage the AVDs you create, but you will not use the android tool for creating a project. The ADT plugin provides a New Project Wizard that helps you set up an Android project in Eclipse. </p> + +<p>If you are developing in Ant, you will use the android tool to manage your AVDs, and you can also use it to create or update a project. </p> + +<p class="note">Note: The android tool replaces the activitycreator tool provided in previous SDK releases.</p> + + <a name="mksdcard"></a> <h2>mksdcard</h2> @@ -21,7 +37,7 @@ page.title=Other Tools <pre>mksdcard [-l label] <size>[K|M] <file></pre> -</p>The table below lists the available options/arguments</p> +<p>The table below lists the available options/arguments</p> <table> <tr> @@ -57,48 +73,6 @@ You can also specify size in kilobytes or megabytes, by appending a "K" or "M" t <p>The dx tool lets you generate Android bytecode from .class files. The tool converts target files and/or directories to Dalvik executable format (.dex) files, so that they can run in the Android environment. It can also dump the class files in a human-readable format and run a target unit test. You can get the usage and options for this tool by using <code>dx --help</code>.</p> -<a name="activitycreator"></a> - -<h2>activitycreator</h2> - -<p>If you aren't using the Eclipse IDE and ADT plugin, you can use the the activitycreator script to get started with a new application. When you run the script, it creates the structure of a minimal Android application that you can build on and extend to meet your needs. </p> - -<p>For Linux and Mac, the SDK provides <code>activitycreator</code>, a shell script, and for Windows <code>activitycreator.bat</code>, a batch script that runs an executable. Regardless of platform, the usage for the script is the same:</p> - -<pre>activitycreator [--out <folder>] [--ide intellij] your.package.name.ActivityName</pre> - -<table> -<tr> - <th>Option</th> - <th>Description</th> -</tr> - -<tr> - <td><code>--out <folder></code></td> - <td>Specifies where to create the files/folders. </td> -</tr> - -<tr> - <td><code>--ide intellij</code></td> - <td>Creates project files for IntelliJ</td> -</tr> - -</table> - - -<p>When run, the script creates these files: </p> - - <ul> - <li>AndroidManifest.xml -- The application manifest file.</li> - <li>build.xml -- An Ant script to build/package the application.</li> - <li>res -- The resource directory.</li> - <li>src -- The source directory.</li> - <li>src/your/package/name/ActivityName.java -- The Activity class. </li> - <li>bin -- The output folder for the compiled .apk (when built by Ant).</li> -</ul> - -<p>When you are ready, you can use Ant to <a href="{@docRoot}guide/developing/other-ide.html#antbuild">build the project</a> so that you can run it on the emulator.</p> -<p>If you are using Eclipse with the ADT plugin, you do not need to use activitycreator. You can use the New Project Wizard, provided by the ADT plugin, instead. </p> diff --git a/docs/html/guide/developing/tools/traceview.jd b/docs/html/guide/developing/tools/traceview.jd index dd3f4bb..95ae823 100644 --- a/docs/html/guide/developing/tools/traceview.jd +++ b/docs/html/guide/developing/tools/traceview.jd @@ -1,23 +1,32 @@ page.title=Traceview: A Graphical Log Viewer @jd:body -<p>Traceview is a graphical viewer for execution logs -saved by your application. The sections below describe how to use the program. </p> +<div id="qv-wrapper"> +<div id="qv"> -<h2>Contents</h2> + <h2>In this document</h2> +<ol> + <li><a href="#creatingtracefiles">Creating Trace Files</a></li> + <li><a href="#copyingfiles">Copying Trace Files to a Host Machine</a></li> + <li><a href="#runningtraceview">Viewing Trace Files in Traceview</a> + <ol> + <li><a href="#timelinepanel">Timeline Panel</a></li> + <li><a href="#profilepanel">Profile Panel</a></li> + </ol></li> + <li><a href="#format">Traceview File Format</a> + <ol> + <li><a href="#datafileformat">Data File Format</a></li> + <li><a href="#keyfileformat">Key File Format</a></li> + </ol></li> + <li><a href="#knownissues">Traceview Known Issues</a></li> + <li><a href="#dmtracedump">Using dmtracedump</a></li> +</ol> +</div> +</div> -<dl> - <dt><a href="#creatingtracefiles">Creating Trace Files</a></dt> - <dt><a href="#copyingfiles">Copying Trace Files to a Host Machine</a></dt> - <dt><a href="#runningtraceview">Viewing Trace Files in Traceview</a></dt> - <dd><a href="#timelinepanel">Timeline Panel</a></dd> - <dd><a href="#profilepanel">Profile Panel</a></dd> - <dt><a href="#format">Traceview File Format</a></dd> - <dd><a href="#datafileformat">Data File Format</a><dd> - <dd><a href="#keyfileformat">Key File Format</a></dd> - <dt><a href="#knownissues">Traceview Known Issues</a></dd> - <dt><a href="#dmtracedump">Using dmtracedump</a></dt> -</dl> +<p>Traceview is a graphical viewer for execution logs +saved by your application. Traceview can help you debug your application and +profile its performance. The sections below describe how to use the program. </p> <a name="creatingtracefiles"></a> @@ -63,10 +72,10 @@ have made the code faster or slower. </p> <p>When using the Android emulator, you must create an SD card image upon which the trace files will be written. For example, from the <code>/tools</code> directory, you -can create an SD card image and mount it when launching the emulator like so:</p> +can create an SD card image named "imgcd" and mount it when launching the emulator like so:</p> <pre> -<b>$</b> mksdcard 1024M ./imgcd -<b>$</b> emulator -sdcard ./img +<b>$</b> mksdcard 1024M ./imgcd +<b>$</b> emulator -sdcard ./imgcd </pre> <p>For more information, read about the <a href="{@docRoot}guide/developing/tools/othertools.html#mksdcard">mksdcard tool</a>.</p> diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 77d3522..a044cea 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -19,11 +19,13 @@ <ul> <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/dialogs.html">Creating Dialogs</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/notifiers/index.html">Notifying the User</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/binding.html">Binding to Data with AdapterView</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/how-android-draws.html">How Android Draws Views</a></li> </ul> </li> @@ -37,7 +39,6 @@ <li><a href="<?cs var:toroot ?>guide/topics/intents/intents-filters.html">Intents and Intent Filters</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 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> --> @@ -61,6 +62,7 @@ <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-configuration-element.html"><uses-configuration></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> @@ -84,7 +86,7 @@ <li><a style="color:gray;">Accelerometer</a></li> </ul> </li> --> - <li><a href="<?cs var:toroot ?>guide/topics/location/index.html">Location</a></li> + <li><a href="<?cs var:toroot ?>guide/topics/location/index.html">Location and Maps</a></li> <!-- <li class="toggle-list"> <div><a style="color:gray;">Wireless Controls</a></div> <ul> @@ -93,6 +95,7 @@ </ul> </li> --> <!-- <li><a style="color:gray;">Localization</a></li> --> + <li><a href="<?cs var:toroot ?>guide/topics/appwidgets/index.html">App Widgets</a></li> </ul> </li> @@ -100,7 +103,6 @@ <ul> <!-- <li><a style="color:gray;">Developing for Android</a></li> signing, upgrading, selecting a package name, select device profile, touch, trackball, dpad available, etc. --> - <li><a href="<?cs var:toroot ?>guide/developing/eclipse-adt.html">In Eclipse, with ADT</a></li> <li><a href="<?cs var:toroot ?>guide/developing/other-ide.html">In Other IDEs</a></li> <li><a href="<?cs var:toroot ?>guide/developing/device.html">On a Device</a></li> @@ -110,9 +112,10 @@ <ul> <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/othertools.html#android">android</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/avd.html" >AVDs</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> <li><a href="<?cs var:toroot ?>guide/developing/tools/draw9patch.html">Draw 9-Patch</a></li> @@ -140,6 +143,12 @@ <li><h2>Best Practices</h2> <ul> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/index.html">UI Guidelines</a></div> + <ul> + <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/widget_design.html">App Widget Design</a></li> + </ul> + </li> <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> diff --git a/docs/html/guide/practices/ui_guidelines/index.jd b/docs/html/guide/practices/ui_guidelines/index.jd new file mode 100644 index 0000000..e19d5b4 --- /dev/null +++ b/docs/html/guide/practices/ui_guidelines/index.jd @@ -0,0 +1,28 @@ +page.title=User Interface Guidelines +@jd:body + + +<img src="{@docRoot}assets/images/uiguidelines1.png" alt="" align="right"> + + +<p>The Android UI team has begun developing guidelines for the interaction and +design of Android applications. Look here for articles that describe these +visual guidelines as we release them.</p> + + + <dl> + <dt><a href="widget_design.html">Widget Design Guidelines</a> </dt> + <dd>Widgets are a new feature introduced in Cupcake. A widget displays +an application's most important or timely information at a glance, on a user's +Home screen. These design guidelines describe how to design widgets that fit +with others on the Home screen. They include links to graphics files and +templates that will make your designer's life easier.</dd> + +</dl> + + + + + + + diff --git a/docs/html/guide/practices/ui_guidelines/widget_design.jd b/docs/html/guide/practices/ui_guidelines/widget_design.jd new file mode 100644 index 0000000..514b315 --- /dev/null +++ b/docs/html/guide/practices/ui_guidelines/widget_design.jd @@ -0,0 +1,274 @@ +page.title=Widget Design Guidelines +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + +<h2>Widget design quickview</h2> + +<ul> +<li>Widgets have six standard sizes on the Home screen</li> +<li>Widgets have standards for size, frames, shadows, and file format, which you can copy</li> +<li>A few tricks make it easier to design widgets that fit graphically on the Home screeen</li> +</ul> + +<h2>In this document</h2> + +<ol> +<li><a href="#anatomy">Standard widget anatomy</a></li> +<li><a href="#design">Designing a widget</a></li> +<li><a href="#sizes">Standard widget sizes</a></li> +<li><a href="#frames">Standard widget frames</a></li> +<li><a href="#shadows">Standard widget shadows</a></li> +<li><a href="#tricks">Widget graphics tips and tricks</a></li> +<li><a href="#file">Widget graphics file format</a></li> +</ol> + +<h2>See also</h2> + +<ol> +<li><a href="{@docRoot}guide/topics/appwidgets/index.html">AppWidgets</a> topic in the <em>Dev Guide</em></li> +<li><a href="http://android-developers.blogspot.com/2009/04/introducing-home-screen-widgets-and.html">AppWidgets blog post</a></li> +</ol> + +</div> +</div> + + +<p>Widgets are a feature introduced in Android 1.5. A widget displays an +application's most important or timely information at a glance, on a user's Home +screen. The standard Android system image includes several examples of widgets, +including widgets for Analog Clock, Music, and other applications.</p> + +<p>Users pick the widgets they want to display on their Home screens by touching +& holding an empty area of the Home screen, selecting Widgets from the menu, +and then selecting the widget they want.</p> + +<p><img src="{@docRoot}images/widget_design/widget_examples.png" alt="Example +Widgets"></p> + +<p>This document describes how to design a widget so it fits graphically with +other widgets and with the other elements of the Android Home screen. It also +describes some standards for widget artwork and some widget graphics tips and +tricks from the Android team.<p> + +<p>For information about developing widgets, see the <a +href="{@docRoot}guide/topics/appwidgets/index.html">AppWidgets</a> section of +the <em>Developer's Guide</em> and the <a +href="http://android-developers.blogspot.com/2009/04/introducing-home-screen-widgets-and.html">AppWidgets</a> blog post.</p> + + +<h2 id="anatomy">Standard widget anatomy</h2> + +<p>Typical Android widgets have three main components: A bounding box, a frame, +and the widget's graphical controls and other elements. Well-designed widgets +leave some padding between the edges of the bounding box and the frame, and +between the inner edges of the frame and the widget's controls. Widgets designed +to fit visually with other widgets on the Home screen take cues from the other +elements on the Home screen for alignment; they also use standard shading +effects. All of these details are described in this document. + +<p><strong>Standard Widget Sizes in Portrait Orientation</strong><br/> +<img src="{@docRoot}images/widget_design/widget_sizes_portrait.png" +alt="Standard Widget Sizes in Portrait Orientation"></p> + +<p> </p> + +<p><strong>Standard Widget Sizes in Landscape Orientation</strong><br/> +<img src="{@docRoot}images/widget_design/widget_sizes_landscape.png" +alt="Standard Widget Sizes in Landscape Orientation"></p> + + +<h2 id="design">Designing a widget</h2> + +<ol> +<li><strong>Select a bounding box size for your widget.</strong></li> + +<p>The most effective widgets display your application's most useful or timely +data in the smallest widget size. Users will weigh the usefulness or your widget +against the portion of the Home screen it covers, so the smaller the better.</p> + +<p>All widgets must fit within the bounding box of one of the six supported +widget sizes, or better yet, within a pair of portrait and landscape orientation +sizes, so your widget looks good when the user switches screen +orientations.</p> + +<p><a href="#sizes">Standard widget sizes</a> illustrates the bounding +dimensions of the six widget sizes (three in portrait and three in landscape +orientation).</p> + + +<li><strong>Select a matching frame.</strong></li> + +<p><a href="#frames">Standard widget frames</a> illustrates the standard frames +for the six widget sizes, with links so you can download copies for your own +use. You don't have to use these frames for your widget, but if you do, your +widgets are more likely to fit visually with other widgets.</p> + +<li><strong>Apply standard shadow effect to your graphics.</strong></li> + +<p>Again, you don't have to use this effect, but <a href="#shadows">Standard +widget shadows</a> shows the Photoshop settings used for standard widgets.</p> + +<li><strong>If your widget includes buttons, draw them in three states +(default, pressed, and selected).</strong></li> + +<p>You can <a +href="{@docRoot}images/widget_design/Music_widget_button_states.psd">download a +Photoshop file that contains the three states of the Play button</a>, taken from +the Music widget, to analyze the Photoshop settings used for the three standard +button effects.</p> + +<p><a href="{@docRoot}images/widget_design/Music_widget_button_states.psd"> <img +src="{@docRoot}images/widget_design/buttons.png" alt="Click to download +Photoshop template"></a></p> + +<li><strong>Finish drawing your artwork and then scale and align it to +fit.</strong></li> + +<p><a href="#tricks">Widget alignment tips and tricks</a> describes some +techniques for aligning your widget's graphics inside the standard frames, along +with a few other widget graphics tricks.</p> + +<li><strong>Save your widget with the correct graphics file +settings.</strong></li> + +<p><a href="#file">Windows graphics file format</a> describes the correct +settings for your widget graphics files.</p> + +</ol> + + +<h2 id="sizes">Standard widget sizes</h2> + +<p>There are six standard widget sizes, based on a Home screen grid of 4 x 4 +(portrait) or 4 x 4 (landscape) cells. These dimensions are the bounding boxes +for the six standard widget sizes. The contents of typical widgets don't draw to +the edge of these dimensions, but fit inside a frame withing the bounding box, +as described in <a href="#design">Designing a widget</a>.</p> + +<p>In portrait orientation, each cell is 80 pixels wide by 100 pixels tall (the +diagram shows a cell in portrait orientation). The three supported widget sizes +in portrait orientation are:<p> + +<table> +<tr><th>Cells</th><th>Pixels</th></tr> +<tr><td>4 x 1</td><td>320 x 100</td></tr> +<tr><td>3 x 3</td><td>240 x 300</td></tr> +<tr><td>2 x 2</td><td>160 x 200</td></tr> +</table> + +<p><img src="{@docRoot}images/widget_design/portrait_sizes.png" alt="Widget +dimensions in portrait orientation"></p> + +<p>In landscape orientation, each cell is 106 pixels wide by 74 pixels tall. The +three supported widget sizes in landscape orientation are:</p> + +<table> +<tr><th>Cells</th><th>Pixels</th></tr> +<tr><td>4 x 1</td><td>424 x 74</td></tr> +<tr><td>3 x 3</td><td>318 x 222</td></tr> +<tr><td>2 x 2</td><td>212 x 148</td></tr> +</table> + +<p><img src="{@docRoot}images/widget_design/landscape_sizes.png" alt="Widget +dimensions in landscape orientation"></p> + + +<h2 id="frames">Standard widget frames</h2> + +<p>For each of the six standard widget sizes there is a standard frame. You can +click the images of the frames in this section to download a Photoshop file for +that frame, which you can use for your own widgets.<p> + +<p><a href="{@docRoot}images/widget_design/4x1_Widget_Frame_Portrait.psd"> <img +src="{@docRoot}images/widget_design/4x1_Widget_Frame_Portrait.png" alt="Click to +download"></a><br>4x1_Widget_Frame_Portrait.psd</p> + +<p><a href="{@docRoot}images/widget_design/3x3_Widget_Frame_Portrait.psd"> <img +src="{@docRoot}images/widget_design/3x3_Widget_Frame_Portrait.png" alt="Click to +download"></a><br>3x3_Widget_Frame_Portrait.psd</p> + +<p><a href="{@docRoot}images/widget_design/2x2_Widget_Frame_Portrait.psd"> <img +src="{@docRoot}images/widget_design/2x2_Widget_Frame_Portrait.png" alt="Click to +download"></a><br>2x2_Widget_Frame_Portrait.psd</p> + +<p><a href="{@docRoot}images/widget_design/4x1_Widget_Frame_Landscape.psd"> <img +src="{@docRoot}images/widget_design/4x1_Widget_Frame_Landscape.png" alt="Click +to download"></a><br>4x1_Widget_Frame_Landscape.psd</p> + +<p><a href="{@docRoot}images/widget_design/3x3_Widget_Frame_Landscape.psd"> <img +src="{@docRoot}images/widget_design/3x3_Widget_Frame_Landscape.png" alt="Click +to download"></a><br>3x3_Widget_Frame_Landscape.psd</p> + +<p><a href="{@docRoot}images/widget_design/2x2_Widget_Frame_Landscape.psd"> <img +src="{@docRoot}images/widget_design/2x2_Widget_Frame_Landscape.png" alt="Click +to download"></a><br>2x2_Widget_Frame_Landscape.psd</p> + + +<h2 id="shadows">Standard widget shadows</h2> + +<p>You can apply a shadow effect to your widget's artwork, so it matches other +standard Android widgets, using the following settings in the Photoshop Layer +Style dialog box.</p> + +<p><img src="{@docRoot}images/widget_design/Layer_Style.png" alt="Layer Style +settings for standard shadows"></p> + + +<h2 id="tricks">Widget graphics tips and tricks</h2> + +<p>The Android team has developed a few tricks for aligning widget artwork +within standard widget bounding boxes and frames, so the widget aligns visually +with other widgets and the other elements of the Home screen, as well as other +techniques for creating widgets. + +<ul> + +<li>Use a screen shot from the Android SDK emulator to align both the shapes and +shadows of your widget controls with the Search widget and with other elements +on the Home screen.</li> + +<p>Cut the widget artwork asset" based on the full size of a cell, including any +padding you want. (That is, for a 4 x 1 widget, cut the asset at 320 by 100 +pixels.)</p> + +<p><img src="{@docRoot}images/widget_design/alignment.png" alt="Aligning widget +graphics" ></p> + +<li>To reduce banding when exporting a widget, apply the following Photoshop Add +Noise setting to your graphic.</li> + +<p><img src="{@docRoot}images/widget_design/Add_Noise.png" alt="Add Noise +settings for widget graphics" ></p> + +<li>Apply 9-patch techniques to shrink the graphic and set the padding of the +content area. (<a href="{@docRoot}guide/developing/tools/draw9patch.html">See +the detailed guide here.</a>)</li> + +<p><strong>Note:</strong> The current Android widget templates were designed +using a custom gradient angle, which means the 9-patch techniques can't be used +to optimize the size of the asset. However, 9-patch techniques were used to set +the content area padding.</p> + +<li>In some cases, devices have low pixel depths that can cause visual banding +and dithering issues. To solve this, application developers should pass assets +through a "proxy" drawable defined as <code>XML:<nine-patch +android:src="@drawable/background" android:dither="true" /></code>. This +technique references the original artwork, in this case +<code>"background.9.png"</code>, and instructs the device to dither it as +needed.</li> + +</ul> + +<h2 id="file">Widget graphics file format</h2> + +<p>Save your widget artwork using the appropriate bounding box size in PNG-24 +format on a transparent background and in 8-bit color.</p> + +<p><img src="{@docRoot}images/widget_design/file_format.png" alt="Widget graphics file format" ></p> + + + + + diff --git a/docs/html/guide/publishing/app-signing.jd b/docs/html/guide/publishing/app-signing.jd index 28c927a..a16c910 100644 --- a/docs/html/guide/publishing/app-signing.jd +++ b/docs/html/guide/publishing/app-signing.jd @@ -22,9 +22,10 @@ page.title=Signing Your Applications <li><a href="#debugmode">Signing in Debug Mode</a></li> <li><a href="#releasemode">Signing for Public Release</a> <ol> - <li><a href="#releasecompile">Compiling for Release</a></li> - <li><a href="#cert">Obtaining a Suitable Private Key</a></li> - <li><a href="#signapp">Signing Your Application</a></li> + <li><a href="#releasecompile">Compiling for release</a></li> + <li><a href="#cert">Obtaining a suitable private key</a></li> + <li><a href="#signapp">Signing your application</a></li> + <li><a href="#ExportWizard">Compiling and signing with Eclipse ADT</a></li> </ol> </li> <li><a href="#secure-key">Securing Your Private Key</a></li> @@ -47,9 +48,9 @@ page.title=Signing Your Applications <p>The Android system requires that all installed applications be digitally signed with a certificate whose private key is held by the application's -developer. The system uses the certificate as a means of identifying the author of -an application and establishing trust relationships between applications, rather -than for controlling which applications the user can install. The certificate +developer. The Android system uses the certificate as a means of identifying the author of +an application and establishing trust relationships between applications. The certificate is not +used to control which applications the user can install. The certificate does not need to be signed by a certificate authority: it is perfectly allowable, and typical, for Android applications to use self-signed certificates.</p> @@ -61,8 +62,8 @@ certificates.</p> that is not signed.</li> <li>You can use self-signed certificates to sign your applications. No certificate authority is needed.</li> - <li>When you are ready to publish your application, you must sign it with a suitable private -key. You can not publish an application that is signed with the default key generated + <li>When you are ready to release your application for end-users, you must sign it with a suitable private +key. You can not publish an application that is signed with the debug key generated by the SDK tools. </li> <li>The system tests a signer certificate's expiration date only at install time. If an @@ -78,20 +79,32 @@ For this reason, you must set up signing for your application before you will be run or debug it on an emulator or device.</p> <p>The Android SDK tools assist you in signing your applications when debugging. Both the ADT Plugin -for Eclipse and the Ant build tool offer two signing modes — debug mode and release mode. +for Eclipse and the Ant build tool offer two signing modes — <em>debug mode</em> +and <em>release mode</em>. <ul> -<li>In debug mode, the build tools use the Keytool utility, included in the JDK, to create +<li>While developing and testing, you can compile in debug mode. +In debug mode, the build tools use the Keytool utility, included in the JDK, to create a keystore and key with a known alias and password. At each compilation, the tools then use the debug key to sign the application .apk file. Because the password is known, the tools don't need to prompt you for the keystore/key password each time you compile.</li> -<li>When your application is ready for release, you compile it in release signing mode. -In this mode, the tools compile your .apk <em>without</em> signing it. You must then sign -the .apk manually — <span style="color:red">with your private key</span> — -using Jarsigner (or similar tool). If you do not have a suitable private key already, -you can run Keytool manually to generate your own keystore/key and then sign your -application with Jarsigner.</li> +<li>When your application is ready for release, you must compile in release mode +and then sign the .apk <span style="color:red">with your private key</span>. +There are two ways to do this: + <ul> + <li>Using Keytool and Jarsigner in the command-line. In this approach, + you first compile your application to an <em>unsigned</em> .apk. You must then sign + the .apk manually with your private key + using Jarsigner (or similar tool). If you do not have a suitable private key already, + you can run Keytool manually to generate your own keystore/key and then sign your + application with Jarsigner.</li> + <li>Using the ADT Export Wizard. If you are developing in Eclipse with the ADT plugin, + you can use the Export Wizard to compile the application, generate a private key + (if necessary), and sign the .apk, all in a single process using the Export Wizard. + </li> + </ul> +</li> </ul> <h2 id="strategies">Signing Strategies</h2> @@ -105,7 +118,7 @@ all of your applications with the same certificate, throughout the expected lifespan of your applications. There are several reasons why you should do so: </p> <ul> -<li>Application upgrade — As you release upgrades to your +<li>Application upgrade – As you release upgrades to your application, you will want to sign the upgrades with the same certificate, if you want users to upgrade seamlessly to the new version. When the system is installing an update to an application, if any of the certificates in the @@ -115,13 +128,13 @@ certificate, you will also need to assign a different package name to the application — in this case, the user installs the new version as a completely new application. </li> -<li>Application modularity — The Android system allows applications that +<li>Application modularity – The Android system allows applications that are signed by the same certificate to run in the same process, if the -applications so request, so that the system treats them as a single application. +applications so requests, so that the system treats them as a single application. In this way you can deploy your application in modules, and users can update each of the modules independently if needed.</li> -<li>Code/data sharing through permissions — The Android system provides +<li>Code/data sharing through permissions – The Android system provides signature-based permissions enforcement, so that an application can expose functionality to another application that is signed with a specified certificate. By signing multiple applications with the same certificate and @@ -167,7 +180,7 @@ 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 +<code>/usr/bin/keytool</code>. In this case, check the symlink target to make sure that it points to the Keytool in the JDK.</p> <p>If you will release your application to the public, you will also need to have @@ -180,38 +193,46 @@ in the JDK. </p> to develop and debug your application, while still meeting the Android system requirement for signing your .apk when it is installed in the emulator or a device. When you use debug mode, the SDK tools invoke Keytool to create a debug -keystore and key. </p> +keystore and key.</p> <p>The SDK tools create the debug keystore/key with predetermined names/passwords;</p> <ul> -<li>Keystore name — "debug.keystore"</li> -<li>Keystore password — "android"</li> -<li>Key alias — "androiddebugkey"</li> -<li>Key password — "android"</li> -<li>CN — "CN=Android Debug,O=Android,C=US"</li> +<li>Keystore name – "debug.keystore"</li> +<li>Keystore password – "android"</li> +<li>Key alias – "androiddebugkey"</li> +<li>Key password – "android"</li> +<li>CN – "CN=Android Debug,O=Android,C=US"</li> </ul></p> +<p>If necessary, you can change the location/name of the debug keystore/key or +supply a custom debug keystore/key to use. In Eclipse/ADT, you can use +<strong>Windows</strong> > <strong>Prefs</strong> > +<strong>Android</strong> > <strong>Build</strong>. However, any custom debug +keystore/key must use the same keystore/key names and passwords as the default +debug key (as described above).</p> + +<p class="note"><strong>Note:</strong> You <em>cannot</em> release your application +to the public when signed with the debug certificate.</p> + +<h3>Eclipse Users</h3> + <p>If you are developing in Eclipse/ADT and have set up Keytool as described above, signing in debug mode is enabled by default. When you run or debug your application, ADT signs the .apk with the debug certificate and installs it on the emulator. No specific action on your part is needed, provided ADT has access to Keytool.</p> +<h3>Ant Users</h3> + <p>If you use Ant to build your .apk files, debug signing mode -is enabled by default, assuming that you are using a build.xml file generated by the -activitycreator tool included in the latest SDK. When you run Ant against build.xml to +is enabled by using the <code>debug</code> option, assuming that you are using a +<code>build.xml</code> file generated by the +<code>android</code> tool. When you run <code>ant debug</code> to compile your app, the build script generates a keystore/key and signs the .apk for you. -No specific action on your part is needed.</p> - -<p>If necessary, you can change the location/name of the debug keystore/key or -supply a custom debug keystore/key to use. In Eclipse/ADT, you can use -<strong>Windows</strong> > <strong>Prefs</strong> > -<strong>Android</strong> > <strong>Build</strong>. However, any custom debug -keystore/key must use the same keystore/key names and passwords as the default -debug key (as described above). </p> +No other action on your part is needed. Read +<a href="{@docRoot}guide/developing/other-ide.html#DebugMode">Developing In Other IDEs: Building +in debug mode</a> for more information.</p> -<p>Note that you <em>cannot</em> release your application to the public if it -is signed with the debug certificate. </p> <h3 id="debugexpiry">Expiry of the Debug Certificate</h3> @@ -227,11 +248,11 @@ looks like this:</p> <p>In Eclipse/ADT, you will see a similar error in the Android console.</p> -<p>To fix this problem, simply delete the <code>debug.keystore</code> file. On Linux/Mac OSX, -the file is stored in <code>~/.android</code>. On Windows XP, the file is stored in <code> -C:\Documents and Settings\<user>\Local Settings\Application Data\Android</code>. -On Windows Vista, the file is stored in <code> -C:\Users\<user>\AppData\Local\Android</code>.</p> +<p>To fix this problem, simply delete the <code>debug.keystore</code> file. +The default storage location for AVDs is in <code>~/.android/avd</code> on OS X and Linux, +in <code>C:\Documents and Settings\<user>\.android\</code> on Windows XP, and in +<code>C:\Users\<user>\.android\</code> on Windows Vista.</p> + <p>The next time you build, the build tools will regenerate a new keystore and debug key.</p> @@ -242,29 +263,45 @@ troubleshooting topic <a href="{@docRoot}guide/appendix/faq/troubleshooting.html I can't compile my app because the build tools generated an expired debug certificate</a>. </p> + <h2 id="releasemode">Signing for Public Release</h2> <p>When your application is ready for release to other users, you must:</p> <ol> -<li>Compile the application in release mode</li> -<li>Obtain a suitable private key, and then</li> -<li>Sign the application with your private key</li> -<li>Secure your private key</li> + <li>Compile the application in release mode</li> + <li>Obtain a suitable private key</li> + <li>Sign the application with your private key</li> </ol> -<p>The sections below provide information about these steps. </p> +<p>The sections below provide information about how to perform these steps.</p> + +<p>If you use Eclipse with the ADT plugin, you can instead use the Export Wizard +to compile and sign an .apk with your private key. The Export Wizard even allows you to +generate a new keystore and private key in the process. Skip to +<a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p> + -<h3 id="releasecompile">Compiling for Release</h3> +<h3 id="releasecompile">Compiling for release</h3> <p>To prepare your application for release, you must first compile it in release mode. In release mode, the Android build tools compile your application as usual, -but without signing it with the debug key. </p> +but without signing it with the debug key.</p> + +<p class="warning"><strong>Note:</strong> +You can not release your application unsigned, or signed with the debug key.</p> + +<h4>Eclipse users</h4> + +<p>To export an <em>unsigned</em> .apk from Eclipse, right-click the project in the Package +Explorer and select <strong>Android Tools</strong> > <strong>Export Unsigned Application +Package</strong>. Then simply specify the file location for the unsigned .apk. +(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open +the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)</p> + +<p>You can also combine the compiling and signing steps with the Export Wizard. See +<a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p> -<p>If you are developing in Eclipse/ADT, right-click the project in the Package -pane and select <strong>Android Tools</strong> > <strong>Export Application -Package</strong>. You can then specify the file location for the unsigned .apk. -Alternatively, you can follow the "Exporting the unsigned .apk" -link in the Manifest Editor overview page. </p> +<h4>Ant users</h4> <p>If you are using Ant, all you need to do is specify the build target "release" in the Ant command. For example, if you are running Ant from the @@ -272,9 +309,8 @@ directory containing your build.xml file, the command would look like this:</p> <pre>$ ant release</pre> -<p>The build script compiles the application .apk without signing it. +<p>The build script compiles the application .apk without signing it.</p> -<p>Note that you can not release your application unsigned, or signed with the debug key.</p> <h3 id="cert">Obtaining a Suitable Private Key</h3> @@ -303,7 +339,7 @@ in <a href="#setup">Basic Setup</a>.</p> command and pass any of the options listed below (and any others, as needed). </p> -<p class="warning">Before you run Keytool, make sure to read +<p class="warning"><strong>Note:</strong> Before you run Keytool, make sure to read <a href="#secure-key">Securing Your Private Key</a> for a discussion of how to keep your key secure and why doing so is critically important to you and to users. In particular, when you are generating your key, you should select strong passwords @@ -378,7 +414,8 @@ will use later, to refer to this keystore when signing your application. </p> href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> -<h3 id="signapp">Signing Your Application</h3> + +<h3 id="signapp">Signing your application</h3> <p>When you are ready to actually sign your .apk for release, you can do so using the Jarsigner tool. Make sure that you have Jarsigner available on your @@ -425,9 +462,9 @@ way, your password is not stored in your shell history.</p></td> my_application.apk alias_name</pre> <p>Running the example command above, Jarsigner prompts you to provide -passwords for the keystore and key. It then modifies the APK +passwords for the keystore and key. It then modifies the .apk in-place, meaning the .apk is now signed. Note that you can sign an -APK multiple times with different keys.</p> +.apk multiple times with different keys.</p> <p>To verify that your .apk is signed, you can use a command like this:</p> @@ -445,7 +482,7 @@ If you want more details, you can try one of these commands:</p> <p>The command above, with the <code>-certs</code> option added, will show you the "CN=" line that describes who created the key.</p> -<p class="note">Note: if you see "CN=Android Debug", this means the .apk was +<p class="note"><strong>Note:</strong> If you see "CN=Android Debug", this means the .apk was signed with the debug key generated by the Android SDK. If you intend to release your application, you must sign it with your private key instead of the debug key.</p> @@ -454,6 +491,32 @@ key.</p> <a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> + +<h3 id="ExportWizard">Compiling and signing with Eclipse ADT</h3> + +<p>When using Eclipse with ADT, you can use the Export Wizard to +export a <em>signed</em> .apk (and even create a new keystore, +if necessary). The Export Wizard performs all the interaction with +the Keytool and Jarsigner for you, which allows you to perform signing via a +graphical interface instead of the command-line. +Because the Export Wizard uses both Keytool and Jarsigner, you should +ensure that they are accessible on your computer, as described above +in the <a href=#setup">Basic Setup for Signing</a>.</p> + +<p>To create a signed .apk, right-click the project in the Package +Explorer and select <strong>Android Tools > Export Signed Application Package</strong>. +(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open +the <em>Overview</em> tab, and click <strong>Use the Export Wizard</strong>.) +The window that appears will display any errors found while +attempting to export your application. If no errors are found, continue with the +Export Wizard, which will guide you through the process of signing your application, +including steps for selecting the private key with which to sign the .apk, +or creating a new keystore and private key.</p> + +<p>When you complete the Export Wizard, you'll +have a signed .apk that's ready for distribution.</p> + + <h2 id="secure-key">Securing Your Private Key</h2> <p>Maintaining the security of your private key is of critical importance, both diff --git a/docs/html/guide/publishing/preparing.jd b/docs/html/guide/publishing/preparing.jd index d355265..b4eaea3 100644 --- a/docs/html/guide/publishing/preparing.jd +++ b/docs/html/guide/publishing/preparing.jd @@ -178,8 +178,8 @@ MapView elements</h3> <div class="sidebox" style="margin-bottom:.5em;padding:1em;"><p> For complete information about getting a Maps API Key, see <a -href="{@docRoot}guide/topics/location/geo/mapkey.html">Obtaining a Maps API -Key</a>.<br></p></div> +href="http://code.google.com/android/add-ons/google-apis/mapkey.html"> +Obtaining a Maps API Key</a>.</p></div> <p>If your application uses one or more Mapview elements, you will need to register your application with the Google @@ -221,7 +221,7 @@ to download Maps data. </li> </ol> <p>For more information about signing and your private key, see <a -href="#signing">Signing Your Applications</a>.</p> +href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>.</p> <h2 id="compile">Compile your application</h2> @@ -234,7 +234,8 @@ you can compile your application for release. </p> <h3 id="signapp">8. Sign your application</h3> <p>Sign your application using your private key. Signing your application -correctly is critically important. Please see <a href="#signing">Signing Your +correctly is critically important. Please see +<a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a> for complete information. </p> <h3 id="testapp">9. Test your compiled and signed application</h3> diff --git a/docs/html/guide/samples/index.jd b/docs/html/guide/samples/index.jd index 4e665fa..365284d 100644 --- a/docs/html/guide/samples/index.jd +++ b/docs/html/guide/samples/index.jd @@ -4,11 +4,13 @@ page.title=Sample Code <p>Sometimes, the best way to learn how things are done is to just look at some code. So here - we've provided links to let you browse the source of some some simple Android applications. </p> + we've provided links to let you browse the source of some sample Android applications included +in the Android SDK. </p> -<p>The source code for these applications is included in the Android SDK, in this location:</p> +<p>The SDK includes a full set of sample applications for each Android platform version +in the SDK. You can find the sample applications for each platform version in this location:</p> -<p style="margin-left:2em"><code><sdk>/samples/</code></p> +<p style="margin-left:2em"><code><sdk>/platforms/android-<version>/samples/</code></p> <p>You can easily add these applications as projects in your development environment, so that you can modify them and watch them execute. </p> diff --git a/docs/html/guide/topics/appwidgets/index.jd b/docs/html/guide/topics/appwidgets/index.jd new file mode 100644 index 0000000..01a9648 --- /dev/null +++ b/docs/html/guide/topics/appwidgets/index.jd @@ -0,0 +1,463 @@ +page.title=App Widgets +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>Key classes</h2> + <ol> + <li>{@link android.appwidget.AppWidgetProvider}</li> + <li>{@link android.appwidget.AppWidgetProviderInfo}</li> + <li>{@link android.appwidget.AppWidgetManager}</li> + </ol> + <h2>In this document</h2> + <ol> + <li><a href="#Basics">The Basics</a></li> + <li><a href="#Manifest">Declaring an App Widget in the Manifest</a></li> + <li><a href="#MetaData">Adding the AppWidgetProviderInfo Metadata</a></li> + <li><a href="#CreatingLayout">Creating the App Widget Layout</a></li> + <li><a href="#AppWidgetProvider">Using the AppWidgetProvider Class</a> + <ol> + <li><a href="#ProviderBroadcasts">Receiving App Widget broadcast Intents</a></li> + </ol> + </li> + <li><a href="#Configuring">Creating an App Widget Configuration Activity</a> + <ol> + <li><a href="#UpdatingFromTheConfiguration">Updating the App Widget from + the configuration Activity</a></li> + </ol> + </li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}guide/practices/ui_guidelines/widget_design.html">App Widget Design + Guidelines</a></li> + <li><a href="http://android-developers.blogspot.com/2009/04/introducing-home-screen-widgets-and.html">Introducing + home screen widgets and the AppWidget framework »</a></li> + </ol> + </div> +</div> + + +<p>App Widgets are miniature application views that can be embedded in other applications +(such as the Home screen) and receive periodic updates. These views are referred +to as Widgets in the user interface, +and you can publish one with an App Widget provider. An application component that is +able to hold other App Widgets is called an App Widget host. The screenshot below shows +the Music App Widget.</p> + +<img src="{@docRoot}images/appwidget.png" alt="" /> + +<p>This document describes how to publish an App Widget using an App Widget provider.</p> + + +<h2 id="Basics">The Basics</h2> + +<p>To create an App Widget, you need the following:</p> + +<dl> + <dt>{@link android.appwidget.AppWidgetProviderInfo} object</dt> + <dd>Describes the metadata for an App Widget, such as the App Widget's layout, update frequency, + and the AppWidgetProvider class. This should be defined in XML.</dd> + <dt>{@link android.appwidget.AppWidgetProvider} class implementation</dt> + <dd>Defines the basic methods that allow you to programmatically interface with the App Widget, + based on broadcast events. Through it, you will receive broadcasts when the App Widget is updated, + enabled, disabled and deleted.</dd> + <dt>View layout</dt> + <dd>Defines the initial layout for the App Widget, defined in XML.</dd> +</dl> + +<p>Additionally, you can implement an App Widget configuration Activity. This is an optional +{@link android.app.Activity} that launches when the user adds your App Widget and allows him or her +to modify App Widget settings at create-time.</p> + +<p>The following sections describe how to setup each of these components.</p> + + +<h2 id="Manifest">Declaring an App Widget in the Manifest</h2> + +<p>First, declare the {@link android.appwidget.AppWidgetProvider} class in your application's +<code>AndroidManifest.xml</code> file. For example:</p> + +<pre> +<receiver android:name="ExampleAppWidgetProvider" > + <intent-filter> + <action android:name="android.appwidget.action.APPWIDGET_UPDATE" /> + </intent-filter> + <meta-data android:name="android.appwidget.provider" + android:resource="@xml/example_appwidget_info" /> +</receiver> +</pre> + +<p>The <code><receiver></code> element requires the <code>android:name</code> +attribute, which specifies the {@link android.appwidget.AppWidgetProvider} used +by the App Widget.</p> + +<p>The <code><intent-filter></code> element must include an <code><action></code> +element with the <code>android:name</code> attribute. This attribute specifies +that the {@link android.appwidget.AppWidgetProvider} accepts the {@link +android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE ACTION_APPWIDGET_UPDATE} broadcast. +This is the only broadcast that you must explicitly declare. The {@link android.appwidget.AppWidgetManager} +automatically sends all other App Widget broadcasts to the AppWidgetProvider as necessary.</p> + +<p>The <code><meta-data></code> element specifies the +{@link android.appwidget.AppWidgetProviderInfo} resource and requires the +following attributes:</p> +<ul> + <li><code>android:name</code> - Specifies the metadata name. Use <code>android.appwidget.provider</code> + to identify the data as the {@link android.appwidget.AppWidgetProviderInfo} descriptor.</li> + <li><code>android:resource</code> - Specifies the {@link android.appwidget.AppWidgetProviderInfo} + resource location.</li> +</ul> + + +<h2 id="MetaData">Adding the AppWidgetProviderInfo Metadata</h2> + +<p>The {@link android.appwidget.AppWidgetProviderInfo} defines the essential +qualities of an App Widget, such as its minimum layout dimensions, its initial layout resource, +how often to update the App Widget, and (optionally) a configuration Activity to launch at create-time. +Define the AppWidgetProviderInfo object in an XML resource using a single +<code><appwidget-provider></code> element and save it in the project's <code>res/xml/</code> +folder.</p> + +<p>For example:</p> + +<pre> +<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android" + android:minWidth="294dp" <!-- density-independent pixels --> + android:minHeight="72dp" + android:updatePeriodMillis="86400000" <!-- once per day --> + android:initialLayout="@layout/example_appwidget" + android:configure="com.example.android.ExampleAppWidgetConfigure" > +</appwidget-provider> +</pre> + +<p>Here's a summary of the <code><appwidget-provider></code> attributes:</p> +<ul> + <li>The values for the <code>minWidth</code> and <code>minHeight</code> attributes specify the minimum + area required by the App Widget's layout. + <p>The default Home screen positions App Widgets in its window based on a grid of + cells that have a defined height and width. If the values for an App Widget's minimum width + or height don't match the dimensions of the cells, + then the App Widget dimensions round <em>up</em> to the nearest cell size. + (See the <a href="{@docRoot}guide/practices/ui_guidelines/widget_design.html">App Widget Design + Guidelines</a> for more information on the Home screen cell sizes.)</p> + <p>Because the Home screen's layout orientation (and thus, the cell sizes) can change, + as a rule of thumb, you should assume the worst-case cell size of 74 pixels for the height + <em>and</em> width of a cell. However, you must subtract 2 from the final dimension to account + for any integer rounding errors that occur in the pixel count. To find your minimum width + and height in density-independent pixels (dp), use this formula:<br/> + <code>(number of cells * 74) - 2</code><br/> + Following this formula, you should use 72 dp for a height of one cell, 294 dp and for a width of four cells.</p> + </li> + <li>The <code>updatePerdiodMillis</code> attribute defines how often the App Widget framework should + request an update from the {@link android.appwidget.AppWidgetProvider} by calling the + {@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[]) + onUpdate()} method. The actual update is not guaranteed to occur exactly on time with this value + and we suggest updating as infrequently as possible—perhaps no more than once an hour to + conserve the battery. You might also allow the user to adjust the frequency in a + configuration—some people might want a stock ticker to update every 15 minutes, or maybe + only four times a day.</li> + <li>The <code>initialLayout</code> attribute points to the layout resource that defines the + App Widget layout.</li> + <li>The <code>configure</code> attribute defines the {@link android.app.Activity} to launch when + the user adds the App Widget, in order for him or her to configure App Widget properties. This is optional + (read <a href="#Configuring">Creating an App Widget Configuration Activity</a> below).</li> +</ul> + +<p>See the {@link android.appwidget.AppWidgetProviderInfo} class for more information on the +attributes accepted by the <code><appwidget-provider></code> element.</p> + + +<h2 id="CreatingLayout">Creating the App Widget Layout</h2> + +<p>You must define an initial layout for your App Widget in XML and save it in the project's +<code>res/layout/</code> directory. You can design your App Widget using the View objects listed +below, but before you begin designing your App Widget, please read and understand the +<a href="{@docRoot}guide/practices/ui_guidelines/widget_design.html">App Widget Design +Guidelines</a>.</p> + +<p>Creating the App Widget layout is simple if you're +familiar with <a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout in XML</a>. +However, you must be aware that App Widget layouts are based on {@link android.widget.RemoteViews}, +which do not support every kind of layout or view widget.</p> + +<p>A RemoteViews object (and, consequently, an App Widget) can support the +following layout classes:</p> + +<ul class="nolist"> + <li>{@link android.widget.FrameLayout}</li> + <li>{@link android.widget.LinearLayout}</li> + <li>{@link android.widget.RelativeLayout}</li> +</ul> + +<p>And the following widget classes:</p> +<ul class="nolist"> + <li>{@link android.widget.AnalogClock}</li> + <li>{@link android.widget.Button}</li> + <li>{@link android.widget.Chronometer}</li> + <li>{@link android.widget.ImageButton}</li> + <li>{@link android.widget.ImageView}</li> + <li>{@link android.widget.ProgressBar}</li> + <li>{@link android.widget.TextView}</li> +</ul> + +<p>Descendants of these classes are not supported.</p> + + +<h2 id="AppWidgetProvider">Using the AppWidgetProvider Class</h2> + +<div class="sidebox-wrapper"> + <div class="sidebox-inner"> + <p>You must declare your AppWidgetProvider class implementation as a broadcast receiver + using the <code><receiver></code> element in the AndroidManifest (see + <a href="#Manifest">Declaring an App Widget in the Manifest</a> above).</p> + </div> +</div> + +<p>The {@link android.appwidget.AppWidgetProvider} class extends BroadcastReceiver as a convenience +class to handle the App Widget broadcasts. The AppWidgetProvider receives only the event broadcasts that +are relevant to the App Widget, such as when the App Widget is updated, deleted, enabled, and disabled. +When these broadcast events occur, the AppWidgetProvider receives the following method calls:</p> + +<dl> + <dt>{@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[])}</dt> + <dd>This is called to update the App Widget at intervals defined by the <code>updatePeriodMillis</code> + attribute in the AppWidgetProviderInfo (see <a href="#MetaData">Adding the + AppWidgetProviderInfo Metadata</a> above). This method is also called + when the user adds the App Widget, so it should perform the essential setup, + such as define event handlers for Views and start a temporary + {@link android.app.Service}, if necessary. However, if you have declared a configuration + Activity, <strong>this method is not called</strong> when the user adds the App Widget, + but is called for the subsequent updates. It is the responsibility of the + configuration Activity to perform the first update when configuration is done. + (See <a href="#Configuring">Creating an App Widget Configuration Activity</a> below.)</dd> + <dt>{@link android.appwidget.AppWidgetProvider#onDeleted(Context,int[])}</dt> + <dd>This is called every time an App Widget is deleted from the App Widget host.</dd> + <dt>{@link android.appwidget.AppWidgetProvider#onEnabled(Context)}</dt> + <dd>This is called when an instance the App Widget is created for the first time. For example, if the user + adds two instances of your App Widget, this is only called the first time. + If you need to open a new database or perform other setup that only needs to occur once + for all App Widget instances, then this is a good place to do it.</dd> + <dt>{@link android.appwidget.AppWidgetProvider#onDisabled(Context)}</dt> + <dd>This is called when the last instance of your App Widget is deleted from the App Widget host. + This is where you should clean up any work done in + {@link android.appwidget.AppWidgetProvider#onEnabled(Context)}, + such as delete a temporary database.</dd> + <dt>{@link android.appwidget.AppWidgetProvider#onReceive(Context,Intent)}</dt> + <dd>This is called for every broadcast and before each of the above callback methods. + You normally don't need to implement this method because the default AppWidgetProvider + implementation filters all App Widget broadcasts and calls the above + methods as appropriate.</dd> +</dl> + +<p class="warning"><strong>Note:</strong> In Android 1.5, there is a known issue in which the +<code>onDeleted()</code> method will not be called when it should be. To work around this issue, +you can implement {@link android.appwidget.AppWidgetProvider#onReceive(Context,Intent) +onReceive()} as described in this +<a href="http://groups.google.com/group/android-developers/msg/e405ca19df2170e2">Group post</a> +to receive the <code>onDeleted()</code> callback. +</p> + +<p>The most important AppWidgetProvider callback is +{@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[]) +onUpdated()} because it is called when each App Widget is added to a host (unless you use +a configuration Activity). If your App Widget accepts any +user interaction events, then you need to register the event handlers in this callback. +If your App Widget doesn't create temporary +files or databases, or perform other work that requires clean-up, then +{@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[]) +onUpdated()} may be the only callback method you need to define. For example, if you want an App Widget +with a button that launches an Activity when clicked, you could use the following +implementation of AppWidgetProvider:</p> + +<pre> +public class ExampleAppWidgetProvider extends AppWidgetProvider { + + public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) { + final int N = appWidgetIds.length; + + // Perform this loop procedure for each App Widget that belongs to this provider + for (int i=0; i<N; i++) { + int appWidgetId = appWidgetIds[i]; + + // Create an Intent to launch ExampleActivity + Intent intent = new Intent(context, ExampleActivity.class); + PendingIntent pendingIntent = PendingIntent.getActivity(context, 0, intent, 0); + + // Get the layout for the App Widget and attach an on-click listener to the button + RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.appwidget_provider_layout); + views.setOnClickPendingIntent(R.id.button, pendingIntent); + + // Tell the AppWidgetManager to perform an update on the current App Widget + appWidgetManager.updateAppWidget(appWidgetId, views); + } + } +} +</pre> + +<p>This AppWidgetProvider defines only the +{@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[]) +onUpdated()} method for the purpose +of defining a {@link android.app.PendingIntent} that launches an {@link android.app.Activity} +and attaching it to the App Widget's button +with {@link android.widget.RemoteViews#setOnClickPendingIntent(int,PendingIntent)}. +Notice that it includes a loop that iterates through each entry in <code>appWidgetIds</code>, which +is an array of IDs that identify each App Widget created by this provider. +In this way, if the user creates more than one instance of the App Widget, then they are +all updated simultaneously. However, only one <code>updatePeriodMillis</code> schedule will be +managed for all instances of the App Widget. For example, if the update schedule is defined +to be every two hours, and a second instance +of the App Widget is added one hour after the first one, then they will both be updated +on the period defined by the first one and the second update period will be ignored +(they'll both be updated every two hours, not every hour).</p> + +<p class="note"><strong>Note:</strong> Because the AppWidgetProvider is a BroadcastReceiver, +your process is not guaranteed to keep running after the callback methods return (see +<a href="{@docRoot}guide/topics/fundamentals.html#broadlife">Application Fundamentals > +Broadcast Receiver Lifecycle</a> for more information). If your App Widget setup process can take several +seconds (perhaps while performing web requests) and you require that your process continues, +consider starting a {@link android.app.Service} +in the {@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[]) +onUpdated()} method. From within the Service, you can perform your own updates to the App Widget +without worrying about the AppWidgetProvider closing down due to an +<a href="{@docRoot}guide/practices/design/responsiveness.html">Application Not Responding</a> +(ANR) error. See the +<a href="http://code.google.com/p/wiktionary-android/source/browse/trunk/Wiktionary/src/com/example/android/wiktionary/WordWidget.java">Wiktionary +sample's AppWidgetProvider</a> for an example of an App Widget running a {@link android.app.Service}.</p> + +<p>Also see the <a +href="{@docRoot}guide/samples/ApiDemos/src/com/example/android/apis/appwidget/ExampleAppWidgetProvider.html"> +ExampleAppWidgetProvider.java</a> sample class.</p> + + +<h3 id="ProviderBroadcasts">Receiving App Widget broadcast Intents</h3> + +<p>{@link android.appwidget.AppWidgetProvider} is just a convenience class. If you would like +to receive the App Widget broadcasts directly, you can implement your own +{@link android.content.BroadcastReceiver} or override the +{@link android.appwidget.AppWidgetProvider#onReceive(Context,Intent)} callback. +The four Intents you need to care about are:</p> +<ul> + <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE}</li> + <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_DELETED}</li> + <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_ENABLED}</li> + <li>{@link android.appwidget.AppWidgetManager#ACTION_APPWIDGET_DISABLED}</li> +</ul> + + + +<h2 id="Configuring">Creating an App Widget Configuration Activity</h2> + +<p>If you would like the user to configure settings when he or she adds a new App Widget, +you can create an App Widget configuration Activity. This {@link android.app.Activity} +will be automatically launched by the App Widget host and allows the user to configure +available settings for the App Widget at create-time, such as the App Widget color, size, +update period or other functionality settings.</p> + +<p>The configuration Activity should be declared as a normal Activity in the Android manifest file. +However, it will be launched by the App Widget host with the {@link +android.appwidget.AppWidgetManager#ACTION_APPWIDGET_CONFIGURE ACTION_APPWIDGET_CONFIGURE} action, +so the Activity needs to accept this Intent. For example:</p> + +<pre> +<activity android:name=".ExampleAppWidgetConfigure"> + <intent-filter> + <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE" /> + </intent-filter> +</activity> +</pre> + +<p>Also, the Activity must be declared in the AppWidgetProviderInfo XML file, with the +<code>android:configure</code> attribute (see <a href="#MetaData">Adding +the AppWidgetProvierInfo Metadata</a> above). For example, the configuration Activity +can be declared like this:</p> + +<pre> +<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android" + ... + android:configure="com.example.android.ExampleAppWidgetConfigure" + ... > +</appwidget-provider> +</pre> + +<p>Notice that the Activity is declared with a fully-qualified namespace, because +it will be referenced from outside your package scope.</p> + +<p>That's all you need to get started with a configuration Activity. Now all you need is the actual +Activity. There are, however, two important things to remember when you implement the Activity:</p> +<ul> + <li>The App Widget host calls the configuration Activity and the configuration Activity should always + return a result. The result should include the App Widget ID + passed by the Intent that launched the Activity (saved in the Intent extras as + {@link android.appwidget.AppWidgetManager#EXTRA_APPWIDGET_ID}).</li> + <li>The {@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[]) + onUpdate()} method <strong>will not be called</strong> when the App Widget is created + (the system will not send the ACTION_APPWIDGET_UPDATE broadcast when a configuration Activity + is launched). It is the responsibility of the configuration Activity to request an update from the + AppWidgetManager when the App Widget is first created. However, + {@link android.appwidget.AppWidgetProvider#onUpdate(Context,AppWidgetManager,int[]) + onUpdate()} will be called for subsequent updates—it is only skipped the first time.</li> +</ul> + +<p>See the code snippets in the following section for an example of how to return a result +from the configuration and update the App Widget.</p> + + +<h3 id="UpdatingFromTheConfiguration">Updating the App Widget from the configuration Activity</h3> + +<p>When an App Widget uses a configuration Activity, it is the responsibility of the Activity +to update the App Widget when configuration is complete. +You can do so by requesting an update directly from the +{@link android.appwidget.AppWidgetManager}.</p> + +<p>Here's a summary of the procedure to properly update the App Widget and close +the configuration Activity:</p> + +<ol> + <li>First, get the App Widget ID from the Intent that launched the Activity: +<pre> +Intent intent = getIntent(); +Bundle extras = intent.getExtras(); +if (extras != null) { + mAppWidgetId = extras.getInt( + AppWidgetManager.EXTRA_APPWIDGET_ID, + AppWidgetManager.INVALID_APPWIDGET_ID); +} +</pre> + </li> + <li>Perform your App Widget configuration.</li> + <li>When the configuration is complete, get an instance of the AppWidgetManager by calling + {@link android.appwidget.AppWidgetManager#getInstance(Context)}: +<pre> +AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context); +</pre> + </li> + <li>Update the App Widget with a {@link android.widget.RemoteViews} layout by calling + {@link android.appwidget.AppWidgetManager#updateAppWidget(int,RemoteViews)}: +<pre> +RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget); +appWidgetManager.updateAppWidget(mAppWidgetId, views); +</pre> + </li> + <li>Finally, create the return Intent, set it with the Activity result, and finish the Activity:</li> +<pre> +Intent resultValue = new Intent(); +resultValue.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, mAppWidgetId); +setResult(RESULT_OK, resultValue); +finish(); +</pre> + </li> +</ol> + +<p class="note"><strong>Tip:</strong> When your configuration Activity first opens, set +the Activity result to RESULT_CANCELED. This way, if the user backs-out of the Activity before +reaching the end, the App Widget host is notified that the configuration was cancelled and the +App Widget will not be added.</p> + +<p>See the <a +href="{@docRoot}guide/samples/ApiDemos/src/com/example/android/apis/appwidget/ExampleAppWidgetConfigure.html"> +ExampleAppWidgetConfigure.java</a> sample class in ApiDemos for an example.</p> + + + diff --git a/docs/html/guide/topics/fundamentals.jd b/docs/html/guide/topics/fundamentals.jd index 3c7f419..71705d3 100644 --- a/docs/html/guide/topics/fundamentals.jd +++ b/docs/html/guide/topics/fundamentals.jd @@ -464,7 +464,7 @@ two intent filters to the activity: </intent-filter> <intent-filter . . . > <action android:name="com.example.project.BOUNCE" /> - <data android:type="image/jpeg" /> + <data android:mimeType="image/jpeg" /> <category android:name="android.intent.category.DEFAULT" /> </intent-filter> </activity> diff --git a/docs/html/guide/topics/geo/lbs.jd b/docs/html/guide/topics/geo/lbs.jd deleted file mode 100644 index 981f6fe..0000000 --- a/docs/html/guide/topics/geo/lbs.jd +++ /dev/null @@ -1,73 +0,0 @@ -page.title=Location-based Service APIs -@jd:body - -<p>The Android SDK includes two packages that provide Android's primary support -for building location-based services: -{@link android.location} and com.google.android.maps. -Please read on below for a brief introduction to each package.</p> - -<h2>android.location</h2> - -<p>This package contains several classes related to -location services in the Android platform. Most importantly, it introduces the -{@link android.location.LocationManager} -service, which provides an API to determine location and bearing if the -underlying device (if it supports the service). The LocationManager -should <strong>not</strong> be -instantiated directly; rather, a handle to it should be retrieved via -{@link android.content.Context#getSystemService(String) -getSystemService(Context.LOCATION_SERVICE)}.</p> - -<p>Once your application has a handle to the LocationManager, your application -will be able to do three things:</p> - -<ul> - <li>Query for the list of all LocationProviders known to the - LocationManager for its last known location.</li> - <li>Register/unregister for periodic updates of current location from a - LocationProvider (specified either by Criteria or name).</li> - <li>Register/unregister for a given Intent to be fired if the device comes - within a given proximity (specified by radius in meters) of a given - lat/long.</li> -</ul> - -<p>However, during initial development, you may not have access to real -data from a real location provider (Network or GPS). So it may be necessary to -spoof some data for your application, with some mock location data.</p> - -<p class="note"><strong>Note:</strong> If you've used mock LocationProviders in -previous versions of the SDK (m3/m5), you can no longer provide canned LocationProviders -in the /system/etc/location directory. These directories will be wiped during boot-up. -Please follow the new procedures below.</p> - - -<h3>Providing Mock Location Data</h3> - -<p>When testing your application on the Android emulator, there are a couple different -ways to send it some spoof location data: with the DDMS tool or the "geo" command.</p> - -<h4 id="ddms">Using DDMS</h4> -<p>With the DDMS tool, you can simulate location data a few different ways:</p> -<ul> - <li>Manually send individual longitude/latitude coordinates to the device.</li> - <li>Use a GPX file describing a route for playback to the device.</li> - <li>Use a KML file describing individual placemarks for sequenced playback to the device.</li> -</ul> -<p>For more information on using DDMS to spoof location data, see the -<a href="{@docRoot}reference/ddms.html#emulator-control">Using DDMS guide</a>. - -<h4 id="geo">Using the "geo" command</h4> -<p>Launch your application in the Android emulator and open a terminal/console in -your SDK's <code>/tools</code> directory. Now you can use:</p> -<ul><li><code>geo fix</code> to send a fixed geo-location. - <p>This command accepts a longitude and latitude in decimal degrees, and - an optional altitude in meters. For example:</p> - <pre>geo fix -121.45356 46.51119 4392</pre> - </li> - <li><code>geo nmea</code> to send an NMEA 0183 sentence. - <p>This command accepts a single NMEA sentence of type '$GPGGA' (fix data) or '$GPRMC' (transit data). - For example:</p> - <pre>geo nmea $GPRMC,081836,A,3751.65,S,14507.36,E,000.0,360.0,130998,011.3,E*62</pre> - </li> -</ul> - diff --git a/docs/html/guide/topics/geo/mapkey.jd b/docs/html/guide/topics/geo/mapkey.jd deleted file mode 100644 index 6442940..0000000 --- a/docs/html/guide/topics/geo/mapkey.jd +++ /dev/null @@ -1,28 +0,0 @@ -page.title=Obtaining a MapView API Key -@jd:body - -<p>MapView is a very useful class that lets you easily integrate Google Maps into your application. It provides built-in map downloading, rendering, and caching, as well as a variety of display options and controls. It provides a wrapper around the Google Maps API that lets your application request and manipulate Google Maps data through class methods, and it lets you work with Maps data as you would other types of Views. </p> - -<p>Because MapView gives you access to Google Maps data, you need to register your application with the Google Maps service and agree to the applicable Terms of Service, before your MapView will be able to obtain data from Google Maps. This will apply whether you are developing your application on the emulator or preparing your application for deployment to mobile devices. </p> - -<p>Registering your application is simple, and has two parts: </p> - -<ol> -<li>Registering a public key fingerprint from the certificate that you will use to sign the .apk. The registration service then provides you a Maps API Key that is associated with your application's signer certificate. </li> -<li>Adding the Maps API Key to a special attribute of the MapView element — <code>android:apiKey</code>. You can use the same Maps API Key for any MapView in any application, provided that the application's .apk is signed with the certificate whose fingerprint you registered with the service. </li> -</ol> - -<p>Once you have registered your application as described above, your MapView will be able to retrieve data from the Google Maps servers. </p> - -<div class="special"> -<p>The MapView registration service is not yet active and Google Maps is not yet enforcing the Maps API Key requirement. The registration service will be activated soon, so that MapViews in any application deployed to a mobile device will require registration and a valid Maps API Key.</p> - -<p>As soon as the registration service becomes available, this page (<a href="http://code.google.com/android/toolbox/apis/mapkey.html">http://code.google.com/android/toolbox/apis/mapkey.html</a>) will be updated with details about how and where to register and how to add your Maps API Key to your application. </p> - -<p>In the meantime, you can continue developing your MapView without registration, provided that you:</p> -<ol type="a"> -<li>Add the attribute "android:apiKey" to the MapView element in your layout XML, with any value. Or</li> -<li>Include an arbitrary string in the <code>apikey</code> parameter of the MapView constructor, if creating the MapView programmatically. </li> -</ol> - -<p>When the Maps API Key checking is activated in the service, any MapViews that do not have a properly registered apiKey will stop working. The map data (tile images) of the MapView will never load (even if the device is on the network). In this case, go to the page linked above and read about how to register your certificate fingerprint and obtain a Maps API Key. </p> diff --git a/docs/html/guide/topics/graphics/2d-graphics.jd b/docs/html/guide/topics/graphics/2d-graphics.jd index 1f62f3d..af584a2 100644 --- a/docs/html/guide/topics/graphics/2d-graphics.jd +++ b/docs/html/guide/topics/graphics/2d-graphics.jd @@ -10,8 +10,8 @@ parent.link=index.html <ol> <li><a href="#drawables">Drawables</a> <ol> - <li><a href="#drawable-images">Creating from resource images</a></li> - <li><a href="#drawable-xml">Creating from resource XML</a></li> + <li><a href="#drawables-from-images">Creating from resource images</a></li> + <li><a href="#drawables-from-xml">Creating from resource XML</a></li> </ol> </li> <li><a href="#shape-drawable">ShapeDrawable</a></li> @@ -59,6 +59,15 @@ From there, you can reference it from your code or your XML layout. Either way, it is referred using a resource ID, which is the file name without the file type extension (E.g., <code>my_image.png</code> is referenced as <var>my_image</var>).</p> +<p class="note"><strong>Note:</strong> Image resources placed in <code>res/drawable/</code> may be +automatically optimized with lossless image compression by the +<a href="{@docRoot}guide/developing/tools/aapt.html">aapt</a> tool. For example, a true-color PNG that does +not require more than 256 colors may be converted to an 8-bit PNG with a color palette. This +will result in an image of equal quality but which requires less memory. So be aware that the +image binaries placed in this directory can change during the build. If you plan on reading +an image as a bit stream in order to convert it to a bitmap, put your images in the <code>res/raw/</code> +folder instead, where they will not be optimized.</p> + <h4>Example code</h4> <p>The following code snippet demonstrates how to build an {@link android.widget.ImageView} that uses an image from drawable resources and add it to the layout.</p> @@ -90,7 +99,7 @@ Resources res = mContext.getResources(); Drawable myImage = res.getDrawable(R.drawable.my_image); </pre> -<p class="caution"><strong>Caution:</strong> Each unique resource in your project can maintain only one +<p class="warning"><strong>Note:</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, diff --git a/docs/html/guide/topics/graphics/opengl.jd b/docs/html/guide/topics/graphics/opengl.jd index eb2932d..901980d 100644 --- a/docs/html/guide/topics/graphics/opengl.jd +++ b/docs/html/guide/topics/graphics/opengl.jd @@ -26,10 +26,7 @@ ES API. However, it may not be identical, so watch out for deviations.</p> <li>In your View's onDraw() method, get a handle to a GL object, and use its methods to perform GL operations.</li> </ol> -<p>For an example of this usage model (based on the classic GL ColorCube), -see -<a href="{@docRoot}guide/samples/ApiDemos/src/com/example/android/apis/graphics/GLSurfaceView.html">com.android.samples.graphics.GLSurfaceView.java</a> -in the ApiDemos sample code project. A slightly more sophisticated version showing how to use +<p>For an example of this usage model (based on the classic GL ColorCube), showing how to use it with threads can be found in <a href="{@docRoot}guide/samples/ApiDemos/src/com/example/android/apis/graphics/GLSurfaceViewActivity.html">com.android.samples.graphics.GLSurfaceViewActivity.java</a>. </p> diff --git a/docs/html/guide/topics/location/geo/mapkey.jd b/docs/html/guide/topics/location/geo/mapkey.jd deleted file mode 100644 index 9aa824c..0000000 --- a/docs/html/guide/topics/location/geo/mapkey.jd +++ /dev/null @@ -1,210 +0,0 @@ -page.title=Obtaining a Maps API Key -@jd:body - -<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> - -</div> - -<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 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>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> - -<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>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> - -<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>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 53f1d29..e988ecb 100644 --- a/docs/html/guide/topics/location/index.jd +++ b/docs/html/guide/topics/location/index.jd @@ -1,35 +1,43 @@ -page.title=Location +page.title=Location and Maps @jd:body <div id="qv-wrapper"> <div id="qv"> + <h2>Location and Maps quickview</h2> + <ul> + <li>Android provides a location framework that your application can use to determine the device's location and bearing and register for updates.</li> + <li>A Google Maps external library is available that lets you display and manage Maps data.</li> + </ul> <h2>In this document</h2> <ol> - <li><a href="#location">android.location</a></li> - <li><a href="#maps">com.google.android.maps</a></li> + <li><a href="#location">Location Services</a></li> + <li><a href="#maps">Google Maps External Library</a></li> + </ol> + <h2>See Also</h2> + <ol> + <li><a href="http://code.google.com/android/add-ons/google-apis/index.html">Google APIs add-on download»</a></li> </ol> </div> </div> -<p>The Android SDK includes two packages that provide Android's primary support -for building location-based services: -{@link android.location} and {@link-fixme com.google.android.maps}. -Please read on below for a brief introduction to each package.</p> +<p>Location- and maps-based applications and services are compelling for mobile device users. You can build these capabilities into your applications using the classes of the {@link android.location} package and the Google Maps external library. The sections below provide details. </p> + +<h2 id="location">Location Services</h2> -<h2 id="location">android.location</h2> +<p>Android gives your applications access to the location services supported by +the device through the classes in the <code>android.location</code> package. The +central component of the location framework is the +{@link android.location.LocationManager} system service, which provides an API to +determine location and bearing if the underlying device (if it supports location +capabilities). </p> -<p>This package contains several classes related to -location services in the Android platform. Most importantly, it introduces the -{@link android.location.LocationManager} -service, which provides an API to determine location and bearing if the -underlying device (if it supports the service). The LocationManager -should <strong>not</strong> be -instantiated directly; rather, a handle to it should be retrieved via -{@link android.content.Context#getSystemService(String) -getSystemService(Context.LOCATION_SERVICE)}.</p> +<p>As with other system services, you do not instantiate a LocationManager directly. +Rather, you request an LocationManager instance from the system by calling +{@link android.content.Context#getSystemService(String) getSystemService(Context.LOCATION_SERVICE)}. +The method returns a handle to a new LocationManager instance.</p> -<p>Once your application has a handle to the LocationManager, your application +<p>Once your application has a handle to a LocationManager instance, your application will be able to do three things:</p> <ul> @@ -42,20 +50,20 @@ will be able to do three things:</p> lat/long.</li> </ul> -<p>However, during initial development, you may not have access to real -data from a real location provider (Network or GPS). So it may be necessary to -spoof some data for your application, with some mock location data.</p> +<p>However, during initial development in the emulator, you may not have access to real +data from a real location provider (Network or GPS). In that case, it may be necessary to +spoof some data for your application using a mock location provider.</p> <p class="note"><strong>Note:</strong> If you've used mock LocationProviders in -previous versions of the SDK (m3/m5), you can no longer provide canned LocationProviders +previous versions of the SDK, you can no longer provide canned LocationProviders in the /system/etc/location directory. These directories will be wiped during boot-up. -Please follow the new procedures below.</p> - +Please follow the new procedures outlined below.</p> <h3>Providing Mock Location Data</h3> <p>When testing your application on the Android emulator, there are a couple different -ways to send it some spoof location data: with the DDMS tool or the "geo" command.</p> +ways to send it some mock location data: you can use the DDMS tool or the "geo" command +option in the emulator console.</p> <h4 id="ddms">Using DDMS</h4> <p>With the DDMS tool, you can simulate location data a few different ways:</p> @@ -67,9 +75,9 @@ ways to send it some spoof location data: with the DDMS tool or the "geo" comman <p>For more information on using DDMS to spoof location data, see the <a href="{@docRoot}guide/developing/tools/ddms.html#emulator-control">Using DDMS guide</a>. -<h4 id="geo">Using the "geo" command</h4> +<h4 id="geo">Using the "geo" command in the emulator console</h4> <p>Launch your application in the Android emulator and open a terminal/console in -your SDK's <code>/tools</code> directory. Now you can use:</p> +your SDK's <code>/tools</code> directory. Connect to the emulator console. Now you can use:</p> <ul><li><code>geo fix</code> to send a fixed geo-location. <p>This command accepts a longitude and latitude in decimal degrees, and an optional altitude in meters. For example:</p> @@ -82,28 +90,51 @@ your SDK's <code>/tools</code> directory. Now you can use:</p> </li> </ul> - -<h2 id="maps">com.google.android.maps</h2> - -<p>This package introduces a number of classes related to -rendering, controlling, and overlaying customized information on your own -Google Mapified Activity. The most important of which is the -{@link-fixme com.google.android.maps.MapView} class, which automagically draws you a -basic Google Map when you add a MapView to your layout. Note that, if you -want to do so, then your Activity that handles the -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/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 -retrieve a {@link-fixme com.google.android.maps.MapController}, for controlling and -animating the map, and {@link-fixme com.google.android.maps.ItemizedOverlay} to -draw {@link-fixme com.google.android.maps.Overlay}s and other information on the Map.</p> - -<p>This is not a standard package in the Android library. In order to use it, you must add the following node to your Android Manifest file, as a child of the -<code><application></code> element:</p> -<pre><uses-library android:name="com.google.android.maps" /></pre> +<p>For information about how to connect to the emulator console, see +<a href="{@docRoot}guide/developing/tools/emulator.html#console">Using the Emulator Console</a>.</p> + +<h2 id="maps">Google Maps External Library</h2> + +<p>To make it easier for you to add powerful mapping capabilities to your +application, Google provides a Maps external library that includes the +com.google.android.maps package. The classes of the com.google.android.maps +package offer built-in downloading, rendering, and caching of Maps tiles, as +well as a variety of display options and controls. </p> + +<p>The key class in the Maps package is +<code>com.google.android.maps.MapView</code>, a subclass of +{@link android.view.ViewGroup ViewGroup}. A MapView displays a map with data obtained +from the Google Maps service. When the MapView has focus, it will capture +keypresses and touch gestures to pan and zoom the map automatically, including +handling network requests for additional maps tiles. It also provides all of the +UI elements necessary for users to control the map. Your application can also +use MapView class methods to control the MapView programmatically and draw a +number of Overlay types on top of the map. </p> + +<p>In general, the MapView class provides a wrapper around the Google Maps API +that lets your application manipulate Google Maps data through class methods, +and it lets you work with Maps data as you would other types of Views.</p> + +<p>The Maps external library is not part of the standard Android library, so it +may not be present on some compliant Android-powered devices. Similarly, the +Maps external library is not included in the standard Android library provided +in the SDK. So that you can develop using the classes of the +com.google.android.maps package, the Maps external library is made available to +you as part of the Google APIs add-on for the Android SDK. </p> + +<p>To learn more about the Maps external library and how to download and use the +Google APIs add-on, visit</p> + +<p style="margin-left:2em;"><a +href="http://code.google.com/android/add-ons/google-apis">http://code.google.com/android/add-ons/google-apis</a></p> + +<p>For your convenience, the Google APIs add-on is also included in the Android +SDK. <!-- To learn now to use the Maps external library in your application, see +[[Using External Libraries]].--></p> + +<p class="note"><strong>Note:</strong> In order to display Google Maps data in a +MapView, you must register with the Google Maps service and obtain a Maps API +Key. For information about how to get a Maps API Key, see <a +href="http://code.google.com/android/add-ons/google-apis/mapkey.html">Obtaining +a Maps API Key</a>.</p> diff --git a/docs/html/guide/topics/media/index.jd b/docs/html/guide/topics/media/index.jd index 4541024..96c500c 100644 --- a/docs/html/guide/topics/media/index.jd +++ b/docs/html/guide/topics/media/index.jd @@ -9,24 +9,33 @@ page.title=Audio and Video <li>Audio playback and record</li> <li>Video playback</li> <li>Handles data from raw resources, files, streams</li> -<li>Built-in codecs for a variety of media. See <a href="{@docRoot}guide/appendix/media-formats.html">Android 1.0 Media Formats</a></li> +<li>Built-in codecs for a variety of media. See <a href="{@docRoot}guide/appendix/media-formats.html">Android Supported Media Formats</a></li> </ul> <h2>Key classes</h2> <ol> -<li><a href="{@docRoot}reference/android/media/MediaPlayer.html">MediaPlayer</a> (all audio and video formats)</li> -<li><a href="{@docRoot}reference/android/media/MediaRecorder.html">MediaRecorder</a> (record, all audio formats)</li> +<li>{@link android.media.MediaPlayer MediaPlayer} (all available formats)</li> +<li>{@link android.media.MediaRecorder MediaRecorder} (all available formats)</li> +<li>{@link android.media.JetPlayer JetPlayer} (playback, JET content)</li> +<li>{@link android.media.SoundPool SoundPool} (sound management)</li> </ol> <h2>In this document</h2> <ol> -<li><a href="#playback.html">Audio and Video Playback</a></li> +<li><a href="#playback.html">Audio and Video Playback</a> + <ol> + <li><a href="#playraw">Playing from a Raw Resource</li> + <li><a href="#playfile">Playing from a File or Stream</li> + <li><a href="#jet">Playing JET Content</li> + </ol> +</li> <li><a href="#capture">Audio Capture</a></li> </ol> <h2>See also</h2> <ol> <li><a href="{@docRoot}guide/topics/data/data-storage.html">Data Storage</a></li> +<li><a href="{@docRoot}guide/topics/media/jet/jetcreator_manual.html">JetCreator User Manual</a></li> </ol> </div> @@ -115,6 +124,28 @@ above.</p> If you're passing a URL to an online media file, the file must be capable of progressive download.</p> +<h3 id="jet">Playing JET content</h3> +<p>The Android platform includes a JET engine that lets you add interactive playback of JET audio content in your applications. You can create JET content for interactive playback using the JetCreator authoring application that ships with the SDK. To play and manage JET content from your application, use the {@link android.media.JetPlayer JetPlayer} class.</p> + +<p>For a description of JET concepts and instructions on how to use the JetCreator authoring tool, see the <a href="{@docRoot}guide/topics/media/jet/jetcreator_manual.html">JetCreator User Manual</a>. The tool is available fully-featured on the OS X and Windows platforms and the Linux version supports all the content creation features, but not the auditioning of the imported assets. </p> + +<p>Here's an example of how to set up JET playback from a .jet file stored on the SD card:</p> + +<pre> +JetPlayer myJet = JetPlayer.getJetPlayer(); +myJet.loadJetFile("/sdcard/level1.jet"); +byte segmentId = 0; + +// queue segment 5, repeat once, use General MIDI, transpose by -1 octave +myJet.queueJetSegment(5, -1, 1, -1, 0, segmentId++); +// queue segment 2 +myJet.queueJetSegment(2, -1, 0, 0, 0, segmentId++); + +myJet.play(); +</pre> + +<p>The SDK includes an example application — JetBoy — that shows how to use {@link android.media.JetPlayer JetPlayer} to create an interactive music soundtrack in your game. It also illustrates how to use JET events to synchronize music and game logic. The application is located at <code><sdk>/platforms/android-1.5/samples/JetBoy</code>. + <h2 id="capture">Audio Capture</h2> <p>Audio capture from the device is a bit more complicated than audio/video playback, but still fairly simple:</p> <ol> diff --git a/docs/html/guide/topics/media/jet/jetcreator_manual.jd b/docs/html/guide/topics/media/jet/jetcreator_manual.jd new file mode 100644 index 0000000..9692d97 --- /dev/null +++ b/docs/html/guide/topics/media/jet/jetcreator_manual.jd @@ -0,0 +1,1152 @@ +page.title=SONiVOX JETCreator User Manual +@jd:body + + + +<p>Content Authoring Application for the JET Interactive Music Engine</p> + + +<h1>1 Introduction</h1> + +<h2>1.1 Overview</h2> + +<p>This document contains the user guidelines +for the SONiVOX JET Creator, an authoring application for creating and +auditioning JET files. JET is an interactive music player for small embedded +devices, including the those running the Android platform. It allows applications to +include interactive music soundtracks, in MIDI +format, that respond in real-time to game play events and user interaction.</p> + + +<p>JET works in conjunction with SONiVOX's +Embedded Audio Synthesizer (EAS) which is the MIDI +playback device for Android. Both the +JET and EAS engines are integrated into the Android embedded platform through the +{@link android.media.JetPlayer} class, as well +as inherent in the JET Creator application. As such, the JET content author can +be sure that the playback will sound exactly the same in both the JET Creator +and the final Android application playing back on Android mobile devices.</p> + + +<p>In addition to the graphical user +interface, there are two main functionalities taking place in JET Creator. The +first involves gathering all the source data (MIDI +files and DLS file), adding JET's real-time attributes and building a JET +(.jet) file that the Android application will use. The second functionality +involves auditioning the interactive playback elements as they will take place +in the Android application.</p> + + +<p>The JET Creator application is written in +the Python programming language, therefore you need to have the current version +of Python and WXWidgets installed. There is both a Mac and Windows version.</p> + + +<h2>1.2 Abbreviations and Common Terms</h2> + +<p>It is important to use a common set of +terms to minimize confusion. Since JET uses MIDI +in a unique way, normal industry terms may not always suffice. Here is the +definition of terms as they are used in this document and in the JET Creator +application:</p> + + +<p><i>Channel</i>: MIDI data associated with a specific MIDI +channel. Standard MIDI allows for 16 channels of MIDI +data each of which are typically associated with a specific instrument. </p> + + + +<p><i>Controller</i>: A MIDI event consisting of a +channel number, controller number, and a controller value. The MIDI + spec associates many controller numbers with +specific functions, such as volume, expression, sustain pedal, etc. JET also +uses controller events as a means of embedding special control information in a +MIDI sequence to provide for audio synchronization.</p> + + + +<p><i>DAW</i>: Digital Audio Workstation. A common term for MIDI +and audio sequencing applications such as Logic, SONAR, Cubase and others. </p> + + + +<p><i>EAS:</i> Embedded MIDI Synthesizer. The +name of the SONiVOX MIDI synthesizer engine.</p> + + + +<p><i>JET</i>: Jet Interactive Engine. The name of the SONiVOX JET interactive +music engine.</p> + + + +<p><i>M/B/T</i>: Measures, Beats and Ticks</p> + + + +<p><i>Segment</i>: A musical section such as a chorus or verse that is a component of +the overall composition. In JET, a segment can be an entire MIDI file or a +derived from a portion of a MIDI file.</p> + + + +<p><i>SMF-0</i>: Standard MIDI File Type 0, a MIDI file that contains a single +track, but may be made up of multiple channels of MIDI +data.</p> + + + +<p><i>SMF-1</i>: Standard MIDI File Type 1, a MIDI file that contains a one more +tracks, and each track may in turn be made up of one or more channels of MIDI + data. By convention, each channel is stored on a +separate track in an SMF-1 file. However, it is possible to have multiple MIDI +channels on a single track, or multiple tracks that contain data for the same MIDI +channel.</p> + + + +<p><i>Track</i>: A single track in a DAW containing a timed sequence of events. Be careful not to confuse Tracks with +Channels. A MIDI file may contain many tracks with several tracks utilizing the +same MIDI channel. </p> + + + + + +<h1>2 The JET Interactive Music Concept</h1> + +<p>Interactive music can be defined as music +that changes in real-time according to non-predictable events such as user +interaction or game play events. In this way, interactive music is much more +engaging as it has the ability to match the energy and mood of a game much +closer than a pre-composed composition that never changes. In some applications +and games, interactive music is central to the game play. Guitar Hero is one +such popular game. When the end user successfully captures the musical notes +coming down the fret board, the music adapts itself and simultaneously keeps +score of successes and failures. JET allows for these types of music driven +games as well.</p> + + + +<p>There are several methods for making and +controlling interactive music and JET is one such method. This section +describes the features of JET and how they might be used in a game or software +application. It also describes how JET can be used to save memory in small +footprint devices such as Android enabled mobile handsets.</p> + +<h3>2.1.1 Data Compression</h3> + +<p>JET supports a flexible music format that +can be used to create extended musical sequences with a minimal amount of data. +A musical composition is broken up into segments that can be sequenced to +create a longer piece. The sequencing can be fixed at the time the music file +is authored, or it can be created dynamically under program control.</p> + +<h3>2.1.2 Linear Music Example</h3> + +<p> +<img border=0 width=575 height=393 src="{@docRoot}images/jet/linear_music.png"> +<br>Figure 1: Linear Music Piece</p> + +<p>This diagram shows how musical segments are +stored. Each segment is authored as a separate MIDI +file. A post-processing tool combines the files into a single container file. +Each segment can contain alternate music tracks that can be muted or un-muted +to create additional interest. An example might be a brass accent in the chorus +that is played only the last time through. Also, segments can be transposed up +or down.</p> + + +<p>The bottom part of the diagram shows how +the musical segments can be recombined to create a linear music piece. In this +example, the bridge might end with a half-step key modulation and the remaining +segments could be transposed up a half-step to match.</p> + +<h3>2.1.3 Non-linear Music Example</h3> + +<p> +<img border=0 width=576 height=389 +src="{@docRoot}images/jet/nonlinear_music.png"> +<br>Figure 2: Non-linear music piece</p> + + +<p>In this diagram, we see a non-linear music +piece. The scenario is a first-person-shooter (FPS) and JET is providing the +background music. The intro plays as the level is loading and then transitions +under program control to the Searching segment. This segment is repeated indefinitely, +perhaps with small variations (using the mute/un-mute feature) until activity +in the game dictates a change.</p> + + + +<p>As the player nears a monster lair, the +program starts a synchronized transition to the Danger segment, increasing the +tension level in the audio. As the player draws closer to the lair, additional +tracks are un-muted to increase the tension.</p> + + + +<p>As the player enters into combat with the +monster, the program starts a synchronized transition to the Combat segment. +The segment repeats indefinitely as the combat continues. A Bonus Hit +temporarily un-mutes a decorative track that notifies the player of a +successful attack, and similarly, another track is temporarily un-muted to +signify when the player receives Special Damage.</p> + + + +<p>At the end of combat, the music transitions +to a victory or defeat segment based on the outcome of battle.</p> + +<h3>2.1.4 Mute/Un-mute Synchronization</h3> + +<p>JET can also synchronize the muting and +un-muting of tracks to events in the music. For example, in the FPS game, it would +probably be desirable to place the musical events relating to bonuses and +damage as close to the actual game event as possible. However, simply un-muting +a track at the moment the game event occurs might result in a music clip +starting in the middle. Alternatively, a clip could be started from the +beginning, but then it wouldn't be synchronized with the other music tracks.</p> + + +<p>However, with the JET sync engine, a clip +can be started at the next opportune moment and maintain synchronization. This +can be accomplished by placing a number of short music clips on a decorative +track. A MIDI event in the stream signifies +the start of a clip and a second event signifies the end of a clip. When the +application calls the JET clip function, the next clip in the track is allowed +to play fully synchronized to the music. Optionally, the track can be +automatically muted by a second MIDI event.</p> + + +<p> +<img border=0 width=576 height=155 +src="{@docRoot}images/jet/sync_muteunmute.png"> +<br>Figure 3: Synchronized Mute/Unmute</p> + + +<h2>2.2 Audio Synchronization</h2> + +<p>JET provides an audio synchronization API +that allows game play to be synchronized to events in the audio. The mechanism +relies on data embedded in the MIDI file at +the time the content is authored. When the JET engine senses an event during +playback it generates a callback into the application program. The timing of +the callback can be adjusted to compensate for any latency in the audio +playback system so that audio and video can be synchronized. The diagram below +shows an example of a simple music game that involves pressing the left and +right arrows in time with the music.</p> + +<p><img border=0 width=576 height=134 +src="{@docRoot}images/jet/music_game.png"> +<br>Figure 4: Music Game</p> + + + +<p>The arrows represent events in the music sequence +where game events need to be synchronized. In this case, the blue arrow +represents a time where the player is supposed to press the left button, and +the red arrow is for the right button. The yellow arrow tells the game engine +that the sequence is complete. The player is allowed a certain time window +before and after the event to press the appropriate key.</p> + + + +<p>If an event is received and the player has +not pressed a button, a timer is set to half the length of the window. If the +player presses the button before the timer expires, the game registers a +success, and if not, the game registers a failure. </p> + + + +<p>If the player presses the button before the +event is received, a timer is set to half the length of the window. If an event +is received before the timer expires, the game registers a success, and if not, +the game registers a failure. Game play might also include bonuses for getting +close to the timing of the actual event. </p> + + + +<h1>3 JET Content Authoring Overview</h1> + +<p>To author JET files and hear them playback +interactively, the content author will work in two applications which are +designed to work together smoothly. The first is application is any +off-the-shelf MIDI sequencing application that +supports VST (for PC) or AU (for Mac) plugins. Here the author will compose +their MIDI music files using the plugin as the +synthesizer device. The second application is the JET Creator application. Here +the author will import their MIDI music files +(and optionally a DLS2 soundset) and setup the conditions for interactive +playback within the JET enabled game. Optionally the content author may create +a custom set of DLS instruments using an instrument editor that supports the +DLS Level 2 format. One such application is Awave from MJSoft. </p> + +<p>Please see the JET Content Authoring Guidelines</i> documentation for additional +details on content authoring.</p> + + + +<h1>4 Installing and Launching JET Creator</h1> + +<p>JET Creator is a python language +application, therefore, you must have Python and wxPython installed on your +machine. </p> + + +<p>JetCreator was created and tested with:</p> + +<p>Python Version 2.5.4</p> + +<p>wxPython Version 2.8.7.1</p> + + +<p>These can be downloaded here:</p> + + + +<p>PC:</p> +<ul> +<li>http://www.python.org/download/releases/2.5.4/</li> + +<li>http://www.wxpython.org/download.php</li> +</ul> + + +<p>MAC:</p> +<ul> +<li>http://wiki.python.org/moin/MacPython/Leopard</li> + +<li>http://www.wxpython.org/download.php</li> +</ul> + + +<p>After installing Python and wxPython, +simply unzip or copy all the files in the JET Creator application directory to +a folder on your hard drive.</p> + + +<p>To launch JET Creator go to a command +prompt and set the directory to where you've installed Python. Next run python +with the command:</p> + +<p><pre>python jetcreator.py</pre></p> + + + + + +<h1>5 Using JET Creator</h1> + + + +<h2>5.1 File Types</h2> + +<p>There are a few different file types +associated with JET Creator.</p> + + + +<p>.jtc JET +Creator project file. This file contains all the information associated with a +JET Creator project. When you Save or Save-as out of JET Creator, this file +type is saved.</p> + + + +<p>.jet JET +File. This output file is automatically generated from JET Creator whenever you +save your JET Creator project. This is the file that bundles all JET assets +together into a single file that the Android application will use. Give this +file to the Android application developer.</p> + + + +<p>.mid File. This is the standard MIDI +type 1 file that JET Creator will use to make segments.</p> + + + +<p>.seg Segment +File. This is a JET Segment file. It has the same name as the MIDI +file which it references but contains additional Segment information.</p> + + + +<p>.zip Zip +Archive file. When you Export a JET Archive, a zip file is created that +contains all the assets (files) necessary for JET Creator. Use this to transfer +JET Creator projects to other people.</p> + + + +<h2>5.2 Open Dialog</h2> + +<p>When +you first launch JET Creator you are presented with an open dialog like the +following.</p> + + + +<p><img border=0 width=450 height=285 +src="{@docRoot}images/jet/jc_open_dlg.png" +</p> + + + + + +<p> <b>Open</b> will open an existing .jtc (JET Creator file) file. Use the browser +button to browse to the directory where you have saved your .jtc file.</p> + + + +<p> <b>New</b> will create a new .jtc file.</p> + + + +<p> <b>Import</b> will import a JET Archive (.zip) file.</p> + + + +<p> <b>Cancel</b> will cancel the dialog and exit the application.</p> + + + + + +<h1>5 Main Window </h1> + +<p>The main window of the JET Creator +application looks like the picture below. There are three main sections from +top to bottom: segment view, event view, and timeline. </p> + + + +<p>The segment view section displays a list of +the current segments, which MIDI file and +(optionally) DLS2 file each segment is derived from. It also shows each +segments start and stop time and each segments quantize, transpose, repeat and +mute flag settings.</p> + + + +<p>Just below the Segment view is the event +view. The event view section displays all events associated with a given +segment. Events only display when the segment they are assigned to is +highlighted. Each event displays its type, start and end points, track and midi +channel assignment, and its event ID.</p> + + + +<p>Just below the Event view is the timeline +display. The timeline shows how many measures a given segment is as well as any +events associated with that segment. The timeline changes to display the +currently selected or playing segment. You can trigger an event in this window +while the segment is play by simply clicking on the event in the timeline +display.</p> + + +<p><img border=0 width=554 height=378 +src="{@docRoot}images/jet/jc_main_wnd.png"> +<br><i>JET +Creator Main Window<o:p></o:p></i></p> + + +<p>The buttons along the left side of main +window do the following:</p> + +<p>Add: +Displays the segment or event window for adding a new segment or event</p> + +<p>Revise: +Displays the segment or event window for updating an existing segment or event</p> + +<p>Delete: +Deletes the selected segment or event (will ask for confirmation)</p> + +<p>Move: +Displays the move window which allows you to move selected segments or events +in time</p> + +<p>Queue All: Queue's +(selects) all segments for playback</p> + +<p>Dequeue All: Dequeues +(deselects) all segments</p> + +<p>Play: +Starts playback of all queued segments. This button changes to Stop if any +segments are playing</p> + +<p>Audition: +Displays the Audition window (see below)</p> + + + +<h2>5.1 Segment Window</h2> + +<p>The segment window is where a given +segment's attributes are assigned and auditioned, as shown in the picture +below. The left side of the window displays the segments attributes that are +stored in the JET file. The right side of the window allows the author to set +mute flags, repeat and transpose settings and audition the segment as it will +play in the JET game.</p> + + + +<p><b>Note</b>: the audition attributes (mute flags, repeat and transpose) are <i +>not</i> stored in the JET content file +(.jet) but rather are defined by the game or application itself. In programming +language, these settings correspond directly with the API calls to the JET +engine. By including them here, the JET content author can simulate how the +segment will respond to the applications API commands during game play.</p> + + + +<p><img border=0 width=553 height=295 +src="{@docRoot}images/jet/jc_seg_wnd.png" > +</p> + +<p>The segment parameters do the following:</p> + +<ul> +<li>Segment Name - Sets +the name of the segment</li> + +<li>MIDI File - +The name and location of the MIDI file from which +the segment is derived. The button to the immediate right will bring up a +browser for locating a midi file on the hard drive.</li> + +<li>DLS File - +The name and location of the DLS2 file, if any, that the MIDI +file uses for that segment.</li> + +<li>Starting M/B/T - +Starting measure, beat and tick of the segment</li> + +<li>Ending M/B/T - +Ending measure, beat and tick of the segment</li> + +<li>Quantize - +Quantize value for quantizing the current segment during playback</li> + +</ul> + +<p>The audition fields are as follows:</p> + +<ul> +<li>Track Mutes - +Shows the MIDI <b>tracks</b> (not channels) +in the MIDI file. Clicking on a track's +checkbox will mute that track. </li> + +<li>Channel - +Displays the MIDI channel assigned to each +track</li> + +<li>Name - +Displays the track name meta event (if present) for each track</li> + +<li>Repeat - +Indicates the number of times a segment should repeat during playback</li> + +<li>Transpose - +Indicates the transposition in semi-tones or half-steps a segment should +transpose during playback</li> + +<li>To the right of the Audition window are a few additional buttons. +These do as follows:</li> + +<li>OK - +Selecting OK confirms all segment settings and closes the segment window</li> + +<li>Cancel - +Selecting Cancel cancels any changes and closes the segment window</li> + +<li>Replicate - +Displays the Replicate Segment window for entering multiple segments at once. +See below.</li> + +<li>Play/Stop Segment - Starts +or Stops playback of the segment using the segment attributes assigned. </li> + +<li>Play/Stop MIDI File - +Starts or Stops playback of the MIDI file +which the segment is assigned to. </li> + +<li>Pause/Resume - +Pauses or Resumes playback.</li> + +</ul> + + + +<h2>5.2 Event Window</a></h2> + +<p>The event window is where a given segment's +event attributes are assigned and auditioned, as shown in the picture below. To +add an event to a segment, the author must first select the segment which will +contain the event, then select the Add button. This will bring up the Event +window.</p> + + + +<p> +<img border=0 width=554 height=294 +src="{@docRoot}images/jet/jc_event_wnd.png"></p> + + + + + +<p>There are two main sections to the event +window. The segment section on the left side of the event window is for display +only. It shows what the segment attributes are for the given segment. The Event +section, on the right side, is where events can be assigned. The following +parameters are available:</p> + + + +<p>Event Name - +Assigns a name to an event</p> + +<p>Event Type - +Selects which type of event to assign.</p> + +<p>Starting M/B/T - +Sets the starting measure, beat, and tick for the event</p> + +<p>Ending M/B/T - +Sets the ending measure, beat, and tick for the event, if applicable</p> + +<p>Track - +Sets which track in the given segment the event will apply to</p> + +<p>Channel - +Sets which MIDI channel the event will apply +to. The MIDI channel should match the MIDI +channel of the track</p> + +<p>Event ID - +Sets the event ID for the event. Multiple events can be assigned to the same +segment and therefore the Event ID is used to identify them</p> + + + +<p>To the right of the Audition window are a few additional buttons. +These do as follows:</p> + +<p> + +<p>OK - +Selecting OK confirms all event settings and closes the event window</p> + +<p>Cancel - +Selecting Cancel cancels any changes and closes the event window</p> + +<p>Replicate - +Displays the Replicate Event window for entering multiple events at once. See +below.</p> + +<p>Play/Stop - +Starts or Stops playback of the segment using the segment attributes assigned. +While the segment is playing, events can be triggered and auditioned.</p> + +<p>Trigger - +Triggers the event assigned. This replicates the API command that the JET game +will use to trigger the event, therefore giving the content author a method for +auditioning the behaviour of the event.</p> + +<p>Mute/UnMute - +Mute/UnMute will mute or unmute the track that the event is assigned to</p> + +<p>Pause/Resume - +Pauses or Resumes playback.</p> + + + +<p>To audition the behaviour of an event, you +can select the Play button. This will initiate playback. The trigger button +will send the trigger event when pressed. This is equivalent to selecting the +green trigger event in the timeline. </p> + + + +<p>Note: Trigger events are meant to unmute a +single track of a segment when triggered, then mute that track at the end of +the trigger segment. Therefore you should make sure the mute flag is set to +mute the track that a trigger event will be unmuting when receiving a trigger event. +</p> + + + +<p>Please read Section <i>6 Under The Hood</i> +below for details on how trigger events work and behave. </p> + + + +<h2>5.3 Replicate Windows</h2> + +<p>Often in creating JET files, you'll need to +create tens or even hundreds of events. You may also need to move events. The +Replicate and Move windows allow for this. There are two Replicate windows for +creating multiple segments or events. They look like the following:</p> + + + +<p><img border=0 width=395 height=419 +src="{@docRoot}images/jet/jc_rep_wnd.png" ></p> + +<p>Replicate Segment Window</p> + + +<p><img border=0 width=398 height=425 +src="{@docRoot}images/jet/jc_repseg_wnd.png"></p> + + + +<p>Replicate Event Window</p> + + + +<p>Both Replicate windows function the same. +After creating an initial segment or event, you can select the Replicate +button. The parameters are as follows:</p> + + + +<p>Name Prefix - +Sets the prefix for the name of each segment or event created</p> + +<p>Starting M/B/T - +Sets the starting time for the first segment or event</p> + +<p>Increment M/B/T - +Sets the time between segments or events created. </p> + +<p>Number - +Sets the number of segments or events you wish to create. If the number +overflows the length of the MIDI file (for +segments) or segment (for events), those objects will not be created.</p> + +<p>Preview - +Preview allows you to examine the objects created before saying OK to insert +them.</p> + + + + + +<h2>5.4 Move Windows</h2> + +<p>The Move function acts similarly to the +Replicate function in that it allows you to edit multiple segments or events at +one time, in this case move them in time. Like Replicate, there are two Move +windows, one for Segments and one for Events. The windows look like the +following:</p> + + + +<p><img border=0 width=400 height=424 +src="{@docRoot}images/jet/jc_moveseg_wnd.png"></p> + + + +<p>Move Event Window</p> + + + +<p>To use Move, first select the segments or +events you wish to move in time, then click the Move button. The parameters are +as follows:</p> + + + +<p>Starting M/B/T - +Sets the starting time for the first segment or event</p> + +<p>Increment M/B/T - +Sets the time in M/B/T you wish to move the objects by. </p> + +<p>Preview - +Preview allows you to examine the objects created before saying OK to move +them.</p> + + + + + +<h2>5.5 Audition Window</a></h2> + +<p>Clicking the Audition button in the main +window of the JET Creator application will open the Audition window. This is +where the content author or application programmer can simulate the interactive +playback as it may occur in the mobile application or game itself.</p> + + + +<p><img border=0 width=554 height=370 +src="{@docRoot}images/jet/jc_audition_wnd.png"></p> + + + +<p>JET Audition Window</p> + + + + + +<p>There are four main sections to the +audition window. The left most section displays the available segments and +their length in seconds. The middle section displays a running list of what +segments are queued for playback and what their playback status is. The far +right section displays the mute flags for the currently playing segment. The +timeline section at the bottom is the same as in the main window. It displays +the currently playing segment as well as a visual display of any event triggers +associated with that segment. </p> + + + +<p>The Audition window allows you to queue up +any segment in any order for playback. To do this simply select the segment you +wish to cue and hit Queue. That segment will appear in the queue window and +start playing (if it is the first segment). Subsequently you can select any +other segment or segments and cue them up for playback. As the segments +complete playback, the next segment in the queue will begin playing. As is the +other windows of JET Creator, you can mute, unmute, trigger event clips, etc. +in realtime as each segment is playing back.</p> + + + +<p>Specifically the buttons behave as follows:</p> + + + +<p>Queue - +loads the selected segment into the queue and starts playback</p> + +<p>Cancel and Queue - +cancels the currently playing segment before queueing the selected segment for +playback</p> + +<p>Cancel Current - +cancels the currently playing segment in the queue and begins playback of the +next segment</p> + +<p>Stop - +stops playback of all queued segments</p> + +<p>Mute All - +mutes all tracks in the current segment</p> + +<p>Mute None - +unmutes all tracks in the current segment</p> + +<p>Original Mutes - +sets the original mute flags for the current segment</p> + + + +<p>The combination of these playback options +allows an author or application programmer to audition any behaviour an +interactive music application may encounter. </p> + + + + + +<h2>5.6 JET Creator Menus </h2> + +<p>The JET Creator menus provide access to +many of the parameters in the main window plus a few additional parameters.</p> + +<h3>5.6.1 File Menu</h3> + +<p>The File Menu contains the following +elements:</p> + + + +<p>New - +Creates a new JET Creator file (.jtc)</p> + +<p>Open - +Opens an existing JET Creator file</p> + +<p>Save - +Saves the currently opened JET Creator file</p> + +<p>Save As - +Saves the currently opened JET Creator file to a new file</p> + +<p>Import Project - Imports a JET Creator archive (.zip)</p> + +<p>Export Project - Exports a JET Creator archive (.zip)</p> + +<p>Exit - +Exits the application</p> + + + +<h3>5.6.2 Edit Menu</h3> + +<p>The Edit Menu contains the following +elements:</p> + + + +<p>Undo - +Undo will undo the last edit made</p> + +<p>Redo - +Redo will redo the last undo</p> + +<p>Cut - +Copy selected parameter into clipboard and Delete selection</p> + +<p>Copy - +Copy selected parameter into clipboard and keep selection</p> + +<p>Paste - +Paste selected parameter</p> + + + +<h3>5.6.3 JET</h3> + +<p>The Edit Menu contains the following +elements:</p> + + + +<p>Properties - +Brings up the JET Creator priorities window. This window allows you to set the +following conditions for a given JET file:</p> + +<p>Copyright Info - Contains copyright info to be inserted into JET file</p> + +<p>Chase Controllers - Option to chase controllers (on/off). This should usually +be ON.</p> + +<p>Delete Empty Tracks - Deletes any empty MIDI tracks</p> + + + +<h3>5.6.4 Segments</h3> + +<p>The Segments Menu contains the following +elements:</p> + + + +<p>Add Segment - +Brings up the Segment window</p> + +<p>Update Segment - Updates segment attributes</p> + +<p>Delete Segment - Deletes the current segment from the +Segment List</p> + + + +<h3>5.6.5 Help</h3> + +<p>The Help Menu will contain at least the +following elements:</p> + + + +<p>JET Creator Help - will launch PDF help document or go to on-line help</p> + +<p>About - +JET Creator version number, SONiVOX info</p> + + + + + +<h1>6 Trigger Events Explained</h1> + +<p>Breaking a MIDI +file into individual (non-linear) segments and queueing up those segments for +playback in a game based on events within the game is one way JET music files are +interactive. Trigger events are an additional method for interactive playback. +Both would be used together in an interactive game or application.</p> + + + +<p>Trigger events allow for the following:</p> + + +<ol> + <li><span + lang=EN-IE>Tracks <i>within</i> a MIDI segment can be turned on or off based on game + events. For example the composer could author two drum tracks, one fast + and one slow. If the action in a game is fast, the fast drum track could + play. If the action in the game is slow, the slow drum track can play.</li> + <li><span + lang=EN-IE>User actions can be compared to trigger events which are + pre-inserted into a music file at musically correct places. Based on the + results, scoring or other game actions can take place. </li> + <li><span + lang=EN-IE>Musical transitions between levels or action sequences can be + synchronized to be musically seemless.</li> +</ol> + + + +<p>Under the hood, JET uses standard MIDI CC +events to accomplish these actions and to synchronize audio. The controllers +used by JET are among those not defined for specific use by the specification. The specific controller definitions +are as follows:</p> + + + +<p> Controllers +80-83 Reserved for use by +application</p> + +<p> Controller +102 JET event marker</p> + +<p> Controller +103 JET clip marker</p> + +<p> Controllers +104-119 Reserved for future use</p> + + + +<h2>6.1 JET Clip Marker (CC103)</h2> + +<p>Controller 103 is reserved for marking +clips in a MIDI track that can be triggered by +the JET_TriggerClip API call. The clip ID is encoded in the low 6 bits of the +controller value. Bit 6 is set to one to indicate the start of a clip, and set +to zero to indicate the end of a clip.</p> + + + +<p>For example, to identify a clip with a clip +ID of 1, the author inserts a MIDI controller +event with controller=103 and value=65 at the start of the clip and another +event with controller=103 and value=1 at the end of the clip. When the +JET_TriggerClip() function is called with a clip ID of 1, the track will be +un-muted when the controller value 65 is encountered and muted again when the +controller value 1 is encountered.</p> + + + +<p><img border=0 width=492 height=367 +src="{@docRoot}images/jet/clip_marker.png"></p> + +<p>Figure 5: Synchronized Clip</p> + + + +<p>In the figure above, if the +JET_TriggerClip() function is called prior to the first controller event, Track +3 will be un-muted when the first controller event occurs, the first clip will +play, and the track will be muted when the second controller event occurs. If +the JET_TriggerClip() function is called after the first controller event has +occurred, Track 3 will be un-muted when the third controller event occurs, the +second clip will play, and the track will be muted again when the fourth +controller event occurs.</p> + + + +<p><b>Note:</b> Normally, the track containing the clip is muted by the application +when the segment is initially queued by the call to JET_QueueSegment(). If it +is not muted, the clip will always play until Jet_TriggerClip() has been called +with the clip ID.</p> + + + +<h2>6.2 JET Event Marker (CC102)</h2> + +<p>Controller 102 is reserved for marking +events in the MIDI streams that are specific +to JET functionality. Currently, the only defined value is 0, which marks the +end of a segment for timing purposes. </p> + + + +<p>Normally, JET starts playback of the next +segment (or repeats the current segment) when the MIDI +end-of-track meta-event is encountered. Some MIDI +authoring tools make it difficult to place the end-of-track marker accurately, +resulting in synchronization problems when segments are joined together.</p> + + + +<p>To avoid this problem, the author can place +a JET end-of-segment marker (controller=102, value=0) at the point where the +segment is to be looped. When the end-of-segment marker is encountered, the +next segment will be triggered, or if the current segment is looped, playback +will resume at the start of the segment.</p> + + + +<p>The end-of-segment marker can also be used +to allow for completion of a musical figure beyond the end of measure that +marks the start of the next segment. For example, the content author might +create a 4-bar segment with a drum fill that ends on beat 1 of the 5<sup>th</sup> +bar, a bar beyond the natural end of the segment. By placing an end-of-segment +marker at the end of the 4<sup>th</sup> bar, the next segment will be +triggered, but the drum fill will continue in parallel with the next segment +providing musical continuity.</p> + + + +<p><img border=0 width=467 height=185 +src="{@docRoot}images/jet/event_marker.png"></p> + +<p>Figure 6: End-of-segment Marker</p> + +<h2>6.3 Application Controllers (CC80-83)</h2> + +<p>The application may use controllers in this +range for its own purposes. When a controller in this range is encountered, the +event is entered into an event queue that can be queried by the application. +Some possible uses include synchronizing video events with audio and marking a +point in a MIDI segment to queue up the next +segment. The range of controllers monitored by the application can be modified +by the application during initialization.</p> + +<h1>7 JET Creator Guidelines</h1> + +<p></p> + +<h2>7.1 Order of Tasks</h2> + +<p>As with all projects, its best to discuss and design the interactive music scheme with the game designer and programmer before beginning your composition. An outline and/or specification can go a long way in saving you from having to redo things after the game is in place.</p> + +<p>In general you’ll want to first write your music in your DAW of choice the way you’re used to composing, then break up the final MIDI file as needed for the application. Next, move to JET Creator and create all of your music segments in the order easiest to preview them when played in order. Finally, add the JET Events to control the segments via the Android game and Audition them as needed in JET Creator. Finally, save the project in JET Creator and hand off the .jet file to the programmer to integrate it in the game. After previewing there will likely be changes to the MIDI file(s) and JET Creator attributes. </p> + +<h2>7.2 Conserving Memory</h2> + +<p>If you’re trying to conserve memory, compose as few MIDI files as possible, and create several segments from that MIDI file. For example a 12 bar MIDI file with three sections of 4 bars, A, B, C, can create a much longer song. Simply create multiple segments that reference the one MIDI file, then order them however you like. For example, A, A, B, A, C, A, B, A, A would create a 36 bar song. Use JET to add repeats, transpose segments, and interactively mute and unmute tracks to keep it even more interesting.</p> + +<h2>7.3 Replicate</h2> + +<p>To make adding segments or events faster, use the Replicate command. Replicate can add multiple segments or events at one time and uses an offset parameter and prefix naming convention to keep things easy to read. The MOVE command is also useful for moving multiple events by a set number of measures, beats or ticks.</p> + +<h2>7.4 Interactive Options</h2> + +<p>There are several interactive audio concepts possible in JET. Below are a few examples although we hope developers will come up with others we haven’t thought of! These are:</p> + +<h3>7.4.1 Multiple Segment Triggering</h3> + +<p>In this method the application is triggering specific segments based on events in the game. For example a hallway with lots of fighting might trigger segment 1 and a hallway with no fighting might trigger segment 2. Using JET TriggerClips in conjunction with this method creates even more diversity.</p> + +<h3>7.4.2 Mute Arrays</h3> + +<p>In this method the application is triggering mute and unmute events to specific tracks in a single MIDI sequence. For example a hallway with lots of fighting might play MIDI tracks 1-16 and a hallway with no fighting might play the same midi file but mute tracks 9-16. Using JET TriggerClips in conjunction with this method creates even more diversity.</p> + +<h3>7.4.3 Music Driven Gameplay</h3> + +<p>Music driven gaming is similar to what Guitar Hero and JETBOY have done in that the music content determines how graphic events are displayed. The application then queries the user response to the graphic events and interactively modifies the music in response. In this method the game is utilizing JET Application Events, MIDI controllers that are embedded in the MIDI file and read by the game in real-time. Based on the user response, multiple segment triggering and/or mute arrays can be set.</p> + diff --git a/docs/html/guide/topics/media/media.jd b/docs/html/guide/topics/media/media.jd deleted file mode 100644 index 463686d..0000000 --- a/docs/html/guide/topics/media/media.jd +++ /dev/null @@ -1,172 +0,0 @@ -page.title=Media Capabilities -@jd:body - -<div class="sidebox"> - -<h3>Media Quickview</h3> - -<h4>Built-in capabilities</h4> -<ul> -<li>Audio playback and record</li> -<li>Video playback</li> -</ul> - -<h4>Data sources</h4> -<ul> -<li>Raw resources</li> -<li>Data files</li> -<li>Streams</li> -</ul> - -<h4>Media Formats</h4> -<ul> -<li>See appendix <a href="{@docRoot}devguide/appendix/media_formats.html">Android 1.0 Media Formats</a></li> -</ul> - -<h4>Key APIs</h4> -<ul> -<li>{@link android.media.MediaPlayer} (playback, all audio and video formats)</li> -<li>{@link android.media.MediaRecorder} (record, all audio formats)</li> -</ul> -</div> - -<p>The Android platform offers built-in encoding/decoding for a variety of common media types, -so that you can easily integrate audio, video, and images into your applications. Accessing the platform's media -capabilities is fairly straightforward &mdash you do so using the same intents and -activities mechanism that the rest of Android uses.</p> - -<p>Android lets you play audio and video from several types of data sources. You can play audio or video from media files stored in the application's resources (raw resources), from standalone files in the filesystem, or from a data stream arriving over a network connection. To play audio or video from your application, use the {@link android.media.MediaPlayer} class.</p> - -<p>The platform also lets you record audio, where supported by the mobile device hardware. Recording of video is not currently supported, but is planned for a future release. To record audio, use the -{@link android.media.MediaRecorder} class. Note that the emulator doesn't have hardware to capture audio, but actual mobile devices are likely to provide these capabilities that you can access through MediaRecorder. </p> - -<p>For a list of the media formats for which Android offers built-in support, see the <a href="{@docRoot}devguide/appendix/media_formats.html">Android Media Formats</a> appendix. </p> - -<h2>Playing Audio and Video</h2> -<p>Media can be played from anywhere: from a raw resource, from a file from the system, -or from an available network (URL).</p> - -<p>You can play back the audio data only to the standard -output device; currently, that is the mobile device speaker or Bluetooth headset. You -cannot play sound files in the conversation audio. </p> - -<h3>Playing from a Raw Resource</h3> -<p>Perhaps the most common thing to want to do is play back media (notably sound) -within your own applications. Doing this is easy:</p> -<ol> - <li>Put the sound (or other media resource) file into the <code>res/raw</code> - folder of your project, where the Eclipse plugin (or aapt) will find it and - make it into a resource that can be referenced from your R class</li> - <li>Create an instance of <code>MediaPlayer</code>, referencing that resource using - {@link android.media.MediaPlayer#create MediaPlayer.create}, and then call - {@link android.media.MediaPlayer#start() start()} on the instance:<br><br></li> -</ol> -<pre> - MediaPlayer mp = MediaPlayer.create(context, R.raw.sound_file_1); - mp.start(); -</pre> -<p>To stop playback, call {@link android.media.MediaPlayer#stop() stop()}. If -you wish to later replay the media, then you must -{@link android.media.MediaPlayer#reset() reset()} and -{@link android.media.MediaPlayer#prepare() prepare()} the MediaPlayer object -before calling {@link android.media.MediaPlayer#start() start()} again. -(<code>create()</code> calls <code>prepare()</code> the first time.)</p> -<p>To pause playback, call {@link android.media.MediaPlayer#pause() pause()}. -Resume playback from where you paused with -{@link android.media.MediaPlayer#start() start()}.</p> - -<h3>Playing from a File or Stream</h3> -<p>You can play back media files from the filesystem or a web URL:</p> -<ol> - <li>Create an instance of the <code>MediaPlayer</code> using <code>new</code></li> - <li>Call {@link android.media.MediaPlayer#setDataSource setDataSource()} - with a String containing the path (local filesystem or URL) - to the file you want to play</li> - <li>First {@link android.media.MediaPlayer#prepare prepare()} then - {@link android.media.MediaPlayer#start() start()} on the instance:<br><br></li> -</ol> -<pre> - MediaPlayer mp = new MediaPlayer(); - mp.setDataSource(PATH_TO_FILE); - mp.prepare(); - mp.start(); -</pre> -<p>{@link android.media.MediaPlayer#stop() stop()} and -{@link android.media.MediaPlayer#pause() pause()} work the same as discussed -above.</p> - <p class="note"><strong>Note:</strong> It is possible that <code>mp</code> could be - null, so good code should <code>null</code> check after the <code>new</code>. - Also, <code>IllegalArgumentException</code> and <code>IOException</code> either - need to be caught or passed on when using <code>setDataSource()</code>, since - the file you are referencing may not exist.</p> -<p class="note"><strong>Note:</strong> -If you're passing a URL to an online media file, the file must be capable of -progressive download.</p> - -<h2>Recording Media Resources</h2> -<p>Recording media is a little more involved than playing it back, as you would -probably expect, but it is still fairly simple. There is just a little more set -up to do</p> -<ol> - <li>Create a new instance of {@link android.media.MediaRecorder - android.media.MediaRecorder} using <code>new</code></li> - <li>Create a new instance of {@link android.content.ContentValues - android.content.ContentValues} and put in some standard properties like - <code>TITLE</code>, <code>TIMESTAMP</code>, and the all important - <code>MIME_TYPE</code></li> - <li>Create a file path for the data to go to (you can use {@link - android.content.ContentResolver android.content.ContentResolver} to - create an entry in the Content database and get it to assign a path - automatically which you can then use)</li> - <li>Set the audio source using {@link android.media.MediaRecorder#setAudioSource - MediaRecorder.setAudioSource()}. You will probably want to use - <code>MediaRecorder.AudioSource.MIC</code></li> - <li>Set output file format using {@link - android.media.MediaRecorder#setOutputFormat MediaRecorder.setOutputFormat()} - </li> - <li>Set the audio encoder using - {@link android.media.MediaRecorder#setAudioEncoder MediaRecorder.setAudioEncoder()} - </li> - <li>Finally, {@link android.media.MediaRecorder#prepare prepare()} and - {@link android.media.MediaRecorder#start start()} the recording. - {@link android.media.MediaRecorder#stop stop()} and - {@link android.media.MediaRecorder#release release()} when you are done</li> -</ol> -<p>Here is a code example that will hopefully help fill in the gaps:</p> -<p><strong>Start Recording</strong></p> -<pre> - recorder = new MediaRecorder(); - ContentValues values = new ContentValues(3); - - values.put(MediaStore.MediaColumns.TITLE, SOME_NAME_HERE); - values.put(MediaStore.MediaColumns.TIMESTAMP, System.currentTimeMillis()); - values.put(MediaStore.MediaColumns.MIME_TYPE, recorder.getMimeContentType()); - - ContentResolver contentResolver = new ContentResolver(); - - Uri base = MediaStore.Audio.INTERNAL_CONTENT_URI; - Uri newUri = contentResolver.insert(base, values); - - if (newUri == null) { - // need to handle exception here - we were not able to create a new - // content entry - } - - String path = contentResolver.getDataFilePath(newUri); - - // could use setPreviewDisplay() to display a preview to suitable View here - - recorder.setAudioSource(MediaRecorder.AudioSource.MIC); - recorder.setOutputFormat(MediaRecorder.OutputFormat.THREE_GPP); - recorder.setAudioEncoder(MediaRecorder.AudioEncoder.AMR_NB); - recorder.setOutputFile(path); - - recorder.prepare(); - recorder.start(); -</pre> -<p><strong>Stop Recording</strong></p> -<pre> - recorder.stop(); - recorder.release(); -</pre> - diff --git a/docs/html/guide/topics/resources/index.jd b/docs/html/guide/topics/resources/index.jd index 7e3bce42..1425cfa 100644 --- a/docs/html/guide/topics/resources/index.jd +++ b/docs/html/guide/topics/resources/index.jd @@ -18,8 +18,8 @@ In general, these are external elements that you want to include and reference w like images, audio, video, text strings, layouts, themes, etc. Every Android application contains a directory for resources (<code>res/</code>) and a directory for assets (<code>assets/</code>). Assets are used less often, because their applications are far fewer. You only need to save data -as an asset when you need to read the raw bites. -The directories for resources and assets both reside at the top of your project directory, alongside your source code directory +as an asset when you need to read the raw bytes. The directories for resources and assets both +reside at the top of an Android project tree, at the same level as your source code directory (<code>src/</code>).</p> <p>The difference between "resources" and "assets" isn't much on the surface, but in general, diff --git a/docs/html/guide/topics/resources/resources-i18n.jd b/docs/html/guide/topics/resources/resources-i18n.jd index b1da4cd..4bbb44a 100644 --- a/docs/html/guide/topics/resources/resources-i18n.jd +++ b/docs/html/guide/topics/resources/resources-i18n.jd @@ -111,21 +111,30 @@ the containing file.</p> <td><code>res/drawable/</code></td> <td><p>.png, .9.png, .jpg files that are compiled into the following Drawable resource subtypes:</p> - <p>To get a resource of this type, use <code>Resource.getDrawable(<em>id</em>)</code> - <ul> + <ul class="nolist"> <li><a href="available-resources.html#imagefileresources">bitmap files</a></li> <li><a href="available-resources.html#ninepatch">9-patches (resizable bitmaps)</a></li> - </ul></td> + </ul> + <p>To get a resource of this type, use <code>mContext.getResources().getDrawable(R.drawable.<em>imageId</em>)</code></p> + <p class="note"><strong>Note:</strong> Image resources placed in here may + be automatically optimized with lossless image compression by the + <a href="{@docRoot}guide/developing/tools/aapt.html">aapt</a> tool. For example, a true-color PNG + that does not require more than 256 colors may be converted to an 8-bit PNG with a color palette. + This will result in an image of equal quality but which requires less memory. So be aware that the + image binaries placed in this directory can change during the build. If you plan on reading + an image as a bit stream in order to convert it to a bitmap, put your images in the + <code>res/raw/</code> folder instead, where they will not be optimized.</p> + </td> </tr> <tr> <td><code>res/layout/</code></td> <td>XML files that are compiled into screen layouts (or part of a screen). - See <a href="{@docRoot}guide/topics/ui/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> <td><p>XML files that can be compiled into many kinds of resource.</p> - <p class="note"><strong>Note:</strong> unlike the other res/ folders, this one + <p class="note"><strong>Note:</strong> Unlike the other res/ folders, this one can hold any number of files that hold descriptions of resources to create rather than the resources themselves. The XML element types control where these resources are placed under the R class.</p> diff --git a/docs/html/guide/topics/ui/custom-components.jd b/docs/html/guide/topics/ui/custom-components.jd index eccc2ca..76d1034 100644 --- a/docs/html/guide/topics/ui/custom-components.jd +++ b/docs/html/guide/topics/ui/custom-components.jd @@ -34,7 +34,7 @@ that you can use to construct your UI.</p> {@link android.widget.TextSwitcher TextSwitcher}. </p> <p>Among the layouts available are {@link android.widget.LinearLayout LinearLayout}, -{@link android.widget.FrameLayout FrameLayout}, {@link android.widget.AbsoluteLayout AbsoluteLayout}, +{@link android.widget.FrameLayout FrameLayout}, {@link android.widget.RelativeLayout RelativeLayout}, 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. diff --git a/docs/html/guide/topics/ui/dialogs.jd b/docs/html/guide/topics/ui/dialogs.jd new file mode 100644 index 0000000..c0c0b1b --- /dev/null +++ b/docs/html/guide/topics/ui/dialogs.jd @@ -0,0 +1,650 @@ +page.title=Creating Dialogs +parent.title=User Interface +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>Key classes</h2> + <ol> + <li>{@link android.app.Dialog}</li> + </ol> + <h2>In this document</h2> + <ol> + <li><a href="#ShowingADialog">Showing a Dialog</a></li> + <li><a href="#DismissingADialog">Dismissing a Dialog</a></li> + <li><a href="#AlertDialog">Creating an AlertDialog</a> + <ol> + <li><a href="#AddingButtons">Adding buttons</a></li> + <li><a href="#AddingAList">Adding a list</a></li> + </ol> + </li> + <li><a href="#ProgressDialog">Creating a ProgressDialog</a> + <ol> + <li><a href="#ShowingAProgressBar">Showing a progress bar</a></li> + </ol> + </li> + <li><a href="#CustomDialog">Creating a Custom Dialog</a></li> + </ol> + </div> +</div> + +<p>A dialog is usually a small window that appears in front of the current Activity. +The underlying Activity loses focus and the dialog accepts all user interaction. +Dialogs are normally used +for notifications and short activities that directly relate to the application in progress.</p> + +<p>The Android API supports the following types of {@link android.app.Dialog} objects:</p> +<dl> + <dt>{@link android.app.AlertDialog}</dt> + <dd>A dialog that can manage zero, one, two, or three buttons, and/or a list of + selectable items that can include checkboxes or radio buttons. The AlertDialog + is capable of constructing most dialog user interfaces and is the suggested dialog type. + See <a href="#AlertDialog">Creating an AlertDialog</a> below.</dd> + <dt>{@link android.app.ProgressDialog}</dt> + <dd>A dialog that displays a progress wheel or progress bar. Because it's an extension of + the AlertDialog, it also supports buttons. + See <a href="#ProgressDialog">Creating a ProgressDialog</a> below.</dd> + <dt>{@link android.app.DatePickerDialog}</dt> + <dd>A dialog that allows the user to select a date. See the + <a href="{@docRoot}guide/tutorials/views/hello-datepicker.html">Hello DatePicker</a> tutorial.</dd> + <dt>{@link android.app.TimePickerDialog}</dt> + <dd>A dialog that allows the user to select a time. See the + <a href="{@docRoot}guide/tutorials/views/hello-timepicker.html">Hello TimePicker</a> tutorial.</dd> +</dl> + +<p>If you would like to customize your own dialog, you can extend the +base {@link android.app.Dialog} object or any of the subclasses listed above and define a new layout. +See the section on <a href="#CustomDialog">Creating a Custom Dialog</a> below.</p> + + +<h2 id="ShowingADialog">Showing a Dialog</h2> + +<p>A dialog is always created and displayed as a part of an {@link android.app.Activity}. +You should normally create dialogs from within your Activity's +{@link android.app.Activity#onCreateDialog(int)} callback method. +When you use this callback, the Android system automatically manages the state of +each dialog and hooks them to the Activity, effectively making it the "owner" of each dialog. +As such, each dialog inherits certain properties from the Activity. For example, when a dialog +is open, the Menu key reveals the options menu defined for the Activity and the volume +keys modify the audio stream used by the Activity.</p> + +<p class="note"><strong>Note:</strong> If you decide to create a dialog outside of the +<code>onCreateDialog()</code> method, it will not be attached to an Activity. You can, however, +attach it to an Activity with {@link android.app.Dialog#setOwnerActivity(Activity)}.</p> + +<p>When you want to show a dialog, call +{@link android.app.Activity#showDialog(int)} and pass it an integer that uniquely identifies the +dialog that you want to display.</p> + +<p>When a dialog is requested for the first time, Android calls +{@link android.app.Activity#onCreateDialog(int)} from your Activity, which is +where you should instantiate the {@link android.app.Dialog}. This callback method +is passed the same ID that you passed to {@link android.app.Activity#showDialog(int)}. +After you create the Dialog, return the object at the end of the method.</p> + +<p>Before the dialog is displayed, Android also calls the optional callback method +{@link android.app.Activity#onPrepareDialog(int,Dialog)}. Define this method if you want to change +any properties of the dialog each time it is opened. This method is called +every time a dialog is opened, whereas {@link android.app.Activity#onCreateDialog(int)} is only +called the very first time a dialog is opened. If you don't define +{@link android.app.Activity#onPrepareDialog(int,Dialog) onPrepareDialog()}, then the dialog will +remain the same as it was the previous time it was opened. This method is also passed the dialog's +ID, along with the Dialog object you created in {@link android.app.Activity#onCreateDialog(int) +onCreateDialog()}.</p> + +<p>The best way to define the {@link android.app.Activity#onCreateDialog(int)} and +{@link android.app.Activity#onPrepareDialog(int,Dialog)} callback methods is with a +<em>switch</em> statement that checks the <var>id</var> parameter that's passed into the method. +Each <em>case</em> should check for a unique dialog ID and then create and define the respective Dialog. +For example, imagine a game that uses two different dialogs: one to indicate that the game +has paused and another to indicate that the game is over. First, define an integer ID for +each dialog:</p> +<pre> +static final int DIALOG_PAUSED_ID = 0; +static final int DIALOG_GAMEOVER_ID = 1; +</pre> + +<p>Then, define the {@link android.app.Activity#onCreateDialog(int)} callback with a +switch case for each ID:</p> +<pre> +protected Dialog onCreateDialog(int id) { + Dialog dialog; + switch(id) { + case DIALOG_PAUSED_ID: + // do the work to define the pause Dialog + break; + case DIALOG_GAMEOVER_ID: + // do the work to define the game over Dialog + break; + default: + dialog = null; + } + return dialog; +} +</pre> + +<p class="note"><strong>Note:</strong> In this example, there's no code inside +the case statements because the procedure for defining your Dialog is outside the scope +of this section. See the section below about <a href="#AlertDialog">Creating an AlertDialog</a>, +offers code suitable for this example.</p> + +<p>When it's time to show one of the dialogs, call {@link android.app.Activity#showDialog(int)} +with the ID of a dialog:</p> +<pre> +showDialog(DIALOG_PAUSED_ID); +</pre> + + +<h2 id="DismissingADialog">Dismissing a Dialog</h2> + +<p>When you're ready to close your dialog, you can dismiss it by calling +{@link android.app.Dialog#dismiss()} on the Dialog object. +If necessary, you can also call {@link android.app.Activity#dismissDialog(int)} from the +Activity, which effectively calls {@link android.app.Dialog#dismiss()} on the +Dialog for you.</p> + +<p>If you are using {@link android.app.Activity#onCreateDialog(int)} to manage the state +of your dialogs (as discussed in the previous section), then every time your dialog is +dismissed, the state of the Dialog +object is retained by the Activity. If you decide that you will no longer need this object or +it's important that the state is cleared, then you should call +{@link android.app.Activity#removeDialog(int)}. This will remove any internal references +to the object and if the dialog is showing, it will dismiss it.</p> + +<h3>Using dismiss listeners</h3> + +<p>If you'd like your applcation to perform some procedures the moment that a dialog is dismissed, +then you should attach an on-dismiss listener to your Dialog.</p> + +<p>First define the {@link android.content.DialogInterface.OnDismissListener} interface. +This interface has just one method, +{@link android.content.DialogInterface.OnDismissListener#onDismiss(DialogInterface)}, which +will be called when the dialog is dismissed. +Then simply pass your OnDismissListener implementation to +{@link android.app.Dialog#setOnDismissListener(DialogInterface.OnDismissListener) +setOnDismissListener()}.</p> + +<p>However, note that dialogs can also be "cancelled." This is a special case that indicates +the dialog was explicitly cancelled by the user. This will occur if the user presses the +"back" button to close the dialog, or if the dialog explicitly calls {@link android.app.Dialog#cancel()} +(perhaps from a "Cancel" button in the dialog). When a dialog is cancelled, +the OnDismissListener will still be notified, but if you'd like to be informed that the dialog +was explicitly cancelled (and not dismissed normally), then you should register +an {@link android.content.DialogInterface.OnCancelListener} with +{@link android.app.Dialog#setOnCancelListener(DialogInterface.OnCancelListener) +setOnCancelListener()}.</p> + + +<h2 id="AlertDialog">Creating an AlertDialog</h2> + +<p>An {@link android.app.AlertDialog} is an extension of the {@link android.app.Dialog} +class. It is capable of constructing most dialog user interfaces and is the suggested dialog type. +You should use it for dialogs that use any of the following features:</p> +<ul> + <li>A title</li> + <li>A text message</li> + <li>One, two, or three buttons</li> + <li>A list of selectable items (with optional checkboxes or radio buttons)</li> +</ul> + +<p>To create an AlertDialog, use the {@link android.app.AlertDialog.Builder} subclass. +Get a Builder with {@link android.app.AlertDialog.Builder#AlertDialog.Builder(Context)} and +then use the class's public methods to define all of the +AlertDialog properties. After you're done with the Builder, retrieve the +AlertDialog object with {@link android.app.AlertDialog.Builder#create()}.</p> + +<p>The following topics show how to define various properties of the AlertDialog using the +AlertDialog.Builder class. If you use any of the following sample code inside your +{@link android.app.Activity#onCreateDialog(int) onCreateDialog()} callback method, +you can return the resulting Dialog object to display the dialog.</p> + + +<h3 id="AddingButtons">Adding buttons</h3> + +<img src="{@docRoot}images/dialog_buttons.png" alt="" style="float:right" /> + +<p>To create an AlertDialog with side-by-side buttons like the one shown in the screenshot to the right, +use the <code>set...Button()</code> methods:</p> + +<pre> +AlertDialog.Builder builder = new AlertDialog.Builder(this); +builder.setMessage("Are you sure you want to exit?") + .setCancelable(false) + .setPositiveButton("Yes", new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int id) { + MyActivity.this.finish(); + } + }) + .setNegativeButton("No", new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int id) { + dialog.cancel(); + } + }); +AlertDialog alert = builder.create(); +</pre> + +<p>First, add a message for the dialog with +{@link android.app.AlertDialog.Builder#setMessage(CharSequence)}. Then, begin +method-chaining and set the dialog +to be <em>not cancelable</em> (so the user cannot close the dialog with the back button) +with {@link android.app.AlertDialog.Builder#setCancelable(boolean)}. For each button, +use one of the <code>set...Button()</code> methods, such as +{@link android.app.AlertDialog.Builder#setPositiveButton(CharSequence,DialogInterface.OnClickListener) +setPositiveButton()}, that accepts the name for the button and a +{@link android.content.DialogInterface.OnClickListener} that defines the action to take +when the user selects the button.</p> + +<p class="note"><strong>Note:</strong> You can only add one of each button type to the +AlertDialog. That is, you cannot have more than one "positive" button. This limits the number +of possible buttons to three: positive, neutral, and negative. These names are technically irrelevant to the +actual functionality of your buttons, but should help you keep track of which one does what.</p> + + +<h3 id="AddingAList">Adding a list</h3> + +<img src="{@docRoot}images/dialog_list.png" alt="" style="float:right" /> + +<p>To create an AlertDialog with a list of selectable items like the one shown to the right, +use the <code>setItems()</code> method:</p> + +<pre> +final CharSequence[] items = {"Red", "Green", "Blue"}; + +AlertDialog.Builder builder = new AlertDialog.Builder(this); +builder.setTitle("Pick a color"); +builder.setItems(items, new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int item) { + Toast.makeText(getApplicationContext(), items[item], Toast.LENGTH_SHORT).show(); + } +}); +AlertDialog alert = builder.create(); +</pre> + +<p>First, add a title to the dialog with +{@link android.app.AlertDialog.Builder#setTitle(CharSequence)}. +Then, add a list of selectable items with +{@link android.app.AlertDialog.Builder#setItems(CharSequence[],DialogInterface.OnClickListener) +setItems()}, which accepts the array of items to display and a +{@link android.content.DialogInterface.OnClickListener} that defines the action to take +when the user selects an item.</p> + + +<h4>Adding checkboxes and radio buttons</h4> + +<img src="{@docRoot}images/dialog_singlechoicelist.png" alt="" style="float:right" /> + +<p>To create a list of multiple-choice items (checkboxes) or +single-choice items (radio buttons) inside the dialog, use the +{@link android.app.AlertDialog.Builder#setMultiChoiceItems(Cursor,String,String, +DialogInterface.OnMultiChoiceClickListener) setMultiChoiceItems()} and +{@link android.app.AlertDialog.Builder#setSingleChoiceItems(int,int,DialogInterface.OnClickListener) +setSingleChoiceItems()} methods, respectively. +If you create one of these selectable lists in the +{@link android.app.Activity#onCreateDialog(int) onCreateDialog()} callback method, +Android manages the state of the list for you. As long as the Activity is active, +the dialog remembers the items that were previously selected, but when the user exits the +Activity, the selection is lost. + +<p class="note"><strong>Note:</strong> To save the selection when the user leaves or +pauses the Activity, you must properly save and restore the setting throughout +the <a href="{@docRoot}guide/topics/fundamentals.html#lcycles">Activity Lifecycle</a>. +To permanently save the selections, even when the Activity process is completely shutdown, +you need to save the settings +with one of the <a href="{@docRoot}guide/topics/data/data-storage.html">Data +Storage</a> techniques.</p> + +<p>To create an AlertDialog with a list of single-choice items like the one shown to the right, +use the same code from the previous example, but replace the <code>setItems()</code> method with +{@link android.app.AlertDialog.Builder#setSingleChoiceItems(int,int,DialogInterface.OnClickListener) +setSingleChoiceItems()}:</p> + +<pre> +final CharSequence[] items = {"Red", "Green", "Blue"}; + +AlertDialog.Builder builder = new AlertDialog.Builder(this); +builder.setTitle("Pick a color"); +builder.setSingleChoiceItems(items, -1, new DialogInterface.OnClickListener() { + public void onClick(DialogInterface dialog, int item) { + Toast.makeText(getApplicationContext(), items[item], Toast.LENGTH_SHORT).show(); + } +}); +AlertDialog alert = builder.create(); +</pre> + +<p>The second parameter in the +{@link android.app.AlertDialog.Builder#setSingleChoiceItems(CharSequence[],int,DialogInterface.OnClickListener) +setSingleChoiceItems()} method is an integer value for the <var>checkedItem</var>, which indicates the +zero-based list position of the default selected item. Use "-1" to indicate that no item should be +selected by default.</p> + + +<h2 id="ProgressDialog">Creating a ProgressDialog</h2> + +<img src="{@docRoot}images/dialog_progress_spinning.png" alt="" style="float:right" /> + +<p>A {@link android.app.ProgressDialog} is an extension of the {@link android.app.AlertDialog} +class that can display a progress animation in the form of a spinning wheel, for a task with +progress that's undefined, or a progress bar, for a task that has a defined progression. +The dialog can also provide buttons, such as one to cancel a download.</p> + +<p>Opening a progress dialog can be as simple as calling +{@link android.app.ProgressDialog#show(Context,CharSequence,CharSequence) +ProgressDialog.show()}. For example, the progress dialog shown to the right can be +easily achieved without managing the dialog through the +{@link android.app.Activity#onCreateDialog(int)} callback, +as shown here:</p> + +<pre> +ProgressDialog dialog = ProgressDialog.show(MyActivity.this, "", + "Loading. Please wait...", true); +</pre> + +<p>The first parameter is the application {@link android.content.Context}, +the second is a title for the dialog (left empty), the third is the message, +and the last parameter is whether the progress +is indeterminate (this is only relevant when creating a progress bar, which is +discussed in the next section). +</p> + +<p>The default style of a progress dialog is the spinning wheel. +If you want to create a progress bar that shows the loading progress with granularity, +some more code is required, as discussed in the next section.</p> + + +<h3 id="ShowingAProgressBar">Showing a progress bar</h3> + +<img src="/images/dialog_progress_bar.png" alt="" style="float:right" /> + +<p>To show the progression with an animated progress bar:</p> + +<ol> + <li>Initialize the + ProgressDialog with the class constructor, + {@link android.app.ProgressDialog#ProgressDialog(Context)}.</li> + <li>Set the progress style to "STYLE_HORIZONTAL" with + {@link android.app.ProgressDialog#setProgressStyle(int)} and + set any other properties, such as the message.</li> + <li>When you're ready to show the dialog, call + {@link android.app.Dialog#show()} or return the ProgressDialog from the + {@link android.app.Activity#onCreateDialog(int)} callback.</li> + <li>You can increment the amount of progress displayed + in the bar by calling either {@link android.app.ProgressDialog#setProgress(int)} with a value for + the total percentage completed so far or {@link android.app.ProgressDialog#incrementProgressBy(int)} + with an incremental value to add to the total percentage completed so far.</li> +</ol> + +<p>For example, your setup might look like this:</p> +<pre> +ProgressDialog progressDialog; +progressDialog = new ProgressDialog(mContext); +progressDialog.setProgressStyle(ProgressDialog.STYLE_HORIZONTAL); +progressDialog.setMessage("Loading..."); +progressDialog.setCancelable(false); +</pre> + +<p>The setup is simple. Most of the code needed to create a progress dialog is actually +involved in the process that updates it. You might find that it's +necessary to create a second thread in your application for this work and then report the progress +back to the Activity's UI thread with a {@link android.os.Handler} object. +If you're not familiar with using additional +threads with a Handler, see the example Activity below that uses a second thread to +increment a progress dialog managed by the Activity.</p> + +<script type="text/javascript"> +function toggleDiv(link) { + var toggleable = $(link).parent(); + if (toggleable.hasClass("closed")) { + $(".toggleme", toggleable).slideDown("fast"); + toggleable.removeClass("closed"); + toggleable.addClass("open"); + $(".toggle-img", toggleable).attr("title", "hide").attr("src", "/assets/images/triangle-opened.png"); + } else { + $(".toggleme", toggleable).slideUp("fast"); + toggleable.removeClass("open"); + toggleable.addClass("closed"); + $(".toggle-img", toggleable).attr("title", "show").attr("src", "/assets/images/triangle-closed.png"); + } + return false; +} +</script> +<style> +.toggleme { + padding:0 0 1px 0; +} +.toggleable a { + text-decoration:none; +} +.toggleable.closed .toggleme { + display:none; +} +#jd-content .toggle-img { + margin:0; +} +</style> + +<div class="toggleable closed"> + <a href="#" onclick="return toggleDiv(this)"> + <img src="/assets/images/triangle-closed.png" class="toggle-img" /> + <strong>Example ProgressDialog with a second thread</strong></a> + <div class="toggleme"> + <p>This example uses a second thread to track the progress of a process (which actually just +counts up to 100). The thread sends a {@link android.os.Message} back to the main +Activity through a {@link android.os.Handler} each time progress is made. The main Activity then updates the +ProgressDialog.</p> + +<pre> +package com.example.progressdialog; + +import android.app.Activity; +import android.app.Dialog; +import android.app.ProgressDialog; +import android.os.Bundle; +import android.os.Handler; +import android.os.Message; +import android.view.View; +import android.view.View.OnClickListener; +import android.widget.Button; + +public class NotificationTest extends Activity { + static final int PROGRESS_DIALOG = 0; + Button button; + ProgressThread progressThread; + ProgressDialog progressDialog; + + /** Called when the activity is first created. */ + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.main); + + // Setup the button that starts the progress dialog + button = (Button) findViewById(R.id.progressDialog); + button.setOnClickListener(new OnClickListener(){ + public void onClick(View v) { + showDialog(PROGRESS_DIALOG); + } + }); + } + + protected Dialog onCreateDialog(int id) { + switch(id) { + case PROGRESS_DIALOG: + progressDialog = new ProgressDialog(NotificationTest.this); + progressDialog.setProgressStyle(ProgressDialog.STYLE_HORIZONTAL); + progressDialog.setMessage("Loading..."); + progressThread = new ProgressThread(handler); + progressThread.start(); + return progressDialog; + default: + return null; + } + } + + // Define the Handler that receives messages from the thread and update the progress + final Handler handler = new Handler() { + public void handleMessage(Message msg) { + int total = msg.getData().getInt("total"); + progressDialog.setProgress(total); + if (total >= 100){ + dismissDialog(PROGRESS_DIALOG); + progressThread.setState(ProgressThread.STATE_DONE); + } + } + }; + + /** Nested class that performs progress calculations (counting) */ + private class ProgressThread extends Thread { + Handler mHandler; + final static int STATE_DONE = 0; + final static int STATE_RUNNING = 1; + int mState; + int total; + + ProgressThread(Handler h) { + mHandler = h; + } + + public void run() { + mState = STATE_RUNNING; + total = 0; + while (mState == STATE_RUNNING) { + try { + Thread.sleep(100); + } catch (InterruptedException e) { + Log.e("ERROR", "Thread Interrupted"); + } + Message msg = mHandler.obtainMessage(); + Bundle b = new Bundle(); + b.putInt("total", total); + msg.setData(b); + mHandler.sendMessage(msg); + total++; + } + } + + /* sets the current state for the thread, + * used to stop the thread */ + public void setState(int state) { + mState = state; + } + } +} +</pre> + </div> <!-- end toggleme --> +</div> <!-- end toggleable --> + + + +<h2 id="CustomDialog">Creating a Custom Dialog</h2> + +<img src="{@docRoot}images/dialog_custom.png" alt="" style="float:right" /> + +<p>If you want a customized design for a dialog, you can create your own layout +for the dialog window with layout and widget elements. +After you've defined your layout, pass the root View object or +layout resource ID to {@link android.app.Dialog#setContentView(View)}.</p> + +<p>For example, to create the dialog shown to the right:</p> + +<ol> + <li>Create an XML layout saved as <code>custom_dialog.xml</code>: +<pre> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/layout_root" + android:orientation="horizontal" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:padding="10dp" + > + <ImageView android:id="@+id/image" + android:layout_width="wrap_content" + android:layout_height="fill_parent" + android:layout_marginRight="10dp" + /> + <TextView android:id="@+id/text" + android:layout_width="wrap_content" + android:layout_height="fill_parent" + android:textColor="#FFF" + /> +</LinearLayout> +</pre> + + <p>This XML defines an {@link android.widget.ImageView} and a {@link android.widget.TextView} + inside a {@link android.widget.LinearLayout}.</p> + <li>Set the above layout as the dialog's content view and define the content + for the ImageView and TextView elements:</p> +<pre> +Context mContext = getApplicationContext(); +Dialog dialog = new Dialog(mContext); + +dialog.setContentView(R.layout.custom_dialog); +dialog.setTitle("Custom Dialog"); + +TextView text = (TextView) dialog.findViewById(R.id.text); +text.setText("Hello, this is a custom dialog!"); +ImageView image = (ImageView) dialog.findViewById(R.id.image); +image.setImageResource(R.drawable.android); +</pre> + + <p>After you instantiate the Dialog, set your custom layout as the dialog's content view with + {@link android.app.Dialog#setContentView(int)}, passing it the layout resource ID. + Now that the Dialog has a defined layout, you can capture View objects from the layout with + {@link android.app.Dialog#findViewById(int)} and modify their content.</p> + </li> + + <li>That's it. You can now show the dialog as described in + <a href="#ShowingADialog">Showing A Dialog</a>.</li> +</ol> + +<p>A dialog made with the base Dialog class must have a title. If you don't call +{@link android.app.Dialog#setTitle(CharSequence) setTitle()}, then the space used for the title +remains empty, but still visible. If you don't want +a title at all, then you should create your custom dialog using the +{@link android.app.AlertDialog} class. However, because an AlertDialog is created easiest with +the {@link android.app.AlertDialog.Builder} class, you do not have access to the +{@link android.app.Dialog#setContentView(int)} method used above. Instead, you must use +{@link android.app.AlertDialog.Builder#setView(View)}. This method accepts a {@link android.view.View} object, +so you need to inflate the layout's root View object from +XML.</p> + +<p>To inflate the XML layout, retrieve the {@link android.view.LayoutInflater} with +{@link android.app.Activity#getLayoutInflater()} +(or {@link android.content.Context#getSystemService(String) getSystemService()}), +and then call +{@link android.view.LayoutInflater#inflate(int, ViewGroup)}, where the first parameter +is the layout resource ID and the second is the ID of the root View. At this point, you can use +the inflated layout to find View objects in the layout and define the content for the +ImageView and TextView elements. Then instantiate the AlertDialog.Builder and set the +inflated layout for the dialog with {@link android.app.AlertDialog.Builder#setView(View)}.</p> + +<p>Here's an example, creating a custom layout in an AlertDialog:</p> + +<pre> +AlertDialog.Builder builder; +AlertDialog alertDialog; + +Context mContext = getApplicationContext(); +LayoutInflater inflater = (LayoutInflater) mContext.getSystemService(LAYOUT_INFLATER); +View layout = inflater.inflate(R.layout.custom_dialog, + (ViewGroup) findViewById(R.id.layout_root)); + +TextView text = (TextView) layout.findViewById(R.id.text); +text.setText("Hello, this is a custom dialog!"); +ImageView image = (ImageView) layout.findViewById(R.id.image); +image.setImageResource(R.drawable.android); + +builder = new AlertDialog.Builder(mContext); +builder.setView(layout); +alertDialog = builder.create(); +</pre> + +<p>Using an AlertDialog for your custom layout lets you +take advantage of built-in AlertDialog features like managed buttons, +selectable lists, a title, an icon and so on.</p> + +<p>For more information, refer to the reference documentation for the +{@link android.app.Dialog} and {@link android.app.AlertDialog.Builder} +classes.</p> + + + diff --git a/docs/html/guide/topics/ui/how-android-draws.jd b/docs/html/guide/topics/ui/how-android-draws.jd index a511005..21f9833 100644 --- a/docs/html/guide/topics/ui/how-android-draws.jd +++ b/docs/html/guide/topics/ui/how-android-draws.jd @@ -70,8 +70,8 @@ and each View is responsible for drawing itself. 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. + For example, RelativeLayout has its own subclass of LayoutParams, which includes + the ability to center child Views horizontally and vertically. </p> <p> diff --git a/docs/html/guide/topics/ui/index.jd b/docs/html/guide/topics/ui/index.jd index 6bd1d15..ef23672 100644 --- a/docs/html/guide/topics/ui/index.jd +++ b/docs/html/guide/topics/ui/index.jd @@ -116,7 +116,7 @@ complex layout.</p> <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, +Some pre-defined view groups offered by Android (called layouts) include LinearLayout, RelativeLayout, 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, diff --git a/docs/html/guide/topics/ui/layout-objects.jd b/docs/html/guide/topics/ui/layout-objects.jd index cf85fd6..bb13a18 100644 --- a/docs/html/guide/topics/ui/layout-objects.jd +++ b/docs/html/guide/topics/ui/layout-objects.jd @@ -10,7 +10,6 @@ parent.link=index.html <li><a href="#framelayout">FrameLayout</a></li> <li><a href="#linearlayout">LinearLayout</a></li> <li><a href="#tablelayout">TableLayout</a></li> - <li><a href="#absolutelayout">AbsoluteLayout</a></li> <li><a href="#relativelayout">RelativeLayout</a></li> <li><a href="#viewgroupsummary">Summary of Important View Groups</a></li> </ol> @@ -143,16 +142,6 @@ documentation for more details. </p> TableLayout</a> tutorial.</p> -<h2 id="absolutelayout">AbsoluteLayout</h2> -<p>{@link android.widget.AbsoluteLayout} enables child views to specify - their own exact x/y coordinates on the screen. Coordinates <em>(0,0)</em> is the upper left - corner, and values increase as you move down and to the right. Margins are not - supported, and overlapping elements are allowed (although not recommended). We - generally recommend against using AbsoluteLayout unless you have good reasons - to use it, because it is fairly rigid and does not adjust to different types of - displays. </p> - - <h2 id="relativelayout">RelativeLayout</h2> <p>{@link android.widget.RelativeLayout} lets child views specify their position relative to the parent view or to each other (specified by ID). So you can @@ -232,11 +221,6 @@ RelativeLayout</a> tutorial.</p> <th scope="col">Description</th> </tr> <tr> - <td>{@link android.widget.AbsoluteLayout AbsoluteLayout}<br /></td> - <td>Enables you to specify the location of child objects relative to the - parent in exact measurements (for example, pixels). </td> - </tr> - <tr> <td>{@link android.widget.FrameLayout FrameLayout}</td> <td>Layout that acts as a view frame to display a single object. </td> diff --git a/docs/html/guide/topics/ui/notifiers/index.jd b/docs/html/guide/topics/ui/notifiers/index.jd new file mode 100644 index 0000000..5b37f5b6 --- /dev/null +++ b/docs/html/guide/topics/ui/notifiers/index.jd @@ -0,0 +1,107 @@ +page.title=Notifying the User +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#Toast">Toast Notification</a></li> + <li><a href="#StatusBarNotification">Status Bar Notification</a></li> + <li><a href="#Dialog">Dialog Notification</a></li> + </ol> + <h2>More about</h2> + <ol> + <li><a href="toasts.html">Creating Toast Notifications</a></li> + <li><a href="notifications.html">Creating Status Bar Notifications</a></li> + <li><a href="{@docRoot}guide/topics/ui/dialogs.html">Creating Dialogs</a></li> + </ol> + </div> +</div> + +<p>Several types of situations may arise that require you to notify the user +about an event that occurs in your application. Some events require the user to respond +and others do not. For example:</p> +<ul> + <li>When an event such as saving a file is complete, a small message +should appear to confirm that the save was successful.</li> + <li>If the application is running in the background and needs the user's attention, +the application should create a notificaiton that allows the user to respond at +his or her convenience.</li> + <li>If the application is +performing work that the user must wait for (such as loading a file), +the application should show a hovering progress wheel or bar.</li> +</ul> + +<p>Each of these notification tasks can be achieved using a different technique:</p> +<ul> + <li>A <a href="#Toast">Toast Notification</a>, for brief messages that come + from the background.</li> + <li>A <a href="#StatusBar">Status Bar Notification</a>, for persistent reminders + that come from the background and request the user's response.</li> + <li>A <a href="#Dialog">Dialog Notification</a>, for Activity-related notifications.</li> +</ul> + +<p>This document summarizes each of these techniques for notifying the user and includes +links to full documentation.</p> + + +<h2 id="Toast">Toast Notification</h2> + +<img src="{@docRoot}images/toast.png" alt="" style="float:right" /> + +<p>A toast notificaiton is a message that pops up on the surface of the window. +It only fills the amount of space required for the message and the user's current +activity remains visible and interactive. The notification automatically fades in and +out, and does not accept interaction events. Because a toast can be created from a background +{@link android.app.Service}, it appears even if the application isn't visible.</p> + +<p>A toast is best for short text messages, such as "File saved," +when you're fairly certain the user is paying attention +to the screen. A toast can not accept user interaction events; if you'd like +the user to respond and take action, consider using a +<a href="#StatusBar">Status Bar Notification</a> instead.</p> + +<p>For more information, refer to <a href="toasts.html">Creating Toast Notifications</a>.</p> + + +<h2 id="StatusBar">Status Bar Notification</h2> + +<img src="{@docRoot}images/notifications_window.png" alt="" style="float:right; clear:right;" /> + +<p>A status bar notification adds an icon to the system's status bar +(with an optional ticker-text message) and an expanded message in the "Notifications" window. +When the user selects the expanded message, Android fires an +{@link android.content.Intent} that is defined by the notification (usually to launch an +{@link android.app.Activity}). +You can also configure the notification to alert the user with a sound, a vibration, and flashing +lights on the device.</p> + +<p>This kind of notification is ideal when your application is working in +a background {@link android.app.Service} and needs to +notify the user about an event. If you need to alert the user about an event that occurs +while your Activity is still in focus, consider using a +<a href="#Dialog">Dialog Notification</a> instead.</p> + +<p>For more information, refer to +<a href="notifications.html">Creating Status Bar Notifications</a>.</p> + + +<h2 id="Dialog">Dialog Notification</h2> + +<img src="{@docRoot}images/dialog_progress_spinning.png" alt="" style="float:right" /> + +<p>A dialog is usually a small window that appears in front of the current Activity. +The underlying Activity loses focus and the dialog accepts all user interaction. +Dialogs are normally used +for notifications and short activities that directly relate to the application in progress.</p> + +<p>You should use a dialog when you need to show a progress bar or a short +message that requires confirmation from the user (such as an alert with "OK" and "Cancel" buttons). +You can use also use dialogs as integral componenents +in your application's UI and for other purposes besides notifications. +For a complete discussion on all the available types of dialogs, +including its uses for notifications, refer to +<a href="{@docRoot}guide/topics/ui/dialogs.html">Creating Dialogs</a>.</p> + + + diff --git a/docs/html/guide/topics/ui/notifiers/notifications.jd b/docs/html/guide/topics/ui/notifiers/notifications.jd new file mode 100644 index 0000000..e6fa48f --- /dev/null +++ b/docs/html/guide/topics/ui/notifiers/notifications.jd @@ -0,0 +1,432 @@ +page.title=Creating Status Bar Notifications +parent.title=Notifying the User +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>Key classes</h2> + <ol> + <li>{@link android.app.Notification}</li> + <li>{@link android.app.NotificationManager}</li> + </ol> + <h2>In this document</h2> + <ol> + <li><a href="#Basics">The Basics</a></li> + <li><a href="#ManageYourNotifications">Managing your Notifications</a></li> + <li><a href="#CreateANotification">Creating a Notification</a> + <ol> + <li><a href="#Update">Updating the notification</a></li> + <li><a href="#Sound">Adding a sound</a></li> + <li><a href="#Vibration">Adding vibration</a></li> + <li><a href="#Lights">Adding flashing lights</a></li> + <li><a href="#More">More features</a></li> + </ol> + </li> + <li><a href="#CustomExpandedView">Creating a Custom Expanded View</a></li> + </ol> + </div> +</div> + +<p>A status bar notification adds an icon to the system's status bar +(with an optional ticker-text message) and an expanded message in the "Notifications" window. +When the user selects the expanded message, Android fires an +{@link android.content.Intent} that is defined by the notification (usually to launch an +{@link android.app.Activity}). +You can also configure the notification to alert the user with a sound, a vibration, and flashing +lights on the device.</p> + +<p>A status bar notification should be used for any case in +which a background Service needs to alert the user about an event that requires a response. A background Service +<strong>should never</strong> launch an Activity on its own in order to receive user interaction. +The Service should instead create a status bar notification that will launch the Activity +when selected by the user.</p> + +<p>The screenshot below shows the status bar with a notification icon on the left side.</p> +<img src="{@docRoot}images/status_bar.png" alt="" /> + +<p>The next screenshot shows the notification's expanded message in the "Notifications" window. +The user can reveal the Notifications window by pulling down the status bar +(or selecting <em>Notifications</em> from the Home options menu).</p> +<img src="{@docRoot}images/notifications_window.png" alt="" /> + + +<h2 id="Basics">The Basics</h2> + +<p>An {@link android.app.Activity} or {@link android.app.Service} can initiate a status bar +notification. Because an Activity can perform actions only while it is +active and in focus, you should create your status bar notifications from a +Service. This way, the notification can be created from the background, +while the user is using another application or +while the device is asleep. To create a notification, you must use two +classes: {@link android.app.Notification} and {@link android.app.NotificationManager}.</p> + +<p>Use an instance of the {@link android.app.Notification} class to define the properties of your +status bar notification, such as the status bar icon, the expanded message, and extra settings such +as a sound to play. The {@link android.app.NotificationManager} is an Android system service that +executes and manages all Notifications. You do not instantiate the NotificationManager. In order +to give it your Notification, you must retrieve a reference to the NotificationManager with +{@link android.app.Activity#getSystemService(String) getSystemService()} and +then, when you want to notify the user, pass it your Notification object with +{@link android.app.NotificationManager#notify(int,Notification) notify()}. </p> + +<p>To create a status bar notification:</p> +<ol> + <li>Get a reference to the NotificationManager: +<pre> +String ns = Context.NOTIFICATION_SERVICE; +NotificationManager mNotificationManager = (NotificationManager) getSystemService(ns); +</pre> + </li> + <li>Instantiate the Notification: +<pre> +int icon = R.drawable.notification_icon; +CharSequence tickerText = "Hello"; +long when = System.currentTimeMillis(); + +Notification notification = new Notification(icon, tickerText, when); +</pre> + </li> + <li>Define the Notification's expanded message and Intent: +<pre> +Context context = getApplicationContext(); +CharSequence contentTitle = "My notification"; +CharSequence contentText = "Hello World!"; +Intent notificationIntent = new Intent(this, MyClass.class); +PendingIntent contentIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0); + +notification.setLatestEventInfo(context, contentTitle, contentText, contentIntent); +</pre> + </li> + <li>Pass the Notification to the NotificationManager: +<pre> +private static final int HELLO_ID = 1; + +mNotificationManager.notify(HELLO_ID, notification); +</pre> + <p>That's it. Your user has now been notified.</p> + </li> +</ol> + + +<h2 id="ManageYourNotifications">Managing your Notifications</h2> + +<p>The {@link android.app.NotificationManager} is a system service that manages all +notifications. You must retrieve a reference to it with the +{@link android.app.Activity#getSystemService(String) getSystemService()} method. +For example:</p> +<pre> +String ns = Context.NOTIFICATION_SERVICE; +NotificationManager mNotificationManager = (NotificationManager) getSystemService(ns); +</pre> + +<p>When you want to send your status bar notification, pass the Notification object +to the NotificationManager with {@link android.app.NotificationManager#notify(int,Notification)}. +The first parameter is the unique ID for the Notification and the second is the Notification object. +The ID uniquely identifies the Notification from within your +application. This is necessary if you need to update the Notification or (if +your application manages different kinds of Notifications) select the appropriate action +when the user returns to your application via the Intent defined in the Notification.</p> + +<p>To clear the status bar notification when the user selects it from the Notifications +window, add the "FLAG_AUTO_CANCEL" flag to your Notification object. You can also clear it +manually with {@link android.app.NotificationManager#cancel(int)}, passing it the notification ID, +or clear all your Notifications with {@link android.app.NotificationManager#cancelAll()}.</p> + + +<h2 id="CreateANotification">Creating a Notification</h2> + +<p>A {@link android.app.Notification} object defines the details of the notification +message that is displayed in the status bar and "Notifications" window, and any other +alert settings, such as sounds and blinking lights.</p> + +<p>A status bar notification <em>requires</em> all of the following:</p> +<ul> + <li>An icon for the status bar</li> + <li>A title and expanded message for the expanded view (unless you define a + <a href="#CustomExpandedView">custom expanded view</a>)</li> + <li>A {@link android.app.PendingIntent}, to be fired when the notification is selected</li> +</ul> +<p>Optional settings for the status bar notification include:</p> +<ul> + <li>A ticker-text message for the status bar</li> + <li>An alert sound</li> + <li>A vibrate setting</li> + <li>A flashing LED setting</li> +</ul> + +<p>The starter-kit for a new Notification includes the +{@link android.app.Notification#Notification(int,CharSequence,long)} constructor and the +{@link android.app.Notification#setLatestEventInfo(Context,CharSequence,CharSequence,PendingIntent)} +method. These define all the required settings for a Notification. +The following snippet demonstrates a basic Notification setup:</p> +<pre> +int icon = R.drawable.notification_icon; // icon from resources +CharSequence tickerText = "Hello"; // ticker-text +long when = System.currentTimeMillis(); // notification time +Context context = getApplicationContext(); // application Context +CharSequence contentTitle = "My notification"; // expanded message title +CharSequence contentText = "Hello World!"; // expanded message text + +Intent notificationIntent = new Intent(this, MyClass.class); +PendingIntent contentIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0); + +// the next two lines initialize the Notification, using the configurations above +Notification notification = new Notification(icon, tickerText, when); +notification.setLatestEventInfo(context, contentTitle, contentText, contentIntent); +</pre> + + +<h3 id="Updating">Updating the notification</h3> + +<p>You can update the information in your status bar notification as events +continue to occur in your application. For example, when a new SMS text message arrives +before previous messages have been read, the Messaging application updates the existing +notification to display the total number of new messages received. +This practice of updating an existing Notification is much better than adding new Notifications +to the NotificationManager because it avoids clutter in the Notifications window.</p> + +<p>Because each notification is uniquely identified +by the NotificationManager with an integer ID, you can revise the notification by calling +{@link android.app.Notification#setLatestEventInfo(Context,CharSequence,CharSequence,PendingIntent) +setLatestEventInfo()} with new values, change some field values of the Notification, and then call +{@link android.app.NotificationManager#notify(int,Notification) notify()} again.</p> + +<p>You can revise each property with the object member fields +(except for the Context and the expanded message title and text). You should always +revise the text message when you update the notification by calling +{@link android.app.Notification#setLatestEventInfo(Context,CharSequence,CharSequence,PendingIntent) +setLatestEventInfo()} with new values for <var>contentTitle</var> and <var>contentText</var>. +Then call {@link android.app.NotificationManager#notify(int,Notification) notify()} to update the +notification. (Of course, if you've created a <a href="#CustomExpandedView">custom expanded +view</a>, then updating these title and text values has no effect.)</p> + + +<h3 id="Sound">Adding a sound</h3> + +<p>You can alert the user with the default notification sound +(which is defined by the user) or with a sound specified by your application.</p> + +<p>To use the user's default sound, add "DEFAULT_SOUND" to the <var>defaults</var> field:</p> +<pre> +notification.defaults |= Notification.DEFAULT_SOUND; +</pre> + +<p>To use a different sound with your notifications, pass a Uri reference to the +<var>sound</var> field. +The following example uses a known audio file saved to the device SD card:</p> +<pre> +notification.sound = Uri.parse("file:///sdcard/notification/ringer.mp3"); +</pre> + +<p>In the next example, the audio file is chosen from the internal +{@link android.provider.MediaStore.Audio.Media MediaStore}'s {@link android.content.ContentProvider}:</p> +<pre> +notification.sound = Uri.withAppendedPath(Audio.Media.INTERNAL_CONTENT_URI, "6"); +</pre> + +<p>In this case, the exact ID of the media file ("6") is known and appended to the content +{@link android.net.Uri}. If you don't know the exact ID, you must query all the +media available in the MediaStore with a {@link android.content.ContentResolver}. +See the <a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> +documentation for more information on using a ContentResolver.</p> + +<p>If you want the sound to continuously repeat until the user responds to the notification +or the notification is cancelled, add "FLAG_INSISTENT" to the <var>flags</var> field.</p> + +<p class="note"><strong>Note:</strong> If the <var>defaults</var> field includes +"DEFAULT_SOUND", then the default sound overrides any sound defined by the <var>sound</var> field.</p> + + +<h3 id="Vibration">Adding vibration</h3> + +<p>You can alert the user with the the default +vibration pattern or with a vibration pattern defined by your application.</p> + +<p>To use the default pattern, add "DEFAULT_VIBRATE" to the <var>defaults</var> field:</p> +<pre> +notification.defaults |= Notification.DEFAULT_VIBRATE; +</pre> + +<p>To define your own vibration pattern, pass an array of <em>long</em> values to the +<var>vibrate</var> field:</p> +<pre> +long[] vibrate = {0,100,200,300}; +notification.vibrate = vibrate; +</pre> + +<p>The long array defines the alternating pattern for the length of vibration off and on +(in milliseconds). The first value is how long to wait (off) before beginning, the second +value is the length of the first vibration, the third is the next length off, and so on. +The pattern can be as long as you like, but it can't be set to repeat. +</p> + +<p class="note"><strong>Note:</strong> If the <var>defaults</var> field includes +"DEFAULT_VIBRATE", then the default vibration overrides any vibration defined by the +<var>vibrate</var> field.</p> + + +<h3 id="Lights">Adding flashing lights</h3> + +<p>To alert the user by flashing LED lights, you can implement the default +light pattern (if available), or define your own color and pattern for the lights.</p> + +<p>To use the default light setting, add "DEFAULT_LIGHTS" to the <var>defaults</var> field:</p> +<pre> +notification.defaults |= Notification.DEFAULT_LIGHTS; +</pre> + +<p>To define your own color and pattern, define a value for the <var>ledARGB</var> field +(for the color), the <var>ledOffMS</var> field (length of time, in milliseconds, to +keep the light off), the <var>ledOnMS</var> (length of time, in milliseconds, to keep the light on), +and also add "FLAG_SHOW_LIGHTS" to the <var>flags</var> field:</p> +<pre> +notification.ledARGB = 0xff00ff00; +notification.ledOnMS = 300; +notification.ledOffMS = 1000; +notification.flags |= Notification.FLAG_SHOW_LIGHTS; +</pre> + +<p>In this example, the green light repeatedly flashes on for 300 milliseconds and +turns off for one second. Not every color in the spectrum is supported by the +device LEDs, and not every device supports the same colors, so the hardware +estimates to the best of its ability. Green is the most common notification color.</p> + + +<h3 id="More">More features</h3> + +<p>You can add several more features to your notifications +using Notification fields and flags. Some useful features include the following:</p> + +<dl> + <dt>"FLAG_AUTO_CANCEL" flag</dt> + <dd>Add this to the <var>flags</var> field to automatically cancel the notification + after it is selected from the Notifications window.</dd> + <dt>"FLAG_INSISTENT" flag</dt> + <dd>Add this to the <var>flags</var> field to repeat the audio until the + user responds.</dd> + <dt>"FLAG_ONGOING_EVENT" flag</dt> + <dd>Add this to the <var>flags</var> field to group the notification under the "Ongoing" + title in the Notifications window. This indicates that the application is on-going — + its processes is still running in the background, even when the application is not + visible (such as with music or a phone call).</dd> + <dt>"FLAG_NO_CLEAR" flag</dt> + <dd>Add this to the <var>flags</var> field to indicate that the notification should + <em>not</em> be cleared by the "Clear notifications" button. This is particularly useful if + your notification is on-going.</dd> + <dt><var>number</var> field</dt> + <dd>This value indicates the current number of events represented by the notification. + The appropriate number is overlayed on top of the status bar icon. + If you intend to use this field, then you must start with "1" when the Notification is first + created. (If you change the value from zero to anything greater during an update, the number + is not shown.)</dd> + <dt><var>iconLevel</var> field</dt> + <dd>This value indicates the current level of a + {@link android.graphics.drawable.LevelListDrawable} that is used for the notification icon. + You can animate the icon in the status bar by changing this value to correlate with the + drawable's defined in a LevelListDrawable. See the {@link android.graphics.drawable.LevelListDrawable} + reference for more information.</dd> +</dl> + +<p>See the {@link android.app.Notification} class reference for more information about additional +features that you can customize for your application.</p> + + +<h2 id="CustomExpandedView">Creating a Custom Expanded View</h2> + +<img src="{@docRoot}images/custom_message.png" alt="" style="float:right;" /> + +<p>By default, the expanded view used in the "Notifications" window includes a basic title and text +message. These are defined by the <var>contentTitle</var> and <var>contentText</var> +parameters of the {@link android.app.Notification#setLatestEventInfo(Context,CharSequence,CharSequence,PendingIntent) +setLatestEventInfo()} method. However, you can also define a custom layout for the expanded view using +{@link android.widget.RemoteViews}. The screenshot to the right shows an example of a +custom expanded view that uses an ImageView and TextView in a LinearLayout.</p> + +<p>To define your own layout for the expanded message, +instantiate a {@link android.widget.RemoteViews} object and +pass it to the <var>contentView</var> field of your Notification. Pass the +{@link android.app.PendingIntent} to the <var>contentIntent</var> field.</p> + +<p>Creating a custom expanded view is best understood with an example:</p> + +<ol> + <li>Create the XML layout for the expanded view. + For example, create a layout file called <code>custom_notification_layout.xml</code> and + build it like so: +<pre> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:orientation="horizontal" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:padding="3dp" + > + <ImageView android:id="@+id/image" + android:layout_width="wrap_content" + android:layout_height="fill_parent" + android:layout_marginRight="10dp" + /> + <TextView android:id="@+id/text" + android:layout_width="wrap_content" + android:layout_height="fill_parent" + android:textColor="#000" + /> +</LinearLayout> +</pre> + + <p>This layout is used for the expanded view, + but the content of the ImageView and TextView still needs to be defined by the applicaiton. + RemoteViews offers some convenient methods that allow you to define this content...</p> + </li> + + <li>In the application code, use the RemoveViews + methods to define the image and text. Then pass the RemoteViews object to the <var>contentView</var> + field of the Notification, as shown in this example: +<pre> +RemoteViews contentView = new RemoteViews(getPackageName(), R.layout.custom_notification_layout); +contentView.setImageViewResource(R.id.image, R.drawable.notification_image); +contentView.setTextViewText(R.id.text, "Hello, this message is in a custom expanded view"); +notification.contentView = contentView; +</pre> + + <p>As shown here, pass the applicaiton's package name and the layout + resource ID to the RemoteViews constructor. Then, define the content for the ImageView and TextView, + using the {@link android.widget.RemoteViews#setImageViewResource(int, int) setImageViewResource()} + and {@link android.widget.RemoteViews#setTextViewText(int, CharSequence) setTextViewText()}. + In each case, pass the reference ID of the appropriate View object that you want to set, along with + the value for that View. Finally, the RemoteViews object is passed to the Notification in the + <var>contentView</var> field.</p> + </li> + + <li>Because you don't need the + {@link android.app.Notification#setLatestEventInfo(Context,CharSequence,CharSequence,PendingIntent) + setLatestEventInfo()} method when using a custom view, you must define the Intent for the Notification + with the <var>contentIntent</var> field, as in this example: +<pre> +Intent notificationIntent = new Intent(this, MyClass.class); +PendingIntent contentIntent = PendingIntent.getActivity(this, 0, notificationIntent, 0); +notification.contentIntent = contentIntent; +</pre> + </li> + + <li>The notification can now be sent as usual: + <pre>mNotificationManager.notify(CUSTOM_VIEW_ID, notification);</pre> + </li> +</ol> + + +<p>The RemoteViews class also includes methods that you can use to easily add a +{@link android.widget.Chronometer} or {@link android.widget.ProgressBar} +in your notification's expanded view. For more information about creating custom layouts with +RemoteViews, refer to the {@link android.widget.RemoteViews} class reference.</p> + +<p class="warning"><strong>Note:</strong> +When creating a custom expanded view, you must take special care to ensure that your +custom layout functions properly in different device orientations and resolutions. While this +advice applies to all View layouts created on Android, it is especially important in this case +because your layout real estate is very restricted. So don't make your custom layout too +complex and be sure to test it in various configurations.</p> + + + + diff --git a/docs/html/guide/topics/ui/notifiers/toasts.jd b/docs/html/guide/topics/ui/notifiers/toasts.jd new file mode 100644 index 0000000..a800c3c --- /dev/null +++ b/docs/html/guide/topics/ui/notifiers/toasts.jd @@ -0,0 +1,154 @@ +page.title=Creating Toast Notifications +parent.title=Notifying the User +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>Key classes</h2> + <ol> + <li>{@link android.widget.Toast}</li> + </ol> + <h2>In this document</h2> + <ol> + <li><a href="#Basics">The Basics</a></li> + <li><a href="#Position">Positioning your Toast</a></li> + <li><a href="#CustomToastView">Creating a Custom Toast View</a></li> + </ol> + </div> +</div> + +<p>A toast notificaiton is a message that pops up on the surface of the window. +It only fills the amount of space required for the message and the user's current +activity remains visible and interactive. The notification automatically fades in and +out, and does not accept interaction events.</p> + +<p>The screenshot below shows an example toast notification from the Alarm application. +Once an alarm is turned on, a toast is displayed to assure you that the +alarm was set.</p> +<img src="{@docRoot}images/toast.png" alt="" /> + +<p>A toast can be created and displayed from an {@link android.app.Activity} or +{@link android.app.Service}. If you create a toast notification from a Service, it +appears in front of the Activity currently in focus.</p> + +<p>If user response to the notification is required, consider using a +<a href="notifications.html">Status Bar Notification</a>.</p> + + +<h2 id="Basics">The Basics</h2> + +<p>First, instantiate a {@link android.widget.Toast} +object with one of the {@link android.widget.Toast#makeText(Context,int,int) makeText()} methods. +This method takes three parameters: the application {@link android.content.Context}, +the text message, and the duration for the toast. It returns a properly initialized Toast +object. You can display the toast notification with {@link android.widget.Toast#show()}, +as shown in the following example:</p> + +<pre> +Context context = getApplicationContext(); +CharSequence text = "Hello toast!"; +int duration = Toast.LENGTH_SHORT; + +Toast toast = Toast.makeText(context, text, duration); +toast.show(); +</pre> + +<p>This example demonstrates everything you need for most toast notifications. +You should rarely need anything else. You may, however, want to position the +toast differently or even use your own layout instead of a simple text message. +The following sections describe how you can do these things.</p> + +<p>You can also chain your methods and avoid holding on to the Toast object, like this:</p> +<pre>Toast.makeText(context, text, duration).show();</pre> + + +<h2 id="Positioning">Positioning your Toast</h2> + +<p>A standard toast notification appears near the bottom of the screen, centered horizontally. +You can change this position with the {@link android.widget.Toast#setGravity(int,int,int)} +method. This accepts three parameters: a {@link android.view.Gravity} constant, +an x-position offset, and a y-position offset.</p> + +<p>For example, if you decide that the toast should appear in the top-left corner, you can set the +gravity like this:</p> +<pre> +toast.setGravity(Gravity.TOP|Gravity.LEFT, 0, 0); +</pre> + +<p>If you want to nudge the position to the right, increase the value of the second parameter. +To nudge it down, increase the value of the last parameter. + + +<h2 id="CustomToastView">Creating a Custom Toast View</h2> + +<img src="{@docRoot}images/custom_toast.png" alt="" style="float:right" /> + +<p>If a simple text message isn't enough, you can create a customized layout for your +toast notification. To create a custom layout, define a View layout, +in XML or in your application code, and pass the root {@link android.view.View} object +to the {@link android.widget.Toast#setView(View)} method.</p> + +<p>For example, you can create the layout for the toast visible in the screenshot to the right +with the following XML (saved as <em>toast_layout.xml</em>):</p> +<pre> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/toast_layout_root" + android:orientation="horizontal" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:padding="10dp" + android:background="#DAAA" + > + <ImageView android:id="@+id/image" + android:layout_width="wrap_content" + android:layout_height="fill_parent" + android:layout_marginRight="10dp" + /> + <TextView android:id="@+id/text" + android:layout_width="wrap_content" + android:layout_height="fill_parent" + android:textColor="#FFF" + /> +</LinearLayout> +</pre> + +<p>Notice that the ID of the LinearLayout element is "toast_layout". You must use this +ID to inflate the layout from the XML, as shown here:</p> + +<pre> +LayoutInflater inflater = getLayoutInflater(); +View layout = inflater.inflate(R.layout.toast_layout, + (ViewGroup) findViewById(R.id.toast_layout_root)); + +ImageView image = (ImageView) layout.findViewById(R.id.image); +image.setImageResource(R.drawable.android); +TextView text = (TextView) layout.findViewById(R.id.text); +text.setText("Hello! This is a custom toast!"); + +Toast toast = new Toast(getApplicationContext()); +toast.setGravity(Gravity.CENTER_VERTICAL, 0, 0); +toast.setDuration(Toast.LENGTH_LONG); +toast.setView(layout); +toast.show(); +</pre> + +<p>First, retrieve the {@link android.view.LayoutInflater} with +{@link android.app.Activity#getLayoutInflater()} +(or {@link android.content.Context#getSystemService(String) getSystemService()}), +and then inflate the layout from XML using +{@link android.view.LayoutInflater#inflate(int, ViewGroup)}. The first parameter +is the layout resource ID and the second is the root View. You can use +this inflated layout to find more View objects in the layout, so now capture and +define the content for the ImageView and TextView elements. Finally, create +a new Toast with {@link android.widget.Toast#Toast(Context)} and set some properties +of the toast, such as the gravity and duration. Then call +{@link android.widget.Toast#setView(View)} and pass it the inflated layout. +You can now display the toast with your custom layout by calling +{@link android.widget.Toast#show()}.</p> + +<p class="note"><strong>Note:</strong> Do not use the public constructor for a Toast +unless you are going to define the layout with {@link android.widget.Toast#setView(View)}. +If you do not have a custom layout to use, you must use +{@link android.widget.Toast#makeText(Context,int,int)} to create the Toast.</p> + diff --git a/docs/html/guide/tutorials/hello-world.jd b/docs/html/guide/tutorials/hello-world.jd index f277b10..4d1e9cd 100644 --- a/docs/html/guide/tutorials/hello-world.jd +++ b/docs/html/guide/tutorials/hello-world.jd @@ -1,6 +1,21 @@ page.title=Hello, World @jd:body +<div id="qv-wrapper"> + <div id="qv"> + <h2>In this document</h2> + <ol> + <li><a href="#avd">Create an AVD</a></li> + <li><a href="#create">Create the Project</a></li> + <li><a href="#ui">Construct the UI</a></li> + <li><a href="#run">Run the Code</a></li> + <li><a href="#upgrading">Upgrade the UI to an XML Layout</a></li> + <li><a href="#debugging">Debug Your Project</a></li> + <li><a href="#noeclipse">Creating the Project Without Eclipse</a></li> + </ol> + </div> +</div> + <p>As a developer, you know that the first impression of a development framework is how easy it is to write "Hello, World." Well, on Android, it's pretty easy. @@ -19,56 +34,63 @@ here when you've completed the installation.</p> <h2 id="avd">Create an AVD</h2> -<p class="note"><strong>Note:</strong> If you're developing with an Android SDK older -than the one provided for Android 1.5, you can skip this step and continue with -<a href="#create">Create the Project</a>.</p> +<div class="sidebox-wrapper"> + <div class="sidebox-inner"> + <p>To learn more about how to use AVDs and the options + available to you, refer to the + <a href="{@docRoot}guide/developing/tools/avd.html">Android + Virtual Devices</a> document.</p> + </div> +</div> -<p>In this tutorial, you will run your applicion in the Android Emulator. +<p>In this tutorial, you will run your application in the Android Emulator. Before you can launch the emulator, you must create an Android Virtual Device (AVD). An AVD defines the system image and device settings used by the emulator.</p> -<p>To create an AVD, use the <code>android</code> tool provided in the Android SDK. +<p>To create an AVD, use the "android" tool provided in the Android SDK. Open a command prompt or terminal, navigate to the -<code>/tools</code> directory in the SDK package and execute: +<code>tools/</code> directory in the SDK package and execute: <pre> -android create avd --target 1 --name myavd +android create avd --target 2 --name my_avd </pre> -<p>The tool now asks if you would like to create a custom hardware profile, say -<code>no</code>. That's it. You now have an AVD and can use it to run the Emulator.</p> +<p>The tool now asks if you would like to create a custom hardware profile. +For the time being, press Return to skip it ("no" is the default response). +That's it. This configures an AVD named "my_avd" that uses the Android 1.5 +platform. The AVD is now ready for use in the emulator.</p> + +<p>In the above command, the <code>--target</code> option is required +and specifies the deployment target to run on the emulator. +The <code>--name</code> option is also required and defines the +name for the new AVD.</p> -<p>In the above command, the <code>target</code> option is required -and specifies the target platform for the emulator. (A target defines the system image, -API level and supported skins. To view all available targets, execute: -<code>android list target</code>.) The <code>name</code> option is also required -and defines the name for the new AVD. For more information about <code>android</code>, -see the <a href="{@docRoot}guide/developing/tools/android.html">Android Tool</a> -documentation.</p> -<h2 id="create">Create the Project</h2> +<h2 id="create">Create a New Android Project</h2> + +<p>After you've created an AVD, the next step is to start a new +Android project in Eclipse.</p> <ol> - <li><strong>Open a new Android Project.</strong> - <p>From Eclipse, select the <strong>File > New > Project</strong> menu item. If the Android - Plugin for Eclipse has been successfully installed, the resulting dialog - should have a folder labeled "Android" which should contain a single entry: - "Android Project". (After you create one or more Android projects, an entry for - "Android XML File" will also be available.)</p> - <p>Selected "Android Project" and click <strong>Next</strong>.</p> - - <a href="images/hello_world_0.png"><img src="images/hello_world_0.png" style="height:230px" alt="" /></a> + <li>From Eclipse, select <strong>File > New > Project</strong>. + <p>If the ADT + Plugin for Eclipse has been successfully installed, the resulting dialog + should have a folder labeled "Android" which should contain + "Android Project". (After you create one or more Android projects, an entry for + "Android XML File" will also be available.)</p> + </li> + <li>Selected "Android Project" and click <strong>Next</strong>. + <a href="images/hello_world_0.png"><img src="images/hello_world_0.png" style="height:230px" alt="" /></a> </li> - <li><strong>Fill out the project details.</strong> - <p>The next screen allows you to enter the relevant details for your project:</p> + <li>Fill in the project details with the following values: <ul> <li><em>Project name:</em> HelloAndroid</li> <li><em>Application name:</em> Hello, Android</li> <li><em>Package name:</em> com.example.helloandroid (or your own private namespace)</li> <li><em>Create Activity:</em> HelloAndroid</li> - <li><em>Min SDK Version:</em> 3</li> + <li><em>Min SDK Version:</em> 2</li> </ul> <p>Click <strong>Finish</strong>.</p> @@ -102,25 +124,34 @@ documentation.</p> chooses, but it doesn't need to. As the checkbox suggests, this is optional, but an Activity is almost always used as the basis for an application.</dd> <dt><em>Min SDK Version</em></dt> - <dd>This value specifies the API Level required by your application. With each new + <dd>This value specifies the minimum API Level required by your application. If the API Level + entered here matches the API Level provided by one of the available targets, + then that Build Target will be automatically selected (in this case, entering + "2" as the API Level will select the Android 1.1 target). With each new version of the Android system image and Android SDK, there have likely been additions or changes made to the APIs. When this occurs, a new API Level is assigned to the system image to regulate which applications are allowed to be run. If an - application requires an API Level that is higher than the level supported by the device, - then the application is not allowed to be installed. Because the "Hello World" - application uses APIs that have not changed since the first release, you can safely - declare API Level "1" for the Min SDK Version, which is supported by all Android - devices.</dd> + application requires an API Level that is <em>higher</em> than the level supported + by the device, then the application will not be installed.</dd> </dl> <p><em>Other fields</em>: The checkbox for "Use default location" allows you to change - the location on disk where the project's files will be generated and stored. "Target" - is the platform target for your application.</p> - + the location on disk where the project's files will be generated and stored. "Build Target" + is the platform target that your application will be compiled against + (this should be selected automatically, based on your Min SDK Version).</p> + + <p class="note">Notice that the "Build Target" you've selected uses the Android 1.1 + platform. This means that your application will be compiled against the Android 1.1 + platform library. If you recall, the AVD created above runs on the Android 1.5 platform. + These don't have to match; Android applications are forward-compatible, so an application + built against the 1.1 platform library will run normally on the 1.5 platform. The reverse + is not true.</p> </li> +</ul> -<li><strong>View the generated Activity.</strong> -<p>Open the HelloAndroid.java file, located inside <em>HelloAndroid > src > +<p>Your Android project is now ready. It should be visible in the Package +Explorer on the left. +Open the <code>HelloAndroid.java</code> file, located inside <em>HelloAndroid > src > com.example.helloandroid</em>). It should look like this:</p> <pre> @@ -147,8 +178,6 @@ it is where you should perform all initialization and UI setup. An activity is n have a user interface, but usually will.</p> <p>Now let's modify some code! </p> -</li> -</ol> <h2 id="ui">Construct the UI</h2> @@ -191,10 +220,10 @@ on. The Activity class inherits from Context, and because your HelloAndroid class is a subclass of Activity, it is also a Context. So, you can pass <code>this</code> as your Context reference to the TextView.</p> -<p>Next, define the text content with +<p>Next, you define the text content with {@link android.widget.TextView setText(CharSequence) setText()}.</p> -<p>Finally, pass the TextView to +<p>Finally, you pass the TextView to {@link android.app.Activity#setContentView(View) setContentView()} in order to display it as the content for the Activity UI. If your Activity doesn't call this method, then no UI is present and the system will display a blank @@ -204,42 +233,39 @@ screen.</p> to see it running.</p> -<h2 id="run">Run the Code</h2> +<h2 id="run">Run the Application</h2> -<p>The Eclipse plugin makes it very easy to run your applications. -Select <strong>Run > Run Configurations</strong> (in Eclipse 3.3, -<strong>Run > Open Run Dialog</strong>).</p> +<p>The Eclipse plugin makes it very easy to run your applications:</p> -<p>Select the "Android Application" entry, and click the icon in the -top left corner (the one depicting a sheet of paper with a plus symbol) -or double-click on "Android Application." You should -have a new launcher entry named "New_configuration".</p> - - <a href="images/hello_world_3.png"><img src="images/hello_world_3.png" style="height:230px" alt="" /></a> +<ol> + <li>Select <strong>Run > Run</strong>.</li> + <li>Select "Android Application".</li> +</ol> -<p>Change the name to something meaningful like "Android Activity." Then pick -click the <strong>Browse</strong> button and select your HelloAndroid project. The -plugin will automatically scan your project for Activity subclasses and add -each one it finds to the drop-down list under "Launch Action." Because the -HelloAndroid project only has one Activity, it will be the default Activity. -Leave "Launch Default Activity" selected.</p> +<div class="sidebox-wrapper"> + <div class="sidebox-inner"> + <p>To learn more about creating and editing run configurations in Eclipse, refer to + <a href="{@docRoot}guide/developing/eclipse-adt.html#RunConfig">Developing In Eclipse, + with ADT</a>.</p> + </div> +</div> -<p>Click the <strong>Apply</strong>, then <strong>Run</strong>. The Android Emulator -will start and once it's booted up your application will appear. You should now -see something like this:</p> +<p>The Eclipse ADT will automatically create a new run configuration for your project +and the Android Emulator will automatically launch. Once the emulator is booted up, +your application will appear after a moment. You should now see something like this:</p> <a href="images/hello_world_5.png"><img src="images/hello_world_5.png" style="height:230px" alt="" /></a> <p>The "Hello, Android" you see in the grey bar is actually the application title. The Eclipse plugin -creates this automatically (the string is defined in the /res/values/strings.xml file and referenced -by your AndroidManifest.xml file). The text below the title is the actual text that you have +creates this automatically (the string is defined in the <code>res/values/strings.xml</code> file and referenced +by your <code>AndroidManifest.xml</code> file). The text below the title is the actual text that you have created in the TextView object.</p> -<p>That covers the basic "Hello World" tutorial, but you should continue reading for some more +<p>That concludes the basic "Hello World" tutorial, but you should continue reading for some more valuable information about developing Android applications.</p> -<h2 id="upgrading">Upgrading the UI to an XML Layout</h2> +<h2 id="upgrading">Upgrade the UI to an XML Layout</h2> <p>The "Hello, World" example you just completed uses what is called a "programmatic" UI layout. This means that you constructed and built your application's UI @@ -326,7 +352,7 @@ In this case, it's the only View so you want it to take up the entire screen, wh </table> -<p>These XML layout files belong in the <em>res/layout/</em> directory of your project. The "res" is +<p>These XML layout files belong in the <code>res/layout/</code> directory of your project. The "res" is short for "resources" and the directory contains all the non-code assets that your application requires. In addition to layout files, resources also include assets such as images, sounds, and localized strings.</p> @@ -348,7 +374,7 @@ existing application to use an XML layout.</p> <ol> <li>In the Eclipse Package Explorer, expand the -<em>/res/layout/</em> folder and open <em>main.xml</em> (once opened, you might need to click +<code>/res/layout/</code> folder and open <code>main.xml</code> (once opened, you might need to click the "main.xml" tab at the bottom of the window to see the XML source). Replace the contents with the following XML: @@ -360,7 +386,7 @@ the following XML: <p>Save the file.</p> </li> -<li>Inside the <em>/res/values</em> folder, open <em>strings.xml</em>. +<li>Inside the <code>res/values/</code> folder, open <code>strings.xml</code>. This is where you should save all default text strings for your user interface. If you're using Eclipse, then ADT will have started you with two strings, <em>hello</em> and <em>app_name</em>. Revise <em>hello</em> to something else. Perhaps "Hello, Android! I am a string resource!" @@ -398,7 +424,7 @@ suggestions. You'll find that it helps in a lot of situations.</p> <p>Instead of passing <code>setContentView()</code> a View object, you give it a reference to the layout resource. The resource is identified as <code>R.layout.main</code>, which is actually a compiled object representation of -the layout defined in <em>/res/layout/main.xml</em>. The Eclipse plugin automatically creates this reference for +the layout defined in <code>/res/layout/main.xml</code>. The Eclipse plugin automatically creates this reference for you inside the project's R.java class. If you're not using Eclipse, then the R.java class will be generated for you when you run Ant to build the application. (More about the R class in a moment.)</p> </li> @@ -423,7 +449,7 @@ introduction page for an overview of the <em>Dev Guide</em> documentation.</p> <div class="special"> <h3>R class</h3> -<p>In Eclipse, open the file named R.java (in the /gen [Generated Java Files] folder). +<p>In Eclipse, open the file named <code>R.java</code> (in the <code>gen/</code> [Generated Java Files] folder). It should look something like this:</p> <pre> @@ -445,7 +471,7 @@ public final class R { } </pre> -<p>A project's R.java file is an index into all the resources defined in the +<p>A project's <code>R.java</code> file is an index into all the resources defined in the file. You use this class in your source code as a sort of short-hand way to refer to resources you've included in your project. This is particularly powerful with the code-completion features of IDEs like Eclipse @@ -456,13 +482,13 @@ you're looking for.</p> For now, notice the inner class named "layout", and its member field "main". The Eclipse plugin noticed the XML layout file named main.xml and generated a class for it here. As you add other -resources to your project (such as strings in the <em>res/values/string.xml</em> file or drawables inside -the <em>res/drawable/</em> direcory) you'll see R.java change to keep up.</p> +resources to your project (such as strings in the <code>res/values/string.xml</code> file or drawables inside +the <code>res/drawable/</code> direcory) you'll see <code>R.java</code> change to keep up.</p> <p>When not using Eclipse, this class file will be generated for you at build time (with the Ant tool).</p> <p><em>You should never edit this file by hand.</em></p> </div> -<h2 id="debugging">Debugging Your Project</h2> +<h2 id="debugging">Debug Your Project</h2> <p>The Android Plugin for Eclipse also has excellent integration with the Eclipse debugger. To demonstrate this, introduce a bug into @@ -515,9 +541,9 @@ just as you would for any other application.</p> Thus, it's possible to wrap those tools with another tool, such as an 'ant' build file.</p> - <p>The Android SDK includes a toolk named "android" that can be + <p>The Android SDK includes a tool named "android" that can be used to create all the source code and directory stubs for your project, as well - as an ant-compatible build.xml file. This allows you to build your project + as an ant-compatible <code>build.xml</code> file. This allows you to build your project from the command line, or integrate it with the IDE of your choice.</p> <p>For example, to create a HelloAndroid project similar to the one created @@ -527,18 +553,12 @@ just as you would for any other application.</p> android create project \ --package com.android.helloandroid \ --activity HelloAndroid \ - --target 1 \ - --path <em><path-for-your-project></em>/HelloAndroid \ - --mode activity + --target 2 \ + --path <em><path-to-your-project></em>/HelloAndroid </pre> <p>This creates the required folders and files for the project at the location defined by the <em>path</em>.</p> - <p>To build the project, you'd then run the command <code>ant</code>. When that command - successfully completes, you'll be left with a file named HelloAndroid.apk under - the "bi"' directory. That .apk file is an Android Package, and can be - installed and run in your emulator using the 'adb' tool.</p> - - <p>For more information on how to use these tools, please read + <p>For more information on how to use the SDK tools to create and build projects, please read <a href="{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>.</p> diff --git a/docs/html/guide/tutorials/images/hello_world_1.png b/docs/html/guide/tutorials/images/hello_world_1.png Binary files differindex 02682f4..1e5f7b0 100644 --- a/docs/html/guide/tutorials/images/hello_world_1.png +++ b/docs/html/guide/tutorials/images/hello_world_1.png diff --git a/docs/html/guide/tutorials/images/hello_world_9.png b/docs/html/guide/tutorials/images/hello_world_9.png Binary files differindex e172e63..a66526a 100644 --- a/docs/html/guide/tutorials/images/hello_world_9.png +++ b/docs/html/guide/tutorials/images/hello_world_9.png diff --git a/docs/html/guide/tutorials/notepad/codelab/NotepadCodeLab.zip b/docs/html/guide/tutorials/notepad/codelab/NotepadCodeLab.zip Binary files differindex c7dd989..24fefc1 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 b7f42bf..b5173b8 100644 --- a/docs/html/guide/tutorials/notepad/notepad-ex1.jd +++ b/docs/html/guide/tutorials/notepad/notepad-ex1.jd @@ -44,11 +44,13 @@ selections. </em></li> In the New Android Project dialog, select <strong>Create project from existing source</strong>.</li> <li> Click <strong>Browse</strong> and navigate to where you copied the <code>NotepadCodeLab</code> - (downloaded during <a href="{@docRoot}guide/tutorials/notepad/index.html#preparing">setup</a>). Select - <code>Notepadv1</code> and click <strong>Choose</strong>.</li> + (downloaded during <a href="{@docRoot}guide/tutorials/notepad/index.html#preparing">setup</a>) + and select <code>Notepadv1</code>.</li> <li> - You should see <code>Notepadv1</code> in the <em>Project name</em> and also see the <em>Location</em> - filled in with the path you selected.</li> + The Project Name and other properties should be automatically filled for you. + You must select the Build Target—we recommend selecting a target with the + lowest platform version available. Also add an integer to the Min SDK Version field + that matches the API Level of the selected Build Target.</li> <li> Click <strong>Finish</strong>. The <code>Notepadv1</code> project should open and be visible in your Eclipse package explorer.</li> diff --git a/docs/html/guide/tutorials/views/hello-mapview.jd b/docs/html/guide/tutorials/views/hello-mapview.jd index 976b8ab..868bfaa 100644 --- a/docs/html/guide/tutorials/views/hello-mapview.jd +++ b/docs/html/guide/tutorials/views/hello-mapview.jd @@ -3,6 +3,32 @@ parent.title=Hello, Views parent.link=index.html @jd:body +<div class="special"> +<p>This tutorial requires that you have the Google Maps external library +installed in your SDK environment. By default the Android 1.5 SDK includes the +Google APIs add-on, which in turn includes the Maps external library. If you +don't have the Google APIs SDK add-on, you can download it from this +location:</p> + +<p style="margin-left:2em;"><a +href="http://code.google.com/android/add-ons/google-apis">http://code.google.com/android/add-ons/google-apis</a></p> + +<p>The Google APIs add-on requires Android 1.5 SDK or later release. After +installing the add-on in your SDK, set your project properties to use the build +target called "Google APIs Add-on". See the instructions for setting a build +target in <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing in +Eclipse with ADT</a> or <a +href="{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>, +as appropriate for your environment. </p> + +<p>You will also need to use the android tool to set up an AVD that uses the +Google APIs deployment target. See <a +href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a> for +more information. Once you have set up your environment, you will be able to +build and run the project described in this tutorial</a></p> + +</div> + <p>A MapView allows you to create your own map-viewing Activity. First, we'll create a simple Activity that can view and navigate a map. Then we will add some overlay items.</p> @@ -49,7 +75,7 @@ First, we'll create a simple Activity that can view and navigate a map. Then we certificate has been registered with the Google Maps service. Because MapView uses Google Maps data, this key is required in order to receive the map data, even while you are developing. Registration is free and it only takes a couple minutes to register your certificate and receive a Maps API Key. For instructions on getting a key, read - <a href="{@docRoot}guide/topics/location/geo/mapkey.html">Obtaining a Maps API Key</a>. + <a href="http://code.google.com/android/add-ons/google-apis/mapkey.html">Obtaining a Maps API Key</a>. (For the purpose of this tutorial, you should register with the fingerprint of the SDK debug certificate.) Once you've acquired the Maps API Key, insert it for the <code>apiKey</code> value.</p></li> |
