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