tutorials/views/hello-timepicker.jd

page.title=Time Picker
parent.title=Hello, Views
parent.link=index.html
@jd:body

<p>To provide a widget for selecting a time, use the {@link android.widget.TimePicker}
widget, which allows the user to select the hour and minute in a familiar interface.</p>

<p>In this tutorial, you'll create a {@link android.app.TimePickerDialog}, which presents the
time picker in a floating dialog box at the press of a button. When the time is set by
the user, a {@link android.widget.TextView} will update with the new date.</p>

<ol>
  <li>Start a new project named <em>HelloTimePicker</em>.</li>
  <li>Open the <code>res/layout/main.xml</code> file and insert the following:
    <pre>
&lt;?xml version="1.0" encoding="utf-8"?>
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:orientation="vertical">
    &lt;TextView android:id="@+id/timeDisplay"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text=""/>
    &lt;Button android:id="@+id/pickTime"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Change the time"/>
&lt;/LinearLayout>
</pre>
<p>This is a basic {@link android.widget.LinearLayout} with a {@link android.widget.TextView}
that will display the time and a {@link android.widget.Button} that will open the {@link
android.app.TimePickerDialog}.</p>
    </li>

  <li>Open <code>HelloTimePicker.java</code> and insert the following class members:
<pre>
    private TextView mTimeDisplay;
    private Button mPickTime;

    private int mHour;
    private int mMinute;

    static final int TIME_DIALOG_ID = 0;
</pre>
<p>This declares variables for the layout elements and time fields.
The <code>TIME_DIALOG_ID</code> is a static integer that uniquely identifies the dialog.</p>
  </li>
  <li>Now insert the following code for the {@link android.app.Activity#onCreate(Bundle) onCreate()}
method:
<pre>
    &#64;Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);

        // capture our View elements
        mTimeDisplay = (TextView) findViewById(R.id.timeDisplay);
        mPickTime = (Button) findViewById(R.id.pickTime);

        // add a click listener to the button
        mPickTime.setOnClickListener(new View.OnClickListener() {
            public void onClick(View v) {
                showDialog(TIME_DIALOG_ID);
            }
        });

        // get the current time
        final Calendar c = Calendar.getInstance();
        mHour = c.get(Calendar.HOUR_OF_DAY);
        mMinute = c.get(Calendar.MINUTE);

        // display the current date
        updateDisplay();
    }
</pre>

<p>First, the content is set to the <code>main.xml</code> layout and then the {@link
android.widget.TextView} and {@link android.widget.Button} are captured with {@link
android.app.Activity#findViewById(int)}.
Then an {@link android.view.View.OnClickListener} is created for the {@link android.widget.Button},
so that when clicked, it will call {@link
android.app.Activity#showDialog(int)}, passing the unique integer ID for the time picker
dialog. Using {@link android.app.Activity#showDialog(int)} allows the {@link
android.app.Activity} to manage the life-cycle of the dialog and will call the {@link
android.app.Activity#onCreateDialog(int)} callback method to request the {@link android.app.Dialog}
that should be displayed (which you'll define later). After the on-click listener is set, a new
{@link java.util.Calendar} is created to get the current hour and minute. Finally, the
private <code>updateDisplay()</code> method is called in order to fill the {@link
android.widget.TextView} with the current time.</p>
</li>

<li>Add the <code>updateDisplay()</code> and <code>pad()</code> methods:
<pre>
// updates the time we display in the TextView
private void updateDisplay() {
    mTimeDisplay.setText(
        new StringBuilder()
                .append(pad(mHour)).append(":")
                .append(pad(mMinute)));
}

private static String pad(int c) {
    if (c >= 10)
        return String.valueOf(c);
    else
        return "0" + String.valueOf(c);
}
</pre>
<p>The <code>updateDisplay()</code> method uses the member fields for the time and inserts them in
the <code>mTimeDisplay</code> {@link android.widget.TextView}. The <code>pad()</code> method returns
the appropriate string representation of the hour or minute&mdash;it will prefix a zero to the
number if it's a single digit.</p>
</li>

<li>Add a class member for a {@link android.app.TimePickerDialog.OnTimeSetListener} that will be
called when the user sets a new time:
<pre>
// the callback received when the user "sets" the time in the dialog
private TimePickerDialog.OnTimeSetListener mTimeSetListener =
    new TimePickerDialog.OnTimeSetListener() {
        public void onTimeSet(TimePicker view, int hourOfDay, int minute) {
            mHour = hourOfDay;
            mMinute = minute;
            updateDisplay();
        }
    };
</pre>
<p>When the user is done setting the time (clicks the "Set" button), the
<code>onTimeSet()</code> method is called and it updates the member fields with
the new time and updates the layout's {@link android.widget.TextView}.</p>
</li>

<li>Add the {@link android.app.Activity#onCreateDialog(int)} callback method:
<pre>
&#64;Override
protected Dialog onCreateDialog(int id) {
    switch (id) {
    case TIME_DIALOG_ID:
        return new TimePickerDialog(this,
                mTimeSetListener, mHour, mMinute, false);
    }
    return null;
}
</pre>
<p>This is an {@link android.app.Activity} callback that is passed the identifier you passed to
{@link android.app.Activity#showDialog(int)}, in the {@link android.widget.Button}'s on-click
listener. When the ID matches, this initializes the {@link android.app.TimePickerDialog} with the
member variables initialized at the end of <code>onCreate()</code> and the {@link
android.app.TimePickerDialog.OnTimeSetListener} created in the previous step.</p>
</li>

<li>Run the application.</li>
</ol>
<p>When you press the "Change the time" button, you should see the following:</p>
<img src="images/hello-timepicker.png" width="150px" />

<h3>References</h3>
<ol>
  <li>{@link android.widget.TimePicker}</li>
  <li>{@link android.app.TimePickerDialog.OnTimeSetListener}</li>
  <li>{@link android.widget.Button}</li>
  <li>{@link android.widget.TextView}</li>
  <li>{@link java.util.Calendar}</li>
</ol>