| page.title=Building a Simple User Interface |
| trainingnavtop=true |
| |
| page.tags=ui |
| helpoutsWidget=true |
| |
| @jd:body |
| |
| |
| <!-- This is the training bar --> |
| <div id="tb-wrapper"> |
| <div id="tb"> |
| |
| <h2>This lesson teaches you to</h2> |
| |
| <ol> |
| <li><a href="#LinearLayout">Create a Linear Layout</a></li> |
| <li><a href="#TextInput">Add a Text Field</a></li> |
| <li><a href="#Strings">Add String Resources</a></li> |
| <li><a href="#Button">Add a Button</a></li> |
| <li><a href="#Weight">Make the Input Box Fill in the Screen Width</a></li> |
| </ol> |
| |
| |
| <h2>You should also read</h2> |
| <ul> |
| <li><a href="{@docRoot}guide/topics/ui/declaring-layout.html">Layouts</a></li> |
| </ul> |
| |
| </div> |
| </div> |
| |
| |
| |
| <p>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 href="{@docRoot}guide/topics/ui/controls/button.html">buttons</a> or |
| <a href="{@docRoot}guide/topics/ui/controls/text.html">text fields</a> 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.</p> |
| |
| <p>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 using |
| a hierarchy of UI elements.</p> |
| |
| |
| <div class="sidebox-wrapper"> |
| <div class="sidebox"> |
| <h2>Alternative Layouts</h2> |
| <p>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 <a |
| href="{@docRoot}training/basics/supporting-devices/index.html">Supporting Different |
| Devices</a>.</p> |
| </div> |
| </div> |
| |
| <img src="{@docRoot}images/viewgroup.png" alt="" width="400" height="214" /> |
| <p class="img-caption"><strong>Figure 1.</strong> Illustration of how {@link |
| android.view.ViewGroup} objects form branches in the layout and contain other {@link |
| android.view.View} objects.</p> |
| |
| <p>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.</p> |
| |
| |
| |
| <h2 id="LinearLayout">Create a Linear Layout</h2> |
| |
| <p>Open the <code>fragment_main.xml</code> file from the <code>res/layout/</code> |
| directory.</p> |
| |
| <p class="note"><strong>Note:</strong> In Eclipse, when you open a layout file, you’re first shown |
| 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 <em>fragment_main.xml</em> tab at |
| the bottom of the screen to open the XML editor.</p> |
| |
| <p>The BlankActivity template you chose when you created this project includes the |
| <code>fragment_main.xml</code> file with a {@link |
| android.widget.RelativeLayout} root view and a {@link android.widget.TextView} child view.</p> |
| |
| <p>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 |
| <a href="{@docRoot}reference/android/widget/LinearLayout.html#attr_android:orientation">{@code |
| android:orientation}</a> attribute and set it to <code>"horizontal"</code>. |
| The result looks like this:</p> |
| |
| <pre> |
| <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" |
| xmlns:tools="http://schemas.android.com/tools" |
| android:layout_width="match_parent" |
| android:layout_height="match_parent" |
| android:orientation="horizontal" > |
| </LinearLayout> |
| </pre> |
| |
| <p>{@link android.widget.LinearLayout} is a view group (a subclass of {@link |
| android.view.ViewGroup}) that lays out child views in either a vertical or horizontal orientation, |
| as specified by the <a |
| href="{@docRoot}reference/android/widget/LinearLayout.html#attr_android:orientation">{@code |
| android:orientation}</a> attribute. Each child of a {@link android.widget.LinearLayout} appears on |
| the screen in the order in which it appears in the XML.</p> |
| |
| <p>The other two attributes, <a |
| href="{@docRoot}reference/android/view/View.html#attr_android:layout_width">{@code |
| android:layout_width}</a> and <a |
| href="{@docRoot}reference/android/view/View.html#attr_android:layout_height">{@code |
| android:layout_height}</a>, are required for all views in order to specify their size.</p> |
| |
| <p>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 |
| <code>"match_parent"</code>. This value declares that the view should expand its width |
| or height to <em>match</em> the width or height of the parent view.</p> |
| |
| <p>For more information about layout properties, see the <a |
| href="{@docRoot}guide/topics/ui/declaring-layout.html">Layout</a> guide.</p> |
| |
| |
| |
| <h2 id="TextInput">Add a Text Field</h2> |
| |
| <p>To create a user-editable text field, add an {@link android.widget.EditText |
| <EditText>} element inside the {@link android.widget.LinearLayout <LinearLayout>}.</p> |
| |
| <p>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 |
| inside the {@link android.widget.LinearLayout <LinearLayout>} element:</p> |
| |
| <pre> |
| <EditText android:id="@+id/edit_message" |
| android:layout_width="wrap_content" |
| android:layout_height="wrap_content" |
| android:hint="@string/edit_message" /> |
| </pre> |
| |
| |
| <div class="sidebox-wrapper"> |
| <div class="sidebox"> |
| <h3>About resource objects</h3> |
| <p>A resource object is simply a unique integer name that's associated with an app resource, |
| such as a bitmap, layout file, or string.</p> |
| <p>Every resource has a |
| corresponding resource object defined in your project's {@code gen/R.java} file. You can use the |
| object names in the {@code R} class to refer to your resources, such as when you need to specify a |
| string value for the <a |
| href="{@docRoot}reference/android/widget/TextView.html#attr_android:hint">{@code android:hint}</a> |
| attribute. You can also create arbitrary resource IDs that you associate with a view using the <a |
| href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android:id}</a> attribute, |
| which allows you to reference that view from other code.</p> |
| <p>The SDK tools generate the {@code R.java} each time you compile your app. You should never |
| modify this file by hand.</p> |
| <p>For more information, read the guide to <a |
| href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a>.</p> |
| </div> |
| </div> |
| |
| <p>About these attributes:</p> |
| |
| <dl> |
| <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android:id}</a></dt> |
| <dd>This provides a unique identifier for the view, which you can use to reference the object |
| from your app code, such as to read and manipulate the object (you'll see this in the next |
| lesson). |
| |
| <p>The at sign (<code>@</code>) 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}).</p> |
| |
| <p>The plus sign (<code>+</code>) 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.</p></dd> |
| |
| <dt><a |
| href="{@docRoot}reference/android/view/View.html#attr_android:layout_width">{@code |
| android:layout_width}</a> and <a |
| href="{@docRoot}reference/android/view/View.html#attr_android:layout_height">{@code |
| android:layout_height}</a></dt> |
| <dd>Instead of using specific sizes for the width and height, the <code>"wrap_content"</code> 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 <code>"match_parent"</code>, 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 <a |
| href="{@docRoot}guide/topics/ui/declaring-layout.html">Layouts</a> guide.</dd> |
| |
| <dt><a |
| href="{@docRoot}reference/android/widget/TextView.html#attr_android:hint">{@code |
| android:hint}</a></dt> |
| <dd>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 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. |
| <p class="note"><strong>Note:</strong> 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.</p> |
| </dd> |
| </dl> |
| |
| |
| |
| <h2 id="Strings">Add String Resources</h2> |
| |
| <p>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 resource.</p> |
| |
| <p>By default, your Android project includes a string resource file at |
| <code>res/values/strings.xml</code>. Add a new string named |
| <code>"edit_message"</code> and set the value to "Enter a message." (You can delete |
| the "hello_world" string.)</p> |
| |
| <p>While you’re in this file, also add a "Send" string for the button you’ll soon add, called |
| <code>"button_send"</code>.</p> |
| |
| <p>The result for <code>strings.xml</code> looks like this:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <resources> |
| <string name="app_name">My First App</string> |
| <string name="edit_message">Enter a message</string> |
| <string name="button_send">Send</string> |
| <string name="action_settings">Settings</string> |
| <string name="title_activity_main">MainActivity</string> |
| </resources> |
| </pre> |
| |
| <p>For more information about using string resources to localize your app for other languages, |
| see the <a |
| href="{@docRoot}training/basics/supporting-devices/index.html">Supporting Different Devices</a> |
| class.</p> |
| |
| |
| |
| |
| <h2 id="Button">Add a Button</h2> |
| |
| <p>Now add a {@link android.widget.Button <Button>} to the layout, immediately following the |
| {@link android.widget.EditText <EditText>} element:</p> |
| |
| <pre> |
| <Button |
| android:layout_width="wrap_content" |
| android:layout_height="wrap_content" |
| android:text="@string/button_send" /> |
| </pre> |
| |
| <p>The height and width are set to <code>"wrap_content"</code> so the button is only as big as |
| necessary to fit the button's text. This button doesn't need the |
| <a href="{@docRoot}reference/android/view/View.html#attr_android:id">{@code android:id}</a> |
| attribute, because it won't be referenced from the activity code.</p> |
| |
| |
| |
| <h2 id="Weight">Make the Input Box Fill in the Screen Width</h2> |
| |
| <p>The layout is currently designed so that both the {@link android.widget.EditText} and {@link |
| android.widget.Button} widgets are only as big as necessary to fit their content, as shown in |
| figure 2.</p> |
| |
| <img src="{@docRoot}images/training/firstapp/edittext_wrap.png" /> |
| <p class="img-caption"><strong>Figure 2.</strong> The {@link android.widget.EditText} and {@link |
| android.widget.Button} widgets have their widths set to |
| <code>"wrap_content"</code>.</p> |
| |
| <p>This works fine for the button, but not as well for the text field, because the user might type |
| 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 <em>weight</em> property, which |
| you can specify using the <a |
| href="{@docRoot}reference/android/widget/LinearLayout.LayoutParams.html#weight">{@code |
| android:layout_weight}</a> attribute.</p> |
| |
| <p>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 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.</p> |
| |
| <p>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 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.</p> |
| |
| <pre> |
| <EditText |
| android:layout_weight="1" |
| ... /> |
| </pre> |
| |
| <p>In order to improve the layout efficiency when you specify the weight, you should change the |
| width of the {@link android.widget.EditText} to be |
| zero (0dp). Setting the width to zero improves layout performance because using |
| <code>"wrap_content"</code> as the width requires the system to calculate a width that is |
| ultimately irrelevant because the weight value requires another width calculation to fill the |
| remaining space.</p> |
| <pre> |
| <EditText |
| android:layout_weight="1" |
| android:layout_width="0dp" |
| ... /> |
| </pre> |
| |
| <p>Figure 3 |
| shows the result when you assign all weight to the {@link android.widget.EditText} element.</p> |
| |
| <img src="{@docRoot}images/training/firstapp/edittext_gravity.png" /> |
| <p class="img-caption"><strong>Figure 3.</strong> The {@link android.widget.EditText} widget is |
| given all the layout weight, so fills the remaining space in the {@link |
| android.widget.LinearLayout}.</p> |
| |
| <p>Here’s how your complete layout file should now look:</p> |
| |
| <pre> |
| <?xml version="1.0" encoding="utf-8"?> |
| <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" |
| 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" |
| android:layout_width="0dp" |
| android:layout_height="wrap_content" |
| android:hint="@string/edit_message" /> |
| <Button |
| android:layout_width="wrap_content" |
| android:layout_height="wrap_content" |
| android:text="@string/button_send" /> |
| </LinearLayout> |
| </pre> |
| |
| <p>This layout is applied by the default {@link android.app.Activity} class |
| that the SDK tools generated when you created the project, so you can now run the app to see the |
| results:</p> |
| |
| <ul> |
| <li>In Eclipse, click Run <img src="{@docRoot}images/tools/eclipse-run.png" |
| style="vertical-align:baseline;margin:0" /> from the toolbar.</li> |
| <li>Or from a command line, change directories to the root of your Android project and |
| execute: |
| <pre> |
| ant debug |
| adb install bin/MyFirstApp-debug.apk |
| </pre></li> |
| </ul> |
| |
| <p>Continue to the next lesson to learn how you can respond to button presses, read content |
| from the text field, start another activity, and more.</p> |
| |
| |
| |