Scott Main | 64461bf | 2013-04-11 19:32:08 -0700 | [diff] [blame] | 1 | page.title=Pickers |
Joe Fernandez | 33baa5a | 2013-11-14 11:41:19 -0800 | [diff] [blame] | 2 | page.tags=datepicker,timepicker |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 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 |
Scott Main | 4e2c9dc | 2013-07-23 19:35:17 -0700 | [diff] [blame] | 50 | the <a href="{@docRoot}tools/support-library/index.html">support library</a> for backward |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 51 | compatibility.</p> |
| 52 | |
| 53 | <p class="note"><strong>Note:</strong> The code samples below show how to create dialogs for a time |
Scott Main | 4e2c9dc | 2013-07-23 19:35:17 -0700 | [diff] [blame] | 54 | picker and date picker using the <a href="{@docRoot}tools/support-library/index.html">support |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 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 |
Scott Main | 4e2c9dc | 2013-07-23 19:35:17 -0700 | [diff] [blame] | 70 | href="{@docRoot}tools/support-library/setup.html">Setting Up a Project to Use a |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 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 |
Scott Main | 4e2c9dc | 2013-07-23 19:35:17 -0700 | [diff] [blame] | 175 | href="{@docRoot}tools/support-library/setup.html">Setting Up a Project to Use a |
Scott Main | 50e990c | 2012-06-21 17:14:39 -0700 | [diff] [blame] | 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> |