1 page.title=Pickers 2 page.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. 36 Each 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 38 is 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 43 picker. The {@link android.support.v4.app.DialogFragment} manages the dialog lifecycle for you and 44 allows you to display the pickers in different layout configurations, 45 such 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 48 level 11), if your app supports versions of Android older than 3.0—even as low as Android 49 1.6—you can use the {@link android.support.v4.app.DialogFragment} class that's available in 50 the <a href="{@docRoot}tools/support-library/index.html">support library</a> for backward 51 compatibility.</p> 52 53 <p class="note"><strong>Note:</strong> The code samples below show how to create dialogs for a time 54 picker and date picker using the <a href="{@docRoot}tools/support-library/index.html">support 55 library</a> APIs for {@link android.support.v4.app.DialogFragment}. If your app's <a 56 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> is 11 or 57 higher, 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 64 android.support.v4.app.DialogFragment}, you need to define a fragment class that extends {@link 65 android.support.v4.app.DialogFragment} and return a {@link android.app.TimePickerDialog} from the 66 fragment'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, 69 be sure you've set up your Android project with the support library as described in <a 70 href="{@docRoot}tools/support-library/setup.html">Setting Up a Project to Use a 71 Library</a>.</p> 72 73 <h3 id="TimePickerFragment">Extending DialogFragment for a time picker</h3> 74 75 <p>To define a {@link 76 android.support.v4.app.DialogFragment} for a {@link android.app.TimePickerDialog}, you 77 must:</p> 78 <ul> 79 <li>Define the {@link android.support.v4.app.DialogFragment#onCreateDialog onCreateDialog()} 80 method 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 83 sets the time.</li> 84 </ul> 85 86 <p>Here's an example:</p> 87 88 <pre> 89 public 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 111 arguments.</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, 119 you can display the time picker by creating an instance of the {@link 120 android.support.v4.app.DialogFragment} and calling {@link 121 android.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> 136 public void showTimePickerDialog(View v) { 137 DialogFragment newFragment = new TimePickerFragment(); 138 newFragment.show(getSupportFragmentManager(), "timePicker"); 139 } 140 </pre> 141 142 <p>This method calls {@link 143 android.support.v4.app.DialogFragment#show show()} on a new instance of the {@link 144 android.support.v4.app.DialogFragment} defined above. The {@link 145 android.support.v4.app.DialogFragment#show show()} method requires an instance of {@link 146 android.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 149 3.0, be sure that you call {@link 150 android.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 152 time picker extends {@link android.support.v4.app.FragmentActivity} instead of the standard {@link 153 android.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 166 android.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 169 android.support.v4.app.DialogFragment}, you need to define a fragment class that extends {@link 170 android.support.v4.app.DialogFragment} and return a {@link android.app.DatePickerDialog} from the 171 fragment'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 177 android.support.v4.app.DialogFragment} for a {@link android.app.DatePickerDialog}, you 178 must:</p> 179 <ul> 180 <li>Define the {@link android.support.v4.app.DialogFragment#onCreateDialog onCreateDialog()} 181 method 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 184 sets the date.</li> 185 </ul> 186 187 <p>Here's an example:</p> 188 189 <pre> 190 public 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 212 arguments.</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, 220 you can display the date picker by creating an instance of the {@link 221 android.support.v4.app.DialogFragment} and calling {@link 222 android.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> 237 public void showDatePickerDialog(View v) { 238 DialogFragment newFragment = new DatePickerFragment(); 239 newFragment.show(getSupportFragmentManager(), "datePicker"); 240 } 241 </pre> 242 243 <p>This method calls {@link 244 android.support.v4.app.DialogFragment#show show()} on a new instance of the {@link 245 android.support.v4.app.DialogFragment} defined above. The {@link 246 android.support.v4.app.DialogFragment#show show()} method requires an instance of {@link 247 android.support.v4.app.FragmentManager} and a unique tag name for the fragment.</p> 248 249 250
