1page.title=Pickers
2page.tags=datepicker,timepicker
3@jd:body
4
5<div id="qv-wrapper">
6<div id="qv">
7<h2>In this document</h2>
8<ol>
9  <li><a href="#TimePicker">Creating a Time Picker</a>
10    <ol>
11      <li><a href="#TimePickerFragment">Extending DialogFragment for a time picker</a></li>
12      <li><a href="#ShowingTheTimePicker">Showing the time picker</a></li>
13    </ol>
14  </li>
15  <li><a href="#DatePicker">Creating a Date Picker</a>
16    <ol>
17      <li><a href="#DatePickerFragment">Extending DialogFragment for a date picker</a></li>
18      <li><a href="#ShowingTheDatePicker">Showing the date picker</a></li>
19    </ol>
20  </li>
21</ol>
22  <h2>Key classes</h2>
23  <ol>
24    <li>{@link android.app.DatePickerDialog}</li>
25    <li>{@link android.app.TimePickerDialog}</li>
26    <li>{@link android.support.v4.app.DialogFragment}</li>
27  </ol>
28  <h2>See also</h2>
29  <ol>
30    <li><a href="{@docRoot}guide/components/fragments.html">Fragments</a></li>
31  </ol>
32</div>
33</div>
34
35<p>Android provides controls for the user to pick a time or pick a date as ready-to-use dialogs.
36Each picker provides controls for selecting each part of the time (hour, minute, AM/PM) or date
37(month, day, year). Using these pickers helps ensure that your users can pick a time or date that
38is valid, formatted correctly, and adjusted to the user's locale.</p>
39
40<img src="{@docRoot}images/ui/pickers.png" alt="" />
41
42<p>We recommend that you use {@link android.support.v4.app.DialogFragment} to host each time or date
43picker. The {@link android.support.v4.app.DialogFragment} manages the dialog lifecycle for you and
44allows you to display the pickers in different layout configurations,
45such as in a basic dialog on handsets or as an embedded part of the layout on large screens.</p>
46
47<p>Although {@link android.app.DialogFragment} was first added to the platform in Android 3.0 (API
48level 11), if your app supports versions of Android older than 3.0&mdash;even as low as Android
491.6&mdash;you can use the {@link android.support.v4.app.DialogFragment} class that's available in
50the <a href="{@docRoot}tools/support-library/index.html">support library</a> for backward
51compatibility.</p>
52
53<p class="note"><strong>Note:</strong> The code samples below show how to create dialogs for a time
54picker and date picker using the <a href="{@docRoot}tools/support-library/index.html">support
55library</a> APIs for {@link android.support.v4.app.DialogFragment}. If your app's <a
56href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> is 11 or
57higher, you can instead use the platform version of {@link android.app.DialogFragment}.</p>
58
59
60
61<h2 id="TimePicker">Creating a Time Picker</h2>
62
63<p>To display a {@link android.app.TimePickerDialog} using {@link
64android.support.v4.app.DialogFragment}, you need to define a fragment class that extends {@link
65android.support.v4.app.DialogFragment} and return a {@link android.app.TimePickerDialog} from the
66fragment's {@link android.support.v4.app.DialogFragment#onCreateDialog onCreateDialog()} method.</p>
67
68<p class="note"><strong>Note:</strong> If your app supports versions of Android older than 3.0,
69be sure you've set up your Android project with the support library as described in <a
70href="{@docRoot}tools/support-library/setup.html">Setting Up a Project to Use a
71Library</a>.</p>
72
73<h3 id="TimePickerFragment">Extending DialogFragment for a time picker</h3>
74
75<p>To define a {@link
76android.support.v4.app.DialogFragment} for a {@link android.app.TimePickerDialog}, you
77must:</p>
78<ul>
79  <li>Define the {@link android.support.v4.app.DialogFragment#onCreateDialog onCreateDialog()}
80method to return an instance of {@link android.app.TimePickerDialog}</li>
81  <li>Implement the
82{@link android.app.TimePickerDialog.OnTimeSetListener} interface to receive a callback when the user
83sets the time.</li>
84</ul>
85
86<p>Here's an example:</p>
87
88<pre>
89public static class TimePickerFragment extends DialogFragment
90                            implements TimePickerDialog.OnTimeSetListener {
91
92    &#64;Override
93    public Dialog onCreateDialog(Bundle savedInstanceState) {
94        // Use the current time as the default values for the picker
95        final Calendar c = Calendar.getInstance();
96        int hour = c.get(Calendar.HOUR_OF_DAY);
97        int minute = c.get(Calendar.MINUTE);
98
99        // Create a new instance of TimePickerDialog and return it
100        return new TimePickerDialog(getActivity(), this, hour, minute,
101                DateFormat.is24HourFormat(getActivity()));
102    }
103
104    public void onTimeSet(TimePicker view, int hourOfDay, int minute) {
105        // Do something with the time chosen by the user
106    }
107}
108</pre>
109
110<p>See the {@link android.app.TimePickerDialog} class for information about the constructor
111arguments.</p>
112
113<p>Now all you need is an event that adds an instance of this fragment to your activity.</p>
114
115
116<h3 id="ShowingTheTimePicker">Showing the time picker</h3>
117
118<p>Once you've defined a {@link android.support.v4.app.DialogFragment} like the one shown above,
119you can display the time picker by creating an instance of the {@link
120android.support.v4.app.DialogFragment} and calling {@link
121android.support.v4.app.DialogFragment#show show()}.</p>
122
123<p>For example, here's a button that, when clicked, calls a method to show the dialog:</p>
124
125<pre>
126&lt;Button
127    android:layout_width="wrap_content"
128    android:layout_height="wrap_content"
129    android:text="@string/pick_time"
130    android:onClick="showTimePickerDialog" />
131</pre>
132
133<p>When the user clicks this button, the system calls the following method:</p>
134
135<pre>
136public void showTimePickerDialog(View v) {
137    DialogFragment newFragment = new TimePickerFragment();
138    newFragment.show(getSupportFragmentManager(), "timePicker");
139}
140</pre>
141
142<p>This method calls {@link
143android.support.v4.app.DialogFragment#show show()} on a new instance of the {@link
144android.support.v4.app.DialogFragment} defined above. The {@link
145android.support.v4.app.DialogFragment#show show()} method requires an instance of {@link
146android.support.v4.app.FragmentManager} and a unique tag name for the fragment.</p>
147
148<p class="caution"><strong>Caution:</strong> If your app supports versions of Android lower than
1493.0, be sure that you call {@link
150android.support.v4.app.FragmentActivity#getSupportFragmentManager()} to acquire an instance of
151{@link android.support.v4.app.FragmentManager}. Also make sure that your activity that displays the
152time picker extends {@link android.support.v4.app.FragmentActivity} instead of the standard {@link
153android.app.Activity} class.</p>
154
155
156
157
158
159
160
161
162
163<h2 id="DatePicker">Creating a Date Picker</h2>
164
165<p>Creating a {@link android.app.DatePickerDialog} is just like creating a {@link
166android.app.TimePickerDialog}. The only difference is the dialog you create for the fragment.</p>
167
168<p>To display a {@link android.app.DatePickerDialog} using {@link
169android.support.v4.app.DialogFragment}, you need to define a fragment class that extends {@link
170android.support.v4.app.DialogFragment} and return a {@link android.app.DatePickerDialog} from the
171fragment's {@link android.support.v4.app.DialogFragment#onCreateDialog onCreateDialog()} method.</p>
172
173<p class="note"><strong>Note:</strong> If your app supports versions of Android older than 3.0,
174be sure you've set up your Android project with the support library as described in <a
175href="{@docRoot}tools/support-library/setup.html">Setting Up a Project to Use a
176Library</a>.</p>
177
178<h3 id="DatePickerFragment">Extending DialogFragment for a date picker</h3>
179
180<p>To define a {@link
181android.support.v4.app.DialogFragment} for a {@link android.app.DatePickerDialog}, you
182must:</p>
183<ul>
184  <li>Define the {@link android.support.v4.app.DialogFragment#onCreateDialog onCreateDialog()}
185method to return an instance of {@link android.app.DatePickerDialog}</li>
186  <li>Implement the
187{@link android.app.DatePickerDialog.OnDateSetListener} interface to receive a callback when the user
188sets the date.</li>
189</ul>
190
191<p>Here's an example:</p>
192
193<pre>
194public static class DatePickerFragment extends DialogFragment
195                            implements DatePickerDialog.OnDateSetListener {
196
197    &#64;Override
198    public Dialog onCreateDialog(Bundle savedInstanceState) {
199        // Use the current date as the default date in the picker
200        final Calendar c = Calendar.getInstance();
201        int year = c.get(Calendar.YEAR);
202        int month = c.get(Calendar.MONTH);
203        int day = c.get(Calendar.DAY_OF_MONTH);
204
205        // Create a new instance of DatePickerDialog and return it
206        return new DatePickerDialog(getActivity(), this, year, month, day);
207    }
208
209    public void onDateSet(DatePicker view, int year, int month, int day) {
210        // Do something with the date chosen by the user
211    }
212}
213</pre>
214
215<p>See the {@link android.app.DatePickerDialog} class for information about the constructor
216arguments.</p>
217
218<p>Now all you need is an event that adds an instance of this fragment to your activity.</p>
219
220
221<h3 id="ShowingTheDatePicker">Showing the date picker</h3>
222
223<p>Once you've defined a {@link android.support.v4.app.DialogFragment} like the one shown above,
224you can display the date picker by creating an instance of the {@link
225android.support.v4.app.DialogFragment} and calling {@link
226android.support.v4.app.DialogFragment#show show()}.</p>
227
228<p>For example, here's a button that, when clicked, calls a method to show the dialog:</p>
229
230<pre>
231&lt;Button
232    android:layout_width="wrap_content"
233    android:layout_height="wrap_content"
234    android:text="@string/pick_date"
235    android:onClick="showDatePickerDialog" />
236</pre>
237
238<p>When the user clicks this button, the system calls the following method:</p>
239
240<pre>
241public void showDatePickerDialog(View v) {
242    DialogFragment newFragment = new DatePickerFragment();
243    newFragment.show(getSupportFragmentManager(), "datePicker");
244}
245</pre>
246
247<p>This method calls {@link
248android.support.v4.app.DialogFragment#show show()} on a new instance of the {@link
249android.support.v4.app.DialogFragment} defined above. The {@link
250android.support.v4.app.DialogFragment#show show()} method requires an instance of {@link
251android.support.v4.app.FragmentManager} and a unique tag name for the fragment.</p>
252
253<p class="caution"><strong>Caution:</strong> If your app supports versions of Android lower than
2543.0, be sure that you call {@link
255android.support.v4.app.FragmentActivity#getSupportFragmentManager()} to acquire an instance of
256{@link android.support.v4.app.FragmentManager}. Also make sure that your activity that displays the
257time picker extends {@link android.support.v4.app.FragmentActivity} instead of the standard {@link
258android.app.Activity} class.</p>
259