tutorials/views/hello-formstuff.jd

page.title=Hello, Form Stuff
parent.title=Hello, Views
parent.link=index.html
@jd:body

<p>This page introduces a variety of widgets, like image buttons,
text fields, checkboxes and radio buttons.</p>


<ol>
  <li>Start a new project/Activity called HelloFormStuff.</li>
  <li>Your layout file should have a basic LinearLayout:
    <pre>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent" >

&lt;/LinearLayout>
</pre>
    <p>For each widget you want to add, just put the respective View inside here.</p>
</li>
</ol>
<p class="note"><strong>Tip:</strong> As you add new Android code, press Ctrl(or Cmd) + Shift + O
to import all needed packages.</p>


<h2>ImageButton</h2>
<p>A button with a custom image on it.
We'll make it display a message when pressed.</p>
<ol>
  <li><img src="images/android.png" align="right"/>
	Drag the Android image on the right (or your own image) into the
	res/drawable/ directory of your project.
        We'll use this for the button.</li>
  <li>Open the layout file and, inside the LinearLayout, add the {@link android.widget.ImageButton} element:
<pre>
&lt;ImageButton
    android:id="@+id/android_button"
    android:layout_width="100dip"
    android:layout_height="wrap_content"
    android:src="@drawable/android" />
</pre>
	<p>The source of the button
	is from the res/drawable/ directory, where we've placed the android.png.</p>
        <p class="note"><strong>Tip:</strong> You can also reference some of the many built-in
        images from the Android {@link android.R.drawable} resources,
        like <code>ic_media_play</code>, for a "play" button image. To do so, change the source
        attribute to <code>android:src="@android:drawable/ic_media_play"</code>.</p>
</li>
<li>To make the button to actually do something, add the following
code at the end of the <code>onCreate()</code> method:
<pre>
final ImageButton button = (ImageButton) findViewById(R.id.android_button);
button.setOnClickListener(new OnClickListener() {
    public void onClick(View v) {
        // Perform action on clicks
        Toast.makeText(HelloFormStuff.this, "Beep Bop", Toast.LENGTH_SHORT).show();
    }
});
</pre>
<p>This captures our ImageButton from the layout, then adds an on-click listener to it.
The {@link android.view.View.OnClickListener} must define the <code>onClick()</code> method, which
defines the action to be made when the button is clicked. Here, we show a
{@link android.widget.Toast} message when clicked.</p>
</li>
<li>Run it.</li>
</ol>


<h2>EditText</h2>
<p>A text field for user input. We'll make it display the text entered so far when the "Enter" key is pressed.</p>

<ol>
  <li>Open the layout file and, inside the LinearLayout, add the {@link android.widget.EditText} element:
<pre>
&lt;EditText
    android:id="@+id/edittext"
    android:layout_width="fill_parent"
    android:layout_height="wrap_content"/>
</pre>
</li>
<li>To do something with the text that the user enters, add the following code
to the end of the <code>onCreate()</code> method:
<pre>
final EditText edittext = (EditText) findViewById(R.id.edittext);
edittext.setOnKeyListener(new OnKeyListener() {
    public boolean onKey(View v, int keyCode, KeyEvent event) {
        if ((event.getAction() == KeyEvent.ACTION_DOWN) && (keyCode == KeyEvent.KEYCODE_ENTER)) {
          // Perform action on key press
          Toast.makeText(HelloFormStuff.this, edittext.getText(), Toast.LENGTH_SHORT).show();
          return true;
        }
        return false;
    }
});
</pre>
<p>This captures our EditText element from the layout, then adds an on-key listener to it.
The {@link android.view.View.OnKeyListener} must define the <code>onKey()</code> method, which
defines the action to be made when a key is pressed. In this case, we want to listen for the
Enter key (when pressed down), then pop up a {@link android.widget.Toast} message with the
text from the EditText field. Be sure to return <var>true</var> after the event is handled,
so that the event doesn't bubble-up and get handled by the View (which would result in a
carriage return in the text field).</p>
<li>Run it.</li>
</ol>


<h2>CheckBox</h2>
<p>A checkbox for selecting items. We'll make it display the the current state when pressed.</p>

<ol>
  <li>Open the layout file and, inside the LinearLayout, add the {@link android.widget.CheckBox} element:
<pre>
&lt;CheckBox android:id="@+id/checkbox"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="check it out" />
</pre>
</li>
<li>To do something when the state is changed, add the following code
to the end of the <code>onCreate()</code> method:
<pre>
final CheckBox checkbox = (CheckBox) findViewById(R.id.checkbox);
checkbox.setOnClickListener(new OnClickListener() {
    public void onClick(View v) {
        // Perform action on clicks
        if (checkbox.isChecked()) {
            Toast.makeText(HelloFormStuff.this, "Selected", Toast.LENGTH_SHORT).show();
        } else {
            Toast.makeText(HelloFormStuff.this, "Not selected", Toast.LENGTH_SHORT).show();
        }
    }
});
</pre>
<p>This captures our CheckBox element from the layout, then adds an on-click listener to it.
The {@link android.view.View.OnClickListener} must define the <code>onClick()</code> method, which
defines the action to be made when the checkbox is clicked. Here, we query the current state of the
checkbox, then pop up a {@link android.widget.Toast} message that displays the current state.
Notice that the CheckBox handles its own state change between checked and un-checked, so we just
ask which it currently is.</p>
<li>Run it.</li>
</ol>
<p class="note"><strong>Tip:</strong> If you find that you need to change the state
in another way (such as when loading a saved {@link android.preference.CheckBoxPreference}),
use <code>setChecked(true)</code> or <code>toggle()</code>.</p>


<h2>RadioButton</h2>
<p>Two mutually-exclusive radio buttons&mdash;enabling one disables the other.
When each is pressed, we'll pop up a message.</p>

<ol>
  <li>Open the layout file and, inside the LinearLayout, add two {@link android.widget.RadioButton}s,
inside a {@link android.widget.RadioGroup}:
<pre>
&lt;RadioGroup
  android:layout_width="fill_parent"
  android:layout_height="wrap_content"
  android:orientation="vertical">

  &lt;RadioButton android:id="@+id/radio_red"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:text="Red" />

  &lt;RadioButton android:id="@+id/radio_blue"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      android:text="Blue" />

&lt;/RadioGroup>
</pre>
</li>
<li>To do something when each is selected, we'll need an OnClickListener. Unlike the other
listeners we've created, instead of creating this one as an anonymous inner class,
we'll create it as a new object. This way, we can re-use the OnClickListener for
both RadioButtons. So, add the following code in the HelloFormStuff Activity
(<em>outside</em> the <code>onCreate()</code> method):
<pre>
OnClickListener radio_listener = new OnClickListener() {
    public void onClick(View v) {
        // Perform action on clicks
        RadioButton rb = (RadioButton) v;
        Toast.makeText(HelloFormStuff.this, rb.getText(), Toast.LENGTH_SHORT).show();
    }
};
</pre>
<p>Our <code>onClick()</code> method will be handed the View clicked, so the first thing to do
is cast it into a RadioButton. Then we pop up a
{@link android.widget.Toast} message that displays the selection.</p>
<li>Now, at the bottom of the <code>onCreate()</code> method, add the following:
<pre>
  final RadioButton radio_red = (RadioButton) findViewById(R.id.radio_red);
  final RadioButton radio_blue = (RadioButton) findViewById(R.id.radio_blue);
  radio_red.setOnClickListener(radio_listener);
  radio_blue.setOnClickListener(radio_listener);
</pre>
<p>This captures each of the RadioButtons from our layout and adds the newly-created
OnClickListener to each.</p>
<li>Run it.</li>
</ol>
<p class="note"><strong>Tip:</strong> If you find that you need to change the state of a
RadioButton in another way (such as when loading a saved {@link android.preference.CheckBoxPreference}),
use <code>setChecked(true)</code> or <code>toggle()</code>.</p>


<h2>ToggleButton</h2>
<p>A button used specifically for toggling something on and off.</p>

<ol>
  <li>Open the layout file and, inside the LinearLayout, add the {@link android.widget.ToggleButton} element:
<pre>
&lt;ToggleButton android:id="@+id/togglebutton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content" />
</pre>
</li>
<li>To do something when the state is changed, add the following code
to the end of the <code>onCreate()</code> method:
<pre>
final ToggleButton togglebutton = (ToggleButton) findViewById(R.id.togglebutton);
togglebutton.setOnClickListener(new OnClickListener() {
    public void onClick(View v) {
        // Perform action on clicks
        if (togglebutton.isChecked()) {
            Toast.makeText(HelloFormStuff.this, "ON", Toast.LENGTH_SHORT).show();
        } else {
            Toast.makeText(HelloFormStuff.this, "OFF", Toast.LENGTH_SHORT).show();
        }
    }
});
</pre>
<p>This captures our ToggleButton element from the layout, then adds an on-click listener to it.
The {@link android.view.View.OnClickListener} must define the <code>onClick()</code> method, which
defines the action to be made when the button is clicked. Here, we query the current state of the
ToggleButton, then pop up a {@link android.widget.Toast} message that displays the current state.
Notice that the ToggleButton handles its own state change between checked and un-checked, so we just
ask which it is.</p>
<li>Run it.</li>
</ol>

<p class="note"><strong>Tip:</strong> By default, the text on the button is "ON" and "OFF", but
you can change each of these with <code>setTextOn(<var>CharSequence</var>)</code> and
<code>setTextOff(<var>CharSequence</var>)</code>. And, if you find that you need to change the state
in another way (such as when loading a saved {@link android.preference.CheckBoxPreference}),
use <code>setChecked(true)</code> or <code>toggle()</code>. </p>


<p>If you've added all the form items above, your application should look something like this:</p>
<img src="images/hello-formstuff.png" width="150px" />

<h3>References</h3>
<ul>
	<li>{@link android.widget.ImageButton}</li>
	<li>{@link android.widget.EditText}</li>
	<li>{@link android.widget.CheckBox}</li>
	<li>{@link android.widget.RadioButton}</li>
	<li>{@link android.widget.ToggleButton}</li>
</ul>