diff options
| author | 2013-07-24 06:13:38 +0000 | |
|---|---|---|
| committer | 2013-07-24 06:13:38 +0000 | |
| commit | 21a1df23cda2e08702a19f4fc9cd884da17997cc (patch) | |
| tree | 9e1bdee01fbcbd6f997df1d914333ebeb8cfe264 | |
| parent | b56cd2903e80adb9db64cc375be23e741048b964 (diff) | |
| parent | 5ffbba6455298593a59aeb98fafd0e0ede25b2c8 (diff) | |
Merge "docs: Support Library Guide" into jb-mr2-ub-dev
| -rw-r--r-- | docs/html/images/tools/sdk-manager-support-libs.png | bin | 0 -> 53798 bytes | |||
| -rw-r--r-- | docs/html/tools/support-library/features.jd | 249 | ||||
| -rw-r--r-- | docs/html/tools/support-library/index.jd (renamed from docs/html/tools/extras/support-library.jd) | 403 | ||||
| -rw-r--r-- | docs/html/tools/support-library/setup.jd | 308 | ||||
| -rw-r--r-- | docs/html/tools/tools_toc.cs | 35 |
5 files changed, 736 insertions, 259 deletions
diff --git a/docs/html/images/tools/sdk-manager-support-libs.png b/docs/html/images/tools/sdk-manager-support-libs.png Binary files differnew file mode 100644 index 000000000000..37968005c789 --- /dev/null +++ b/docs/html/images/tools/sdk-manager-support-libs.png diff --git a/docs/html/tools/support-library/features.jd b/docs/html/tools/support-library/features.jd new file mode 100644 index 000000000000..a749a3621444 --- /dev/null +++ b/docs/html/tools/support-library/features.jd @@ -0,0 +1,249 @@ +page.title=Support Library Features + +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#v4">v4 Support Library</a></li> + <li><a href="#v7">v7 Libraries</a> + <ol> + <li><a href="#v7-appcompat">v7 appcompat library</a></li> + <li><a href="#v7-gridlayout">v7 gridlayout library</a></li> + </ol> + </li> + <li><a href="#v13">v13 Support Library</a></li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}tools/support-library/index.html#revisions"> + Support Library Revisions</a></li> + <li><a href="{@docRoot}tools/support-library/setup.html"> + Support Library Setup</a></li> + </ol> + + </div> +</div> + +<p>The Android Support Library package contains several individual libraries that can be included + in your application. Each of these libraries supports a specific range of Android platform + versions and set of features.</p> + +<p>This guide explains the important features and version support provided by the Support + Libraries, to help you decide which of them you should include in your application. In general, + we recommend including the <a href="#v4">v4 support</a> and <a href="#v7-appcompat">v7 + appcompat</a> libraries in your application, because they support a wide range of + Android versions and provide APIs for recommended user interface patterns.</p> + +<p>In order to use any of the following libraries, you must download the library files to your + Android SDK installation. Follow the directions for downloading the Support Libraries in + <a href="{@docRoot}tools/support-library/setup.html#download">Support Library Setup</a> to + complete this step. You must take additional steps to include a specific Support Library in + your application. See the end of each library section below for instructions on how to include + the library in your application.</p> + + +<h2 id="v4">v4 Support Library</h2> + +<p>This library is designed to be used with Android 1.6 (API level 4) and higher. It includes the + largest set of APIs compared to the other packages, including support for application components, + user interface features, accessibility, data handling, network connectivity, and programming + utilities. Here are a few of the key classes included in the v4 package:</p> + +<ul> + <li>App Components + <ul> + <li>{@link android.support.v4.app.Fragment} + - Adds support encapsulation of user interface and functionality with Fragments, enabling + applications provide layouts that adjust between small and large-screen devices.</li> + </ul> + <ul> + <li>{@link android.support.v4.app.NotificationCompat} - Adds support for rich notification + features.</li> + </ul> + <ul> + <li>{@link android.support.v4.content.LocalBroadcastManager} - Allows applications to easily + register for and receive intents within a single application without broadcasting them + globally.</li> + </ul> + </li> + <li>User Interface + <ul> + <li>{@link android.support.v4.view.ViewPager} - Adds a + {@link android.view.ViewGroup} that manages the layout for the + child views, which the user can swipe between.</li> + <li>{@link android.support.v4.view.PagerTitleStrip} + - Adds a non-interactive title strip, that can be added as a child of + {@link android.support.v4.view.ViewPager}.</li> + <li>{@link android.support.v4.view.PagerTabStrip} - Adds a + navigation widget for switching between paged views, that can also be used with + {@link android.support.v4.view.ViewPager}.</li> + <li>{@link android.support.v4.widget.DrawerLayout} - Adds + support for creating a <a href="{@docRoot}training/implementing-navigation/nav-drawer.html" + >Navigation Drawer</a> that can be pulled in from the edge of a window.</li> + <li>{@link android.support.v4.widget.SlidingPaneLayout} + - Adds widget for creating linked summary and detail views that + appropriately adapt to various screen sizes.</li> + </ul> + </li> + <li>Accessibility + <ul> + <li>{@link android.support.v4.widget.ExploreByTouchHelper} + - Adds a helper class for implementing accessibility support for custom views.</li> + </ul> + <ul> + <li>{@link android.support.v4.view.accessibility.AccessibilityEventCompat} - Adds support for + {@link android.view.accessibility.AccessibilityEvent}. For more information about implementing + accessibility, see <a href="{@docRoot}guide/topics/ui/accessibility/index.html" + >Accessibility</a>.</li> + </ul> + <ul> + <li>{@link android.support.v4.view.accessibility.AccessibilityNodeInfoCompat} - Adds support + for {@link android.view.accessibility.AccessibilityNodeInfo}.</li> + </ul> + <ul> + <li>{@link android.support.v4.view.accessibility.AccessibilityNodeProviderCompat} - Adds + support for {@link android.view.accessibility.AccessibilityNodeProvider}.</li> + </ul> + <ul> + <li>{@link android.support.v4.view.AccessibilityDelegateCompat} - Adds support for + {@link android.view.View.AccessibilityDelegate}.</li> + </ul> + </li> + <li>Content + <ul> + <li>{@link android.support.v4.content.Loader} - Adds support for asynchronous loading of data. + The library also provides concrete implementations of this class, including + {@link android.support.v4.content.CursorLoader} and + {@link android.support.v4.content.AsyncTaskLoader}.</li> + </ul> + <ul> + <li>{@link android.support.v4.content.FileProvider} - Adds support for sharing of private + files between applications.</li> + </ul> + </li> +</ul> + +<p> + There are many other APIs included in this package. For complete, detailed information about the + v4 Support Library APIs, see the {@link android.support.v4.app android.support.v4} package in the + API reference. +</p> + +<p>This library is located in the {@code <sdk>/extras/android/support/v4/} directory after + you download the Android Support Libraries. This library does not contain user interface + resources. To include it in your application project, follow the instructions for + <a href="{@docRoot}tools/support-library/setup.html#libs-without-res">adding libraries without + resources</a>.</p> + +<p>The Gradle build script dependency identifier for this library is as follows:</p> + +<pre> +com.android.support:support-v4:18.0.+ +</pre> + +<p>This dependency notation specifies the release version 18.0.0 or higher.</p> + + + +<h2 id="v7">v7 Libraries</h2> + +<p>There are several libraries designed to be used with Android 2.1 (API level 7) and higher. + These libraries provide specific feature sets and can be included in your application + independently from each other.</p> + + +<h3 id="v7-appcompat">v7 appcompat library</h3> + +<p>This library adds support for the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action + Bar</a> user interface <a href="{@docRoot}design/patterns/actionbar.html">design pattern</a>. +</p> + +<p class="note"><strong>Note:</strong> + This library depends on the v4 Support Library. If you are using Ant or Eclipse, make sure + you include the v4 Support Library as part of this library's classpath. +</p> + +<p>Here are a few of the key classes included in the v7 appcompat library:</p> + +<ul> + <li>{@link android.support.v7.app.ActionBar} - Provides an implementation of the action bar + <a href="{@docRoot}design/patterns/actionbar.html">user interface pattern</a>. For more + information on using the Action Bar, see the + <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide. + </li> + <li>{@link android.support.v7.app.ActionBarActivity} - Adds an application activity class that + must be used as a base class for activities that uses the Support Library action bar + implementation. + </li> + <li>{@link android.support.v7.widget.ShareActionProvider} - Adds support for a standardized + sharing action (such as email or posting to social applications) that can be included in an + action bar. + </li> +</ul> + +<p>This library is located in the {@code <sdk>/extras/android/support/v7/appcompat/} + directory after you download the Android Support Libraries. This library contains user + interface resources. To include it in your application project, follow the instructions for + <a href="{@docRoot}tools/support-library/setup.html#libs-with-res">adding libraries with + resources</a>.</p> + +<p>The Gradle build script dependency identifier for this library is as follows:</p> + +<pre> +com.android.support:appcompat-v7:18.0.+ +</pre> + +<p>This dependency notation specifies release version 18.0.0 or higher.</p> + + + +<h3 id="v7-gridlayout">v7 gridlayout library</h3> + +<p>This library adds support for the {@link android.support.v7.widget.GridLayout} class, which + allows you to arrange user interface elements using a grid of rectangular cells. + For detailed information about the v7 gridlayout library APIs, see the + {@link android.support.v7.widget android.support.v7.widget} package in the API reference.</p> + +<p>This library is located in the {@code <sdk>/extras/android/support/v7/gridlayout/} + directory after you download the Android Support Libraries. This library contains user + interface resources. To include it in your application project, follow the instructions for + <a href="{@docRoot}tools/support-library/setup.html#libs-with-res">adding libraries with + resources</a>.</p> + +<p>The Gradle build script dependency identifier for this library is as follows:</p> + +<pre> +com.android.support:gridlayout-v7:18.0.+ +</pre> + +<p>This dependency notation specifies release version 18.0.0 or higher.</p> + + +<h2 id="v13">v13 Support Library</h2> + +<p>This library is designed to be used for Android 3.2 (API level 13) and higher. It adds support + for the <a href="{@docRoot}guide/components/fragments.html">Fragment</a> user interface pattern + with the ({@link android.support.v13.app.FragmentCompat}) class and additional fragment support + classes For more information about fragments, see the + <a href="{@docRoot}guide/components/fragments.html">Fragments</a> developer guide. For detailed + information about the v13 Support Library APIs, see the {@link android.support.v13.app + android.support.v13} package in the API reference. +</p> + +<p>This library is located in the {@code <sdk>/extras/android/support/v13/} directory after + you download the Android Support Libraries. This library does not contain user interface + resources. To include it in your application project, follow the instructions for + <a href="{@docRoot}tools/support-library/setup.html#libs-without-res">adding libraries without + resources</a>.</p> + +<p>The Gradle build script dependency identifier for this library is as follows:</p> + +<pre> +com.android.support:support-v13:18.0.+ +</pre> + +<p>This dependency notation specifies the release version 18.0.0 or higher.</p> diff --git a/docs/html/tools/extras/support-library.jd b/docs/html/tools/support-library/index.jd index a82a98ae4eba..e5efb8d81157 100644 --- a/docs/html/tools/extras/support-library.jd +++ b/docs/html/tools/support-library/index.jd @@ -3,52 +3,149 @@ page.title=Support Library @jd:body <div id="qv-wrapper"> -<div id="qv"> - -<h2>In this document</h2> -<ol> - <li><a href="#Notes">Revisions</a></li> - <li><a href="#Downloading">Downloading the Support Package</a></li> - <li><a href="#SettingUp">Setting Up a Project to Use a Library</a></li> - <li><a href="#Using">Using the v4 Library APIs</a></li> - <li><a href="#Docs">Reference Docs</a></li> - <li><a href="#Samples">Samples</a></li> -</ol> - -<h2>See also</h2> -<ol> - <li><a -href="{@docRoot}training/basics/fragments/support-lib.html">Using the Support Library</a></li> -</ol> + <div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#overview">Overview</a></li> + <li><a href="#revisions">Revisions</a></li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}tools/support-library/features.html"> + Support Library Features</a></li> + <li><a href="{@docRoot}tools/support-library/setup.html"> + Support Library Setup </a></li> + </ol> + </div> </div> -</div> -<p><em>Minimum API level supported:</em> <b>4</b></p> +<p>The Android Support Library package is a set of code libraries that provide useful and important + features for Android applications in addition to the framework APIs. These libraries provide + backward-compatible versions of framework APIs as well as features that are only available + through its API. Each Support Library is backward-compatible to a specific Android API level. + This design means that your applications can use the libraries' features and still be compatible + with devices running Android 1.6 (API level 4) and up.</p> + +<p>This guide provides information about what features are enabled by the different libraries, + how to use them in your development environment and information about the Support Library + releases.</p> + + +<h2 id="overview">Overview</h2> -<p>The Support Package includes static "support libraries" that you can add to your Android -application in order to use APIs that are either not available for older platform versions or that -offer "utility" APIs that aren't a part of the framework APIs. The goal is to simplify your -development by offering more APIs that you can bundle with your application so you can -worry less about platform versions.</p> +<p>Including the Support Libraries in your Android project is considered a best practice for + application developers. Using the features they provide can help you improve the look of your + application, increase performance and broaden the reach of your application to more users. + If you use the Android + <a href="{@docRoot}tools/projects/templates.html">code template</a> tools, you will notice that + all the Android application templates include one or more of the Support Libraries by default.</p> -<p class="note"><strong>Note:</strong> The Support Package includes more than one support -library. Each one has a different <em>minimum API level</em>. For example, one library requires API -level 4 or higher, while another requires API level 13 or higher (v13 is a superset of v4 and -includes additional -support classes to work with v13 APIs). The minimum version is indicated -by the directory name, such as {@code v4/} and {@code v13/}.</p> +<p>The Support Libraries each target a base Android API level and each provides a different set + of features. In order to effectively use the libraries, it is important to consider what features + you want to support and understand what features are supported by each library at what Android + API level. To get started, review the + <a href="{@docRoot}tools/support-library/features.html">Support Library Features</a> guide. + After that, go to the + <a href="{@docRoot}tools/support-library/setup.html">Support Library Setup</a> topic to + learn how to incorporate the Support Libraries into your application. For more details + about Support Library APIs, see the {@link android.support.v4.app android.support} + packages in the API reference.</p> -<h2 id="Notes">Revisions</h2> +<h2 id="revisions">Revisions</h2> -<p>The sections below provide notes about successive releases of -the Support Package, as denoted by revision number.</p> +<p>This section provides details about the Support Library package releases.</p> <div class="toggle-content opened"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" alt="" -/>Support Package, revision 13</a> <em>(May 2013)</em> +/>Android Support Library, revision 18</a> <em>(July 2013)</em> + </p> + <div class="toggle-content-toggleme"> + <dl> + <dt>Changes for v4 support library:</dt> + <dd> + <ul> + <li>User interface + <ul> + <li>Added {@link android.support.v4.text.BidiFormatter} for handling + text strings that combine right to left and left to right-formatted text.</li> + <li>Modified {@link android.support.v4.view.ViewPager} to better handle cases where the + pager has a measured width of zero in the initial layout processing.</li> + <li>Modified {@link android.support.v4.widget.DrawerLayout} and + {@link android.support.v4.widget.SlidingPaneLayout} to not throw exceptions for + measurement while the project code is being edited.</li> + </ul> + </li> + + <li>Accessibility + <ul> + <li>Added {@link android.support.v4.widget.ExploreByTouchHelper} to simplify the + implementation of accessibility for custom views.</li> + <li>Fixed a problem with {@link android.support.v4.view.ViewPager} incorrectly + populating {@link + android.support.v4.view.accessibility.AccessibilityEventCompat#TYPE_VIEW_SCROLLED + TYPE_VIEW_SCROLLED} accessibility events.</li> + <li>Fixed a null pointer exception in {@link android.support.v4.view.ViewPager} when + populating an accessibility event.</li> + <li>Simplified {@link android.support.v4.view.accessibility.AccessibilityNodeInfoCompat} + by changing {@link java.lang.CharSequence} inputs to {@link java.lang.String} objects. + </li> + <li>Deprecated an {@link android.support.v4.view.accessibility.AccessibilityRecordCompat} + constructor that used an {@link java.lang.Object} as input.</li> + </ul> + </li> + + <li>Media + <ul> + <li>Added {@link android.support.v4.media.TransportMediator} helper class to manage + media transport control, such as play, pause, skip and other media actions.</li> + <li>Added {@link android.support.v4.hardware.display.DisplayManagerCompat} for managing + display output to one or more device displays.</li> + </ul> + </li> + + <li>Other changes + <ul> + <li>Added {@link android.support.v4.content.WakefulBroadcastReceiver} helper class for + implementing a common pattern of detecting a device wakeup event and passing work off + to a {@link android.app.Service} while ensuring that the device does not go back to + sleep before the handoff is complete.</li> + <li>Added two new APIs, + {@link android.support.v4.content.AsyncTaskLoader#commitContentChanged + commitContentChanged()} and + {@link android.support.v4.content.AsyncTaskLoader#rollbackContentChanged + rollbackContentChanged()}, to {@link android.support.v4.content.AsyncTaskLoader} to + help deal with background updates for data changes that are subsequently canceled. + </li> + </ul> + </li> + </ul> + </dd> + + <dt>New v7 appcompat library:</dt> + <dd> + <ul> + <li>Added {@link android.support.v7.app.ActionBar} to allow implementation of the + action bar user interface <a href="{@docRoot}/design/patterns/actionbar.html">design + pattern</a> back to Android 2.1 (API level 7) and higher. Use of this class requires + that you implement your activity by extending the new + {@link android.support.v7.app.ActionBarActivity} class.</li> + </ul> + </dd> + + </dl> + </div> +</div> + + +<div class="toggle-content closed"> + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" +/>Android Support Library, revision 13</a> <em>(May 2013)</em> </p> <div class="toggle-content-toggleme"> <dl> @@ -71,8 +168,9 @@ the Support Package, as denoted by revision number.</p> <li>Added {@link android.support.v4.content.FileProvider} to allow sharing of private files between applications.</li> <li>Updated {@link android.support.v4.view.ViewPager} to throw an exception if the - associated {@link android.support.v4.view.PagerAdapter} class is modified without a call - to {@link android.support.v4.view.PagerAdapter#notifyDataSetChanged notifyDataSetChanged()}. + associated {@link android.support.v4.view.PagerAdapter} class is modified without a + call to {@link android.support.v4.view.PagerAdapter#notifyDataSetChanged + notifyDataSetChanged()}. </li> <li>Fixed an issue with {@link android.support.v4.view.ViewPager} children drawing sort order.</li> @@ -81,6 +179,15 @@ the Support Package, as denoted by revision number.</p> between tap timeout and long press events.</li> </ul> </dd> + + <dt>New v7 gridlayout library:</dt> + <dd> + <ul> + <li>Added {@link android.support.v7.widget.GridLayout} to provide support for the + {@link android.widget.GridLayout} layout object.</li> + <li>Added {@link android.support.v7.widget.Space} which can be used to create blank areas + within a {@link android.support.v7.widget.GridLayout} layout object.</li> + </ul> </dl> </div> </div> @@ -89,7 +196,7 @@ the Support Package, as denoted by revision number.</p> <div class="toggle-content closed"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" -/>Support Package, revision 12</a> <em>(February 2013)</em> +/>Android Support Library, revision 12</a> <em>(February 2013)</em> </p> <div class="toggle-content-toggleme"> <dl> @@ -110,10 +217,11 @@ the Support Package, as denoted by revision number.</p> </div> </div> + <div class="toggle-content closed"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" -/>Support Package, revision 11</a> <em>(November 2012)</em> +/>Android Support Library, revision 11</a> <em>(November 2012)</em> </p> <div class="toggle-content-toggleme"> <dl> @@ -175,7 +283,7 @@ the Support Package, as denoted by revision number.</p> <div class="toggle-content closed"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" -/>Support Package, revision 10</a> <em>(August 2012)</em> +/>Android Support Library, revision 10</a> <em>(August 2012)</em> </p> <div class="toggle-content-toggleme"> <dl> @@ -194,7 +302,7 @@ the Support Package, as denoted by revision number.</p> <div class="toggle-content closed"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" -/>Support Package, revision 9</a> <em>(June 2012)</em> +/>Android Support Library, revision 9</a> <em>(June 2012)</em> </p> <div class="toggle-content-toggleme"> <dl> @@ -260,10 +368,11 @@ isActiveNetworkMetered()} method.</li> </div> </div> + <div class="toggle-content closed"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" -/>Support Package, revision 8</a> <em>(April 2012)</em> +/>Android Support Library, revision 8</a> <em>(April 2012)</em> </p> <div class="toggle-content-toggleme"> <dl> @@ -282,10 +391,11 @@ isActiveNetworkMetered()} method.</li> </div> </div> + <div class="toggle-content closed"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" -/>Support Package, revision 7</a> <em>(March 2012)</em> +/>Android Support Library, revision 7</a> <em>(March 2012)</em> </p> <div class="toggle-content-toggleme"> <dl> @@ -311,10 +421,11 @@ for creating standardized system notifications.</li> </div> </div> + <div class="toggle-content closed"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" -/>Support Package, revision 6</a> <em>(December 2011)</em> +/>Android Support Library, revision 6</a> <em>(December 2011)</em> </p> <div class="toggle-content-toggleme"> @@ -367,7 +478,7 @@ for creating standardized system notifications.</li> <div class="toggle-content closed"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" -/>Support Package, revision 5</a> <em>(December 2011)</em> +/>Android Support Library, revision 5</a> <em>(December 2011)</em> </p> <div class="toggle-content-toggleme"> <dl> @@ -426,7 +537,7 @@ for creating standardized system notifications.</li> <div class="toggle-content closed"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" -/>Support Package, revision 4</a> <em>(October 2011)</em> +/>Android Support Library, revision 4</a> <em>(October 2011)</em> </p> <div class="toggle-content-toggleme"> <dl> @@ -468,7 +579,7 @@ for creating standardized system notifications.</li> <div class="toggle-content closed"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" -/>Compatibility Package, revision 3</a> <em>(July 2011)</em> +/>Android Support Library, revision 3</a> <em>(July 2011)</em> </p> <div class="toggle-content-toggleme"> <dl> @@ -519,7 +630,7 @@ Android 3.2 and higher (all other APIs in the v4 library are already available w <div class="toggle-content closed"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" -/>Compatibility Package, revision 2</a> <em>(May 2011)</em> +/>Android Support Library, revision 2</a> <em>(May 2011)</em> </p> <div class="toggle-content-toggleme"> <dl> @@ -527,7 +638,7 @@ Android 3.2 and higher (all other APIs in the v4 library are already available w <dd> <ul> <li>Support for fragment animations</li> - <li>Fix {@code android.support.v4.app.Fragment#onActivityResult Fragment.onActivityResult()} + <li>Fix {@link android.support.v4.app.Fragment#onActivityResult Fragment.onActivityResult()} bug</li> </ul> </dd> @@ -539,204 +650,10 @@ Android 3.2 and higher (all other APIs in the v4 library are already available w <div class="toggle-content closed"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" -/>Compatibility Package, revision 1</a> <em>(March 2011)</em> +/>Android Support Library, revision 1</a> <em>(March 2011)</em> </p> <div class="toggle-content-toggleme"> <p>Initial release with the v4 library.</p> </div> </div> - - -<h2 id="Downloading">Downloading the Support Package</h2> - -<p>The Support Package is provided as a downloadable package from the Android SDK -Manager. To install:</p> - -<ol> - <li>Launch the Android SDK Manager. - <p>From Eclipse, you can select <strong>Window</strong> -> <strong>Android SDK Manager</strong>. Or, launch {@code SDK Manager.exe} from -the {@code <sdk>/} directory (on Windows only) or {@code android} from the {@code -<sdk>/tools/} directory.</p></li> - <li>Expand the Android Repository, check <strong>Android Support package</strong> -and click <strong>Install selected</strong>.</li> - <li>Proceed to install the package.</li> -</ol> - -<p>When done, all files (including source code, samples, and the JAR files) are saved -into the <code><sdk>/extras/android/support/</code> directory. This directory contains -each of the different support libraries, such as the library for API level 4 and up and the library -for API level 13 and up, each named with the respective version (such as {@code v4/}).</p> - - -<h2 id="SettingUp">Setting Up a Project to Use a Library</h2> - -<p>To add one of the libraries to your Android project:</p> -<dl> - <dt> - Add the JAR file to your project. - </dt> - <dd> - Copy the JAR file for the library you want to use into your Android project. To do this: - <ul> - <li> - Create the directory {@code libs/} at the root of your project - (next to {@code src/}, {@code res/}, and so forth). - </li> - <li> - Locate the JAR file for the library you want to use and copy it into the - {@code libs/} directory. - <p> - For example, the library that supports API level 4 and up is located at - {@code <sdk>/extras/android/support/v4/android-support-v4.jar}. - </p> - </li> - </ul> - <p> - Your build system may expect to find the JAR file in a directory other than - {@code libs}. Read the documentation for your build system to learn where to put the - JAR file. - </p> - </dd> - <dt> - If necessary, add the {@code libs/} directory to your build path. - </dt> - <dd> - Read the documentation for your build system to learn how to add the JAR file to the - build path. - </dd> -</dl> -<p> - To confirm that you've added the JAR file to the correct directory and added it to the build - path: -</p> -<ol> - <li> - Edit one of your source files to add an {@code import} statement that imports a - class from the {@code android.support.*} package. - </li> - <li> - Build your app. The code should compile cleanly. - </li> - <li> - As a double-check, run your app. It should run correctly, without any runtime exceptions - indicating that the class in {@code android.support.*} can't be found. - </li> -</ol> -<p>Your application is now ready to use the library APIs. All the -provided APIs are available in the {@code android.support} package (for -example, {@code android.support.v4}).</p> - -<p class="note"><strong>Tip:</strong> To see the library APIs in action, take a look at the sample -apps in {@code <sdk>/extras/android/support/<version>/samples/}.</p> - -<p class="warning"><strong>Warning:</strong> Be certain that you not confuse the standard -{@code android} packages with those in {@code android.support} library. Some code completion tools -might -get this wrong, especially if you're building against recent versions of the platform. To be safe, -keep your build target set to the same version as you have defined for your <a -href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> -and double check the import statements for classes that also exist in the support library, such as -{@code SimpleCursorAdapter}.</p> - - -<h2 id="Using">Using the v4 Library APIs</h2> - -<p>The support library for v4 provides access to several classes introduced with Android 3.0 and -beyond, plus some updated version of existing classes, and even some APIs that currently don't -exist in the Android platform. Some of the most useful and notable classes that have -counterparts in the v4 support library are:</p> - -<ul> - <li>{@link android.app.Fragment}</li> - <li>{@link android.app.FragmentManager}</li> - <li>{@link android.app.FragmentTransaction}</li> - <li>{@link android.app.ListFragment}</li> - <li>{@link android.app.DialogFragment}</li> - <li>{@link android.app.LoaderManager}</li> - <li>{@link android.content.Loader}</li> - <li>{@link android.content.AsyncTaskLoader}</li> - <li>{@link android.content.CursorLoader}</li> -</ul> - -<p>For each of the classes above (and others not listed), the APIs work almost exactly the same -as the counterparts in the latest Android platform. Thus, you can usually refer to -the online documentation for information about the supported APIs. There are some -differences, however. Most notably:</p> - -<ul> - <li>When creating an activity to use fragments, you must declare your activity to extend the -{@link android.support.v4.app.FragmentActivity} class (instead of the traditional -{@link android.app.Activity} class).</li> - <li>To manage your fragments and loaders, you must use the methods - {@link android.support.v4.app.FragmentActivity#getSupportFragmentManager - FragmentActivity.getSupportFragmentManager()} and - {@link android.support.v4.app.FragmentActivity#getSupportLoaderManager - FragmentActivity.getSupportLoaderManager()} (instead of the - {@link android.app.Activity#getFragmentManager()} and - {@link android.app.Activity#getLoaderManager()} methods).</li> - <li>The {@link android.app.ActionBar} is <strong>not supported</strong> by the library. -However, when creating your <a href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options -Menu</a>, you can declare which items should be added to the Action Bar when it's available (on -Android 3.0 or later). You can do so with the -{@link android.support.v4.view.MenuCompat#setShowAsAction MenuCompat.setShowAsAction()} method, for -example: -<pre> -public boolean onCreateOptionsMenu(Menu menu) { - MenuInflater inflater = getMenuInflater(); - inflater.inflate(R.menu.options, menu); - MenuCompat.setShowAsAction(menu.findItem(R.id.action_search), 1); - return true; -} -</pre> -<p>Also see the <a href="{@docRoot}resources/samples/ActionBarCompat/index.html">Action Bar -Compatibility</a> sample for a demonstration of how to use {@link android.app.ActionBar} on Android -3.0+ and also support action bar functionality on older versions.</p> -</li> -</ul> - -<div class="note"><p><strong>Tip:</strong> To enable the Holographic theme on devices -running Android 3.0 or higher, declare in your manifest file that your application targets -API level 11, for example:</p> -<pre> -<uses-sdk android:minSdkVersion="4" android:targetSdkVersion="11" /> -</pre> -<p>This way, your application automatically receives the Holographic theme and the Action Bar for -each activity when running on Android 3.0 and higher.</p> -</div> - -<p>For more information about how you can optimize your application for the latest -Android-powered devices, read <a href="{@docRoot}guide/practices/tablets-and-handsets.html" ->Supporting Tablets and Handsets</a>.</p> - - -<h2 id="Docs">Reference Docs</h2> - -<p>The reference documentation for the Support Packages is included as part of the Android -online developer documentation:</p> - -<ul> - <li><a href="{@docRoot}reference/android/support/v4/app/package-summary.html">Support Package - API 4 Reference</a></li> - <li><a href="{@docRoot}reference/android/support/v13/app/package-summary.html">Support Package - API 13 Reference</a></li> -</ul> - - -<h2 id="Samples">Samples</h2> - -<p>If you want to see some code that uses the support libraries, samples are included with the -Support Package, inside each support library directory, for example; {@code -<sdk>/extras/android/support/v4/samples/}. You can also view these samples as part of the -Android online developer documentation:</p> - -<ul> - <li><a href="{@docRoot}resources/samples/Support4Demos/index.html">Support API 4 Demos</a></li> - <li><a href="{@docRoot}resources/samples/Support13Demos/index.html">Support API 13 Demos</a></li> -</ul> - -<p>Additionally, the <a href="http://code.google.com/p/iosched/">Google I/O App</a> is a complete -application that uses the v4 support library to provide a single APK for both handsets and tablets -and also demonstrates some of Android's best practices in Android UI design.</p> - diff --git a/docs/html/tools/support-library/setup.jd b/docs/html/tools/support-library/setup.jd new file mode 100644 index 000000000000..a2ece159f341 --- /dev/null +++ b/docs/html/tools/support-library/setup.jd @@ -0,0 +1,308 @@ +page.title=Support Library Setup + +@jd:body + + +<div id="qv-wrapper"> + <div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#download">Downloading the Support Library</a></li> + <li><a href="#choosing">Choosing Support Libraries</a></li> + <li><a href="add-library">Adding Support Libraries</a> + <ol> + <li><a href="#libs-without-res">Adding libraries without resources</a></li> + <li><a href="#libs-with-res">Adding libraries with resources</a></li> + </ol> + </li> + <li><a href="#using-apis">Using Support Library APIs</a> + <ol> + <li><a href="#manifest">Manifest Declaration Changes</a></li> + </ol> + </li> + <li><a href="#samples">Code Samples</a></li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}tools/support-library/index.html#revisions"> + Support Library Revisions</a></li> + <li><a href="{@docRoot}tools/support-library/features.html"> + Support Library Features</a></li> + </ol> + + </div> +</div> + +<p>How you setup the Android Support Libraries in your development project depends on what features + you want to use and what range of Android platform versions you want to support with your + application.</p> + +<p>This document guides you through downloading the Support Library package and adding libraries + to your development environment.</p> + + +<h2 id="download">Downloading the Support Libraries</h2> + +<p>The Android Support Library package is provided as a supplemental download to the Android SDK + and is available through the Android + <a href="{@docRoot}tools/help/sdk-manager.html">SDK Manager</a>. Follow the + instructions below to obtain the Support Library files. +</p> + +<p>To download the Support Library through the SDK Manager:</p> + +<ol> + <li>Start the Android <a href="{@docRoot}tools/help/sdk-manager.html">SDK Manager</a>.</li> + <li>In the SDK Manager window, scroll to the end of the <em>Packages</em> list, + find the <em>Extras</em> folder and, if necessary, expand to show its contents.</li> + <li>Select the <strong>Android Support Library</strong> item. + <p class="note"> + <strong>Note:</strong> If you're developing with Android Studio, select and install the + <strong>Android Support Repository</strong> item instead. + </p> + </li> + <li>Click the <strong>Install packages...</strong> button.</li> +</ol> + +<img src="{@docRoot}images/tools/sdk-manager-support-libs.png" width="525" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> The Android SDK Manager with the +Android Support Library selected.</p> + +<p>After downloading, the tool installs the Support Library files to your existing Android SDK + directory. The library files are located in the following subdirectory of your SDK: + {@code <sdk>/extras/android/support/} directory.</p> + + +<h2 id="choosing">Choosing Support Libraries</h2> + +<p>Before adding a Support Library to your application, decide what features you want to include + and the lowest Android versions you want to support. For more information on the features + provided by the different libraries, see + <a href="{@docRoot}tools/support-library/features.html">Support Library Features</a>.</p> + + +<h2 id="add-library">Adding Support Libraries</h2> + +<p>In order to use a Support Library, you must modify your application's project's + classpath dependencies within your development environment. You must perform this procedure for + each Support Library you want to use.</p> + +<p>Some Support Libraries contain resources beyond compiled code classes, such as images or XML + files. For example, the <a href="tools/support-library/features.html#v7-appcompat">v7 + appcompat</a> and <a href="tools/support-library/features.html#v7-gridlayout">v7 gridlayout</a> + libraries include resources.</p> + +<p>If you are not sure if a library contains resources, check the + <a href="{@docRoot}tools/support-library/features.html">Support Library Features</a> page. + The following sections describe how to add a Support Library with or without resources to your + application project. </p> + + +<h3 id="libs-without-res">Adding libraries without resources</h3> + +<p>To add a Support Library without resources to your application project:</p> + +<div class="toggle-content closed"> +<p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)"> + <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt="" + />Using Eclipse</a></p> + + <div class="toggle-content-toggleme"> + <ol> + <li>Make sure you have downloaded the <strong>Android Support Library</strong> + using the <a href="#download">SDK Manager</a>.</li> + <li>Create a {@code /libs} directory in the root of your application project.</li> + <li>Copy the JAR file from your Android SDK installation directory (e.g., + {@code <sdk>/extras/android/support/v4/android-support-v4.jar}) into your + application's project {@code /libs} directory. + <li>Right click the JAR file and select <strong>Build Path > Add to Build Path</strong>. + </li> + </ol> + </div> +</div> + +<div class="toggle-content closed"> +<p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)"> + <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt="" + />Using Android Studio</a></p> + + <div class="toggle-content-toggleme"> + <ol> + <li>Make sure you have downloaded the <strong>Android Support Repository</strong>. + using the <a href="#download">SDK Manager</a>.</li> + <li>Open the {@code build.gradle} file for your application.</li> + <li>Add the support library to the {@code dependencies} section. For example, to add the v4 + support library, add the following lines: +<pre> +dependencies { + ... + <b>compile "com.android.support:support-v4:18.0.+"</b> +} +</pre> + </li> + </ol> + </div> +</div> + + +<h3 id="libs-with-res">Adding libraries with resources</h3> + +<p>To add a Support Library with resources to your application project:</p> + +<div class="toggle-content closed"> + <p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)"> + <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt="" + />Using Eclipse</a></p> + <div class="toggle-content-toggleme"> + +<p>Create a <a href="{@docRoot}tools/projects/index.html#LibraryProjects">library +project</a> based on the support library code:</p> + +<ol> + <li>Make sure you have downloaded the <strong>Android Support Library</strong> + using the <a href="#download">SDK Manager</a>.</li> + <li>Create a library project and ensure the required JAR files are included in the project's + build path: + <ol> + <li>Select <strong>File > Import</strong>.</li> + <li>Select <strong>Existing Android Code Into Workspace</strong> and click + <strong>Next</strong>.</li> + <li>Browse to the SDK installation directory and then to the Support Library folder. + For example, if you are adding the {@code appcompat} project, browse to + <code><sdk>/extras/android/support/v7/appcompat/</code>.</li> + <li>Click <strong>Finish</strong> to import the project. For the v7 appcompat project, you + should now see a new project titled <em>android-support-v7-appcompat</em>.</li> + <li>In the new library project, expand the {@code /libs} folder, right-click each {@code .jar} + file and select <strong>Build Path > Add to Build Path</strong>. For example, when + creating the the v7 appcompat project, add both the {@code android-support-v4.jar} and + {@code android-support-v7-appcompat.jar} files to the build path.</li> + <li>Right-click the project and select <strong>Build Path > Configure Build Path</strong>. + </li> + <li>In the <strong>Order and Export</strong> tab, check the <code>.jar</code> files you just + added to the build path, so they are available to projects that depend on this library + project. For example, the {@code appcompat} project requires you to export both the + {@code android-support-v4.jar} and {@code android-support-v7-appcompat.jar} files.</li> + <li>Uncheck <strong>Android Dependencies</strong>.</li> + <li>Click <strong>OK</strong> to complete the changes.</li> + </ol> + </li> +</ol> + +<p>You now have a library project for your selected Support Library that you can use with one or + more application projects.</p> + +<p>Add the library to your application project:</p> + <ol> + <li>In the Project Explorer, right-click your project and select <strong>Properties</strong>. + <li>In the Library pane, click <strong>Add</strong>. + <li>Select the library project and click <strong>OK</strong>. For example, the + {@code appcompat} project should be listed as <strong>android-support-v7-appcompat</strong>. + </li> + <li>In the properties window, click <strong>OK</strong>. + </ol> + + </div> +</div> + + +<div class="toggle-content closed"> +<p style="margin-top:5px"><a href="#" onclick="return toggleContent(this)"> + <img src="/assets/images/triangle-closed.png" class="toggle-content-img" alt="" + />Using Android Studio</a></p> + + <div class="toggle-content-toggleme"> + <ol> + <li>Make sure you have downloaded the <strong>Android Support Repository</strong> + using the <a href="#download">SDK Manager</a>.</li> + <li>Open the {@code build.gradle} file for your application.</li> + <li>Add the support library feature project identifier to the {@code dependencies} section. + For example, to include the {@code appcompat} project add + {@code compile "com.android.support:appcompat-v7:18.0.+"} to the dependencies section, as + shown in the following example: +<pre> +dependencies { + ... + <b>compile "com.android.support:appcompat-v7:18.0.+"</b> +} +</pre> + </li> + </ol> + </div> +</div> + + +<h2 id="using-apis">Using Support Library APIs</h2> + +<p>Support Library classes that provide support for existing framework APIs typically have the + same name as framework class but are located in the <code>android.support</code> class packages, + or have a <code>*Compat</code> suffix.</p> + +<div class="caution"> + <p><strong>Caution:</strong> When using classes from the Support Library, be certain you import + the class from the appropriate package. For example, when applying the {@code ActionBar} + class:</p> + <ul> + <li>{@code android.support.v7.app.ActionBar} when using the Support Library.</li> + <li>{@code android.app.ActionBar} when developing only for API level 11 or higher.</li> + </ul> +</div> + +<p class="note"> + <strong>Note:</strong> After including the Support Library in your application project, we + strongly recommend using the + <a href="{@docRoot}tools/help/proguard.html">ProGuard</a> tool to prepare your application APK + for release. In addition to protecting your source code, the ProGuard tool also removes unused + classes from any libraries you include in your application, which keeps the download size of + your application as small as possible. For more information, see + <a href="{@docRoot}tools/help/proguard.html">ProGuard</a>. +</p> + +<p>Further guidance for using some Support Library features is provided in the Android developer + <a href="{@docRoot}training/index.html">training classes</a>, + <a href="{@docRoot}guide/components/index.html">guides</a> + and samples. For more information about the individual Support Library classes and methods, see + the {@link android.support.v4.app android.support} packages in the API reference. +</p> + + +<h3 id="manifest">Manifest Declaration Changes</h3> + +<p>If you are increasing the backward compatibility of your existing application to an earlier + version of the Android API with the Support Library, make sure to update your application's + manifest. Specifically, you should update the <code>android:minSdkVersion</code> + element of the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"> + <code><uses-sdk></code></a> tag in the manifest to the new, lower version number, as + shown below:</p> + +<pre> + <uses-sdk + android:minSdkVersion="<b>7</b>" + android:targetSdkVersion="17" /> +</pre> + +<p>This change tells Google Play that your application can be installed on devices with Android + 2.1 (API level 7) and higher.</p> + +<p class="note"> + <strong>Note:</strong> If you are including the v4 support and v7 appcompat libraries in your + application, you should specify a minimum SDK version of <code>"7"</code> (and not + <code>"4"</code>). The highest support library level you include in your application determines + the lowest API version in which it can operate. +</p> + + +<h2 id="samples">Code Samples</h2> + +<p>Each Support Library includes code samples to help you get started using the support +APIs. The code is included in the download from the SDK Manager and is placed inside the Android +SDK installation directory, as listed below:</p> + +<ul> + <li>4v Samples: {@code <sdk>/extras/android/support/samples/Support4Demos/}</li> + <li>7v Samples: {@code <sdk>/extras/android/support/samples/Support7Demos/}</li> + <li>13v Samples: {@code <sdk>/extras/android/support/samples/Support13Demos/}</li> + <li>App Navigation: {@code <sdk>/extras/android/support/samples/SupportAppNavigation/}</li> +</ul> + diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs index c555f9841841..8ad61ec20f53 100644 --- a/docs/html/tools/tools_toc.cs +++ b/docs/html/tools/tools_toc.cs @@ -56,7 +56,13 @@ <li><a href="<?cs var:toroot ?>tools/devices/emulator.html"><span class="en">Using the Emulator</span></a></li> </ul> </li> - <li><a href="<?cs var:toroot ?>tools/device.html"><span class="en">Using Hardware Devices</span></a></li> + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>tools/device.html"><span class="en">Using Hardware Devices</span></a></div> + <ul> + <li><a href="<?cs var:toroot ?>tools/extras/oem-usb.html"><span + class="en">USB Drivers</span></a></li> + </ul> + </li> <li class="nav-section"> <div class="nav-section-header"><a href="<?cs var:toroot ?>tools/projects/index.html"><span class="en">Setting Up Projects</span></a></div> <ul> @@ -144,8 +150,18 @@ <li><a href="<?cs var:toroot ?>tools/publishing/app-signing.html"><span class="en">Signing Your Apps</span></a></li> </ul> </li> -</ul> -</li> + </ul> + </li> + + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>tools/support-library/index.html"><span +class="en">Support Library</span></a></div> + <ul> + <li><a href="<?cs var:toroot ?>tools/support-library/features.html">Features</a></li> + <li><a href="<?cs var:toroot ?>tools/support-library/setup.html">Setup</a></li> + </ul> + </li> + <li class="nav-section"> <div class="nav-section-header"><a href="<?cs var:toroot ?>tools/help/index.html"><span class="en">Tools Help</span></a></div> @@ -223,19 +239,6 @@ class="en">Platforms</span></a></li> <li class="nav-section"> - <div class="nav-section-header"><a href="<?cs var:toroot -?>tools/extras/index.html"><span class="en">Extras</span></a></div> - <ul> - <li><a href="<?cs var:toroot ?>tools/extras/support-library.html"><span class="en">Support -Library</span></a></li> - <li><a href="<?cs var:toroot ?>tools/extras/oem-usb.html"><span -class="en">USB Drivers</span></a> - </li> - </ul> - </li> - - - <li class="nav-section"> <div class="nav-section-header empty"><a href="<?cs var:toroot ?>tools/samples/index.html"><span class="en">Samples</span></a></div> </li> |