From 5fe696f7b0ffe3b40d75026b16983246ec4cda4c Mon Sep 17 00:00:00 2001 From: Scott Main <> Date: Sun, 26 Apr 2009 23:57:28 -0700 Subject: AI 147814: tweaks to the hello world tutorial. use an API Level 2 build target, but deploy to level 3, add some discussion on this; instantly run, instead of creating a new configuration; update screenshots for ADT wizard and the debug section; other edits BUG=1791815 Automated import of CL 147814 --- docs/html/guide/tutorials/hello-world.jd | 190 ++++++++++++--------- docs/html/guide/tutorials/images/hello_world_1.png | Bin 9635 -> 10031 bytes docs/html/guide/tutorials/images/hello_world_9.png | Bin 25933 -> 6791 bytes 3 files changed, 106 insertions(+), 84 deletions(-) (limited to 'docs/html/guide/tutorials') diff --git a/docs/html/guide/tutorials/hello-world.jd b/docs/html/guide/tutorials/hello-world.jd index f277b10..a888529 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 +
+
+

In this document

+
    +
  1. Create an AVD
    2. +
  2. Create the Project
    3. +
  3. Construct the UI
    4. +
  4. Run the Code
    5. +
  5. Upgrade the UI to an XML Layout
    6. +
  6. Debug Your Project
    7. +
  7. Creating the Project Without Eclipse
    8. +
+
+
+

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. @@ -23,52 +38,61 @@ here when you've completed the installation.

than the one provided for Android 1.5, you can skip this step and continue with Create the Project.

-

In this tutorial, you will run your applicion in the Android Emulator. +

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.

-

To create an AVD, use the android tool provided in the Android SDK. +

To create an AVD, use the "android" tool provided in the Android SDK. Open a command prompt or terminal, navigate to the -/tools directory in the SDK package and execute: +tools/ directory in the SDK package and execute: 

-android create avd --target 1 --name myavd
+android create avd --target 2 --name my_avd
-

The tool now asks if you would like to create a custom hardware profile, say -no. That's it. You now have an AVD and can use it to run the Emulator.

+

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.

+ +
+
+

To learn more about Android Virtual Devices (and targets), refer to the + AVD document.

+
+
+ +

In the above command, the --target option is required +and specifies the deployment target to run on the emulator. +The --name option is also required and defines the +name for the new AVD.

+ -

In the above command, the target 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: -android list target.) The name option is also required -and defines the name for the new AVD. For more information about android, -see the Android Tool -documentation.

+

Create a New Android Project

-

Create the Project

+

After you've created an AVD, the next step is to start a new +Android project in Eclipse.

    -
  1. Open a new Android Project. -

    From Eclipse, select the File > New > Project 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.)

    -

    Selected "Android Project" and click Next.

    - - +
  2. From Eclipse, select File > New > Project. +

    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.)

    +
    3. +
  3. Selected "Android Project" and click Next. +
    4. -
  4. Fill out the project details. -

    The next screen allows you to enter the relevant details for your project:

    +
  5. Fill in the project details with the following values:

    Click Finish.

    @@ -102,25 +126,34 @@ documentation.

    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.
    Min SDK Version
    -
    This value specifies the API Level required by your application. With each new +
    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.
    + application requires an API Level that is higher than the level supported + by the device, then the application will not be installed.

    Other fields: 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.

    - + 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).

    + +

    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.

    6. + -
  6. View the generated Activity. -

    Open the HelloAndroid.java file, located inside HelloAndroid > src > +

    Your Android project is now ready. It should be visible in the Package +Explorer on the left. +Open the HelloAndroid.java file, located inside HelloAndroid > src > com.example.helloandroid). It should look like this:

    @@ -147,8 +180,6 @@ it is where you should perform all initialization and UI setup. An activity is n
 have a user interface, but usually will.
    
 
 
    Now let's modify some code! 
    
-
    7. -

Construct the UI

@@ -191,10 +222,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 this as your Context reference to the TextView.

-

Next, define the text content with +

Next, you define the text content with {@link android.widget.TextView setText(CharSequence) setText()}.

-

Finally, pass the TextView to +

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 +235,39 @@ screen.

to see it running.

-

Run the Code

+

Run the Application

-

The Eclipse plugin makes it very easy to run your applications. -Select Run > Run Configurations (in Eclipse 3.3, -Run > Open Run Dialog).

+

The Eclipse plugin makes it very easy to run your applications:

-

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".

- - +
    +
  1. Select Run > Run.
    2. +
  2. Select "Android Application".
    3. +
-

Change the name to something meaningful like "Android Activity." Then pick -click the Browse 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.

+
+
+

To learn more about creating and editing run configurations in Eclipse, refer to + Developing In Eclipse, + with ADT.

+
+
-

Click the Apply, then Run. The Android Emulator -will start and once it's booted up your application will appear. You should now -see something like this:

+

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:

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 res/values/strings.xml file and referenced +by your AndroidManifest.xml file). The text below the title is the actual text that you have created in the TextView object.

-

That covers the basic "Hello World" tutorial, but you should continue reading for some more +

That concludes the basic "Hello World" tutorial, but you should continue reading for some more valuable information about developing Android applications.

-

Upgrading the UI to an XML Layout

+

Upgrade the UI to an XML Layout

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 +354,7 @@ In this case, it's the only View so you want it to take up the entire screen, wh -

These XML layout files belong in the res/layout/ directory of your project. The "res" is +

These XML layout files belong in the res/layout/ 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.

@@ -348,7 +376,7 @@ existing application to use an XML layout.

  1. In the Eclipse Package Explorer, expand the -/res/layout/ folder and open main.xml (once opened, you might need to click +/res/layout/ folder and open main.xml (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 +388,7 @@ the following XML:

    Save the file.

    2. -
  2. Inside the /res/values folder, open strings.xml. +
  3. Inside the res/values/ folder, open strings.xml. 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, hello and app_name. Revise hello to something else. Perhaps "Hello, Android! I am a string resource!" @@ -398,7 +426,7 @@ suggestions. You'll find that it helps in a lot of situations.

    Instead of passing setContentView() a View object, you give it a reference to the layout resource. The resource is identified as R.layout.main, which is actually a compiled object representation of -the layout defined in /res/layout/main.xml. The Eclipse plugin automatically creates this reference for +the layout defined in /res/layout/main.xml. 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.)

    4. @@ -423,7 +451,7 @@ introduction page for an overview of the Dev Guide documentation.

    R class

    -

    In Eclipse, open the file named R.java (in the /gen [Generated Java Files] folder). +

    In Eclipse, open the file named R.java (in the gen/ [Generated Java Files] folder). It should look something like this:

    @@ -445,7 +473,7 @@ public final class R {
 }
    -

    A project's R.java file is an index into all the resources defined in the +

    A project's R.java file is an index into all the resources defined in the file. You use this class in your source code as a sort of short-hand way to refer to resources you've included in your project. This is particularly powerful with the code-completion features of IDEs like Eclipse @@ -456,13 +484,13 @@ you're looking for.

    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 res/values/string.xml file or drawables inside -the res/drawable/ direcory) you'll see R.java change to keep up.

    +resources to your project (such as strings in the res/values/string.xml file or drawables inside +the res/drawable/ direcory) you'll see R.java change to keep up.

    When not using Eclipse, this class file will be generated for you at build time (with the Ant tool).

    You should never edit this file by hand.

    -

    Debugging Your Project

    +

    Debug Your Project

    The Android Plugin for Eclipse also has excellent integration with the Eclipse debugger. To demonstrate this, introduce a bug into @@ -515,9 +543,9 @@ just as you would for any other application.

    Thus, it's possible to wrap those tools with another tool, such as an 'ant' build file.

    -

    The Android SDK includes a toolk named "android" that can be +

    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 build.xml file. This allows you to build your project from the command line, or integrate it with the IDE of your choice.

    For example, to create a HelloAndroid project similar to the one created @@ -527,18 +555,12 @@ just as you would for any other application.

    android create project \ --package com.android.helloandroid \ --activity HelloAndroid \ - --target 1 \ - --path <path-for-your-project>/HelloAndroid \ - --mode activity + --target 2 \ + --path <path-to-your-project>/HelloAndroid

    This creates the required folders and files for the project at the location defined by the path.

    -

    To build the project, you'd then run the command ant. When that command - successfully completes, you'll be left with a file named HelloAndroid.apk under - the "bi"' directory. That .apk file is an Android Package, and can be - installed and run in your emulator using the 'adb' tool.

    - -

    For more information on how to use these tools, please read +

    For more information on how to use the SDK tools to create and build projects, please read Developing in Other IDEs.

    diff --git a/docs/html/guide/tutorials/images/hello_world_1.png b/docs/html/guide/tutorials/images/hello_world_1.png index 02682f4..1e5f7b0 100644 Binary files a/docs/html/guide/tutorials/images/hello_world_1.png and b/docs/html/guide/tutorials/images/hello_world_1.png differ diff --git a/docs/html/guide/tutorials/images/hello_world_9.png b/docs/html/guide/tutorials/images/hello_world_9.png index e172e63..a66526a 100644 Binary files a/docs/html/guide/tutorials/images/hello_world_9.png and b/docs/html/guide/tutorials/images/hello_world_9.png differ -- cgit v1.1