Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 1 | page.title=Support Package |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 2 | |
| 3 | @jd:body |
| 4 | |
| 5 | <div id="qv-wrapper"> |
| 6 | <div id="qv"> |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 7 | |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 8 | <h2>In this document</h2> |
| 9 | <ol> |
| 10 | <li><a href="#Notes">Revisions</a></li> |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 11 | <li><a href="#Downloading">Downloading the Support Package</a></li> |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 12 | <li><a href="#SettingUp">Setting Up a Project to Use a Library</a></li> |
| 13 | <li><a href="#Using">Using the v4 Library APIs</a></li> |
| 14 | <li><a href="#Docs">Reference Docs</a></li> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 15 | <li><a href="#Samples">Samples</a></li> |
| 16 | </ol> |
| 17 | |
| 18 | <h2>See also</h2> |
| 19 | <ol> |
| 20 | <li><a |
| 21 | href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for Android 3.0</a></li> |
| 22 | <li><a href="http://code.google.com/p/iosched/">Google I/O App source code</a></li> |
| 23 | </ol> |
| 24 | |
| 25 | </div> |
| 26 | </div> |
| 27 | |
| 28 | <p><em>Minimum API level supported:</em> <b>4</b></p> |
| 29 | |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 30 | <p>The Support Package includes static "support libraries" that you can add to your Android |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 31 | application in order to use APIs that are either not available for older platform versions or that |
| 32 | offer "utility" APIs that aren't a part of the framework APIs. The goal is to simplify your |
Scott Main | ffcbe48 | 2011-07-15 09:50:49 -0700 | [diff] [blame] | 33 | development by offering more APIs that you can bundle with your application so you can |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 34 | worry less about platform versions.</p> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 35 | |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 36 | <p class="note"><strong>Note:</strong> The Support Package includes more than one support |
Scott Main | ffcbe48 | 2011-07-15 09:50:49 -0700 | [diff] [blame] | 37 | library. Each one has a different <em>minimum API level</em>. For example, one library requires API |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 38 | level 4 or higher, while another requires API level 13 or higher (v13 is a superset of v4 and |
| 39 | includes additional |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 40 | support classes to work with v13 APIs). The minimum version is indicated |
Scott Main | ffcbe48 | 2011-07-15 09:50:49 -0700 | [diff] [blame] | 41 | by the directory name, such as {@code v4/} and {@code v13/}.</p> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 42 | |
| 43 | |
| 44 | <h2 id="Notes">Revisions</h2> |
| 45 | |
| 46 | <p>The sections below provide notes about successive releases of |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 47 | the Support Package, as denoted by revision number.</p> |
| 48 | |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 49 | <div class="toggle-content open"> |
| 50 | |
| 51 | <p><a href="#" onclick="return toggleContent(this)"> |
| 52 | <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" /> |
Joe Fernandez | dad557e | 2012-03-16 01:17:58 -0700 | [diff] [blame] | 53 | Support Package, revision 7 (March 2012) |
| 54 | </a></p> |
| 55 | |
| 56 | <div class="toggle-content-toggleme" style="padding-left:2em"> |
| 57 | <dl> |
| 58 | <dt>Changes for v4 support library:</dt> |
| 59 | <dd> |
| 60 | <ul> |
| 61 | <li>Added {@link android.support.v4.app.ShareCompat}, which provides helper classes |
| 62 | for sending and receiving content for social sharing applications, including new metadata for |
| 63 | attributing shared data to the source app. This class also provides compatible integration with the |
| 64 | new {@link android.widget.ShareActionProvider} in Android 4.0.</li> |
| 65 | <li>Added {@link android.support.v4.app.NavUtils} and {@link |
| 66 | android.support.v4.app.TaskStackBuilder} to provide support for implementing the |
| 67 | <a href="{@docRoot}design/index.html">Android Design</a> guidelines for navigation. These |
| 68 | additions include a way to implement the action bar's <em>Up</em> button across versions. |
| 69 | For an example implementation of this pattern, see the AppNavigation sample in |
| 70 | ({@code <em><sdk></em>/samples/<em><platform></em>/AppNavigation}).</li> |
| 71 | <li>Added {@link android.support.v4.app.NotificationCompat.Builder} to provide a |
| 72 | compatibility implementation of Android 3.0's {@link android.app.Notification.Builder} helper class |
| 73 | for creating standardized system notifications.</li> |
| 74 | </ul> |
| 75 | </dd> |
| 76 | </dl> |
| 77 | </div> |
| 78 | |
| 79 | <div class="toggle-content closed"> |
| 80 | |
| 81 | <p><a href="#" onclick="return toggleContent(this)"> |
| 82 | <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" /> |
Joe Fernandez | e4f2031 | 2011-12-15 13:23:53 -0800 | [diff] [blame] | 83 | Support Package, revision 6 (December 2011) |
| 84 | </a></p> |
| 85 | |
| 86 | <div class="toggle-content-toggleme" style="padding-left:2em"> |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 87 | <p class="note"><strong>Note:</strong> Reference for support library APIs are now available with |
| 88 | the framework references, for example: {@link android.support.v4.app}.</p> |
| 89 | <dl> |
Joe Fernandez | e4f2031 | 2011-12-15 13:23:53 -0800 | [diff] [blame] | 90 | <dt>Changes for v4 support library:</dt> |
| 91 | <dd> |
| 92 | <ul> |
| 93 | <li>Changes to ViewPager: |
| 94 | <ul> |
| 95 | <li>Added extra decorative view support for {@link android.support.v4.view.ViewPager}. |
| 96 | Decorative views may be supplied as child views of a pager in XML layout.</li> |
| 97 | <li>Added {@link android.support.v4.view.PagerAdapter#getPageTitle |
| 98 | PagerAdapter.getPageTitle()} to supply title strings for pages, which defaults to no |
| 99 | title for each page.</li> |
| 100 | <li>Added {@link android.support.v4.view.PagerTitleStrip}, a non-interactive title |
| 101 | strip, that can be added as a child of ViewPager. Developers can supply text |
| 102 | appearance and color, as well as layout sizing and gravity information.</li> |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 103 | <li>Updated {@link android.support.v4.view.PagerAdapter} methods to take ViewGroup |
| 104 | objects, rather than View to avoid class casting in adapter implementations.</li> |
| 105 | <li>Updated {@link android.support.v4.view.ViewPager} to use Launcher-style |
| 106 | fling behavior.</li> |
Joe Fernandez | e4f2031 | 2011-12-15 13:23:53 -0800 | [diff] [blame] | 107 | <li>Bug fixes for user interface interaction and test automation.</li> |
| 108 | </ul> |
| 109 | </li> |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 110 | |
Joe Fernandez | e4f2031 | 2011-12-15 13:23:53 -0800 | [diff] [blame] | 111 | <li>Support for Fragments: |
| 112 | <ul> |
| 113 | <li>Changed {@code setStartDeferred()} method to {@link |
| 114 | android.support.v4.app.Fragment#setUserVisibleHint}.</li> |
| 115 | <li>Added deferred start for off-screen pages to improve performance.</li> |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 116 | </ul> |
Joe Fernandez | e4f2031 | 2011-12-15 13:23:53 -0800 | [diff] [blame] | 117 | </li> |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 118 | |
Joe Fernandez | e4f2031 | 2011-12-15 13:23:53 -0800 | [diff] [blame] | 119 | <li>Support for Accessiblity APIs: |
| 120 | <ul> |
| 121 | <li>Updated {@link android.support.v4.view.AccessibilityDelegateCompat} methods |
| 122 | to return empty lists instead of null.</li> |
| 123 | <li>Added new APIs needed by the v4 samples.</li> |
| 124 | </ul> |
| 125 | </li> |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 126 | |
Joe Fernandez | e4f2031 | 2011-12-15 13:23:53 -0800 | [diff] [blame] | 127 | </ul> |
| 128 | </dd> |
| 129 | </dl> |
| 130 | </div> |
| 131 | |
| 132 | <div class="toggle-content closed"> |
| 133 | |
| 134 | <p><a href="#" onclick="return toggleContent(this)"> |
| 135 | <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" /> |
| 136 | Support Package, revision 5 (December 2011) |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 137 | </a></p> |
| 138 | |
| 139 | <div class="toggle-content-toggleme" style="padding-left:2em"> |
| 140 | <dl> |
| 141 | <dt>Changes for v4 support library:</dt> |
| 142 | <dd> |
| 143 | <ul> |
| 144 | <li>Support for Accessiblity APIs: |
| 145 | <ul> |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 146 | <li>Added {@link android.support.v4.view.AccessibilityDelegateCompat} |
| 147 | to support {@link android.view.View.AccessibilityDelegate}.</li> |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 148 | |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 149 | <li>Added {@link android.support.v4.view.accessibility.AccessibilityEventCompat} |
| 150 | to support {@link android.view.accessibility.AccessibilityEvent}.</li> |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 151 | |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 152 | <li>Added {@link android.support.v4.view.accessibility.AccessibilityManagerCompat} |
| 153 | to support {@link android.view.accessibility.AccessibilityManager}.</li> |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 154 | |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 155 | <li>Added {@link android.support.v4.view.accessibility.AccessibilityNodeInfoCompat} |
| 156 | to support {@link android.view.accessibility.AccessibilityNodeInfo}.</li> |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 157 | |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 158 | <li>Added {@link android.support.v4.view.accessibility.AccessibilityRecordCompat} |
| 159 | to support {@link android.view.accessibility.AccessibilityRecord}.</li> |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 160 | |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 161 | <li>Added {@link |
| 162 | android.support.v4.accessibilityservice.AccessibilityServiceInfoCompat} |
| 163 | to support {@link android.accessibilityservice.AccessibilityServiceInfo}.</li> |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 164 | |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 165 | <li>Added {@link android.support.v4.view.ViewGroupCompat} |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 166 | to support accessibility features in {@link android.view.ViewGroup}. |
| 167 | </li> |
| 168 | |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 169 | <li>Modified {@link android.support.v4.view.ViewCompat} |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 170 | to support accessibility features in {@link android.view.View}.</li> |
| 171 | </ul> |
| 172 | </li> |
| 173 | |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 174 | <li>Changes to ViewPager: |
Joe Fernandez | e4f2031 | 2011-12-15 13:23:53 -0800 | [diff] [blame] | 175 | <ul> |
| 176 | <li>Added support for margins between pages. |
| 177 | An optional {@link android.graphics.drawable.Drawable} can be provided |
| 178 | to fill the margins.</li> |
| 179 | <li>Added support for {@link android.widget.EdgeEffect}.</li> |
| 180 | <li>Added support for keyboard navigation</li> |
| 181 | <li>Added support to control how many pages are kept to either side |
| 182 | of the current page.</li> |
| 183 | <li>Improved touch physics.</li> |
| 184 | <li>Bug fixes for user interface behavior.</li> |
| 185 | </ul> |
| 186 | </li> |
| 187 | </ul> |
| 188 | </dd> |
| 189 | </dl> |
| 190 | </div> |
| 191 | |
| 192 | <div class="toggle-content closed"> |
| 193 | |
| 194 | <p><a href="#" onclick="return toggleContent(this)"> |
| 195 | <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" /> |
| 196 | Support Package, revision 4 (October 2011) |
| 197 | </a></p> |
| 198 | |
| 199 | <div class="toggle-content-toggleme" style="padding-left:2em"> |
| 200 | <dl> |
| 201 | <dt>Changes for v4 support library:</dt> |
| 202 | <dd> |
| 203 | <ul> |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 204 | <li>Added <code>EdgeEffectCompat</code> to |
| 205 | support {@link android.widget.EdgeEffect}.</li> |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 206 | |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 207 | <li>Added <code>LocalBroadcastManager</code> to allow applications to easily |
| 208 | register for and receive intents within a single application without |
| 209 | broadcasting them globally.</li> |
| 210 | |
| 211 | <li>Added support in <code>ViewCompat</code> to check for and set overscroll |
| 212 | modes for {@link android.view.View}s on Android 2.3 and later.</li> |
| 213 | <li>Changes to Fragment APIs: |
| 214 | <ul> |
| 215 | <li>Added new APIs to control the visibility of new menus.</li> |
| 216 | <li>Added custom animation APIs.</li> |
| 217 | <li>Added APIs in <code>FragmentActivity</code> to retain custom, |
| 218 | non-configuration instance data.</li> |
| 219 | <li>Various bug fixes.</li> |
| 220 | </ul> |
| 221 | </li> |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 222 | |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 223 | <li>Fixed a {@link android.content.Loader} bug that caused issues in |
| 224 | canceling {@link android.os.AsyncTask}s when running on Froyo and older |
| 225 | versions of the platform. The support |
| 226 | code now uses its own version of {@link android.os.AsyncTask} to keep the same |
| 227 | behavior on all platform versions.</li> |
| 228 | |
| 229 | </ul> |
| 230 | </dd> |
| 231 | </dl> |
| 232 | </div> |
| 233 | |
| 234 | |
| 235 | |
| 236 | </div> |
| 237 | |
| 238 | |
| 239 | <div class="toggle-content closed"> |
| 240 | |
| 241 | <p><a href="#" onclick="return toggleContent(this)"> |
| 242 | <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" /> |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 243 | Compatibility Package, revision 3 (July 2011) |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 244 | </a></p> |
| 245 | |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 246 | <div class="toggle-content-toggleme" style="padding-left:2em"> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 247 | <dl> |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 248 | <dt>Changes for v4 support library:</dt> |
| 249 | <dd> |
| 250 | <ul> |
| 251 | <li>Adds support for {@link android.app.Fragment.SavedState}</li> |
| 252 | <li>Adds {@code MotionEventCompat} to support newer {@link |
| 253 | android.view.MotionEvent} APIs</li> |
| 254 | <li>Adds {@code VelocityTrackerCompat} to support a newer {@link |
| 255 | android.view.VelocityTracker} APIs</li> |
| 256 | <li>Adds {@code ViewConfigurationCompat} to support a newer {@link |
| 257 | android.view.ViewConfiguration} APIs</li> |
| 258 | <li>All new APIs (available only in the support library) that allow you to create UIs |
Scott Main | ffcbe48 | 2011-07-15 09:50:49 -0700 | [diff] [blame] | 259 | with horizontal paging, allowing users to swipe left and right between content views. Classes to |
| 260 | support this include: |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 261 | <ul> |
| 262 | <li>{@code ViewPager}: A {@link android.view.ViewGroup} that manages the |
| 263 | layout for the child views, which the user can swipe between.</li> |
| 264 | <li>{@code PagerAdapter}: An adapter that populates the {@code ViewPager} with the |
| 265 | views that represent each page.</li> |
| 266 | <li>{@code FragmentPagerAdapter}: An extension of {@code PagerAdapter} for flipping |
| 267 | between fragments.</li> |
Scott Main | ffcbe48 | 2011-07-15 09:50:49 -0700 | [diff] [blame] | 268 | <li>{@code FragmentStatePagerAdapter}: An extension of {@code PagerAdapter} for |
| 269 | flipping between fragments that uses the library's support for {@link |
| 270 | android.app.Fragment.SavedState}.</li> |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 271 | </ul> |
| 272 | </li> |
| 273 | </ul> |
| 274 | </dd> |
| 275 | <dt>New v13 support library:</dt> |
| 276 | <dd> |
| 277 | <ul> |
| 278 | <li>Includes the {@code FragmentPagerAdapter} and {@code FragmentStatePagerAdapter} |
| 279 | to support the horizontal paging. |
| 280 | <p>These are exactly the same as the APIs added to the v4 support library, but rely on |
| 281 | other platform components in Android 3.2. Use this library instead of v4 if you're developing for |
| 282 | Android 3.2 and higher (all other APIs in the v4 library are already available with API level |
| 283 | 13).</p> |
| 284 | </li> |
| 285 | </ul> |
| 286 | </dd> |
| 287 | </dl> |
| 288 | </div> |
| 289 | |
| 290 | </div> |
| 291 | |
| 292 | |
| 293 | <div class="toggle-content closed"> |
| 294 | |
| 295 | <p><a href="#" onclick="return toggleContent(this)"> |
| 296 | <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" /> |
| 297 | Compatibility Package, revision 2 (May 2011) |
| 298 | </a></p> |
| 299 | |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 300 | <div class="toggle-content-toggleme" style="padding-left:2em"> |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 301 | <dl> |
| 302 | <dt>Changes for v4 library:</dt> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 303 | <dd> |
| 304 | <ul> |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 305 | <li>Support for fragment animations</li> |
Joe Fernandez | e4f2031 | 2011-12-15 13:23:53 -0800 | [diff] [blame] | 306 | <li>Fix {@code android.support.v4.app.Fragment#onActivityResult Fragment.onActivityResult()} |
| 307 | bug</li> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 308 | </ul> |
| 309 | </dd> |
| 310 | </dl> |
| 311 | </div> |
| 312 | |
| 313 | </div> |
| 314 | |
| 315 | |
| 316 | <div class="toggle-content closed"> |
| 317 | |
| 318 | <p><a href="#" onclick="return toggleContent(this)"> |
| 319 | <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" /> |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 320 | Compatibility Package, revision 1 (March 2011) |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 321 | </a></p> |
| 322 | |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 323 | <div class="toggle-content-toggleme" style="padding-left:2em"> |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 324 | <p>Initial release with the v4 library.</p> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 325 | </div> |
| 326 | |
| 327 | </div> |
| 328 | |
| 329 | |
| 330 | |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 331 | <h2 id="Downloading">Downloading the Support Package</h2> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 332 | |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 333 | <p>The Support Package is provided as a downloadable package from the Android SDK and AVD |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 334 | Manager. To install:</p> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 335 | |
| 336 | <ol> |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 337 | <li>Launch the SDK and AVD Manager. |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 338 | <p>From Eclipse, you can select <strong>Window</strong> |
| 339 | > <strong>Android SDK and AVD Manager</strong>. Or, launch {@code SDK Manager.exe} from |
| 340 | the {@code <sdk>/} directory (on Windows only) or {@code android} from the {@code |
| 341 | <sdk>/tools/} directory.</p></li> |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 342 | <li>Expand the Android Repository, check <strong>Android Support package</strong> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 343 | and click <strong>Install selected</strong>.</li> |
| 344 | <li>Proceed to install the package.</li> |
| 345 | </ol> |
| 346 | |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 347 | <p>When done, all files (including source code, samples, and the {@code .jar} files) are saved |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 348 | into the <code><sdk>/extras/android/support/</code> directory. This directory contains |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 349 | each of the different support libraries, such as the library for API level 4 and up and the library |
| 350 | for API level 13 and up, each named with the respective version (such as {@code v4/}).</p> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 351 | |
| 352 | |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 353 | <h2 id="SettingUp">Setting Up a Project to Use a Library</h2> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 354 | |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 355 | <p>To add one of the libraries to your Android project:</p> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 356 | <ol> |
| 357 | <li>In your Android project, create a directory named {@code libs} at the root of your |
| 358 | project (next to {@code src/}, {@code res/}, etc.)</li> |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 359 | <li>Locate the JAR file for the library you want to use and copy it into the {@code |
| 360 | libs/} directory. |
| 361 | <p>For example, the library that supports API level 4 and up is located at {@code |
Robert Ly | 8db858f | 2011-10-18 13:30:47 -0700 | [diff] [blame] | 362 | <sdk>/extras/android/support/v4/android-support-v4.jar}.</p> |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 363 | </li> |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 364 | <li>Add the JAR to your project build path. |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 365 | <p>In Eclipse, right-click the JAR file in the Package Explorer, select <strong>Build |
Joe Fernandez | e4f2031 | 2011-12-15 13:23:53 -0800 | [diff] [blame] | 366 | Path</strong> > <strong>Add to Build Path</strong>.</p> |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 367 | </li> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 368 | </ol> |
| 369 | |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 370 | <p>Your application is now ready to use the library APIs. All the |
| 371 | provided APIs are available in the {@code android.support} package (for |
| 372 | example, {@code android.support.v4}).</p> |
| 373 | |
| 374 | <p class="note"><strong>Tip:</strong> To see the library APIs in action, take a look at the sample |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 375 | apps in {@code <sdk>/extras/android/support/<version>/samples/}.</p> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 376 | |
| 377 | <p class="warning"><strong>Warning:</strong> Be certain that you not confuse the standard |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 378 | {@code android} packages with those in {@code android.support} library. Some code completion tools |
| 379 | might |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 380 | get this wrong, especially if you're building against recent versions of the platform. To be safe, |
| 381 | keep your build target set to the same version as you have defined for your <a |
| 382 | href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 383 | and double check the import statements for classes that also exist in the support library, such as |
| 384 | {@code SimpleCursorAdapter}.</p> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 385 | |
| 386 | |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 387 | <h2 id="Using">Using the v4 Library APIs</h2> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 388 | |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 389 | <p>The support library for v4 provides access to several classes introduced with Android 3.0 and |
| 390 | beyond, plus some updated version of existing classes, and even some APIs that currently don't |
| 391 | exist in the Android platform. Some of the most useful and notable classes that have |
| 392 | counterparts in the v4 support library are:</p> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 393 | |
| 394 | <ul> |
| 395 | <li>{@link android.app.Fragment}</li> |
| 396 | <li>{@link android.app.FragmentManager}</li> |
| 397 | <li>{@link android.app.FragmentTransaction}</li> |
| 398 | <li>{@link android.app.ListFragment}</li> |
| 399 | <li>{@link android.app.DialogFragment}</li> |
| 400 | <li>{@link android.app.LoaderManager}</li> |
| 401 | <li>{@link android.content.Loader}</li> |
| 402 | <li>{@link android.content.AsyncTaskLoader}</li> |
| 403 | <li>{@link android.content.CursorLoader}</li> |
| 404 | </ul> |
| 405 | |
| 406 | <p>For each of the classes above (and others not listed), the APIs work almost exactly the same |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 407 | as the counterparts in the latest Android platform. Thus, you can usually refer to |
| 408 | the online documentation for information about the supported APIs. There are some |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 409 | differences, however. Most notably:</p> |
| 410 | |
| 411 | <ul> |
| 412 | <li>When creating an activity to use fragments, you must declare your activity to extend the |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 413 | {@link android.support.v4.app.FragmentActivity} class (instead of the traditional |
| 414 | {@link android.app.Activity} class).</li> |
| 415 | <li>To manage your fragments and loaders, you must use the methods |
| 416 | {@link android.support.v4.app.FragmentActivity#getSupportFragmentManager |
| 417 | FragmentActivity.getSupportFragmentManager()} and |
| 418 | {@link android.support.v4.app.FragmentActivity#getSupportLoaderManager |
| 419 | FragmentActivity.getSupportLoaderManager()} (instead of the |
| 420 | {@link android.app.Activity#getFragmentManager()} and |
| 421 | {@link android.app.Activity#getLoaderManager()} methods).</li> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 422 | <li>The {@link android.app.ActionBar} is <strong>not supported</strong> by the library. |
| 423 | However, when creating your <a href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options |
| 424 | Menu</a>, you can declare which items should be added to the Action Bar when it's available (on |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 425 | Android 3.0 or later). You can do so with the |
| 426 | {@link android.support.v4.view.MenuCompat#setShowAsAction MenuCompat.setShowAsAction()} method, for |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 427 | example: |
| 428 | <pre> |
| 429 | public boolean onCreateOptionsMenu(Menu menu) { |
| 430 | MenuInflater inflater = getMenuInflater(); |
| 431 | inflater.inflate(R.menu.options, menu); |
| 432 | MenuCompat.setShowAsAction(menu.findItem(R.id.action_search), 1); |
| 433 | return true; |
| 434 | } |
| 435 | </pre> |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 436 | <p>Also see the <a href="{@docRoot}resources/samples/ActionBarCompat/index.html">Action Bar |
| 437 | Compatibility</a> sample for a demonstration of how to use {@link android.app.ActionBar} on Android |
| 438 | 3.0+ and also support action bar functionality on older versions.</p> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 439 | </li> |
| 440 | </ul> |
| 441 | |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 442 | <div class="note"><p><strong>Tip:</strong> To enable the Holographic theme on devices |
| 443 | running Android 3.0 or higher, declare in your manifest file that your application targets |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 444 | API level 11, for example:</p> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 445 | <pre> |
| 446 | <uses-sdk android:minSdkVersion="4" android:targetSdkVersion="11" /> |
| 447 | </pre> |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 448 | <p>This way, your application automatically receives the Holographic theme and the Action Bar for |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 449 | each activity when running on Android 3.0 and higher.</p> |
| 450 | </div> |
| 451 | |
| 452 | <p>For more information about how you can optimize your application for the latest |
| 453 | Android-powered devices, read <a href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing |
| 454 | Apps for Android 3.0</a>.</p> |
| 455 | |
| 456 | |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 457 | <h2 id="Docs">Reference Docs</h2> |
| 458 | |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 459 | <p>The reference documentation for the Support Packages is included as part of the Android |
| 460 | online developer documentation:</p> |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 461 | |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 462 | <ul> |
| 463 | <li><a href="{@docRoot}reference/android/support/v4/app/package-summary.html">Support Package |
| 464 | API 4 Reference</a></li> |
| 465 | <li><a href="{@docRoot}reference/android/support/v13/app/package-summary.html">Support Package |
| 466 | API 13 Reference</a></li> |
| 467 | </ul> |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 468 | |
| 469 | |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 470 | <h2 id="Samples">Samples</h2> |
| 471 | |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 472 | <p>If you want to see some code that uses the support libraries, samples are included with the |
Joe Fernandez | 71d5c1d | 2011-12-15 22:33:41 -0800 | [diff] [blame] | 473 | Support Package, inside each support library directory, for example; {@code |
| 474 | <sdk>/extras/android/support/v4/samples/}. You can also view these samples as part of the |
| 475 | Android online developer documentation:</p> |
| 476 | |
| 477 | <ul> |
| 478 | <li><a href="{@docRoot}resources/samples/Support4Demos/index.html">Support API 4 Demos</a></li> |
| 479 | <li><a href="{@docRoot}resources/samples/Support13Demos/index.html">Support API 13 Demos</a></li> |
| 480 | </ul> |
Scott Main | 28fb09e | 2011-05-23 17:27:17 -0700 | [diff] [blame] | 481 | |
| 482 | <p>Additionally, the <a href="http://code.google.com/p/iosched/">Google I/O App</a> is a complete |
Scott Main | aecaf93 | 2011-07-14 10:01:42 -0700 | [diff] [blame] | 483 | application that uses the v4 support library to provide a single APK for both handsets and tablets |
| 484 | and also demonstrates some of Android's best practices in Android UI design.</p> |