| 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>In this lesson, you create a layout in XML that includes a text field and a |
| button. In the next lesson, your app responds when the button is pressed by sending the |
| content of the text field to another activity.</p> |
| |
| <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>. |
| {@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> |
| |
| <p>Layouts are subclasses of the {@link android.view.ViewGroup}. In this exercise, you'll work with |
| a {@link android.widget.LinearLayout}.</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> |
| |
| |
| <h2 id="LinearLayout">Create a Linear Layout</h2> |
| |
| <ol> |
| <li>In Android Studio's <b>Project</b> window, open <b>app > res > |
| layout > activity_main.xml</b>. |
| <p>This XML file defines the layout of your activity. It contains the |
| default "Hello World" text view.</p> |
| </li> |
| <li>When you open a layout file, you’re first shown the design editor in the |
| <a href="/studio/write/layout-editor.html">Layout Editor</a>. For this lesson, |
| you work directly with the XML, so click the <b>Text</b> tab at the bottom |
| of the window to switch to the text editor. |
| </li> |
| <li>Delete everything and insert the following XML: |
| <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"> |
| </LinearLayout> |
| </pre> |
| |
| </li> |
| |
| </ol> |
| |
| <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>Two other 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>In the <code>activity_main.xml</code> file, within the |
| {@link android.widget.LinearLayout <LinearLayout>} element, add the following |
| {@link android.widget.EditText <EditText>} element:</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"> |
| <b><EditText android:id="@+id/edit_message" |
| android:layout_width="wrap_content" |
| android:layout_height="wrap_content" |
| android:hint="@string/edit_message" /></b> |
| </LinearLayout> |
| </pre> |
| |
| <p>Don't worry about the error that appears for |
| <code>@string/edit_message</code>; you'll fix that soon.</p> |
| |
| <p>Here is a description of the attributes in the |
| {@link android.widget.EditText <EditText>} you added:</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> |
| |
| <div class="sidebox-wrapper"> |
| <div class="sidebox"> |
| <h3>Resource Objects</h3> |
| <p>A resource object is 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 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} file 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>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 R.java} file that refers to the {@link |
| android.widget.EditText} element. With the resource ID 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>By default, your Android project includes a string resource file at |
| <b>res > values > strings.xml</b>. Here, you'll add two new strings.</p> |
| |
| <ol> |
| <li>From the <b>Project</b> window, open <b>res > values > strings.xml</b>.</li> |
| <li>Add two strings so that your file looks like this: |
| <pre><?xml version="1.0" encoding="utf-8"?> |
| <resources> |
| <string name="app_name">My First App</string> |
| <b><string name="edit_message">Enter a message</string> |
| <string name="button_send">Send</string></b> |
| </resources> |
| </pre> |
| </li> |
| </ol> |
| |
| <p>For text in the user interface, always specify each string as |
| a resource. String resources allow you to manage all UI text in a single location, |
| which makes the text easier to find and update. Externalizing the strings also allows you to |
| localize your app to different languages by providing alternative definitions for each |
| string resource.</p> |
| |
| <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>Go back to the <code>activity_main.xml</code> file and add a button after the |
| {@link android.widget.EditText <EditText>}. Your file should look like this:</p> |
| <pre><LinearLayout |
| xmlns:android="http://schemas.android.com/apk/res/android" |
| xmlns:tools="http://schemas.android.com/tools" |
| android:orientation="horizontal" |
| android:layout_width="match_parent" |
| android:layout_height="match_parent"> |
| <EditText android:id="@+id/edit_message" |
| android:layout_width="wrap_content" |
| android:layout_height="wrap_content" |
| android:hint="@string/edit_message" /> |
| <b><Button |
| android:layout_width="wrap_content" |
| android:layout_height="wrap_content" |
| android:text="@string/button_send" /></b> |
| </LinearLayout> |
| </pre> |
| |
| <p class="note"><strong>Note:</strong> 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> |
| |
| <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 figure 2 shows. |
| </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. 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 soda, 1 part syrup" means two-thirds of the drink is soda. 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.</p> |
| |
| <h2 id="Weight">Make the Input Box Fill in the Screen Width</h2> |
| |
| <p>In <code>activity_main.xml</code>, modify the |
| {@link android.widget.EditText <EditText>} so that the attributes look like |
| this:</p> |
| |
| <pre> |
| <EditText android:id="@+id/edit_message" |
| <b>android:layout_weight="1" |
| android:layout_width="0dp"</b> |
| android:layout_height="wrap_content" |
| android:hint="@string/edit_message" /> |
| </pre> |
| |
| <p>Setting the width to zero (0dp) 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> |
| |
| <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 it fills the remaining space in the {@link |
| android.widget.LinearLayout}.</p> |
| |
| <p>Here’s how your complete <code>activity_main.xml</code>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:orientation="horizontal" |
| android:layout_width="match_parent" |
| android:layout_height="match_parent"> |
| <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> |
| |
| <h2>Run Your App</h2> |
| |
| <p>To see how the app now looks on your device or emulator, |
| click <strong>Run</strong> |
| <img src="{@docRoot}images/tools/as-run.png" |
| style="vertical-align:baseline;margin:0; max-height:1em" /> in the |
| toolbar.</p> |
| |
| <p>To add app behaviors such as responding to a button and starting |
| another activity, continue to the <a href="starting-activity.html">next |
| lesson</a>.</p> |