Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am 21a1df23: Merge "docs: Support Library Guide" into jb-mr2-ub-dev

Browse Source 
* commit '21a1df23cda2e08702a19f4fc9cd884da17997cc':
  docs: Support Library Guide
This commit is contained in:
Joe Fernandez
2013-07-24 16:20:23 -07:00
committed by Android Git Automerger
parent ae9beefd23 21a1df23cd
commit 82ce96f3ec
5 changed files with 735 additions and 258 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/html/images/tools/sdk-manager-support-libs.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 52 KiB

249
docs/html/tools/support-library/features.jd Normal file
View File

@@ -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 &lt;sdk&gt;/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 &lt;sdk&gt;/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 &lt;sdk&gt;/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 &lt;sdk&gt;/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>

401
docs/html/tools/extras/support-library.jd → docs/html/tools/support-library/index.jd
View File

@@ -3,52 +3,149 @@ page.title=Support Library
@jd:body
<div id="qv-wrapper">
<div id="qv">
<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>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}training/basics/fragments/support-lib.html">Using the Support Library</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>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 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>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="Notes">Revisions</h2>
<h2 id="overview">Overview</h2>
<p>The sections below provide notes about successive releases of
the Support Package, as denoted by revision number.</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>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="revisions">Revisions</h2>
<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>
&gt; <strong>Android SDK Manager</strong>. Or, launch {@code SDK Manager.exe} from
the {@code &lt;sdk&gt;/} directory (on Windows only) or {@code android} from the {@code
&lt;sdk&gt;/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>&lt;sdk&gt;/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 &lt;sdk&gt;/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 &lt;sdk&gt;/extras/android/support/&lt;version&gt;/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>
&lt;uses-sdk android:minSdkVersion="4" android:targetSdkVersion="11" /&gt;
</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
&lt;sdk&gt;/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>

308
docs/html/tools/support-library/setup.jd Normal file
View File

@@ -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 &lt;sdk&gt;/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 &lt;sdk&gt;/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 &gt; 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 &gt; 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>&lt;sdk&gt;/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 &gt; 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 &gt; 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>&lt;uses-sdk&gt;</code></a> tag in the manifest to the new, lower version number, as
shown below:</p>
<pre>
&lt;uses-sdk
android:minSdkVersion="<b>7</b>"
android:targetSdkVersion="17" /&gt;
</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 &lt;sdk&gt;/extras/android/support/samples/Support4Demos/}</li>
<li>7v Samples: {@code &lt;sdk&gt;/extras/android/support/samples/Support7Demos/}</li>
<li>13v Samples: {@code &lt;sdk&gt;/extras/android/support/samples/Support13Demos/}</li>
<li>App Navigation: {@code &lt;sdk&gt;/extras/android/support/samples/SupportAppNavigation/}</li>
</ul>

35
docs/html/tools/tools_toc.cs
View File

@@ -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>
@@ -222,19 +238,6 @@ class="en">Platforms</span></a></li>
</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>