1page.title=Support Library 2 3@jd:body 4 5<div id="qv-wrapper"> 6<div id="qv"> 7 8<h2>In this document</h2> 9<ol> 10 <li><a href="#Notes">Revisions</a></li> 11 <li><a href="#Downloading">Downloading the Support Package</a></li> 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> 15 <li><a href="#Samples">Samples</a></li> 16</ol> 17 18<h2>See also</h2> 19<ol> 20 <li><a 21href="{@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 30<p>The Support Package includes static "support libraries" that you can add to your Android 31application in order to use APIs that are either not available for older platform versions or that 32offer "utility" APIs that aren't a part of the framework APIs. The goal is to simplify your 33development by offering more APIs that you can bundle with your application so you can 34worry less about platform versions.</p> 35 36<p class="note"><strong>Note:</strong> The Support Package includes more than one support 37library. Each one has a different <em>minimum API level</em>. For example, one library requires API 38level 4 or higher, while another requires API level 13 or higher (v13 is a superset of v4 and 39includes additional 40support classes to work with v13 APIs). The minimum version is indicated 41by the directory name, such as {@code v4/} and {@code v13/}.</p> 42 43 44<h2 id="Notes">Revisions</h2> 45 46<p>The sections below provide notes about successive releases of 47the Support Package, as denoted by revision number.</p> 48 49<div class="toggle-content opened"> 50 <p><a href="#" onclick="return toggleContent(this)"> 51 <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" alt="" 52/>Support Package, revision 13</a> <em>(May 2013)</em> 53 </p> 54 <div class="toggle-content-toggleme"> 55 <dl> 56 <dt>Changes for v4 support library:</dt> 57 <dd> 58 <ul> 59 <li>Added {@link android.support.v4.widget.DrawerLayout} for creating a 60 <a href="{@docRoot}training/implementing-navigation/nav-drawer.html">Navigation 61 Drawer</a> that can be pulled in from the edge of a window.</li> 62 <li>Added {@link android.support.v4.widget.SlidingPaneLayout} widget for creating linked 63 summary and detail views that appropriately adapt to various screen sizes.</li> 64 <li>Added {@link android.support.v4.app.ActionBarDrawerToggle} as a way to tie 65 together the functions of {@link android.support.v4.widget.DrawerLayout} and {@link 66 android.app.ActionBar}.</li> 67 <li>Added {@link android.support.v4.widget.ViewDragHelper} as a new common component 68 for dragging views within a parent view.</li> 69 <li>Added {@link android.support.v4.widget.ScrollerCompat} to provide {@link 70 android.widget.Scroller} and {@link android.widget.OverScroller} compatibility support. 71 </li> 72 <li>Added {@link android.support.v4.content.FileProvider} to allow sharing of private 73 files between applications.</li> 74 <li>Updated {@link android.support.v4.view.ViewPager} to throw an exception if the 75 associated {@link android.support.v4.view.PagerAdapter} class is modified without a call 76 to {@link android.support.v4.view.PagerAdapter#notifyDataSetChanged notifyDataSetChanged()}. 77 </li> 78 <li>Fixed an issue with {@link android.support.v4.view.ViewPager} children drawing sort 79 order.</li> 80 <li>Fixed {@link android.support.v4.view.GestureDetectorCompat} to dispatch missing 81 {@link android.view.GestureDetector.SimpleOnGestureListener#onSingleTapConfirmed} calls 82 between tap timeout and long press events.</li> 83 </ul> 84 </dd> 85 </dl> 86 </div> 87</div> 88 89 90<div class="toggle-content closed"> 91 <p><a href="#" onclick="return toggleContent(this)"> 92 <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" 93/>Support Package, revision 12</a> <em>(February 2013)</em> 94 </p> 95 <div class="toggle-content-toggleme"> 96 <dl> 97 <dt>Changes for v4 support library:</dt> 98 <dd> 99 <ul> 100 <li>Improved interaction behavior for {@link android.support.v4.view.ViewPager}.</li> 101 <li>Fixed a bug that could cause {@link android.support.v4.view.ViewPager} to select the 102 wrong page.</li> 103 <li>Fixed use of {@link android.support.v4.view.ViewPager#removeView removeView()} method 104 during layout for {@link android.support.v4.view.ViewPager}.</li> 105 <li>Fixed issue with {@link android.support.v4.widget.SearchViewCompat} where using the 106 back button to dismiss does not clear the search text. This fix only applies to 107 host API levels 14 and higher.</li> 108 </ul> 109 </dd> 110 </dl> 111 </div> 112</div> 113 114<div class="toggle-content closed"> 115 <p><a href="#" onclick="return toggleContent(this)"> 116 <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" 117/>Support Package, revision 11</a> <em>(November 2012)</em> 118 </p> 119 <div class="toggle-content-toggleme"> 120 <dl> 121 <dt>Changes for v4 support library:</dt> 122 <dd> 123 <ul> 124 <li>User Interface 125 <ul> 126 <li>Added support for nested {@link android.support.v4.app.Fragment} classes.</li> 127 <li>Added improvements to {@link android.support.v4.app.FragmentManager} debugging. 128 </li> 129 <li>Fixed problem in {@link android.support.v4.app.FragmentTabHost} where fragment 130 and tab interaction could result in a {@link android.widget.ListView} state loss. 131 </li> 132 <li>Fixed issue with user-visible hint in 133 {@link android.support.v4.app.FragmentStatePagerAdapter}.</li> 134 <li>Added {@link android.support.v4.view.ViewPager.PageTransformer PageTransformer} 135 interface to {@link android.support.v4.view.ViewPager} to allow applications to 136 supply a custom transition behavior for scrolling.</li> 137 <li>Added new features and fixes to {@link android.support.v4.app.TaskStackBuilder} 138 from current release.</li> 139 <li>Fixed {@link android.support.v4.view.PagerTitleStrip} to correctly track the 140 {@link android.support.v4.view.PagerAdapter} currently in use.</li> 141 <li>Fixed display flickering, positioning, and text clipping problems with 142 {@link android.support.v4.view.PagerTitleStrip}.</li> 143 <li>Fixed {@link android.support.v4.view.PagerTabStrip} to properly respect padding 144 when drawing an underline.</li> 145 </ul> 146 </li> 147 <li>Accessibility 148 <ul> 149 <li>Added support for new accessibility gesture and touch event types in 150 {@link android.support.v4.view.accessibility.AccessibilityEventCompat}.</li> 151 <li>Added support for new accessibility APIs in 152 {@link android.support.v4.view.ViewCompat}.</li> 153 <li>Added support for {@link android.support.v4.view.ViewCompat#performAccessibilityAction 154 performAccessibilityAction()} method to {@link android.support.v4.view.ViewCompat}. 155 </li> 156 </ul> 157 </li> 158 <li>Added support for gestures with {@link android.support.v4.view.GestureDetectorCompat}. 159 </li> 160 <li>Added support for performing atomic operations on files using a new 161 {@link android.support.v4.util.AtomicFile} class.</li> 162 <li>Added support for the full set of {@code make} methods in 163 {@link android.support.v4.content.IntentCompat}.</li> 164 <li>Added {@link android.support.v4.util.LruCache#trimToSize trimToSize()} method in 165 {@link android.support.v4.util.LruCache} utility class.</li> 166 <li>Updated {@link android.support.v4.net.ConnectivityManagerCompat} to get NetworkInfo 167 from a {@link android.net.ConnectivityManager#CONNECTIVITY_ACTION} 168 broadcast.</li> 169 </ul> 170 </dd> 171 </dl> 172 </div> 173</div> 174 175 176<div class="toggle-content closed"> 177 <p><a href="#" onclick="return toggleContent(this)"> 178 <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" 179/>Support Package, revision 10</a> <em>(August 2012)</em> 180 </p> 181 <div class="toggle-content-toggleme"> 182 <dl> 183 <dt>Changes for v4 support library:</dt> 184 <dd> 185 <ul> 186 <li>Added support for notification features introduced in Android 4.1 (API level 16) with 187 additions to {@link android.support.v4.app.NotificationCompat}.</li> 188 </ul> 189 </dd> 190 </dl> 191 </div> 192</div> 193 194 195<div class="toggle-content closed"> 196 <p><a href="#" onclick="return toggleContent(this)"> 197 <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" 198/>Support Package, revision 9</a> <em>(June 2012)</em> 199 </p> 200 <div class="toggle-content-toggleme"> 201 <dl> 202 <dt>Changes for v4 support library:</dt> 203 <dd> 204 <ul> 205 206 <li>User Interface Support 207 <ul> 208 <li>Added {@link android.support.v4.view.PagerTabStrip} support, providing enhanced 209functionality beyond {@link android.support.v4.view.PagerTitleStrip}.</li> 210 <li>Fixed various bugs for {@link android.support.v4.view.PagerTitleStrip} and 211{@link android.support.v4.view.PagerTabStrip}, including {@link 212android.widget.TextView#setAllCaps setAllCaps} option, title alignment, 213appearance improvements, minimum width constraints and touch navigation issues.</li> 214 <li>Added support for {@link android.support.v4.view.ViewPager} page gutters, which 215helps the {@link android.support.v4.view.ViewPager} class provide paging support for content with 216a large horizontal scroll range, such as a map.</li> 217 <li>Fixed numerous bugs for {@link android.support.v4.view.ViewPager}, including size 218and data set change problems, page positioning, user interaction, scroll tracking and keyboard 219navigation problems.</li> 220 <li>Fixed many bugs for {@link android.support.v4.app.Fragment}, including proper 221handling of {@link android.support.v4.app.Fragment#onActivityResult onActivityResult()} when 222the target fragment no longer exists, dispatching selection events to invisible fragments, improved 223{@link android.support.v4.app.FragmentTransaction#replace FragmentTransaction.replace()} behavior 224and added better state handling for fragments being moved out of view.</li> 225 <li>Added support for the {@link 226android.support.v4.view.ViewCompat postOnAnimation()} method in {@link 227android.support.v4.view.ViewCompat}.</li> 228 <li>Updated {@link android.support.v4.app.NavUtils} to use Android 4.1 (API level 16) 229<em>Up</em> navigation functionality when available.</li> 230 </ul> 231 </li> 232 233 <li>Accessibility 234 <ul> 235 <li>Updated accessibility support classes, including {@link 236android.support.v4.view.accessibility.AccessibilityNodeInfoCompat}, to follow fixes made in Android 2374.1 (API level 16).</li> 238 <li>Added support for accessibility scroll actions in {@link 239android.support.v4.view.ViewPager}.</li> 240 </ul> 241 </li> 242 243 <li>General improvements 244 <ul> 245 <li>Updated {@link android.support.v4.app.TaskStackBuilder} to reflect API changes in 246Android 4.1 (API level 16).</li> 247 <li>Enhanced {@link android.support.v4.app.TaskStackBuilder} to allow it to be used 248from a Service.</li> 249 <li>Added support for {@link android.support.v4.content.IntentCompat EXTRA_HTML_TEXT} 250to {@link android.support.v4.app.ShareCompat}.</li> 251 <li>Updated {@link android.support.v4.app.NotificationCompat.Builder} to support the 252{@link android.support.v4.app.NotificationCompat.Builder#setNumber setNumber()} method.</li> 253 <li>Added support in {@link android.support.v4.net.ConnectivityManagerCompat} for the 254{@link android.support.v4.net.ConnectivityManagerCompat#isActiveNetworkMetered 255isActiveNetworkMetered()} method.</li> 256 </ul> 257 </li> 258 </ul> 259 </dd> 260 </dl> 261 </div> 262</div> 263 264<div class="toggle-content closed"> 265 <p><a href="#" onclick="return toggleContent(this)"> 266 <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" 267/>Support Package, revision 8</a> <em>(April 2012)</em> 268 </p> 269 <div class="toggle-content-toggleme"> 270 <dl> 271 <dt>Changes for v4 support library:</dt> 272 <dd> 273 <ul> 274 <li>Fixed intent flags for {@link android.app.PendingIntent} objects generated 275 by {@link android.support.v4.app.TaskStackBuilder}.</li> 276 <li>Removed unused attributes from the gridlayout library projects to make sure 277 the library can be built with API level 7 and higher.</li> 278 <li>Added {@code .classpath} and {@code .project} files for the gridlayout 279 library project.</li> 280 </ul> 281 </dd> 282 </dl> 283 </div> 284</div> 285 286<div class="toggle-content closed"> 287 <p><a href="#" onclick="return toggleContent(this)"> 288 <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" 289/>Support Package, revision 7</a> <em>(March 2012)</em> 290 </p> 291 <div class="toggle-content-toggleme"> 292 <dl> 293 <dt>Changes for v4 support library:</dt> 294 <dd> 295 <ul> 296 <li>Added {@link android.support.v4.app.ShareCompat}, which provides helper classes 297for sending and receiving content for social sharing applications, including new metadata for 298attributing shared data to the source app. This class also provides compatible integration with the 299new {@link android.widget.ShareActionProvider} in Android 4.0.</li> 300 <li>Added {@link android.support.v4.app.NavUtils} and {@link 301android.support.v4.app.TaskStackBuilder} to provide support for implementing the 302<a href="{@docRoot}design/index.html">Android Design</a> guidelines for navigation. These 303additions include a way to implement the action bar's <em>Up</em> button across versions. 304For an example implementation of this pattern, see the AppNavigation sample in 305({@code <em><sdk></em>/samples/<em><platform></em>/AppNavigation}).</li> 306 <li>Added {@link android.support.v4.app.NotificationCompat.Builder} to provide a 307compatibility implementation of Android 3.0's {@link android.app.Notification.Builder} helper class 308for creating standardized system notifications.</li> 309 </ul> 310 </dd> 311 </dl> 312 </div> 313</div> 314 315<div class="toggle-content closed"> 316 <p><a href="#" onclick="return toggleContent(this)"> 317 <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" 318/>Support Package, revision 6</a> <em>(December 2011)</em> 319 </p> 320 <div class="toggle-content-toggleme"> 321 322 <p class="note"><strong>Note:</strong> Reference for support library APIs are now available with 323 the framework references, for example: {@link android.support.v4.app}.</p> 324<dl> 325 <dt>Changes for v4 support library:</dt> 326 <dd> 327 <ul> 328 <li>Changes to ViewPager: 329 <ul> 330 <li>Added extra decorative view support for {@link android.support.v4.view.ViewPager}. 331 Decorative views may be supplied as child views of a pager in XML layout.</li> 332 <li>Added {@link android.support.v4.view.PagerAdapter#getPageTitle 333 PagerAdapter.getPageTitle()} to supply title strings for pages, which defaults to no 334 title for each page.</li> 335 <li>Added {@link android.support.v4.view.PagerTitleStrip}, a non-interactive title 336 strip, that can be added as a child of ViewPager. Developers can supply text 337 appearance and color, as well as layout sizing and gravity information.</li> 338 <li>Updated {@link android.support.v4.view.PagerAdapter} methods to take ViewGroup 339 objects, rather than View to avoid class casting in adapter implementations.</li> 340 <li>Updated {@link android.support.v4.view.ViewPager} to use Launcher-style 341 fling behavior.</li> 342 <li>Bug fixes for user interface interaction and test automation.</li> 343 </ul> 344 </li> 345 346 <li>Support for Fragments: 347 <ul> 348 <li>Changed {@code setStartDeferred()} method to {@link 349 android.support.v4.app.Fragment#setUserVisibleHint}.</li> 350 <li>Added deferred start for off-screen pages to improve performance.</li> 351 </ul> 352 </li> 353 354 <li>Support for Accessiblity APIs: 355 <ul> 356 <li>Updated {@link android.support.v4.view.AccessibilityDelegateCompat} methods 357 to return empty lists instead of null.</li> 358 <li>Added new APIs needed by the v4 samples.</li> 359 </ul> 360 </li> 361 362 </ul> 363 </dd> 364 </dl> 365 </div> 366</div> 367 368<div class="toggle-content closed"> 369 <p><a href="#" onclick="return toggleContent(this)"> 370 <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" 371/>Support Package, revision 5</a> <em>(December 2011)</em> 372 </p> 373 <div class="toggle-content-toggleme"> 374 <dl> 375 <dt>Changes for v4 support library:</dt> 376 <dd> 377 <ul> 378 <li>Support for Accessiblity APIs: 379 <ul> 380 <li>Added {@link android.support.v4.view.AccessibilityDelegateCompat} 381 to support {@link android.view.View.AccessibilityDelegate}.</li> 382 383 <li>Added {@link android.support.v4.view.accessibility.AccessibilityEventCompat} 384 to support {@link android.view.accessibility.AccessibilityEvent}.</li> 385 386 <li>Added {@link android.support.v4.view.accessibility.AccessibilityManagerCompat} 387 to support {@link android.view.accessibility.AccessibilityManager}.</li> 388 389 <li>Added {@link android.support.v4.view.accessibility.AccessibilityNodeInfoCompat} 390 to support {@link android.view.accessibility.AccessibilityNodeInfo}.</li> 391 392 <li>Added {@link android.support.v4.view.accessibility.AccessibilityRecordCompat} 393 to support {@link android.view.accessibility.AccessibilityRecord}.</li> 394 395 <li>Added {@link 396 android.support.v4.accessibilityservice.AccessibilityServiceInfoCompat} 397 to support {@link android.accessibilityservice.AccessibilityServiceInfo}.</li> 398 399 <li>Added {@link android.support.v4.view.ViewGroupCompat} 400 to support accessibility features in {@link android.view.ViewGroup}. 401 </li> 402 403 <li>Modified {@link android.support.v4.view.ViewCompat} 404 to support accessibility features in {@link android.view.View}.</li> 405 </ul> 406 </li> 407 408 <li>Changes to ViewPager: 409 <ul> 410 <li>Added support for margins between pages. 411 An optional {@link android.graphics.drawable.Drawable} can be provided 412 to fill the margins.</li> 413 <li>Added support for {@link android.widget.EdgeEffect}.</li> 414 <li>Added support for keyboard navigation</li> 415 <li>Added support to control how many pages are kept to either side 416 of the current page.</li> 417 <li>Improved touch physics.</li> 418 <li>Bug fixes for user interface behavior.</li> 419 </ul> 420 </li> 421 </ul> 422 </dd> 423 </dl> 424 </div> 425</div> 426 427<div class="toggle-content closed"> 428 <p><a href="#" onclick="return toggleContent(this)"> 429 <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" 430/>Support Package, revision 4</a> <em>(October 2011)</em> 431 </p> 432 <div class="toggle-content-toggleme"> 433 <dl> 434 <dt>Changes for v4 support library:</dt> 435 <dd> 436 <ul> 437 <li>Added <code>EdgeEffectCompat</code> to 438 support {@link android.widget.EdgeEffect}.</li> 439 440 <li>Added <code>LocalBroadcastManager</code> to allow applications to easily 441 register for and receive intents within a single application without 442 broadcasting them globally.</li> 443 444 <li>Added support in <code>ViewCompat</code> to check for and set overscroll 445 modes for {@link android.view.View}s on Android 2.3 and later.</li> 446 <li>Changes to Fragment APIs: 447 <ul> 448 <li>Added new APIs to control the visibility of new menus.</li> 449 <li>Added custom animation APIs.</li> 450 <li>Added APIs in <code>FragmentActivity</code> to retain custom, 451 non-configuration instance data.</li> 452 <li>Various bug fixes.</li> 453 </ul> 454 </li> 455 456 <li>Fixed a {@link android.content.Loader} bug that caused issues in 457 canceling {@link android.os.AsyncTask}s when running on Froyo and older 458 versions of the platform. The support 459 code now uses its own version of {@link android.os.AsyncTask} to keep the same 460 behavior on all platform versions.</li> 461 462 </ul> 463 </dd> 464 </dl> 465 </div> 466</div> 467 468 469<div class="toggle-content closed"> 470 <p><a href="#" onclick="return toggleContent(this)"> 471 <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" 472/>Compatibility Package, revision 3</a> <em>(July 2011)</em> 473 </p> 474 <div class="toggle-content-toggleme"> 475 <dl> 476 <dt>Changes for v4 support library:</dt> 477 <dd> 478 <ul> 479 <li>Adds support for {@link android.app.Fragment.SavedState}</li> 480 <li>Adds {@code MotionEventCompat} to support newer {@link 481android.view.MotionEvent} APIs</li> 482 <li>Adds {@code VelocityTrackerCompat} to support a newer {@link 483android.view.VelocityTracker} APIs</li> 484 <li>Adds {@code ViewConfigurationCompat} to support a newer {@link 485android.view.ViewConfiguration} APIs</li> 486 <li>All new APIs (available only in the support library) that allow you to create UIs 487with horizontal paging, allowing users to swipe left and right between content views. Classes to 488support this include: 489 <ul> 490 <li>{@code ViewPager}: A {@link android.view.ViewGroup} that manages the 491layout for the child views, which the user can swipe between.</li> 492 <li>{@code PagerAdapter}: An adapter that populates the {@code ViewPager} with the 493views that represent each page.</li> 494 <li>{@code FragmentPagerAdapter}: An extension of {@code PagerAdapter} for flipping 495between fragments.</li> 496 <li>{@code FragmentStatePagerAdapter}: An extension of {@code PagerAdapter} for 497flipping between fragments that uses the library's support for {@link 498android.app.Fragment.SavedState}.</li> 499 </ul> 500 </li> 501 </ul> 502 </dd> 503 <dt>New v13 support library:</dt> 504 <dd> 505 <ul> 506 <li>Includes the {@code FragmentPagerAdapter} and {@code FragmentStatePagerAdapter} 507to support the horizontal paging. 508 <p>These are exactly the same as the APIs added to the v4 support library, but rely on 509other platform components in Android 3.2. Use this library instead of v4 if you're developing for 510Android 3.2 and higher (all other APIs in the v4 library are already available with API level 51113).</p> 512 </li> 513 </ul> 514 </dd> 515 </dl> 516 </div> 517</div> 518 519 520<div class="toggle-content closed"> 521 <p><a href="#" onclick="return toggleContent(this)"> 522 <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" 523/>Compatibility Package, revision 2</a> <em>(May 2011)</em> 524 </p> 525 <div class="toggle-content-toggleme"> 526 <dl> 527 <dt>Changes for v4 library:</dt> 528 <dd> 529 <ul> 530 <li>Support for fragment animations</li> 531 <li>Fix {@code android.support.v4.app.Fragment#onActivityResult Fragment.onActivityResult()} 532 bug</li> 533 </ul> 534 </dd> 535 </dl> 536 </div> 537</div> 538 539 540<div class="toggle-content closed"> 541 <p><a href="#" onclick="return toggleContent(this)"> 542 <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" 543/>Compatibility Package, revision 1</a> <em>(March 2011)</em> 544 </p> 545 <div class="toggle-content-toggleme"> 546 <p>Initial release with the v4 library.</p> 547 </div> 548</div> 549 550 551 552<h2 id="Downloading">Downloading the Support Package</h2> 553 554<p>The Support Package is provided as a downloadable package from the Android SDK 555Manager. To install:</p> 556 557<ol> 558 <li>Launch the Android SDK Manager. 559 <p>From Eclipse, you can select <strong>Window</strong> 560> <strong>Android SDK Manager</strong>. Or, launch {@code SDK Manager.exe} from 561the {@code <sdk>/} directory (on Windows only) or {@code android} from the {@code 562<sdk>/tools/} directory.</p></li> 563 <li>Expand the Android Repository, check <strong>Android Support package</strong> 564and click <strong>Install selected</strong>.</li> 565 <li>Proceed to install the package.</li> 566</ol> 567 568<p>When done, all files (including source code, samples, and the JAR files) are saved 569into the <code><sdk>/extras/android/support/</code> directory. This directory contains 570each of the different support libraries, such as the library for API level 4 and up and the library 571for API level 13 and up, each named with the respective version (such as {@code v4/}).</p> 572 573 574<h2 id="SettingUp">Setting Up a Project to Use a Library</h2> 575 576<p>To add one of the libraries to your Android project:</p> 577<dl> 578 <dt> 579 Add the JAR file to your project. 580 </dt> 581 <dd> 582 Copy the JAR file for the library you want to use into your Android project. To do this: 583 <ul> 584 <li> 585 Create the directory {@code libs/} at the root of your project 586 (next to {@code src/}, {@code res/}, and so forth). 587 </li> 588 <li> 589 Locate the JAR file for the library you want to use and copy it into the 590 {@code libs/} directory. 591 <p> 592 For example, the library that supports API level 4 and up is located at 593 {@code <sdk>/extras/android/support/v4/android-support-v4.jar}. 594 </p> 595 </li> 596 </ul> 597 <p> 598 Your build system may expect to find the JAR file in a directory other than 599 {@code libs}. Read the documentation for your build system to learn where to put the 600 JAR file. 601 </p> 602 </dd> 603 <dt> 604 If necessary, add the {@code libs/} directory to your build path. 605 </dt> 606 <dd> 607 Read the documentation for your build system to learn how to add the JAR file to the 608 build path. 609 </dd> 610</dl> 611<p> 612 To confirm that you've added the JAR file to the correct directory and added it to the build 613 path: 614</p> 615<ol> 616 <li> 617 Edit one of your source files to add an {@code import} statement that imports a 618 class from the {@code android.support.*} package. 619 </li> 620 <li> 621 Build your app. The code should compile cleanly. 622 </li> 623 <li> 624 As a double-check, run your app. It should run correctly, without any runtime exceptions 625 indicating that the class in {@code android.support.*} can't be found. 626 </li> 627</ol> 628<p>Your application is now ready to use the library APIs. All the 629provided APIs are available in the {@code android.support} package (for 630example, {@code android.support.v4}).</p> 631 632<p class="note"><strong>Tip:</strong> To see the library APIs in action, take a look at the sample 633apps in {@code <sdk>/extras/android/support/<version>/samples/}.</p> 634 635<p class="warning"><strong>Warning:</strong> Be certain that you not confuse the standard 636{@code android} packages with those in {@code android.support} library. Some code completion tools 637might 638get this wrong, especially if you're building against recent versions of the platform. To be safe, 639keep your build target set to the same version as you have defined for your <a 640href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> 641and double check the import statements for classes that also exist in the support library, such as 642{@code SimpleCursorAdapter}.</p> 643 644 645<h2 id="Using">Using the v4 Library APIs</h2> 646 647<p>The support library for v4 provides access to several classes introduced with Android 3.0 and 648beyond, plus some updated version of existing classes, and even some APIs that currently don't 649exist in the Android platform. Some of the most useful and notable classes that have 650counterparts in the v4 support library are:</p> 651 652<ul> 653 <li>{@link android.app.Fragment}</li> 654 <li>{@link android.app.FragmentManager}</li> 655 <li>{@link android.app.FragmentTransaction}</li> 656 <li>{@link android.app.ListFragment}</li> 657 <li>{@link android.app.DialogFragment}</li> 658 <li>{@link android.app.LoaderManager}</li> 659 <li>{@link android.content.Loader}</li> 660 <li>{@link android.content.AsyncTaskLoader}</li> 661 <li>{@link android.content.CursorLoader}</li> 662</ul> 663 664<p>For each of the classes above (and others not listed), the APIs work almost exactly the same 665as the counterparts in the latest Android platform. Thus, you can usually refer to 666the online documentation for information about the supported APIs. There are some 667differences, however. Most notably:</p> 668 669<ul> 670 <li>When creating an activity to use fragments, you must declare your activity to extend the 671{@link android.support.v4.app.FragmentActivity} class (instead of the traditional 672{@link android.app.Activity} class).</li> 673 <li>To manage your fragments and loaders, you must use the methods 674 {@link android.support.v4.app.FragmentActivity#getSupportFragmentManager 675 FragmentActivity.getSupportFragmentManager()} and 676 {@link android.support.v4.app.FragmentActivity#getSupportLoaderManager 677 FragmentActivity.getSupportLoaderManager()} (instead of the 678 {@link android.app.Activity#getFragmentManager()} and 679 {@link android.app.Activity#getLoaderManager()} methods).</li> 680 <li>The {@link android.app.ActionBar} is <strong>not supported</strong> by the library. 681However, when creating your <a href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options 682Menu</a>, you can declare which items should be added to the Action Bar when it's available (on 683Android 3.0 or later). You can do so with the 684{@link android.support.v4.view.MenuCompat#setShowAsAction MenuCompat.setShowAsAction()} method, for 685example: 686<pre> 687public boolean onCreateOptionsMenu(Menu menu) { 688 MenuInflater inflater = getMenuInflater(); 689 inflater.inflate(R.menu.options, menu); 690 MenuCompat.setShowAsAction(menu.findItem(R.id.action_search), 1); 691 return true; 692} 693</pre> 694<p>Also see the <a href="{@docRoot}resources/samples/ActionBarCompat/index.html">Action Bar 695Compatibility</a> sample for a demonstration of how to use {@link android.app.ActionBar} on Android 6963.0+ and also support action bar functionality on older versions.</p> 697</li> 698</ul> 699 700<div class="note"><p><strong>Tip:</strong> To enable the Holographic theme on devices 701running Android 3.0 or higher, declare in your manifest file that your application targets 702API level 11, for example:</p> 703<pre> 704<uses-sdk android:minSdkVersion="4" android:targetSdkVersion="11" /> 705</pre> 706<p>This way, your application automatically receives the Holographic theme and the Action Bar for 707each activity when running on Android 3.0 and higher.</p> 708</div> 709 710<p>For more information about how you can optimize your application for the latest 711Android-powered devices, read <a href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing 712Apps for Android 3.0</a>.</p> 713 714 715<h2 id="Docs">Reference Docs</h2> 716 717<p>The reference documentation for the Support Packages is included as part of the Android 718online developer documentation:</p> 719 720<ul> 721 <li><a href="{@docRoot}reference/android/support/v4/app/package-summary.html">Support Package 722 API 4 Reference</a></li> 723 <li><a href="{@docRoot}reference/android/support/v13/app/package-summary.html">Support Package 724 API 13 Reference</a></li> 725</ul> 726 727 728<h2 id="Samples">Samples</h2> 729 730<p>If you want to see some code that uses the support libraries, samples are included with the 731Support Package, inside each support library directory, for example; {@code 732<sdk>/extras/android/support/v4/samples/}. You can also view these samples as part of the 733Android online developer documentation:</p> 734 735<ul> 736 <li><a href="{@docRoot}resources/samples/Support4Demos/index.html">Support API 4 Demos</a></li> 737 <li><a href="{@docRoot}resources/samples/Support13Demos/index.html">Support API 13 Demos</a></li> 738</ul> 739 740<p>Additionally, the <a href="http://code.google.com/p/iosched/">Google I/O App</a> is a complete 741application that uses the v4 support library to provide a single APK for both handsets and tablets 742and also demonstrates some of Android's best practices in Android UI design.</p> 743 744
