1 page.title= Pickers 2 parent.title=Form Controls 3 parent.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. 37 Each 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 39 is 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 44 picker. The {@link android.support.v4.app.DialogFragment} manages the dialog lifecycle for you and 45 allows you to display the pickers in different layout configurations, 46 such 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 49 level 11), if your app supports versions of Android older than 3.0—even as low as Android 50 1.6—you can use the {@link android.support.v4.app.DialogFragment} class that's available in 51 the <a href="{@docRoot}tools/extras/support-library.html">support library</a> for backward 52 compatibility.</p> 53 54 <p class="note"><strong>Note:</strong> The code samples below show how to create dialogs for a time 55 picker and date picker using the <a href="{@docRoot}tools/extras/support-library.html">support 56 library</a> APIs for {@link android.support.v4.app.DialogFragment}. If your app's <a 57 href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> is 11 or 58 higher, 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 65 android.support.v4.app.DialogFragment}, you need to define a fragment class that extends {@link 66 android.support.v4.app.DialogFragment} and return a {@link android.app.TimePickerDialog} from the 67 fragment'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, 70 be sure you've set up your Android project with the support library as described in <a 71 href="{@docRoot}tools/extras/support-library.html#SettingUp">Setting Up a Project to Use a 72 Library</a>.</p> 73 74 <h3 id="TimePickerFragment">Extending DialogFragment for a time picker</h3> 75 76 <p>To define a {@link 77 android.support.v4.app.DialogFragment} for a {@link android.app.TimePickerDialog}, you 78 must:</p> 79 <ul> 80 <li>Define the {@link android.support.v4.app.DialogFragment#onCreateDialog onCreateDialog()} 81 method 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 84 sets the time.</li> 85 </ul> 86 87 <p>Here's an example:</p> 88 89 <pre> 90 public 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 112 arguments.</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, 120 you can display the time picker by creating an instance of the {@link 121 android.support.v4.app.DialogFragment} and calling {@link 122 android.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> 137 public void showTimePickerDialog(View v) { 138 DialogFragment newFragment = new TimePickerFragment(); 139 newFragment.show(getSupportFragmentManager(), "timePicker"); 140 } 141 </pre> 142 143 <p>This method calls {@link 144 android.support.v4.app.DialogFragment#show show()} on a new instance of the {@link 145 android.support.v4.app.DialogFragment} defined above. The {@link 146 android.support.v4.app.DialogFragment#show show()} method requires an instance of {@link 147 android.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 150 3.0, be sure that you call {@link 151 android.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 153 time picker extends {@link android.support.v4.app.FragmentActivity} instead of the standard {@link 154 android.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 167 android.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 170 android.support.v4.app.DialogFragment}, you need to define a fragment class that extends {@link 171 android.support.v4.app.DialogFragment} and return a {@link android.app.DatePickerDialog} from the 172 fragment'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, 175 be sure you've set up your Android project with the support library as described in <a 176 href="{@docRoot}tools/extras/support-library.html#SettingUp">Setting Up a Project to Use a 177 Library</a>.</p> 178 179 <h3 id="DatePickerFragment">Extending DialogFragment for a date picker</h3> 180 181 <p>To define a {@link 182 android.support.v4.app.DialogFragment} for a {@link android.app.DatePickerDialog}, you 183 must:</p> 184 <ul> 185 <li>Define the {@link android.support.v4.app.DialogFragment#onCreateDialog onCreateDialog()} 186 method 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 189 sets the date.</li> 190 </ul> 191 192 <p>Here's an example:</p> 193 194 <pre> 195 public 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 217 arguments.</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, 225 you can display the date picker by creating an instance of the {@link 226 android.support.v4.app.DialogFragment} and calling {@link 227 android.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> 242 public void showDatePickerDialog(View v) { 243 DialogFragment newFragment = new DatePickerFragment(); 244 newFragment.show(getSupportFragmentManager(), "datePicker"); 245 } 246 </pre> 247 248 <p>This method calls {@link 249 android.support.v4.app.DialogFragment#show show()} on a new instance of the {@link 250 android.support.v4.app.DialogFragment} defined above. The {@link 251 android.support.v4.app.DialogFragment#show show()} method requires an instance of {@link 252 android.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 255 3.0, be sure that you call {@link 256 android.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 258 time picker extends {@link android.support.v4.app.FragmentActivity} instead of the standard {@link 259 android.app.Activity} class.</p> 260
