Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 5ffbba64 authored by Joe Fernandez's avatar Joe Fernandez
Browse files

docs: Support Library Guide 

Extending the Support Library documentation to explain how to
support mainstream features such as ActionBar across multiple
versions of Android.

Change-Id: I8ddeeb912884a39b2fb8717129d22993102ef650
parent 797a99ff

docs/html/images/tools/sdk-manager-support-libs.png

0 → 100644
+52.5 KiB
Loading image diff...

docs/html/tools/support-library/features.jd

0 → 100644
+249 −0
Original line number Diff line number Diff line 
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>

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

+160 −243

File changed and moved.

Preview size limit exceeded, changes collapsed.

docs/html/tools/support-library/setup.jd

0 → 100644
+308 −0
Original line number Diff line number Diff line 
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>

docs/html/tools/tools_toc.cs

+19 −16

File changed.

Preview size limit exceeded, changes collapsed.