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—even as low as Android 491.6—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 @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<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 174<h3 id="DatePickerFragment">Extending DialogFragment for a date picker</h3> 175 176<p>To define a {@link 177android.support.v4.app.DialogFragment} for a {@link android.app.DatePickerDialog}, you 178must:</p> 179<ul> 180 <li>Define the {@link android.support.v4.app.DialogFragment#onCreateDialog onCreateDialog()} 181method to return an instance of {@link android.app.DatePickerDialog}</li> 182 <li>Implement the 183{@link android.app.DatePickerDialog.OnDateSetListener} interface to receive a callback when the user 184sets the date.</li> 185</ul> 186 187<p>Here's an example:</p> 188 189<pre> 190public static class DatePickerFragment extends DialogFragment 191 implements DatePickerDialog.OnDateSetListener { 192 193 @Override 194 public Dialog onCreateDialog(Bundle savedInstanceState) { 195 // Use the current date as the default date in the picker 196 final Calendar c = Calendar.getInstance(); 197 int year = c.get(Calendar.YEAR); 198 int month = c.get(Calendar.MONTH); 199 int day = c.get(Calendar.DAY_OF_MONTH); 200 201 // Create a new instance of DatePickerDialog and return it 202 return new DatePickerDialog(getActivity(), this, year, month, day); 203 } 204 205 public void onDateSet(DatePicker view, int year, int month, int day) { 206 // Do something with the date chosen by the user 207 } 208} 209</pre> 210 211<p>See the {@link android.app.DatePickerDialog} class for information about the constructor 212arguments.</p> 213 214<p>Now all you need is an event that adds an instance of this fragment to your activity.</p> 215 216 217<h3 id="ShowingTheDatePicker">Showing the date picker</h3> 218 219<p>Once you've defined a {@link android.support.v4.app.DialogFragment} like the one shown above, 220you can display the date picker by creating an instance of the {@link 221android.support.v4.app.DialogFragment} and calling {@link 222android.support.v4.app.DialogFragment#show show()}.</p> 223 224<p>For example, here's a button that, when clicked, calls a method to show the dialog:</p> 225 226<pre> 227<Button 228 android:layout_width="wrap_content" 229 android:layout_height="wrap_content" 230 android:text="@string/pick_date" 231 android:onClick="showDatePickerDialog" /> 232</pre> 233 234<p>When the user clicks this button, the system calls the following method:</p> 235 236<pre> 237public void showDatePickerDialog(View v) { 238 DialogFragment newFragment = new DatePickerFragment(); 239 newFragment.show(getSupportFragmentManager(), "datePicker"); 240} 241</pre> 242 243<p>This method calls {@link 244android.support.v4.app.DialogFragment#show show()} on a new instance of the {@link 245android.support.v4.app.DialogFragment} defined above. The {@link 246android.support.v4.app.DialogFragment#show show()} method requires an instance of {@link 247android.support.v4.app.FragmentManager} and a unique tag name for the fragment.</p> 248 249 250
