Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit e874366f authored by Bill Gruber's avatar Bill Gruber
Browse files

Cherry pick from honeycomb-mr2 Change ID I7ded723152d7beface51b45b882d4ccf92981927 

Doc fix: Hello World tutorial updates
Bug: 5149925

Change-Id: I715947dbda66657a92d5b86fb467444f331029cd
parent 890be6b9

docs/html/resources/tutorials/hello-world.jd

+112 −105
Original line number Diff line number Diff line
@@ -18,16 +18,14 @@ parent.link=../browser.html?tag=tutorial 
  </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. 

It's particularly easy if you're using Eclipse as your IDE, because we've provided a

great plugin that handles your project creation and management to greatly speed-up your

development cycles.</p>

<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. It's particularly easy if you're using

Eclipse as your IDE, because we've provided a great plugin that handles your project creation and

management to greatly speed up your development cycles.</p>



<p>This tutorial assumes that you're using Eclipse. If you're not, see 

<a href="{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>.

You can then return to this tutorial and ignore anything about Eclipse.</p>

<p>This tutorial assumes that you're using Eclipse. If you're using the command line, see

<a href="{@docRoot}/guide/developing/building/building-cmdline.html">Building and Running from the

Command Line</a>. You can then return to this tutorial and ignore anything about Eclipse.</p>



<p>Before you start, you should already have the SDK installed, and if you're

using Eclipse, you should have installed the ADT plugin as well. If you have not
@@ -47,8 +45,8 @@ you need to do it now.</p> 
  <li>In the Android SDK and AVD Manager, choose <strong>Available

Packages</strong> in the left panel.</li>



<li>Click the repository site checkbox to display the components

available for installation.</li>

<li>In the right panel, expand the Android Repository list to display

the components available for installation.</li>



  <li>Select at least one platform to install, and click <strong>Install

Selected</strong>. If you aren't sure which platform to install, use the latest
@@ -60,9 +58,8 @@ version.</li> 
<div class="sidebox-wrapper">

  <div class="sidebox">

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

       available to you, see <a href="{@docRoot}guide/developing/devices/index.html">Managing

       Virtual Devices</a>.</p>

  </div>

</div>
@@ -75,28 +72,27 @@ device settings used by the emulator.</p> 


<p>To create an AVD:</p>

<ol>

  <li>In Eclipse, choose <strong>Window &gt; Android SDK and AVD Manager</strong>. 

  <li>In Eclipse, select <strong>Window &gt; Android SDK and AVD Manager</strong>.</li>

  <li>Select <strong>Virtual Devices</strong> in the left panel.</li>



  <li>Click <strong>New</strong>. </li>

 



  <li>Click <strong>New...</strong>.

    <p>The <strong>Create New AVD</strong> dialog appears.</p>



  </li>

  <li>Type the name of the AVD, such as "my_avd".</li>

  <li>Choose a target. The target is the platform (that is, the version of the Android

    SDK, such as 2.1) you want to run on the emulator. </li>

  

  <p>You can ignore the rest of the fields for now. </p>

  <li>Choose a target.

    <p>The target is the platform (that is, the version of the Android SDK, such as 2.3.3) you want

    to run on the emulator. For this tutorial, choose the latest platform that you have installed

    and ignore the rest of the fields.</p>

  </li>

  <li>Click <strong>Create AVD</strong>.</li>

</ol>

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

<p>After you've created an AVD you can move to the next step and start a new Android project in

Eclipse.</p>



<ol>

    <li>From Eclipse, select <strong>File &gt; New &gt; Project</strong>. 

    <li>In Eclipse, select <strong>File &gt; New &gt; 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
@@ -111,6 +107,8 @@ Android project in Eclipse.</p> 
    <li>Fill in the project details with the following values:

        <ul>

          <li><em>Project name:</em> HelloAndroid</li>

          <li><em>Build Target:</em> Select a platform version that is equal to or lower than the

          target you chose for your AVD.</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>
@@ -123,16 +121,27 @@ Android project in Eclipse.</p> 


        <dl>

            <dt><em>Project Name</em></dt>

                <dd>This is the Eclipse Project name &mdash; the name of the directory

                that will contain the project files.</dd>

                <dd>This is the Eclipse project name &mdash; the name of the directory

                that contains the project files.</dd>

            <dt><em>Build Target</em></dt>

                <dd>This is the version of the Android SDK that you're using to build your

                application. For example, if you choose Android 2.1, your application will be

                compiled against the Android 2.1 platform library. The target you choose here

                does not have to match the target you chose for your AVD; however, the target must

                be equal to or lower than the target you chose for your AVD. Android

                applications are forward-compatible, which means an application will run on the

                platform against which it is built as well as all platforms that are released in the

                future. For example, an application that is built against the 2.1 platform library

                will run normally on an AVD or device that is running the 2.3.3. The reverse is not

                true.</dd>

            <dt><em>Application Name</em></dt>

                <dd>This is the human-readable title for your application &mdash; the name that

                will appear on the Android device.</dd>

                appears on the Android device.</dd>

            <dt><em>Package Name</em></dt>

                <dd>This is the package namespace (following the same rules as for

                  packages in the Java programming language) that you want all your source code to

                  reside under. This also sets the package name under which the stub

                  Activity will be generated.

                  Activity is generated.

                  <p>Your package name must be unique across

                  all packages installed on the Android system; for this reason, it's

                  important to use a standard domain-style package for your
@@ -141,34 +150,28 @@ Android project in Eclipse.</p> 
                  when you develop your own applications, you should use a namespace that's

                  appropriate to your organization or entity.</p></dd>

            <dt><em>Create Activity</em></dt>

                <dd>This is the name for the class stub that will be generated by the plugin.

                This will be a subclass of Android's {@link android.app.Activity} class.  An 

                <dd>This is the name for the class stub that is generated by the plugin.

                This is a subclass of Android's {@link android.app.Activity} class.  An

                Activity is simply a class that can run and do work. It can create a UI if it

                chooses, but it doesn't need to. 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 minimum API Level required by your application. For

                more information, see <a href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a>.

                <dd>This value specifies the minimum API Level on which your application will run.

                The <em>Min SDK Version</em> should be the same as the <em>Build Target</em> you

                chose. For example, if the <em>Build Target</em> is Android 2.1, then the <em>Min

                SDK Version</em> should be 7 or lower (it can never be higher than 7). For more

                information, see

                <a href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a>.

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

        the location on disk where the project's files are generated and stored.</p>

    </li>

</ol>



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

<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>
@@ -190,9 +193,9 @@ public class HelloAndroid extends Activity { 
single application entity that is used to perform actions. An application may have many separate

activities, but the user interacts with them one at a time. The

{@link android.app.Activity#onCreate(Bundle) onCreate()} method

will be called by the Android system when your Activity starts &mdash;

is called by the Android system when your Activity starts &mdash;

it is where you should perform all initialization and UI setup. An activity is not required to

have a user interface, but usually will.</p>

have a user interface, but usually does.</p>



<p>Now let's modify some code! </p>
@@ -222,7 +225,8 @@ public class HelloAndroid extends Activity { 


<p class="note"><strong>Tip:</strong> An easy way to add import packages to your project is

to press <strong>Ctrl-Shift-O</strong> (<strong>Cmd-Shift-O</strong>, on Mac). This is an Eclipse

shortcut that identifies missing packages based on your code and adds them for you.</p>

shortcut that identifies missing packages based on your code and adds them for you. You may have

to expand the <code>import</code> statements in your code for this to work.</p>



<p>An Android user interface is composed of hierarchies of objects called

Views. A {@link android.view.View} is a drawable object used as an element in your UI layout,
@@ -469,8 +473,10 @@ you need to do is click the green arrow icon to run, or select 
string, the application looks the same. After all, the point was to show that the two different

layout approaches produce identical results.</p>



<p class="note"><strong>Tip:</strong> Use the shortcut <strong>Ctrl-F11</strong> 

(<strong>Cmd-Shift-F11</strong>, on Mac) to run your currently visible application.</p>

<p class="note"><strong>Note:</strong> You may have to unlock the screen on the emulator to see

your application &mdash; just as you would unlock the screen on a device. If you have problems

running the emulator, see <a href="{@docRoot}guide/developing/devices/emulator.html">Using the

Android Emulator</a>.</p>



<p>Continue reading for an introduction

to debugging and a little more information on using other IDEs. When you're ready to learn more,
@@ -514,12 +520,13 @@ particularly powerful with the code-completion features of IDEs like Eclipse 
because it lets you quickly and interactively locate the specific reference

you're looking for.</p>



<p>It's possible yours looks slighly different than this (perhaps the hexadecimal values are different). 

<p>It's possible yours looks slightly different than this (perhaps the hexadecimal values are

different).

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

the <code>res/drawable/</code> directory) 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>