From 82e1d979ff7d6571f124b00d4354d40aa8757664 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Wed, 21 Nov 2012 14:21:12 -0800 Subject: update building first app class with some changes to eclipse workflow and account for small differences when using an IDE other than eclipse Change-Id: I1ea8a00cd3d03623a43d6b5f75234095130c0aa3 --- docs/html/images/screens_support/avds-config.png | Bin 66660 -> 66715 bytes .../training/firstapp/adt-firstapp-setup.png | Bin 43290 -> 81191 bytes .../images/training/firstapp/adt-new-activity.png | Bin 38397 -> 55693 bytes docs/html/sdk/installing/adding-packages.jd | 39 +++-- docs/html/training/basics/firstapp/building-ui.jd | 10 +- .../training/basics/firstapp/creating-project.jd | 53 ++++--- docs/html/training/basics/firstapp/running-app.jd | 27 +++- .../training/basics/firstapp/starting-activity.jd | 159 +++++++++++++++------ 8 files changed, 196 insertions(+), 92 deletions(-) diff --git a/docs/html/images/screens_support/avds-config.png b/docs/html/images/screens_support/avds-config.png index c7d534cdd463..97bd5f6d0b4f 100644 Binary files a/docs/html/images/screens_support/avds-config.png and b/docs/html/images/screens_support/avds-config.png differ diff --git a/docs/html/images/training/firstapp/adt-firstapp-setup.png b/docs/html/images/training/firstapp/adt-firstapp-setup.png index daf02b25be00..bf9528596927 100644 Binary files a/docs/html/images/training/firstapp/adt-firstapp-setup.png and b/docs/html/images/training/firstapp/adt-firstapp-setup.png differ diff --git a/docs/html/images/training/firstapp/adt-new-activity.png b/docs/html/images/training/firstapp/adt-new-activity.png index 2d579d30521f..c396793655c7 100644 Binary files a/docs/html/images/training/firstapp/adt-new-activity.png and b/docs/html/images/training/firstapp/adt-new-activity.png differ diff --git a/docs/html/sdk/installing/adding-packages.jd b/docs/html/sdk/installing/adding-packages.jd index 2853db1884fa..bba936e84d4d 100644 --- a/docs/html/sdk/installing/adding-packages.jd +++ b/docs/html/sdk/installing/adding-packages.jd @@ -21,18 +21,24 @@ Android SDK, then execute android sdk. -
  • When the Android SDK Manager opens, it automatically selects a set of recommended packages, -as shown in figure 1. -Simply click Install to install the recommended packages. The Android SDK Manager -installs the selected packages into -your Android SDK environment.
    • +
  • The SDK Manager shows all the SDK packages available for you to add to your Android SDK. +As a minimum configuration for your SDK, we recommend you install the following: + + +

    Once you've chosen your packages, click Install. The Android SDK Manager +installs the selected packages into your Android SDK environment.

    • -

    If you install the recommended packages, you're now ready to start developing apps! -To start developing, read With these packages installed, you're ready to start developing. +To get started, read Building Your First App.

    - +

    Figure 1. The Android SDK Manager shows the SDK packages that are available, already installed, or for which an update is available.

    @@ -40,15 +46,18 @@ SDK packages that are available, already installed, or for which an update is av

    Additional information

    -

    For more information about using the SDK Manager and some of the available packages, -see the SDK Manager document.

    - -

    Everything you need to develop Android apps is on this web site, including +

  • For more information about using the SDK Manager and some of the available packages, +see the SDK Manager document.
    • +
  • This web site provides all information you need to develop Android apps, including design guidelines, developer training, API reference, and information -about how you can distribute your app. -For additional resources about developing and distributing your app, see the -Developer Support Resources.

    +about how you can distribute your app. We recommend +you begin by reading Building Your First App.
    • +
  • For additional resources about developing and distributing your app, see the +Developer Support Resources.
    • + diff --git a/docs/html/training/basics/firstapp/building-ui.jd b/docs/html/training/basics/firstapp/building-ui.jd index bc6c47c19161..0f188618f440 100644 --- a/docs/html/training/basics/firstapp/building-ui.jd +++ b/docs/html/training/basics/firstapp/building-ui.jd @@ -62,7 +62,7 @@ Devices.

    - +

    Figure 1. Illustration of how {@link android.view.ViewGroup} objects form branches in the layout and contain other {@link android.view.View} objects.

    @@ -83,7 +83,7 @@ the Graphical Layout editor. This is an editor that helps you build layouts usin lesson, you’re going to work directly with the XML, so click the activity_main.xml tab at the bottom of the screen to open the XML editor.

    -

    The BlankActivity template you used to start this project creates the +

    The BlankActivity template you chose when you created this project includes the activity_main.xml file with a {@link android.widget.RelativeLayout} root view and a {@link android.widget.TextView} child view.

    @@ -225,9 +225,9 @@ localize your app to different languages by providing alternative definitions fo string resource.

    By default, your Android project includes a string resource file at -res/values/strings.xml. Open this file and delete the {@code <string>} element -named "hello_world". Then add a new one named -"edit_message" and set the value to "Enter a message."

    +res/values/strings.xml. Add a new string named +"edit_message" and set the value to "Enter a message." (You can delete +the "hello_world" string.)

    While you’re in this file, also add a "Send" string for the button you’ll soon add, called "button_send".

    diff --git a/docs/html/training/basics/firstapp/creating-project.jd b/docs/html/training/basics/firstapp/creating-project.jd index 2ea8b2f84146..9516e378afd4 100644 --- a/docs/html/training/basics/firstapp/creating-project.jd +++ b/docs/html/training/basics/firstapp/creating-project.jd @@ -42,7 +42,7 @@ SDK tools from a command line.

    Note: You should already have the Android SDK installed, and if you're using Eclipse, you should also have the ADT -plugin installed (version 20.0.0 or higher). If you don't have these, follow the guide to installed (version 21.0.0 or higher). If you don't have these, follow the guide to Installing the Android SDK before you start this lesson.

    @@ -50,13 +50,10 @@ lesson.

    Create a Project with Eclipse

      -
    1. In Eclipse, click New Android - App Project - in the toolbar. (If you don’t see this button, -then you have not installed the ADT plugin—see Installing the Eclipse Plugin.) -
      2. +
    2. Click New in the toolbar.
      3. +
    3. In the window that appears, open the Android folder, + select Android Application Project, and click Next.
      4. @@ -65,16 +62,35 @@ href="{@docRoot}sdk/installing/installing-adt.html">Installing the Eclipse Plugi
    4. Fill in the form that appears:
        -
      • Application Name is the app name that appears to users. +
      • Application Name is the app name that appears to users. For this project, use "My First App."

        • -
      • Project Name is the name of your project directory and the name visible in Eclipse.
        • -
      • Package Name is the package namespace for your app (following the same +
      • Project Name is the name of your project directory and the name visible in Eclipse.
        • +
      • Package Name is the package namespace for your app (following the same rules as packages in the Java programming language). Your package name must be unique across all packages installed on the Android system. For this reason, it's generally best if you use a name that begins with the reverse domain name of your organization or publisher entity. For this project, you can use something like "com.example.myfirstapp." However, you cannot publish your app on Google Play using the "com.example" namespace.
        • -
      • Build SDK is the platform version against which you will compile your app. +
      • Minimum Required SDK is the lowest version of Android that your app supports, + indicated using the API level. + To support as many devices as possible, you should set this to the lowest version available + that allows your app to provide its core feature set. If any feature of your app is possible + only on newer versions of Android and it's not critical to the app's core feature set, you + can enable the feature only when running on the versions that support it (as + discussed in Supporting Different Platform Versions). + Leave this set to the default value for this project. +
        • +
      • Target SDK indicates the highest version of Android (also using the + API level) with which you + have tested with your application. +

        As new versions of Android become available, you should + test your app on the new version and update this value to match the latest API level + in order to take advantage of new platform features.

        +
        • +
      • Compile With is the platform version against which you will compile your app. By default, this is set to the latest version of Android available in your SDK. (It should be Android 4.1 or greater; if you don't have such a version available, you must install one using the SDK Manager). @@ -82,17 +98,14 @@ However, you cannot publish your app on Google Play using the "com.example" name support older versions, but setting the build target to the latest version allows you to enable new features and optimize your app for a great user experience on the latest devices.
        • -
      • Minimum Required SDK is the lowest version of Android that your app supports. - To support as many devices as possible, you should set this to the lowest version available - that allows your app to provide its core feature set. If any feature of your app is possible - only on newer versions of Android and it's not critical to the app's core feature set, you - can enable the feature only when running on the versions that support it. -

        Leave this set to the default value for this project.

        +
      • Theme specifies the Android UI style to apply for your app. You can leave + this alone.

      Click Next.

      5. - -
    5. The following screen provides tools to help you create a launcher icon for your app. +
    6. On the next screen to configure the project, leave the default selections and click + Next.
      7. +
    7. The next screen can help you create a launcher icon for your app.

      You can customize an icon in several ways and the tool generates an icon for all screen densities. Before you publish your app, you should be sure your icon meets the specifications defined in the document.

    -

    To run the app from Eclipse, open one of your project's files and click -Run -from the toolbar. Eclipse installs the app on your connected device and starts -it.

    +

    To run the app from Eclipse:

    +
      +
    1. Open one of your project's files and click +Run +from the toolbar.
      2. +
    2. In the Run as window that appears, select + Android Application and click OK.
      3. +
    +

    Eclipse installs the app on your connected device and starts it.

    Or to run your app from a command line:

    @@ -159,9 +165,16 @@ Give it a name, a platform target, an SD card size, and a skin (HVGA is default)
  • After the emulator boots up, unlock the emulator screen.
    • -

    To run the app from Eclipse, open one of your project's files and click -Run -from the toolbar. Eclipse installs the app on your AVD and starts it.

    +

    To run the app from Eclipse:

    +
      +
    1. Open one of your project's files and click +Run +from the toolbar.
      2. +
    2. In the Run as window that appears, select + Android Application and click OK.
      3. +
    +

    Eclipse installs the app on your AVD and starts it.

    Or to run your app from the command line:

    diff --git a/docs/html/training/basics/firstapp/starting-activity.jd b/docs/html/training/basics/firstapp/starting-activity.jd index 3dafcfa3f96b..8943c9df1298 100644 --- a/docs/html/training/basics/firstapp/starting-activity.jd +++ b/docs/html/training/basics/firstapp/starting-activity.jd @@ -19,11 +19,7 @@ previous.link=building-ui.html
  • Respond to the Send Button
  • Build an Intent
  • Start the Second Activity
    • -
  • Create the Second Activity -
      -
    1. Add it to the manifest
      2. -
    -
    • +
  • Create the Second Activity
  • Receive the Intent
  • Display the Message
    • @@ -49,8 +45,8 @@ starts a new activity when the user clicks the Send button.

    Respond to the Send Button

    -

    To respond to the button's on-click event, open the main.xml layout file and add the -To respond to the button's on-click event, open the activity_main.xml +layout file and add the {@code android:onClick} attribute to the {@link android.widget.Button <Button>} element:

    @@ -67,7 +63,8 @@ href="{@docRoot}reference/android/view/View.html#attr_android:onClick">{@code android:onClick} attribute’s value, "sendMessage", is the name of a method in your activity that the system calls when the user clicks the button.

    -

    Open the MainActivity class and add the corresponding method:

    +

    Open the MainActivity class (located in the project's +src/ directory) and add the corresponding method:

     /** Called when the user clicks the Send button */
@@ -76,6 +73,11 @@ public void sendMessage(View view) {
 }
    +

    This requires that you import the {@link android.view.View} class:

    +
    +import android.view.View;
+
    +

    Tip: In Eclipse, press Ctrl + Shift + O to import missing classes (Cmd + Shift + O on Mac).

    @@ -137,7 +139,8 @@ will raise an error if you’re using an IDE such as Eclipse because the class d Ignore the error for now; you’ll create the class soon.

    An intent not only allows you to start another activity, but it can carry a bundle of data to the -activity as well. So, use {@link android.app.Activity#findViewById findViewById()} to get the +activity as well. Inside the {@code sendMessage()} method, +use {@link android.app.Activity#findViewById findViewById()} to get the {@link android.widget.EditText} element and add its text value to the intent:

    @@ -147,11 +150,17 @@ String message = editText.getText().toString();
 intent.putExtra(EXTRA_MESSAGE, message);
    +

    Note: +You now need import statements for android.content.Intent +and android.widget.EditText. You'll define the EXTRA_MESSAGE +constant in a moment.

    +

    An {@link android.content.Intent} can carry a collection of various data types as key-value pairs called extras. The {@link android.content.Intent#putExtra putExtra()} method takes the key name in the first parameter and the value in the second parameter.

    -

    In order for the next activity to query the extra data, you should define your key using a +

    In order for the next activity to query the extra data, you should define the key +for your intent's extra using a public constant. So add the {@code EXTRA_MESSAGE} definition to the top of the {@code MainActivity} class:

    @@ -166,9 +175,11 @@ public class MainActivity extends Activity { as a prefix. This ensures they are unique, in case your app interacts with other apps.

    + +

    Start the Second Activity

    -

    To start an activity, you simply need to call {@link android.app.Activity#startActivity +

    To start an activity, call {@link android.app.Activity#startActivity startActivity()} and pass it your {@link android.content.Intent}. The system receives this call and starts an instance of the {@link android.app.Activity} specified by the {@link android.content.Intent}.

    @@ -202,19 +213,19 @@ work.

    To create a new activity using Eclipse:

      -
    1. Click New Click New in the toolbar.
    2. In the window that appears, open the Android folder and select Android Activity. Click Next.
    3. Select BlankActivity and click Next.
    4. Fill in the activity details:
        -
      • Project: MyFirstApp
        • -
      • Activity Name: DisplayMessageActivity
        • -
      • Layout Name: activity_display_message
        • -
      • Navigation Type: None
        • -
      • Hierarchial Parent: com.example.myfirstapp.MainActivity
        • -
      • Title: My Message
        • +
      • Project: MyFirstApp
        • +
      • Activity Name: DisplayMessageActivity
        • +
      • Layout Name: activity_display_message
        • +
      • Title: My Message
        • +
      • Hierarchial Parent: com.example.myfirstapp.MainActivity
        • +
      • Navigation Type: None

      Click Finish.

      5. @@ -224,44 +235,94 @@ work.

      {@code DisplayMessageActivity.java} in the project's src/ directory, next to the original {@code MainActivity.java} file.

      -

      Open the {@code DisplayMessageActivity.java} file. If you used Eclipse to create it, the class +

      Open the {@code DisplayMessageActivity.java} file. If you used Eclipse to create this +activity:

      + + +

      The class should look like this:

       public class DisplayMessageActivity extends Activity {
     @Override
-    public void onCreate(Bundle savedInstanceState) {
+    protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.activity_display_message);
+        // Show the Up button in the action bar.
+        getActionBar().setDisplayHomeAsUpEnabled(true);
+    }
+
+    @Override
+    public boolean onOptionsItemSelected(MenuItem item) {
+        switch (item.getItemId()) {
+        case android.R.id.home:
+            NavUtils.navigateUpFromSameTask(this);
+            return true;
+        }
+        return super.onOptionsItemSelected(item);
     }
 }
      +

      If you used an IDE other than Eclipse, update your {@code DisplayMessageActivity} +class with the above code.

      +

      All subclasses of {@link android.app.Activity} must implement the {@link android.app.Activity#onCreate onCreate()} method. The system calls this when creating a new -instance of the activity. It is where you must define the activity layout and where you should +instance of the activity. This method is where you must define the activity layout +with the {@link android.app.Activity#setContentView setContentView()} method +and is where you should perform initial setup for the activity components.

      +

      Note: If you are using an IDE other than Eclipse, your project +does not contain the {@code activity_display_message} layout that's requested by +{@link android.app.Activity#setContentView setContentView()}. That's OK because +you will update this method later and won't be using that layout.

      + + +

      Add the title string

      + +

      If you used Eclipse, you can skip to the next section, +because the template provides +the title string for the new activity.

      + +

      If you're using an IDE other than Eclipse, +add the new activity's title to the {@code strings.xml} file:

      +
      +<resources>
+    ...
+    <string name="title_activity_display_message">My Message</string>
+</resources>
+
      +

      Add it to the manifest

      -

      You must declare all activities in your manifest file, AndroidManifest.xml, using an +

      All activities must be declared in your manifest file, AndroidManifest.xml, using an {@code <activity>} element.

      -

      When you use the Eclipse tools to create the activity, it creates a default entry. It should +

      When you use the Eclipse tools to create the activity, it creates a default entry. If you're +using a different IDE, you need to add the manifest entry yourself. It should look like this:

       <application ... >
     ...
     <activity
-        android:name=".DisplayMessageActivity"
-        android:label="@string/title_activity_display_message" >
+        android:name="com.example.myfirstapp.DisplayMessageActivity"
+        android:label="@string/title_activity_display_message"
+        android:parentActivityName="com.example.myfirstapp.MainActivity" >
         <meta-data
             android:name="android.support.PARENT_ACTIVITY"
             android:value="com.example.myfirstapp.MainActivity" />
@@ -269,24 +330,32 @@ look like this:
      
 </application>
      -

      The {@code - <meta-data>} element declares the name of this activity's parent activity - within the app's logical hierarchy. The Android Support Library uses this information - to implement default navigation behaviors, such as Up navigation.

      - -

      Note: During installation, you should have downloaded -the latest Support Library. Eclipse automatically includes this library in your app project (you -can see the library's JAR file listed under Android Dependencies). If you're not using -Eclipse, you may need to manually add the library to your project—follow this guide for setting up the Support Library.

      - -

      The app is now runnable because the {@link android.content.Intent} in the -first activity now resolves to the {@code DisplayMessageActivity} class. If you run the app now, -clicking the Send button starts the second activity, but it's still using the default -"Hello world" layout.

      +

      The {@code +android:parentActivityName} attribute declares the name of this activity's parent activity +within the app's logical hierarchy. The system uses this value +to implement default navigation behaviors, such as Up navigation on +Android 4.1 (API level 16) and higher. You can provide the same navigation behaviors for +older versions of Android by using the +Support Library and adding +the {@code +<meta-data>} element as shown here.

      + +

      Note: Your Android SDK should already include +the latest Android Support Library. It's included with the ADT Bundle but if you're using +a different IDE, you should have installed it during the +Adding Platforms and Packages step. +When using the templates in Eclipse, the Support Library is automatically added to your app project +(you can see the library's JAR file listed under Android Dependencies). If you're not using +Eclipse, you need to manually add the library to your project—follow the guide for setting up the Support Library +then return here.

      + +

      If you're developing with Eclipse, you can run the app now, but not much happens. +Clicking the Send button starts the second activity but it uses +a default "Hello world" layout provided by the template. You'll soon update the +activity to instead display a custom text view, so if you're using a different IDE, +don't worry that the app won't yet compile.

      Receive the Intent

      -- cgit v1.2.3-59-g8ed1b