AnAndroid basic components use

Android basic components use1.1Using XML-Based LayoutsWhile it is technically possible to create and attach widgets to our activity purely through Java code, the way we did in Chapter 4, the more common approach is to use an XML-based layout file. Dynamic instantiation of widgets is reserved for more complicated scenarios, where the widgets are not known at compile-time (e g., populating a column of radio buttons based on data retrieved off the Internet). With that in mind, it’s time to break out the XML and learn how to lay out Android activities that way. What Is an XML-Based Layout? As the name suggests, an XML-based layout is a specification of widgets’ relationships to each other—and to their containers (more on this in Chapter 7)—encoded in XML format. Specifically, Android considers XML-based layouts to be resources, and as such layout files are stored in the res/layout directory inside your Android project. Each XML file contains a tree of elements specifying a layout of widgets and their containers that make up one view hierarchy. The attributes of the XML elements are properties, describing how a widget should look or how a container should behave. For example, if a Button element has an attribute value of android:textStyle = "bold", that means that the text appearing on the face of the button should be rendered in a boldface font style. Android’s SDK ships with a tool (aapt) which uses the layouts. This tool should be automatically invoked by your Android tool chain (e.g., Eclipse, Ant’s build.xml). Of particular importance to you as a developer is that aapt generates the R.java source file within your project, allowing you to access layouts and widgets within those layouts directly from your Java code. Why Use XML-Based Layouts? Most everything you do using XML layout files can be achieved through Java code. For example, you could use setTypeface() to have a button render its text in bold, instead of using a property in an XML layout. Since XML layouts are yet another file for you to keep track of, we need good reasons for using such files. Perhaps the biggest reason is to assist in the creation of tools for view definition, such as a GUI builder in an IDE like Eclipse or a dedicated Android GUI designer like DroidDraw1. Such GUI builders could, in principle, generate Java code instead of XML. The challenge is re-reading the UI definition to support edits—that is far simpler if the data is in a structured format like XML than in a programming language. Moreover, keeping generated XML definitions separated from hand-written Java code makes it less likely that somebody’s custom-crafted source will get clobbered by accident when the generated bits get re-generated. XML forms a nice middle ground between something that is easy for tool-writers to use and easy for programmers to work with by hand as needed. Also, XML as a GUI definition format is becoming more commonplace. Microsoft’s XAML2, Adobe’s Flex3, and Mozilla’s XUL4 all take a similar approach to that of Android: put layout details in an XML file and put programming smarts in source files (e.g., JavaScript for XUL). Many less-well-known GUI frameworks, such as ZK5, also use XML for view definition. While “following the herd” is not necessarily the best policy, it does have the advantage of helping to ease the transition into Android from any other XML-centered view description language. OK, So What Does It Look Like? Here is the Button from the previous chapter’s sample application, converted into an XML layout file, found in the Layouts/NowRedux sample project. This code sample along with all others in this chapter can be found in the Source Code area of http://apress.com. The class name of the widget—Button—forms the name of the XML element. Since Button is an Android-supplied widget, we can just use the bare class name. If you create your own widgets as subclasses of android.view.View, you would need to provide a full package declaration as well.The root element needs to declare the Android XML namespace: xmlns:android="http://schemas.android.com/apk/res/android" All other elements will be children of the root and will inherit that namespace declaration. Because we want to reference this button from our Java code, we need to give it an identifier via the android:id attribute. We will cover this concept in greater detail later in this chapter. The remaining attributes are properties of this Button instance: • android:text indicates the initial text to be displayed on the button face (in this case, an empty string) • android:layout_width and android:layout_height tell Android to have the button’s width and height fill the “parent”, in this case the entire screen—these attributes will be covered in greater detail in Chapter 7. Since this single widget is the only content in our activity, we only need this single element. Complex UIs will require a whole tree of elements, representing the widgets and containers that control their positioning. All the remaining chapters of this book will use the XML layout form whenever practical. What’s with the @ Signs? Many widgets and containers only need to appear in the XML layout file and do not need to be referenced in your Java code. For example, a static label (TextView) frequently only needs to be in the layout file to indicate where it should appear. These sorts of elements in the XML file do not need to have the android:id attribute to give them a name. Anything you do want to use in your Java source, though, needs an android:id. The convention is to use @+id/... as the id value, where the ... represents your locallyunique name for the widget in question. In the XML layout example in the preceding section, @+id/button is the identifier for the Button widget. Android provides a few special android:id values, of the form @android:id/.... We will see some of these in various chapters of this book, such as Chapters 8 and 10. We Attach These to the Java How?Given that you have painstakingly set up the widgets and containers in an XML layout file named main.xml stored in res/layout, all you need is one statement in your activity’s onCreate() callback to use that layout: setContentView(R.layout.main); This is the same setContentView() we used earlier, passing it an instance of a View subclass (in that case, a Button). The Android-built view, constructed from our layout, is accessed from that code-generated R class. All of the layouts are accessible under R.layout, keyed by the base name of the layout file—main.xml results in R.layout.main. To access our identified widgets, use findViewById(), passing in the numeric identifier of the widget in question. That numeric identifier was generated by Android in the R class as R.id.something (where something is the specific widget you are seeking). Those widgets are simply subclasses of View, just like the Button instance we created in Chapter 4. The Rest of the Story In the original Now demo, the button’s face would show the current time, which would reflect when the button was last pushed (or when the activity was first shown, if the button had not yet been pushed). Most of that logic still works, even in this revised demo (NowRedux). However, rather than instantiating the Button in our activity’s onCreate() callback, we can reference the one from the XML layout: package com.commonsware.android.layouts; import android.app.Activity; import android.os.Bundle; import android.view.View; import android.widget.Button; import java.util.Date; public class NowRedux extends Activity implements View.OnClickListener { Button btn; @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.main); btn=(Button)findViewById(R.id.button);btn.setOnClickListener(this);updateTime(); } public void onClick(View view) { updateTime(); } private void updateTime() { btn.setText(new Date().toString()); } } The first difference is that rather than setting the content view to be a view we created in Java code, we set it to reference the XML layout (setContentView(R.layout.main)). The R.java source file will be updated when we rebuild this project to include a reference to our layout file (stored as main.xml in our project’s res/layout directory). The other difference is that we need to get our hands on our Button instance, for which we use the findViewById() call. Since we identified our button as @+id/button, we can reference the button’s identifier as R.id.button. Now, with the Button instance in hand, we can set the callback and set the label as needed. As you can see in Figure 5-1, the results look the same as with the original Now demo. Figure 5-1. The NowRedux sample activity1.2Employing Basic Widgets Every GUI toolkit has some basic widgets: fields, labels, buttons, etc. Android’s toolkit is no different in scope, and the basic widgets will provide a good introduction as to how widgets work in Android activities. Assigning Labels The simplest widget is the label, referred to in Android as a TextView. Like in most GUI toolkits, labels are bits of text not editable directly by users. Typically, they are used to identify adjacent widgets (e.g., a “Name:” label before a field where one fills in a name). In Java, you can create a label by creating a TextView instance. More commonly, though, you will create labels in XML layout files by adding a TextView element to the layout, with an android:text property to set the value of the label itself. If you need to swap labels based on certain criteria, such as internationalization, you may wish to use a resource reference in the XML instead, as will be described in Chapter 9. TextView has numerous other properties of relevance for labels, such as: • android:typeface to set the typeface to use for the label (e.g., monospace) • android:textStyle to indicate that the typeface should be made bold (bold), italic (italic),or bold and italic (bold_italic) • android:textColor to set the color of the label’s text, in RGB hex format (e.g., #FF0000 for red) For example, in the Basic/Label project, you will find the following layout file: As you can see in Figure 6-1, just that layout alone, with the stub Java source provided by Android’s project builder (e.g., activityCreator), gives you the application. Figure 6-1. The LabelDemo sample applicationButton, Button, Who’s Got the Button? We’ve already seen the use of the Button widget in Chapters 4 and 5. As it turns out, Button is a subclass of TextView, so everything discussed in the preceding section in terms of formatting the face of the button still holds. Fleeting Images Android has two widgets to help you embed images in your activities: ImageView and ImageButton. As the names suggest, they are image-based analogues to TextView and Button, respectively. Each widget takes an android:src attribute (in an XML layout) to specify what picture to use. These usually reference a drawable resource, described in greater detail in the chapter on resources. You can also set the image content based on a Uri from a content provider via setImageURI(). ImageButton, a subclass of ImageView, mixes in the standard Button behaviors, for responding to clicks and whatnot. For example, take a peek at the main.xml layout from the Basic/ImageView sample project which is found along with all other code samples at http://apress.com: The result, just using the code-generated activity, is shown in Figure 6-2. Figure 6-2. The ImageViewDemo sample applicationFields of Green. Or Other Colors. Along with buttons and labels, fields are the third “anchor” of most GUI toolkits. In Android, they are implemented via the EditText widget, which is a subclass of the TextView used for labels. Along with the standard TextView properties (e.g., android:textStyle), EditText has many others that will be useful for you in constructing fields, including: • android:autoText, to control if the field should provide automatic spelling assistance • android:capitalize, to control if the field should automatically capitalize the first letter of entered text (e.g., first name, city) • android:digits, to configure the field to accept only certain digits • android:singleLine, to control if the field is for single-line input or multiple-line input (e.g., does move you to the next widget or add a newline?) Beyond those, you can configure fields to use specialized input methods, such as android:numeric for numeric-only input, android:password for shrouded password input, and android:phoneNumber for entering in phone numbers. If you want to create your own input method scheme (e.g., postal codes, Social Security numbers), you need to create your own implementation of the InputMethod interface, then configure the field to use it via android: inputMethod. For example, from the Basic/Field project, here is an XML layout file showing an EditText: Note that android:singleLine is false, so users will be able to enter in several lines of text. For this project, the FieldDemo.java file populates the input field with some prose: package com.commonsware.android.basic; import android.app.Activity; import android.os.Bundle; import android.widget.EditText; public class FieldDemo extends Activity { @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.main); EditText fld=(EditText)findViewById(R.id.field); fld.setText("Licensed under the Apache License, Version 2.0 " + "(the \"License\"); you may not use this file " + "except in compliance with the License. You may " + "obtain a copy of the License at " + "http://www.apache.org/licenses/LICENSE-2.0");}} The result, once built and installed into the emulator, is shown in Figure 6-3. Figure 6-3. The FieldDemo sample applicationNote Android’s emulator only allows one application in the launcher per unique Java package. Since all the demos in this chapter share the com.commonsware.android.basic package, you will only see one of these demos in your emulator’s launcher at any one time. Another flavor of field is one that offers auto-completion, to help users supply a value without typing in the whole text. That is provided in Android as the AutoCompleteTextView widget and is discussed in Chapter 8. Just Another Box to Check The classic checkbox has two states: checked and unchecked. Clicking the checkbox toggles between those states to indicate a choice (e.g., “Add rush delivery to my order”). In Android, there is a CheckBox widget to meet this need. It has TextView as an ancestor, so you can use TextView properties like android:textColor to format the widget. Within Java, you can invoke: • isChecked() to determine if the checkbox has been checked • setChecked() to force the checkbox into a checked or unchecked state • toggle() to toggle the checkbox as if the user checked it Also, you can register a listener object (in this case, an instance of OnCheckedChangeListener) to be notified when the state of the checkbox changes. For example, from the Basic/CheckBox project, here is a simple checkbox layout: The corresponding CheckBoxDemo.java retrieves and configures the behavior of the checkbox: public class CheckBoxDemo extends Activity implements CompoundButton.OnCheckedChangeListener { CheckBox cb; @Override public void onCreate(Bundle icicle) { super.onCreate(icicle); setContentView(R.layout.main); cb=(CheckBox)findViewById(R.id.check);cb.setOnCheckedChangeListener(this); } public void onCheckedChanged(CompoundButton buttonView, boolean isChecked) {if (isChecked) {cb.setText("This checkbox is: checked");}else {cb.setText("This checkbox is: unchecked");}}}Note that the activity serves as its own listener for checkbox state changes since it implements the OnCheckedChangeListener interface (via cb.setOnCheckedChangeListener(this)). The callback for the listener is onCheckedChanged(), which receives the checkbox whose state has changed and what the new state is. In this case, we update the text of the checkbox to reflect what the actual box contains. The result? Clicking the checkbox immediately updates its text, as you can see in Figures 6-4 and 6-5. Figure 6-4. The CheckBoxDemo sample application, with the checkbox unchecked Figure 6-5. The same application, now with the checkbox checkedTurn the Radio Up As with other implementations of radio buttons in other toolkits, Android’s radio buttons are two-state, like checkboxes, but can be grouped such that only one radio button in the group can be checked at any time. Like CheckBox, RadioButton inherits from CompoundButton, which in turn inherits from TextView. Hence, all the standard TextView properties for font face, style, color, etc., are available for controlling the look of radio buttons. Similarly, you can call isChecked() on a RadioButton to see if it is selected, toggle() to select it, and so on, like you can with a CheckBox. Most times, you will want to put your RadioButton widgets inside of a RadioGroup. The RadioGroup indicates a set of radio buttons whose state is tied, meaning only one button out of the group can be selected at any time. If you assign an android:id to your RadioGroup in your XML layout, you can access the group from your Java code and invoke: • check() to check a specific radio button via its ID (e.g., group.check(R.id.radio1)) • clearCheck() to clear all radio buttons, so none in the group are checked • getCheckedRadioButtonId() to get the ID of the currently-checked radio button (or -1 if none are checked) For example, from the Basic/RadioButton sample application, here is an XML layout showing a RadioGroup wrapping a set of RadioButton widgets: Figure 6-6 shows the result using the stock Android-generated Java for the project and this layout. Figure 6-6. The RadioButtonDemo sample applicationNote that the radio button group is initially set to be completely unchecked at the outset. To pre-set one of the radio buttons to be checked, use either setChecked() on the RadioButton or check() on the RadioGroup from within your onCreate() callback in your activity. It’s Quite a View All widgets, including the ones previously shown, extend View, and as such give all widgets an array of useful properties and methods beyond those already described. Useful Properties Some of the properties on View most likely to be used include: • Controls the focus sequence: • android:nextFocusDown • android:nextFocusLeft • android:nextFocusRight • android:nextFocusUp • android:visibility, which controls whether the widget is initially visible • android:background, which typically provides an RGB color value (e.g., #00FF00 for green) to serve as the background for the widgetUseful Methods You can toggle whether or not a widget is enabled via setEnabled() and see if it is enabled via isEnabled(). One common use pattern for this is to disable some widgets based on a CheckBox or RadioButton selection. You can give a widget focus via requestFocus() and see if it is focused via isFocused(). You might use this in concert with disabling widgets as previously mentioned, to ensure the proper widget has the focus once your disabling operation is complete. To help navigate the tree of widgets and containers that make up an activity’s overall view, you can use: • getParent() to find the parent widget or container • findViewById() to find a child widget with a certain ID • getRootView() to get the root of the tree (e.g., what you provided to the activity via setContentView())