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 <p class="note"><strong>Note:</strong> If your app supports versions of Android older than 3.0, 174 be sure you've set up your Android project with the support library as described in <a 175 href="{@docRoot}tools/support-library/setup.html">Setting Up a Project to Use a 176 Library</a>.</p> 177 178 <h3 id="DatePickerFragment">Extending DialogFragment for a date picker</h3> 179 180 <p>To define a {@link 181 android.support.v4.app.DialogFragment} for a {@link android.app.DatePickerDialog}, you 182 must:</p> 183 <ul> 184 <li>Define the {@link android.support.v4.app.DialogFragment#onCreateDialog onCreateDialog()} 185 method 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 188 sets the date.</li> 189 </ul> 190 191 <p>Here's an example:</p> 192 193 <pre> 194 public static class DatePickerFragment extends DialogFragment 195 implements DatePickerDialog.OnDateSetListener { 196 197 @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 216 arguments.</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, 224 you can display the date picker by creating an instance of the {@link 225 android.support.v4.app.DialogFragment} and calling {@link 226 android.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 <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> 241 public void showDatePickerDialog(View v) { 242 DialogFragment newFragment = new DatePickerFragment(); 243 newFragment.show(getSupportFragmentManager(), "datePicker"); 244 } 245 </pre> 246 247 <p>This method calls {@link 248 android.support.v4.app.DialogFragment#show show()} on a new instance of the {@link 249 android.support.v4.app.DialogFragment} defined above. The {@link 250 android.support.v4.app.DialogFragment#show show()} method requires an instance of {@link 251 android.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 254 3.0, be sure that you call {@link 255 android.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 257 time picker extends {@link android.support.v4.app.FragmentActivity} instead of the standard {@link 258 android.app.Activity} class.</p> 259
