| page.title=Building a Simple User Interface |
| parent.title=Building Your First App |
| parent.link=index.html |
| |
| trainingnavtop=true |
| previous.title=Running Your App |
| previous.link=running-app.html |
| next.title=Starting Another Activity |
| next.link=starting-activity.html |
| |
| @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">Use a Linear Layout</a></li> |
| <li><a href="#TextInput">Add a Text Input Box</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">XML 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 button or text field 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 with a |
| hierarchy of view elements.</p> |
| |
| |
| <div class="sidebox-wrapper"> |
| <div class="sidebox"> |
| <h2>Alternative Layouts</h2> |
| <p>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 |
| 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 |
| Hardware</a>.</p> |
| </div> |
| </div> |
| |
| <img src="{@docRoot}images/viewgroup.png" alt="" /> |
| <p class="img-caption"><strong>Figure 1.</strong> Illustration of how {@link |
| android.view.ViewGroup} objects form branches in the layout and contain {@link |
| android.view.View} objects.</p> |
| |
| <p>In this lesson, you'll create a layout in XML that includes a text input 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">Use a Linear Layout</h2> |
| |
| <p>Open the <code>main.xml</code> file from the <code>res/layout/</code> |
| directory (every new Android project includes this file by default).</p> |
| |
| <p class="note"><strong>Note:</strong> 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 <em>main.xml</em> tab at |
| the bottom of the screen to open the XML editor.</p> |
| |
| <p>By default, the <code>main.xml</code> 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.</p> |
| |
| <p>First, delete the {@link android.widget.TextView} element and change the value |
| <a href="{@docRoot}reference/android/widget/LinearLayout.html#attr_android:orientation">{@code |
| android:orientation}</a> to be <code>"horizontal"</code>. The result looks like this:</p> |
| |
| <pre> |
| <?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" |
| 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>"fill_parent"</code>.</p> |
| |
| <p class="note"><strong>Note:</strong> Beginning with Android 2.2 (API level 8), |
| <code>"fill_parent"</code> has been renamed <code>"match_parent"</code> to better reflect the |
| behavior. The reason is that if you set a view to <code>"fill_parent"</code> it does not expand to |
| fill the remaining space after sibling views are considered, but instead expands to |
| <em>match</em> the size of the parent view no matter what—it will overlap any sibling |
| views.</p> |
| |
| <p>For more information about layout properties, see the <a |
| href="{@docRoot}guide/topics/ui/declaring-layout.html">XML Layout</a> guide.</p> |
| |
| |
| |
| <h2 id="TextInput">Add a Text Input Box</h2> |
| |
| <p>To create a user-editable text box, 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 box.</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> |
| </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-symbol (<code>@</code>) 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.)</p> |
| |
| <p>The plus-symbol (<code>+</code>) 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, <code>edit_message</code>, to create a new identifier in |
| your project's {@code gen/R.java} file that is now assiciated with the {@link |
| android.widget.EditText} element. Once the resource ID is created, other references to the ID do not |
| need the plus symbol. 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>"fill_parent"</code>, then the {@link android.widget.EditText} |
| element would fill the screen, because it'd match the size of the parent {@link |
| android.widget.LinearLayout}. For more information, see the <a |
| href="{@docRoot}guide/topics/ui/declaring-layout.html">XML 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 box is empty. Instead of using a hard-coded |
| string as the value, the value given in this example refers to a string resource. When you add the |
| {@code |
| "@string/edit_message"} value, you’ll see a compiler error because there’s no matching string |
| resource by that name. You'll fix this in the next section by defining the string |
| resource.</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 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 |
| localize your app to different languages by providing alternative definitions for each |
| string.</p> |
| |
| <p>By default, your Android project includes a string resource file at |
| <code>res/values/strings.xml</code>. Open this file, delete the existing <code>"hello"</code> |
| string, and add one for the |
| <code>"edit_message"</code> string used by the {@link android.widget.EditText <EditText>} |
| element.</p> |
| |
| <p>While you’re in this file, also add a 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> |
| </resources> |
| </pre> |
| |
| <p>For more information about using string resources to localize your app for several languages, |
| see the <a |
| href="{@docRoot}training/basics/supporting-devices/index.html">Supporting Various 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.</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 box, 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 box. |
| {@link android.widget.LinearLayout} enables such a design 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 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 |
| parts vodka, 1 part coffee liquer" 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.</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 each view is |
| given the space it requires. So, to fill the remaining space 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" |
| android:layout_width="fill_parent" |
| android:layout_height="fill_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:id="@+id/button_send" |
| 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 <strong>Run</strong> 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> |
| |
| |
| |