From 39871b7e4368b9789e715dde5ef4ff9e891380cf Mon Sep 17 00:00:00 2001 From: Scott Main Date: Thu, 19 Jul 2012 21:11:49 -0700 Subject: docs: update Building Your First App class to reflect changes to New Project setup in eclipse Change-Id: I57c02676fbc2886872c2d294c5517b458e8751c5 --- docs/html/training/basics/firstapp/building-ui.jd | 171 ++++++++++++---------- 1 file changed, 90 insertions(+), 81 deletions(-) (limited to 'docs/html/training/basics/firstapp/building-ui.jd') diff --git a/docs/html/training/basics/firstapp/building-ui.jd b/docs/html/training/basics/firstapp/building-ui.jd index f0ec79e..bc6c47c 100644 --- a/docs/html/training/basics/firstapp/building-ui.jd +++ b/docs/html/training/basics/firstapp/building-ui.jd @@ -18,7 +18,7 @@ next.link=starting-activity.html

This lesson teaches you to

    -
  1. Use a Linear Layout
    2. +
  2. Create a Linear Layout
  3. Add a Text Field
  4. Add String Resources
  5. Add a Button
    6. @@ -28,10 +28,9 @@ next.link=starting-activity.html

    You should also read

    - - + @@ -39,63 +38,68 @@ next.link=starting-activity.html

    The graphical user interface for an Android app is built using a hierarchy of {@link android.view.View} and {@link android.view.ViewGroup} objects. {@link android.view.View} objects are -usually UI widgets such as a button or text field and {@link android.view.ViewGroup} objects are +usually UI widgets such as buttons or +text fields and {@link +android.view.ViewGroup} objects are invisible view containers that define how the child views are laid out, such as in a grid or a vertical list.

    Android provides an XML vocabulary that corresponds to the subclasses of {@link -android.view.View} and {@link android.view.ViewGroup} so you can define your UI in XML with a -hierarchy of view elements.

    +android.view.View} and {@link android.view.ViewGroup} so you can define your UI in XML using +a hierarchy of UI elements.

    Alternative Layouts

    -

    Separating the UI layout into XML files is important for several reasons, -but it's especially important on Android because it allows you to define alternative layouts for +

    Declaring your UI layout in XML rather than runtime code is useful for several reasons, +but it's especially important so you can create different layouts for different screen sizes. For example, you can create two versions of a layout and tell the system to use one on "small" screens and the other on "large" screens. For more information, see the class about Supporting Different -Hardware.

    +Devices.

    - +

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

    -

    In this lesson, you'll create a layout in XML that includes a text input field and a +

    In this lesson, you'll create a layout in XML that includes a text field and a button. In the following lesson, you'll respond when the button is pressed by sending the content of the text field to another activity.

    -

    Use a Linear Layout

    +

    Create a Linear Layout

    -

    Open the main.xml file from the res/layout/ -directory (every new Android project includes this file by default).

    +

    Open the activity_main.xml file from the res/layout/ +directory.

    Note: In Eclipse, when you open a layout file, you’re first shown -the ADT Layout Editor. This is an editor that helps you build layouts using WYSIWYG tools. For this -lesson, you’re going to work directly with the XML, so click the main.xml tab at +the Graphical Layout editor. This is an editor that helps you build layouts using WYSIWYG tools. For this +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.

    -

    By default, the main.xml file includes a layout with a {@link -android.widget.LinearLayout} root view group and a {@link android.widget.TextView} child view. -You’re going to re-use the {@link android.widget.LinearLayout} in this lesson, but change its -contents and layout orientation.

    +

    The BlankActivity template you used to start this project creates the +activity_main.xml file with a {@link +android.widget.RelativeLayout} root view and a {@link android.widget.TextView} child view.

    -

    First, delete the {@link android.widget.TextView} element and change the value +

    First, delete the {@link android.widget.TextView <TextView>} element and change the {@link + android.widget.RelativeLayout <RelativeLayout>} element to {@link + android.widget.LinearLayout <LinearLayout>}. Then add the {@code -android:orientation} to be "horizontal". The result looks like this:

    +android:orientation} attribute and set it to "horizontal". +The result looks like this:

     <?xml version="1.0" encoding="utf-8"?>
 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
-    android:layout_width="fill_parent"
-    android:layout_height="fill_parent"
+    xmlns:tools="http://schemas.android.com/tools"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
     android:orientation="horizontal" >
 </LinearLayout>
    @@ -116,26 +120,18 @@ android:layout_height}, are required for all views in order to specify their

    Because the {@link android.widget.LinearLayout} is the root view in the layout, it should fill the entire screen area that's available to the app by setting the width and height to -"fill_parent".

    - -

    Note: Beginning with Android 2.2 (API level 8), -"fill_parent" has been renamed "match_parent" to better reflect the -behavior. The reason is that if you set a view to "fill_parent" it does not expand to -fill the remaining space after sibling views are considered, but instead expands to -match the size of the parent view no matter what—it will overlap any sibling -views.

    +"match_parent". This value declares that the view should expand its width +or height to match the width or height of the parent view.

    For more information about layout properties, see the XML Layout guide.

    +href="{@docRoot}guide/topics/ui/declaring-layout.html">Layout guide.

    Add a Text Field

    To create a user-editable text field, add an {@link android.widget.EditText -<EditText>} element inside the {@link android.widget.LinearLayout <LinearLayout>}. The {@link -android.widget.EditText} class is a subclass of {@link android.view.View} that displays an editable -text field.

    +<EditText>} element inside the {@link android.widget.LinearLayout <LinearLayout>}.

    Like every {@link android.view.View} object, you must define certain XML attributes to specify the {@link android.widget.EditText} object's properties. Here’s how you should declare it @@ -164,6 +160,8 @@ href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android which allows you to reference that view from other code.

    The SDK tools generate the {@code R.java} each time you compile your app. You should never modify this file by hand.

    +

    For more information, read the guide to Providing Resources.

    @@ -175,17 +173,18 @@ modify this file by hand.

    from your app code, such as to read and manipulate the object (you'll see this in the next lesson). -

    The at-symbol (@) is required when you want to refer to a resource object from -XML, followed by the resource type ({@code id} in this case), then the resource name ({@code -edit_message}). (Other resources can use the same name as long as they are not the same -resource type—for example, the string resource uses the same name.)

    - -

    The plus-symbol (+) is needed only when you're defining a resource ID for the -first time. It tells the SDK tools that the resource ID needs to be created. Thus, when the app is -compiled, the SDK tools use the ID value, edit_message, to create a new identifier in -your project's {@code gen/R.java} file that is now associated with the {@link -android.widget.EditText} element. Once the resource ID is created, other references to the ID do not -need the plus symbol. This is the only attribute that may need the plus-symbol. See the sidebox for +

    The at sign (@) is required when you're referring to any resource object from +XML. It is followed by the resource type ({@code id} in this case), a slash, then the resource name +({@code edit_message}).

    + +

    The plus sign (+) before the resource type is needed only when you're defining a +resource ID for the first time. When you compile the app, +the SDK tools use the ID name to create a new resource ID in +your project's {@code gen/R.java} file that refers to the {@link +android.widget.EditText} element. Once the resource ID is declared once this way, +other references to the ID do not +need the plus sign. Using the plus sign is necessary only when specifying a new resource ID and not +needed for concrete resources such as strings or layouts. See the sidebox for more information about resource objects.

    {@c android:layout_height}
    Instead of using specific sizes for the width and height, the "wrap_content" value specifies that the view should be only as big as needed to fit the contents of the view. If you -were to instead use "fill_parent", then the {@link android.widget.EditText} -element would fill the screen, because it'd match the size of the parent {@link +were to instead use "match_parent", then the {@link android.widget.EditText} +element would fill the screen, because it would match the size of the parent {@link android.widget.LinearLayout}. For more information, see the XML Layouts guide.
    +href="{@docRoot}guide/topics/ui/declaring-layout.html">Layouts guide.
    {@code android:hint}
    This is a default string to display when the text field is empty. Instead of using a hard-coded -string as the value, the {@code "@string/edit_message"} value refers to a string resource defined -in a separate file. Because this value refers to an existing resource, it does not need the -plus-symbol. However, because you haven't defined the string resource yet, you’ll see a compiler -error when you add the {@code "@string/edit_message"} value. You'll fix this in the next section by -defining the string resource.
    +string as the value, the {@code "@string/edit_message"} value refers to a string resource defined in +a separate file. Because this refers to a concrete resource (not just an identifier), it does not +need the plus sign. However, because you haven't defined the string resource yet, you’ll see a +compiler error at first. You'll fix this in the next section by defining the string. +

    Note: This string resource has the same name as the element ID: +{@code edit_message}. However, references +to resources are always scoped by the resource type (such as {@code id} or {@code string}), so using +the same name does not cause collisions.

    +

    Add String Resources

    -

    When you need to add text in the user interface, you should always specify each string of text in -a resource file. String resources allow you to maintain a single location for all string -values, which makes it easier to find and update text. Externalizing the strings also allows you to +

    When you need to add text in the user interface, you should always specify each string as +a resource. String resources allow you to manage all UI text in a single location, +which makes it easier to find and update text. Externalizing the strings also allows you to localize your app to different languages by providing alternative definitions for each -string.

    +string resource.

    By default, your Android project includes a string resource file at -res/values/strings.xml. Open this file, delete the existing "hello" -string, and add one for the -"edit_message" string used by the {@link android.widget.EditText <EditText>} -element.

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

    -

    While you’re in this file, also add a string for the button you’ll soon add, called +

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

    The result for strings.xml looks like this:

    @@ -238,12 +240,14 @@ element.

    <string name="app_name">My First App</string> <string name="edit_message">Enter a message</string> <string name="button_send">Send</string> + <string name="menu_settings">Settings</string> + <string name="title_activity_main">MainActivity</string> </resources> -

    For more information about using string resources to localize your app for several languages, +

    For more information about using string resources to localize your app for other languages, see the Supporting Various Devices +href="{@docRoot}training/basics/supporting-devices/index.html">Supporting Different Devices class.

    @@ -280,23 +284,26 @@ android.widget.Button} widgets have their widths set to "wrap_content".

    This works fine for the button, but not as well for the text field, because the user might type -something longer and there's extra space left on the screen. So, it'd be nice to fill that width -using the text field. -{@link android.widget.LinearLayout} enables such a design with the weight property, which +something longer. So, it would be nice to fill the unused screen width +with the text field. You can do this inside a +{@link android.widget.LinearLayout} with the weight property, which you can specify using the {@code android:layout_weight} attribute.

    -

    The weight value allows you to specify the amount of remaining space each view should consume, -relative to the amount consumed by sibling views, just like the ingredients in a drink recipe: "2 +

    The weight value is a number that specifies the amount of remaining space each view should +consume, +relative to the amount consumed by sibling views. This works kind of like the +amount of ingredients in a drink recipe: "2 parts vodka, 1 part coffee liqueur" means two-thirds of the drink is vodka. For example, if you give -one view a weight of 2 and another one a weight of 1, the sum is 3, so the first view gets 2/3 of -the remaining space and the second view gets the rest. If you give a third view a weight of 1, -then the first view now gets 1/2 the remaining space, while the remaining two each get 1/4.

    +one view a weight of 2 and another one a weight of 1, the sum is 3, so the first view fills 2/3 of +the remaining space and the second view fills the rest. If you add a third view and give it a weight +of 1, then the first view (with weight of 2) now gets 1/2 the remaining space, while the remaining +two each get 1/4.

    The default weight for all views is 0, so if you specify any weight value -greater than 0 to only one view, then that view fills whatever space remains after each view is -given the space it requires. So, to fill the remaining space with the {@link +greater than 0 to only one view, then that view fills whatever space remains after all views are +given the space they require. So, to fill the remaining space in your layout with the {@link android.widget.EditText} element, give it a weight of 1 and leave the button with no weight.

    @@ -331,8 +338,9 @@ android.widget.LinearLayout}.
    
 
     <?xml version="1.0" encoding="utf-8"?>
 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
-    android:layout_width="fill_parent"
-    android:layout_height="fill_parent"
+    xmlns:tools="http://schemas.android.com/tools"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
     android:orientation="horizontal">
     <EditText android:id="@+id/edit_message"
         android:layout_weight="1"
@@ -351,7 +359,8 @@ that the SDK tools generated when you created the project, so you can now run th
 results:
    
 
 
      
-  
    • In Eclipse, click Run from the toolbar.
      • 
+  
    • In Eclipse, click Run  from the toolbar.
      • 
   
    • Or from a command line, change directories to the root of your Android project and
 execute:
 
      -- 
cgit v1.1