diff options
Diffstat (limited to 'docs/html/tools')
23 files changed, 1667 insertions, 867 deletions
diff --git a/docs/html/tools/building/buidling-cmdline-ant.jd b/docs/html/tools/building/buidling-cmdline-ant.jd deleted file mode 100644 index 51158de..0000000 --- a/docs/html/tools/building/buidling-cmdline-ant.jd +++ /dev/null @@ -1,381 +0,0 @@ -page.title=Building and Running from the Command Line -parent.title=Building and Running -parent.link=index.html -@jd:body - - <div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#DebugMode">Building in Debug Mode</a></li> - <li><a href="#ReleaseMode">Building in Release Mode</a> - <ol> - <li><a href="#ManualReleaseMode">Build unsigned</a></li> - <li><a href="#AutoReleaseMode">Build signed and aligned</a></li> - <li><a href="#OnceBuilt">Once built and signed in release mode</a></li> - </ol> - </li> - <li><a href="#RunningOnEmulator">Running on the Emulator</a></li> - <li><a href="#RunningOnDevice">Running on a Device</a></li> - <li><a href="#Signing">Application Signing</a></li> - <li><a href="#AntReference">Ant Command Reference</a></li> - </ol> - <h2>See also</h2> - <ol> - <li><a href="{@docRoot}tools/devices/managing-avds-cmdline.html">Managing AVDs from -the Command Line</a></li> - <li><a href="{@docRoot}tools/devices/emulator.html">Using the Android -Emulator</a></li> - <li><a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a></li> - </ol> - </div> - </div> - - <p>There are two ways to build your application using the Ant build script: one for - testing/debugging your application — <em>debug mode</em> — and one for building your - final package for release — <em>release mode</em>. Regardless of which way you build your application, - it must be signed before it can install on an emulator or device—with a debug key when building - in debug mode and with your own private key when building in release mode.</p> - - <p>Whether you're building in debug mode or release mode, you need to use the Ant tool to compile - and build your project. This will create the .apk file that you can install on an emulator or device. - When you build in debug mode, the .apk file is automatically signed by the SDK tools with - a debug key, so it's instantly ready for installation onto an emulator or attached - development device. You cannot distribute an application that is signed with a debug key. - When you build in release mode, the .apk file is <em>unsigned</em>, so you - must manually sign it with your own private key, using Keytool and Jarsigner.</p> - - <p>It's important that you read and understand <a href= - "{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>, particularly once - you're ready to release your application and share it with end-users. That document describes the - procedure for generating a private key and then using it to sign your .apk file. If you're just - getting started, however, you can quickly run your applications on an emulator or your own - development device by building in debug mode.</p> - - <p>If you don't have Ant, you can obtain it from the <a href="http://ant.apache.org/">Apache Ant - home page</a>. Install it and make sure it is in your executable PATH. Before calling Ant, you - need to declare the JAVA_HOME environment variable to specify the path to where the JDK is - installed.</p> - - <p class="note"><strong>Note:</strong> When installing JDK on Windows, the default is to install - in the "Program Files" directory. This location will cause <code>ant</code> to fail, because of - the space. To fix the problem, you can specify the JAVA_HOME variable like this: - <pre>set JAVA_HOME=c:\Progra~1\Java\<jdkdir></pre> - - <p>The easiest solution, however, is to install JDK in a non-space directory, for example:</p> - - <pre>c:\java\jdk1.7</pre> - - <h2 id="DebugMode">Building in Debug Mode</h2> - - <p>For immediate application testing and debugging, you can build your application in debug mode - and immediately install it on an emulator. In debug mode, the build tools automatically sign your - application with a debug key and optimize the package with {@code zipalign}.</p> - - <p>To build in debug mode:</p> - - <ol> - <li>Open a command-line and navigate to the root of your project directory.</li> - <li>Use Ant to compile your project in debug mode: - <pre> -ant debug -</pre> - - <p>This creates your debug <code>.apk</code> file inside the project <code>bin/</code> directory, named - <code><your_project_name>-debug.apk</code>. The file is already signed with - the debug key and has been aligned with - <a href="{@docRoot}tools/help/zipalign.html"><code>zipalign</code></a>. - </p> - </li> - </ol> - - <p>Each time you change a source file or resource, you must run Ant again in order to package up - the latest version of the application.</p> - - <p>To install and run your application on an emulator, see the following section about <a href= - "#RunningOnEmulator">Running on the Emulator</a>.</p> - - <h2 id="ReleaseMode">Building in Release Mode</h2> - - <p>When you're ready to release and distribute your application to end-users, you must build your - application in release mode. Once you have built in release mode, it's a good idea to perform - additional testing and debugging with the final .apk.</p> - - <p>Before you start building your application in release mode, be aware that you must sign the - resulting application package with your private key, and should then align it using the {@code - zipalign} tool. There are two approaches to building in release mode: build an unsigned package - in release mode and then manually sign and align the package, or allow the build script to sign - and align the package for you.</p> - - <h3 id="ManualReleaseMode">Build unsigned</h3> - - <p>If you build your application <em>unsigned</em>, then you will need to manually sign and align - the package.</p> - - <p>To build an <em>unsigned</em> .apk in release mode:</p> - - <ol> - <li>Open a command-line and navigate to the root of your project directory.</li> - - <li>Use Ant to compile your project in release mode: - <pre> -ant release -</pre> - </li> - </ol> - - <p>This creates your Android application .apk file inside the project <code>bin/</code> - directory, named <code><em><your_project_name></em>-unsigned.apk</code>.</p> - - <p class="note"><strong>Note:</strong> The .apk file is <em>unsigned</em> at this point and can't - be installed until signed with your private key.</p> - - <p>Once you have created the unsigned .apk, your next step is to sign the .apk with your private - key and then align it with {@code zipalign}. To complete this procedure, read <a href= - "{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>.</p> - - <p>When your <code>.apk</code> has been signed and aligned, it's ready to be distributed to end-users. - You should test the final build on different devices or AVDs to ensure that it - runs properly on different platforms.</p> - - <h3 id="AutoReleaseMode">Build signed and aligned</h3> - - <p>If you would like, you can configure the Android build script to automatically sign and align - your application package. To do so, you must provide the path to your keystore and the name of - your key alias in your project's {@code ant.properties} file. With this information provided, - the build script will prompt you for your keystore and alias password when you build in release - mode and produce your final application package, which will be ready for distribution.</p> - - <p class="caution"><strong>Caution:</strong> Due to the way Ant handles input, the password that - you enter during the build process <strong>will be visible</strong>. If you are concerned about - your keystore and alias password being visible on screen, then you may prefer to perform the - application signing manually, via Jarsigner (or a similar tool). To instead perform the signing - procedure manually, <a href="#ManualReleaseMode">build unsigned</a> and then continue with - <a href="{@docRoot}tools/publishing/app-signing.html">Signing Your Applications</a>.</p> - - <p>To specify your keystore and alias, open the project {@code ant.properties} file (found in - the root of the project directory) and add entries for {@code key.store} and {@code key.alias}. - For example:</p> - <pre> -key.store=path/to/my.keystore -key.alias=mykeystore -</pre> - - <p>Save your changes. Now you can build a <em>signed</em> .apk in release mode:</p> - - <ol> - <li>Open a command-line and navigate to the root of your project directory.</li> - - <li>Use Ant to compile your project in release mode: - <pre> -ant release -</pre> - </li> - - <li>When prompted, enter you keystore and alias passwords. - - <p class="caution"><strong>Caution:</strong> As described above, your password will be - visible on the screen.</p> - </li> - </ol> - - <p>This creates your Android application .apk file inside the project <code>bin/</code> - directory, named <code><em><your_project_name></em>-release.apk</code>. This .apk file has - been signed with the private key specified in {@code ant.properties} and aligned with {@code - zipalign}. It's ready for installation and distribution.</p> - - <h3 id="OnceBuilt">Once built and signed in release mode</h3> - - <p>Once you have signed your application with a private key, you can install and run it on an - <a href="#RunningOnEmulator">emulator</a> or <a href="#RunningOnDevice">device</a>. You can - also try installing it onto a device from a web server. Simply upload the signed .apk to a web - site, then load the .apk URL in your Android web browser to download the application and begin - installation. (On your device, be sure you have enabled - <em>Settings > Applications > Unknown sources</em>.)</p> - - <h2 id="RunningOnEmulator">Running on the Emulator</h2> - - <p>Before you can run your application on the Android Emulator, you must <a href= - "{@docRoot}tools/devices/managing-avds.html">create an AVD</a>.</p> - - <p>To run your application:</p> - - <ol> - <li> - <strong>Open the AVD Manager and launch a virtual device</strong> - - <p>From your SDK's <code>platform-tools/</code> directory, execute the {@code android} tool -with the <code>avd</code> options:</p> - <pre> -android avd -</pre> - - <p>In the <em>Virtual Devices</em> view, select an AVD and click <strong>Start</strong>.</p> - </li> - - <li> - <strong>Install your application</strong> - - <p>From your SDK's <code>tools/</code> directory, install the {@code .apk} on the - emulator:</p> - <pre> -adb install <em><path_to_your_bin></em>.apk -</pre> - - <p>Your .apk file (signed with either a release or debug key) is in your project {@code bin/} - directory after you build your application.</p> - - <p>If there is more than one emulator running, you must specify the emulator upon which to - install the application, by its serial number, with the <code>-s</code> option. For - example:</p> - <pre> -adb -s emulator-5554 install <em>path/to/your/app</em>.apk -</pre> - - <p>To see a list of available device serial numbers, execute {@code adb devices}.</p> - </li> - </ol> - - <p>If you don't see your application on the emulator, try closing the emulator and launching the - virtual device again from the AVD Manager. Sometimes when you install an application for the - first time, it won't show up in the application launcher or be accessible by other applications. - This is because the package manager usually examines manifests completely only on emulator - startup.</p> - - <p>Be certain to create multiple AVDs upon which to test your application. You should have one - AVD for each platform and screen type with which your application is compatible. For instance, if - your application compiles against the Android 4.0 (API Level 14) platform, you should create an - AVD for each platform equal to and greater than 4.0 and an AVD for each <a href= - "{@docRoot}guide/practices/screens_support.html">screen type</a> you support, then test your - application on each one.</p> - - <p class="note"><strong>Tip:</strong> If you have <em>only one</em> emulator running, you can - build your application and install it on the emulator in one simple step. Navigate to the root of - your project directory and use Ant to compile the project with <em>install mode</em>: <code>ant - install</code>. This will build your application, sign it with the debug key, and install it on - the currently running emulator.</p> - - <h2 id="RunningOnDevice">Running on a Device</h2> - - <p>Before you can run your application on a device, you must perform some basic setup for your - device:</p> - - <ul> - <li>Enable <strong>USB debugging</strong> on your device. - <ul> - <li>On most devices running Android 3.2 or older, you can find the option under - <strong>Settings > Applications > Development</strong>.</li> - <li>On Android 4.0 and newer, it's in <strong>Settings > Developer options</strong>. - <p class="note"><strong>Note:</strong> On Android 4.2 and newer, <strong>Developer - options</strong> is hidden by default. To make it available, go - to <strong>Settings > About phone</strong> and tap <strong>Build number</strong> - seven times. Return to the previous screen to find <strong>Developer options</strong>.</p> - </li> - </ul> - </li> - - <li>Ensure that your development computer can detect your device when connected via USB</li> - </ul> - - <p>Read <a href="{@docRoot}tools/device.html#setting-up">Setting up a Device for - Development</a> for more information.</p> - - <p>Once your device is set up and connected via USB, navigate to your SDK's <code>platform-tools/</code> - directory and install the <code>.apk</code> on the device:</p> - <pre> -adb -d install <em>path/to/your/app</em>.apk -</pre> - - <p>The {@code -d} flag specifies that you want to use the attached device (in case you also have - an emulator running).</p> - - <p>For more information on the tools used above, please see the following documents:</p> - - <ul> - <li><a href="{@docRoot}tools/help/android.html">android Tool</a></li> - - <li><a href="{@docRoot}tools/devices/emulator.html">Android Emulator</a></li> - - <li><a href="{@docRoot}tools/help/adb.html">Android Debug Bridge</a> (ADB)</li> - </ul> - - <h2 id="Signing">Application Signing</h2> - - <p>As you begin developing Android applications, understand that all Android applications must be - digitally signed before the system will install them on an emulator or device. There are two ways - to do this: with a <em>debug key</em> (for immediate testing on an emulator or development - device) or with a <em>private key</em> (for application distribution).</p> - - <p>The Android build tools help you get started by automatically signing your .apk files with a - debug key at build time. This means that you can compile your application and install it on the - emulator without having to generate your own private key. However, please note that if you intend - to publish your application, you <strong>must</strong> sign the application with your own private - key, rather than the debug key generated by the SDK tools.</p> - - <p>The ADT plugin helps you get started quickly by signing your .apk files with a debug key, - prior to installing them on an emulator or development device. This means that you can quickly - run your application from Eclipse without having to generate your own private key. No specific - action on your part is needed, provided ADT has access to Keytool. However, please note that if - you intend to publish your application, you <strong>must</strong> sign the application with your - own private key, rather than the debug key generated by the SDK tools.</p> - - <p>Please read <a href="{@docRoot}tools/publishing/app-signing.html">Signing Your - Applications</a>, which provides a thorough guide to application signing on Android and what it - means to you as an Android application developer. The document also includes a guide to exporting - and signing your application with the ADT's Export Wizard.</p> - - <h2 id="AntReference">Ant Command Reference</h2> - <dt><code>ant clean</code></dt> - <dd>Cleans the project. If you include the <code>all</code> target before <code>clean</code> -(<code>ant all clean</code>), other projects are also cleaned. For instance if you clean a -test project, the tested project is also cleaned.</dd> - - <dt><code>ant debug</code></dt> - <dd>Builds a debug package. Works on application, library, and test projects and compiles - dependencies as needed.</dd> - - <dt id="emma"><code>ant emma debug</code></dt> - <dd>Builds a test project while building the tested project with instrumentation turned on. - This is used to run tests with code coverage enabled.</dd> - - <dt><code>ant release</code></dt> - <dd>Builds a release package.</dd> - - <dt><code>ant instrument</code> - </dt> - <dd>Builds an instrumented debug package. This is generally called automatically when building a - test project with code coverage enabled (with the <code>emma</code> - target)</dd> - - <dt><code>ant <build_target> install</code></dt> - <dd>Builds and installs a package. Using <code>install</code> by itself fails.</dd> - - <dt><code>ant installd</code></dt> - <dd>Installs an already compiled debug package. This fails if the <code>.apk</code> is not - already built.</dd> - - <dt><code>ant installr</code></dt> - <dd>Installs an already compiled release package. This fails if the <code>.apk</code> is not - already built.</dd> - - <dt><code>ant installt</code></dt> - <dd>Installs an already compiled test package. Also installs the <code>.apk</code> of the - tested application. This fails if the <code>.apk</code> is not already built.</dd> - - <dt><code>ant installi</code></dt> - <dd>Installs an already compiled instrumented package. This is generally not used manually as - it's called when installing a test package. This fails if the <code>.apk</code> is not already - built.</dd> - - <dt><code>ant test</code></dt> - <dd>Runs the tests (for test projects). The tested and test <code>.apk</code> files must be - previously installed.</dd> - - <dt><code>ant debug installt test</code></dt> - <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and - runs the tests.</dd> - - <dt><code>ant emma debug install test</code></dt> - <dd>Builds a test project and the tested project, installs both <code>.apk</code> files, and - runs the tests with code coverage enabled.</dd> - diff --git a/docs/html/tools/building/building-eclipse.jd b/docs/html/tools/building/building-eclipse.jd index 79ef3de..89c3e16 100644 --- a/docs/html/tools/building/building-eclipse.jd +++ b/docs/html/tools/building/building-eclipse.jd @@ -34,12 +34,12 @@ parent.link=index.html <p>This document shows you how to run your application on an emulator or a real device from Eclipse—all of which is done using the debug version of your application. For more information about how to sign your application with a private key for release, see <a href= - "{@docRoot}tools/workflow/publishing/app-signing.html#ExportWizard">Signing Your Applications</a></p> + "{@docRoot}tools/publishing/app-signing.html#ExportWizard">Signing Your Applications</a></p> <h2 id="RunningOnEmulatorEclipse">Running on the emulator</h2> <p>Before you can run your application on the Android Emulator, you must <a href= - "{@docRoot}tools/workflow/devices/managing-avds.html">create an AVD</a>.</p> + "{@docRoot}tools/devices/managing-avds.html">create an AVD</a>.</p> <p>To run (or debug) your application, select <strong>Run</strong> > <strong>Run</strong> (or <strong>Run</strong> > <strong>Debug</strong>) from the Eclipse menu bar. The ADT plugin will @@ -100,7 +100,7 @@ parent.link=index.html <li>Ensure that your development computer can detect your device when connected via USB</li> </ul> - <p>Read <a href="{@docRoot}tools/workflow/devices/device.html">Using Hardware Devices</a> + <p>Read <a href="{@docRoot}tools/device.html">Using Hardware Devices</a> for more information.</p> <p>Once set up and your device is connected via USB, install your application on the device by diff --git a/docs/html/tools/building/manifest-merge.jd b/docs/html/tools/building/manifest-merge.jd index 54166ec..2253584 100644 --- a/docs/html/tools/building/manifest-merge.jd +++ b/docs/html/tools/building/manifest-merge.jd @@ -303,7 +303,12 @@ attribute value. </p> <p class="note"><strong>Note:</strong> Android Studio provides a default <code>${applicationId}</code> placeholder for the <code>build.gradle</code> -<code>applicationId</code> value that is not shown in the build file.</p> +<code>applicationId</code> value that is not shown in the build file. +When building an AAR (Android ARchive) package for library modules, do not provide an +automatic <code>@{applicationId}</code> placeholder in the +<a href="{@docRoot}tools/building/manifest-merge.html">manifest merge</a> settings. +Instead, use a different placeholder, such as <code>@{libApplicationId}</code> and +provide a value for it if you want to include application Ids in the archive library. </p> <p>Manifest entry:</p> diff --git a/docs/html/tools/building/plugin-for-gradle.jd b/docs/html/tools/building/plugin-for-gradle.jd index 1ca19f8..513153d 100644 --- a/docs/html/tools/building/plugin-for-gradle.jd +++ b/docs/html/tools/building/plugin-for-gradle.jd @@ -1,4 +1,4 @@ -page.title=Android Plug-in for Gradle +page.title=Android Plugin for Gradle @jd:body diff --git a/docs/html/tools/data-binding/guide.jd b/docs/html/tools/data-binding/guide.jd index 7c4c15a..2de5bc2 100644 --- a/docs/html/tools/data-binding/guide.jd +++ b/docs/html/tools/data-binding/guide.jd @@ -28,6 +28,10 @@ page.tags="databinding", "layouts" <li> <a href="#binding_data">Binding Data</a> </li> + + <li> + <a href="#binding_events">Binding Events</a> + </li> </ol> </li> @@ -141,7 +145,7 @@ page.tags="databinding", "layouts" — it's a support library, so you can use it with all Android platform versions back to <strong>Android 2.1</strong> (API level 7+).</p> -<p>To use data binding, Android Plugin for Gradle <strong>1.3.0-beta1</strong> +<p>To use data binding, Android Plugin for Gradle <strong>1.3.0-beta4</strong> or higher is required.</p> <h4>Beta release</h4> @@ -187,9 +191,9 @@ or higher is required.</p> <p>To get started with Data Binding, download the library from the Support repository in the Android SDK manager. </p> -<p>The Data Binding plugin requires Android Plugin for Gradle <strong>1.3.0-beta1 -or higher</strong>, so update your build dependencies (in -<code>build.gradle</code>) as needed.</p> +<p>The Data Binding plugin requires Android Plugin for Gradle <strong>1.3.0-beta4 +or higher</strong>, so update your build dependencies (in the top-level +<code>build.gradle</code> file) as needed.</p> <p>Also, make sure you are using a compatible version of Android Studio. <strong>Android Studio 1.3</strong> adds the code-completion and layout-preview @@ -201,18 +205,18 @@ support for data binding.</p> <p> To set up your application to use data binding, add data binding to the class - path of your <code>build.gradle</code> file, right below "android". + path of your top-level <code>build.gradle</code> file, right below "android". </p> <pre> dependencies { - classpath <strong>"com.android.tools.build:gradle:1.3.0-beta1" - </strong>classpath <strong>"com.android.databinding:dataBinder:</strong>1.0-rc0" + classpath <strong>"com.android.tools.build:gradle:1.3.0-beta4"</strong> + classpath <strong>"com.android.databinding:dataBinder:1.0-rc1"</strong> } -} </pre> <p> - Then make sure jcenter is in the repositories list for your sub projects. + Then make sure jcenter is in the repositories list for your projects in the top-level + <code>build.gradle</code> file. </p> <pre> @@ -228,8 +232,8 @@ allprojects { </p> <pre> -apply plugin: ‘com.android.application' -apply plugin: '<strong>com.android.databinding</strong>' +apply plugin: 'com.android.application' +apply plugin: 'com.android.databinding' </pre> <p> The data binding plugin is going to add necessary <strong>provided</strong> @@ -252,23 +256,23 @@ apply plugin: '<strong>com.android.databinding</strong>' </p> <pre> -<em><?</em><strong>xml version="1.0" encoding="utf-8"</strong><em>?> -</em><<strong>layout xmlns:android="http://schemas.android.com/apk/res/android"</strong>> - <<strong>data</strong>> - <<strong>variable name="user" type="com.example.User"</strong>/> - </<strong>data</strong>> - <<strong>LinearLayout +<?xml version="1.0" encoding="utf-8"?> +<layout xmlns:android="http://schemas.android.com/apk/res/android"> + <data> + <variable name="user" type="com.example.User"/> + </data> + <LinearLayout android:orientation="vertical" android:layout_width="match_parent" - android:layout_height="match_parent"</strong>> - <<strong>TextView android:layout_width="wrap_content" + android:layout_height="match_parent"> + <TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.firstName}"</strong>/> - <<strong>TextView android:layout_width="wrap_content" + android:text="@{user.firstName}"/> + <TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.lastName}"</strong>/> - </<strong>LinearLayout</strong>> -</<strong>layout</strong>> + android:text="@{user.lastName}"/> + </LinearLayout> +</layout> </pre> <p> The user <strong>variable</strong> within <strong>data</strong> describes a @@ -285,9 +289,9 @@ apply plugin: '<strong>com.android.databinding</strong>' </p> <pre> -<<strong>TextView android:layout_width="wrap_content" +<TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.firstName}"</strong>/> + android:text="@{user.firstName}"/> </pre> <h3 id="data_object"> Data Object @@ -298,12 +302,12 @@ apply plugin: '<strong>com.android.databinding</strong>' </p> <pre> -<strong>public class </strong>User { - <strong>public final </strong>String <strong>firstName</strong>; - <strong>public final </strong>String <strong>lastName</strong>; - <strong>public </strong>User(String firstName, String lastName) { - <strong>this</strong>.<strong>firstName </strong>= firstName; - <strong>this</strong>.<strong>lastName </strong>= lastName; +public class User { + public final String firstName; + public final String lastName; + public User(String firstName, String lastName) { + this.firstName = firstName; + this.lastName = lastName; } } </pre> @@ -314,18 +318,18 @@ apply plugin: '<strong>com.android.databinding</strong>' </p> <pre> -<strong>public class </strong>User { - <strong>private final </strong>String <strong>firstName</strong>; - <strong>private final </strong>String <strong>lastName</strong>; - <strong>public </strong>User(String firstName, String lastName) { - <strong>this</strong>.<strong>firstName </strong>= firstName; - <strong>this</strong>.<strong>lastName </strong>= lastName; +public class User { + private final String firstName; + private final String lastName; + public User(String firstName, String lastName) { + this.firstName = firstName; + this.lastName = lastName; } - <strong>public </strong>String getFirstName() { - <strong>return this</strong>.<strong>firstName</strong>; + public String getFirstName() { + return this.firstName; } - <strong>public </strong>String getLastName() { - <strong>return this</strong>.<strong>lastName</strong>; + public String getLastName() { + return this.lastName; } } </pre> @@ -334,7 +338,8 @@ apply plugin: '<strong>com.android.databinding</strong>' expression <strong><code>@{user.firstName}</code></strong> used for the TextView’s <strong><code>android:text</code></strong> attribute will access the <strong><code>firstName</code></strong> field in the former class - and the <code>getFirstName()</code> method in the latter class. + and the <code>getFirstName()</code> method in the latter class. Alternatively, it + will also be resolved to <code>firstName()</code> if that method exists. </p> <h3 id="binding_data"> @@ -344,8 +349,8 @@ apply plugin: '<strong>com.android.databinding</strong>' <p> By default, a Binding class will be generated based on the name of the layout file, converting it to Pascal case and suffixing “Binding” to it. The above - layout file was <code>activity_main.xml</code> so the generate class was - <code>ActivityMainBinding</code>. This class holds all the bindings from the + layout file was <code>main_activity.xml</code> so the generate class was + <code>MainActivityBinding</code>. This class holds all the bindings from the layout properties (e.g. the <code>user</code> variable) to the layout’s Views and knows how to assign values for the binding expressions.The easiest means for creating the bindings is to do it while inflating: @@ -353,10 +358,10 @@ apply plugin: '<strong>com.android.databinding</strong>' <pre> @Override -<strong>protected void </strong>onCreate(Bundle savedInstanceState) { - <strong>super</strong>.onCreate(savedInstanceState); - ActivityMainBinding binding = DataBindingUtil.<em>setContentView</em>(<strong>this</strong>, R.layout.<em><strong>main_activity</strong></em>); - User user = <strong>new </strong>User(<strong>"Test"</strong>, <strong>"User"</strong>); +protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + MainActivityBinding binding = DataBindingUtil.setContentView(this, R.layout.main_activity); + User user = new User("Test", "User"); binding.setUser(user); } </pre> @@ -374,11 +379,55 @@ MainActivityBinding binding = MainActivityBinding.<em>inflate</em>(getLayoutInfl </p> <pre> -ListItemBinding binding = ListItemBinding.inflate(layoutInflater, viewGroup, -false); +ListItemBinding binding = ListItemBinding.inflate(layoutInflater, viewGroup, false); //or ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.layout.<em><strong>list_item</strong></em>, viewGroup, <strong>false</strong>); </pre> + +<h3 id="binding_events"> + Binding Events +</h3> +<p> + Events may be bound to handler methods directly, similar to the way + <strong><code>android:onClick</code></strong> can be assigned to a method in the Activity. + Event attribute names are governed by the name of the listener method with a few exceptions. + For example, {@link android.view.View.OnLongClickListener} has a method {@link android.view.View.OnLongClickListener#onLongClick onLongClick()}, + so the attribute for this event is <code>android:onLongClick</code>. +</p> +<p> + To assign an event to its handler, use a normal binding expression, with the value + being the method name to call. For example, if your data object has two methods: +</p> +<pre>public class MyHandlers { + public void onClickFriend(View view) { ... } + public void onClickEnemy(View view) { ... } +} +</pre> +<p> + The binding expression can assign the click listener for a View: +</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<layout xmlns:android="http://schemas.android.com/apk/res/android"> + <data> + <variable name="handlers" type="com.example.Handlers"/> + <variable name="user" type="com.example.User"/> + </data> + <LinearLayout + android:orientation="vertical" + android:layout_width="match_parent" + android:layout_height="match_parent"> + <TextView android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@{user.firstName}" + android:onClick="@{user.isFriend ? handlers.onClickFriend : handlers.onClickEnemy}"/> + <TextView android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:text="@{user.lastName}" + android:onClick="@{user.isFriend ? handlers.onClickFriend : handlers.onClickEnemy}"/> + </LinearLayout> +</layout> +</pre> <h2 id="layout_details"> Layout Details </h2> @@ -394,20 +443,20 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>data</strong>> - <<strong>import type="android.view.View"</strong>/> -</<strong>data</strong>> +<data> + <import type="android.view.View"/> +</data> </pre> <p> Now, View may be used within your binding expression: </p> <pre> -<<strong>TextView +<TextView android:text="@{user.lastName}" android:layout_width="wrap_content" android:layout_height="wrap_content" - android:visibility="@{user.isAdult ? View.VISIBLE : View.GONE}"</strong>/> + android:visibility="@{user.isAdult ? View.VISIBLE : View.GONE}"/> </pre> <p> When there are class name conflicts, one of the classes may be renamed to an @@ -415,9 +464,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>import type="android.view.View"</strong>/> -<<strong>import type="com.example.real.estate.View" - alias="Vista"</strong>/> +<import type="android.view.View"/> +<import type="com.example.real.estate.View" + alias="Vista"/> </pre> <p> Now, <strong><code>Vista</code></strong> may be used to reference the @@ -428,12 +477,12 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>data</strong>> - <<strong>import type="com.example.User"</strong>/> - <<strong>import type="java.util.List"</strong>/> - <<strong>variable name="user" type="User"</strong>/> - <<strong>variable name="userList" type="List&lt;User>"</strong>/> - </<strong>data</strong>> +<data> + <import type="com.example.User"/> + <import type="java.util.List"/> + <variable name="user" type="User"/> + <variable name="userList" type="List&lt;User>"/> +</data> </pre> <p class="caution"> <strong>Note</strong>: Android Studio does not yet handle imports so the @@ -443,10 +492,10 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>TextView +<TextView android:text="@{((User)(user.connection)).lastName}" android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> + android:layout_height="wrap_content"/> </pre> <p> Imported types may also be used when referencing static fields and methods in @@ -454,15 +503,15 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>data</strong>> - <<strong>import type="com.example.MyStringUtils"</strong>/> - <<strong>variable name="user" type="com.example.User"</strong>/> -</<strong>data</strong>> +<data> + <import type="com.example.MyStringUtils"/> + <variable name="user" type="com.example.User"/> +</data> … -<<strong>TextView +<TextView android:text="@{MyStringUtils.capitalize(user.lastName)}" android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> + android:layout_height="wrap_content"/> </pre> <p> Just as in Java, <code>java.lang.*</code> is imported automatically. @@ -481,16 +530,16 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>data</strong>> - <<strong>import type="android.graphics.drawable.Drawable"</strong>/> - <<strong>variable name="user" type="com.example.User"</strong>/> - <<strong>variable name="image" type="Drawable"</strong>/> - <<strong>variable name="note" type="String"</strong>/> -</<strong>data</strong>> +<data> + <import type="android.graphics.drawable.Drawable"/> + <variable name="user" type="com.example.User"/> + <variable name="image" type="Drawable"/> + <variable name="note" type="String"/> +</data> </pre> <p> The variable types are inspected at compile time, so if a variable implements - <a href="#observable_objects">Observable</a> or is an <a href= + {@link android.databinding.Observable} or is an <a href= "#observable_collections">observable collection</a>, that should be reflected in the type. If the variable is a base class or interface that does not implement the Observable* interface, the variables will <strong>not @@ -533,9 +582,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>data class="ContactItem"</strong>> +<data class="ContactItem"> ... -</<strong>data</strong>> +</data> </pre> <p> This generates the binding class as <code>ContactItem</code> in the @@ -545,9 +594,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>data class=".ContactItem"</strong>> +<data class=".ContactItem"> ... -</<strong>data</strong>> +</data> </pre> <p> In this case, <code>ContactItem</code> is generated in the module package @@ -555,9 +604,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<<strong>data class="com.example.ContactItem"</strong>> +<data class="com.example.ContactItem"> ... -</<strong>data</strong>> +</data> </pre> <h3 id="includes"> Includes @@ -570,28 +619,46 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<em><?</em><strong>xml version="1.0" encoding="utf-8"</strong><em>?> -</em><<strong>layout xmlns:android="http://schemas.android.com/apk/res/android" -</strong> <strong> xmlns:bind="http://schemas.android.com/apk/res-auto"</strong>> - <<strong>data</strong>> - <<strong>variable name="user" type="com.example.User"</strong>/> - </<strong>data</strong>> - <<strong>LinearLayout +<?xml version="1.0" encoding="utf-8"?> +<layout xmlns:android="http://schemas.android.com/apk/res/android" + xmlns:bind="http://schemas.android.com/apk/res-auto"> + <data> + <variable name="user" type="com.example.User"/> + </data> + <LinearLayout android:orientation="vertical" android:layout_width="match_parent" - android:layout_height="match_parent"</strong>> - <<strong>include layout="@layout/name" - bind:user="@{user}"</strong>/> - <<strong>include layout="@layout/contact" - bind:user="@{user}"</strong>/> - </<strong>LinearLayout</strong>> -</<strong>layout</strong>> + android:layout_height="match_parent"> + <include layout="@layout/name" + bind:user="@{user}"/> + <include layout="@layout/contact" + bind:user="@{user}"/> + </LinearLayout> +</layout> </pre> <p> Here, there must be a <code>user</code> variable in both the <code>name.xml</code> and <code>contact.xml</code> layout files. </p> - +<p> + Data binding does not support include as a direct child of a merge element. For example, + <strong>the following layout is not supported:</strong> +</p> +<pre> +<?xml version="1.0" encoding="utf-8"?> +<layout xmlns:android="http://schemas.android.com/apk/res/android" + xmlns:bind="http://schemas.android.com/apk/res-auto"> + <data> + <variable name="user" type="com.example.User"/> + </data> + <merge> + <include layout="@layout/name" + bind:user="@{user}"/> + <include layout="@layout/contact" + bind:user="@{user}"/> + </merge> +</layout> +</pre> <h3 id="expression_language"> Expression Language </h3> @@ -613,10 +680,10 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </li> <li> - <code>L</code>ogical <strong><code>&& ||</code></strong> + Logical <strong><code>&& ||</code></strong> </li> - <li>Binary <strong><code>&</code> <code>|</code> <code>^</code></strong> + <li>Binary <strong><code>& | ^</code></strong> </li> <li>Unary <strong><code>+ - ! ~</code></strong> @@ -659,9 +726,9 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </p> <pre> -<strong>android:text="@{String.valueOf(index + 1)}" +android:text="@{String.valueOf(index + 1)}" android:visibility="@{age &lt; 13 ? View.GONE : View.VISIBLE}" -android:transitionName='@{"image_" + id}'</strong> +android:transitionName='@{"image_" + id}' </pre> <h4 id="missing_operations"> Missing Operations @@ -746,23 +813,23 @@ android:transitionName='@{"image_" + id}'</strong> </p> <pre> -<<strong>data</strong>> - <<strong>import type="android.util.SparseArray"</strong>/> - <<strong>import type="java.util.Map"</strong>/> - <<strong>import type="java.util.List"</strong>/> - <<strong>variable name="list" type="List<String>"</strong>/> - <<strong>variable name="sparse" type="SparseArray&lt;String>"</strong>/> - <<strong>variable name="map" type="Map&lt;String, String>"</strong>/> - <<strong>variable name="index" type="int"</strong>/> - <<strong>variable name="key" type="String"</strong>/> -</<strong>data</strong>> +<data> + <import type="android.util.SparseArray"/> + <import type="java.util.Map"/> + <import type="java.util.List"/> + <variable name="list" type="List&lt;String>"/> + <variable name="sparse" type="SparseArray&lt;String>"/> + <variable name="map" type="Map&lt;String, String>"/> + <variable name="index" type="int"/> + <variable name="key" type="String"/> +</data> +… +android:text="@{list[index]}" … -<strong>android:text="@{list[index]}" -</strong>… -<strong>android:text="@{sparse[index]}" -</strong>… -<strong>android:text="@{map[key]}" -</strong> +android:text="@{sparse[index]}" +… +android:text="@{map[key]}" + </pre> <h4 id="string_literals"> String Literals @@ -774,7 +841,7 @@ android:transitionName='@{"image_" + id}'</strong> </p> <pre> -<strong>android:text='@{map["firstName"]}'</strong> +android:text='@{map["firstName"]}' </pre> <p> It is also possible to use double quotes to surround the attribute value. @@ -783,8 +850,8 @@ android:transitionName='@{"image_" + id}'</strong> </p> <pre> -<strong>android:text="@{map[`firstName`}" -android:text="@{map[&quot;firstName&quot;]}"</strong> +android:text="@{map[`firstName`}" +android:text="@{map[&quot;firstName&quot;]}" </pre> <h4 id="resources"> Resources @@ -796,15 +863,15 @@ android:text="@{map[&quot;firstName&quot;]}"</strong> </p> <pre> -<strong>android:padding="@{large? @dimen/largePadding : @dimen/smallPadding}"</strong> +android:padding="@{large? @dimen/largePadding : @dimen/smallPadding}" </pre> <p> Format strings and plurals may be evaluated by providing parameters: </p> <pre> -<strong>android:text="@{@string/nameFormat(firstName, lastName)}" -android:text="@{@plurals/banana(bananaCount)}"</strong> +android:text="@{@string/nameFormat(firstName, lastName)}" +android:text="@{@plurals/banana(bananaCount)}" </pre> <p> When a plural takes multiple parameters, all parameters should be passed: @@ -815,7 +882,7 @@ android:text="@{@plurals/banana(bananaCount)}"</strong> Have an orange Have %d oranges -android:text="<strong>@{@plurals/orange(orangeCount, orangeCount)}</strong>" +android:text="@{@plurals/orange(orangeCount, orangeCount)}" </pre> <p> Some resources require explicit type evaluation. @@ -836,9 +903,7 @@ android:text="<strong>@{@plurals/orange(orangeCount, orangeCount)} <tr> <td> - <pre> -String[] -</pre> + String[] </td> <td> @array @@ -901,9 +966,7 @@ String[] color <code>int</code> </td> <td> - <pre> -@color -</pre> + @color </td> <td> @color @@ -932,8 +995,9 @@ String[] a POJO will not cause the UI to update. The real power of data binding can be used by giving your data objects the ability to notify when data changes. There are three different data change notification mechanisms, - <code>Observable</code> objects, <code>ObservableField</code>s, and - <code>observable collections</code>. + <a href="#observable_objects">Observable objects</a>, + <a href="#observablefields">observable fields</a>, and + <a href="#observable_collections">observable collection</a>s. </p> <p> @@ -946,49 +1010,49 @@ String[] </h3> <p> - A class implementing <code>android.databinding.Observable</code> interface + A class implementing the {@link android.databinding.Observable} interface will allow the binding to attach a single listener to a bound object to listen for changes of all properties on that object. </p> <p> - The <code>Observable</code> interface has a mechanism to add and remove + The {@link android.databinding.Observable} interface has a mechanism to add and remove listeners, but notifying is up to the developer. To make development easier, - a base class, <code>BaseObservable,</code> was created to implement the + a base class, {@link android.databinding.BaseObservable}, was created to implement the listener registration mechanism. The data class implementer is still responsible for notifying when the properties change. This is done by - assigning a <code>Bindable</code> annotation to the getter and notifying in + assigning a {@link android.databinding.Bindable} annotation to the getter and notifying in the setter. </p> <pre> -<strong>private static class </strong>User <strong>extends </strong>BaseObservable { - <strong>private </strong>String <strong>firstName</strong>; - <strong>private </strong>String <strong>lastName</strong>; +private static class User extends BaseObservable { + private String firstName; + private String lastName; @Bindable - <strong>public </strong>String getFirstName() { - <strong>return this</strong>.<strong>firstName</strong>; + public String getFirstName() { + return this.firstName; } @Bindable - <strong>public </strong>String getFirstName() { - <strong>return this</strong>.<strong>lastName</strong>; + public String getLastName() { + return this.lastName; } - <strong>public void </strong>setFirstName(String firstName) { - <strong>this</strong>.<strong>firstName </strong>= firstName; + public void setFirstName(String firstName) { + this.firstName = firstName; notifyPropertyChanged(BR.firstName); } - <strong>public void </strong>setLastName(String lastName) { - <strong>this</strong>.<strong>lastName </strong>= lastName; + public void setLastName(String lastName) { + this.lastName = lastName; notifyPropertyChanged(BR.lastName); } } </pre> <p> - The <code>Bindable</code> annotation generates an entry in the BR class file + The {@link android.databinding.Bindable} annotation generates an entry in the BR class file during compilation. The BR class file will be generated in the module - package.If the base class for data classes cannot be changed, the - <code>Observable</code> interface may be implemented using the convenient - <code>PropertyChangeRegistry</code> to store and notify listeners + package. If the base class for data classes cannot be changed, the + {@link android.databinding.Observable} interface may be implemented using the convenient + {@link android.databinding.PropertyChangeRegistry} to store and notify listeners efficiently. </p> @@ -997,20 +1061,30 @@ String[] </h3> <p> - A little work is involved in creating Observable classes, so developers who - want to save time or have few properties may use ObservableFields. - ObservableFields are self-contained observable objects that have a single - field. There are versions for all primitive types and one for reference - types. To use, create a public final field in the data class: + A little work is involved in creating {@link android.databinding.Observable} classes, so + developers who want to save time or have few properties may use + {@link android.databinding.ObservableField} and its siblings + {@link android.databinding.ObservableBoolean}, + {@link android.databinding.ObservableByte}, + {@link android.databinding.ObservableChar}, + {@link android.databinding.ObservableShort}, + {@link android.databinding.ObservableInt}, + {@link android.databinding.ObservableLong}, + {@link android.databinding.ObservableFloat}, + {@link android.databinding.ObservableDouble}, and + {@link android.databinding.ObservableParcelable}. + <code>ObservableFields</code> are self-contained observable objects that have a single + field. The primitive versions avoid boxing and unboxing during access operations. + To use, create a public final field in the data class: </p> <pre> -<strong>private static class </strong>User <strong>extends </strong>BaseObservable { - <strong>public final </strong>ObservableField<String> <strong>firstName </strong>= - <strong>new </strong>ObservableField<>(); - <strong>public final </strong>ObservableField<String> <strong>lastName </strong>= - <strong>new </strong>ObservableField<>(); - <strong>public final </strong>ObservableInt <strong>age </strong>= <strong>new </strong>ObservableInt(); +private static class User { + public final ObservableField<String> firstName = + new ObservableField<>(); + public final ObservableField<String> lastName = + new ObservableField<>(); + public final ObservableInt age = new ObservableInt(); } </pre> <p> @@ -1018,8 +1092,8 @@ String[] </p> <pre> -user.<strong>firstName</strong>.set(<strong>"Google"</strong>); -<strong>int </strong>age = user.<strong>age</strong>.get(); +user.firstName.set("Google"); +int age = user.age.get(); </pre> <h3 id="observable_collections"> Observable Collections @@ -1027,43 +1101,44 @@ user.<strong>firstName</strong>.set(<strong>"Google"</strong>); <p> Some applications use more dynamic structures to hold data. Observable - collections allow keyed access to these data objects.ObservableArrayMap is + collections allow keyed access to these data objects. + {@link android.databinding.ObservableArrayMap} is useful when the key is a reference type, such as String. </p> <pre> -ObservableArrayMap<String, Object> user = <strong>new </strong>ObservableArrayMap<>(); -user.put(<strong>"firstName"</strong>, <strong>"Google"</strong>); -user.put(<strong>"lastName"</strong>, <strong>"Inc."</strong>); -user.put(<strong>"age"</strong>, 17); +ObservableArrayMap<String, Object> user = new ObservableArrayMap<>(); +user.put("firstName", "Google"); +user.put("lastName", "Inc."); +user.put("age", 17); </pre> <p> In the layout, the map may be accessed through the String keys: </p> <pre> -<<strong>data</strong>> - <<strong>import type="android.databinding.ObservableMap"</strong>/> - <<strong>variable name="user" type="ObservableMap&lt;String, Object>"</strong>/> -</<strong>data</strong>> +<data> + <import type="android.databinding.ObservableMap"/> + <variable name="user" type="ObservableMap&lt;String, Object>"/> +</data> … -<<strong>TextView +<TextView android:text='@{user["lastName"]}' android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> -<<strong>TextView + android:layout_height="wrap_content"/> +<TextView android:text='@{String.valueOf(1 + (Integer)user["age"])}' android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> + android:layout_height="wrap_content"/> </pre> <p> - ObservableArrayList is useful when the key is an integer: + {@link android.databinding.ObservableArrayList} is useful when the key is an integer: </p> <pre> -ObservableArrayList<Object> user = <strong>new </strong>ObservableArrayList<>(); -user.add(<strong>"Google"</strong>); -user.add(<strong>"Inc."</strong>); +ObservableArrayList<Object> user = new ObservableArrayList<>(); +user.add("Google"); +user.add("Inc."); user.add(17); </pre> <p> @@ -1071,20 +1146,20 @@ user.add(17); </p> <pre> -<<strong>data</strong>> - <<strong>import type="android.databinding.ObservableList"</strong>/> - <<strong>import type="com.example.my.app.Fields"</strong>/> - <<strong>variable name="user" type="ObservableList&lt;Object>"</strong>/> -</<strong>data</strong>> +<data> + <import type="android.databinding.ObservableList"/> + <import type="com.example.my.app.Fields"/> + <variable name="user" type="ObservableList&lt;Object>"/> +</data> … -<<strong>TextView +<TextView android:text='@{user[Fields.LAST_NAME]}' android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> -<<strong>TextView + android:layout_height="wrap_content"/> +<TextView android:text='@{String.valueOf(1 + (Integer)user[Fields.AGE])}' android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> + android:layout_height="wrap_content"/> </pre> <h2 id="generated_binding"> Generated Binding @@ -1094,7 +1169,7 @@ user.add(17); The generated binding class links the layout variables with the Views within the layout. As discussed earlier, the name and package of the Binding may be <a href="#custom_binding_class_names">customized</a>. The Generated binding - classes all extend <code>android.databinding.ViewDataBinding</code>. + classes all extend {@link android.databinding.ViewDataBinding}. </p> <h3 id="creating"> @@ -1107,13 +1182,13 @@ user.add(17); within the layout. There are a few ways to bind to a layout. The most common is to use the static methods on the Binding class.The inflate method inflates the View hierarchy and binds to it all it one step. There is a simpler - version that only takes a <code>LayoutInflater</code> and one that takes a - <code>ViewGroup</code> as well: + version that only takes a {@link android.view.LayoutInflater} and one that takes a + {@link android.view.ViewGroup} as well: </p> <pre> -MyLayoutBinding binding = MyLayoutBinding.<em>inflate</em>(<strong>layoutInflater</strong>); -MyLayoutBinding binding = MyLayoutBinding.<em>inflate</em>(LayoutInflater, viewGroup, false); +MyLayoutBinding binding = MyLayoutBinding.inflate(layoutInflater); +MyLayoutBinding binding = MyLayoutBinding.inflate(layoutInflater, viewGroup, false); </pre> <p> If the layout was inflated using a different mechanism, it may be bound @@ -1121,17 +1196,17 @@ MyLayoutBinding binding = MyLayoutBinding.<em>inflate</em>(LayoutInflater, viewG </p> <pre> -MyLayoutBinding binding = MyLayoutBinding.<em>bind</em>(viewRoot); +MyLayoutBinding binding = MyLayoutBinding.bind(viewRoot); </pre> <p> Sometimes the binding cannot be known in advance. In such cases, the binding - can be created using the DataBindingUtil class: + can be created using the {@link android.databinding.DataBindingUtil} class: </p> <pre> -ViewDataBinding binding = DataBindingUtil.<em>inflate</em>(LayoutInflater, layoutId, +ViewDataBinding binding = DataBindingUtil.inflate(LayoutInflater, layoutId, parent, attachToParent); -ViewDataBinding binding = DataBindingUtil.<em>bindTo</em>(viewRoot, layoutId); +ViewDataBinding binding = DataBindingUtil.bindTo(viewRoot, layoutId); </pre> <h3 id="views_with_ids"> Views With IDs @@ -1145,32 +1220,32 @@ ViewDataBinding binding = DataBindingUtil.<em>bindTo</em>(viewRoot, layoutId); </p> <pre> -<<strong>layout xmlns:android="http://schemas.android.com/apk/res/android"</strong>> - <<strong>data</strong>> - <<strong>variable name="user" type="com.example.User"</strong>/> - </<strong>data</strong>> - <<strong>LinearLayout +<layout xmlns:android="http://schemas.android.com/apk/res/android"> + <data> + <variable name="user" type="com.example.User"/> + </data> + <LinearLayout android:orientation="vertical" android:layout_width="match_parent" - android:layout_height="match_parent"</strong>> - <<strong>TextView android:layout_width="wrap_content" + android:layout_height="match_parent"> + <TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.firstName}"</strong> - <strong>android:id="@+id/firstName"</strong>/> - <<strong>TextView android:layout_width="wrap_content" + android:text="@{user.firstName}" + android:id="@+id/firstName"/> + <TextView android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="@{user.lastName}"</strong> - <strong>android:id="@+id/lastName"</strong>/> - </<strong>LinearLayout</strong>> -</<strong>layout</strong>> + android:text="@{user.lastName}" + android:id="@+id/lastName"/> + </LinearLayout> +</layout> </pre> <p> Will generate a binding class with: </p> <pre> -<strong>public final </strong>TextView <strong>firstName</strong>; -<strong>public final </strong>TextView <strong>lastName</strong>; +public final TextView firstName; +public final TextView lastName; </pre> <p> IDs are not nearly as necessary as without data binding, but there are still @@ -1186,49 +1261,49 @@ ViewDataBinding binding = DataBindingUtil.<em>bindTo</em>(viewRoot, layoutId); </p> <pre> -<<strong>data</strong>> - <<strong>import type="android.graphics.drawable.Drawable"</strong>/> - <<strong>variable name="user" type="com.example.User"</strong>/> - <<strong>variable name="image" type="Drawable"</strong>/> - <<strong>variable name="note" type="String"</strong>/> -</<strong>data</strong>> +<data> + <import type="android.graphics.drawable.Drawable"/> + <variable name="user" type="com.example.User"/> + <variable name="image" type="Drawable"/> + <variable name="note" type="String"/> +</data> </pre> <p> will generate setters and getters in the binding: </p> <pre> -<strong>public abstract </strong>com.example.User getUser(); -<strong>public abstract void </strong>setUser(com.example.User user); -<strong>public abstract </strong>Drawable getImage(); -<strong>public abstract void </strong>setImage(Drawable image); -<strong>public abstract </strong>String getNote(); -<strong>public abstract void </strong>setNote(String note); +public abstract com.example.User getUser(); +public abstract void setUser(com.example.User user); +public abstract Drawable getImage(); +public abstract void setImage(Drawable image); +public abstract String getNote(); +public abstract void setNote(String note); </pre> <h3 id="viewstubs"> ViewStubs </h3> <p> - ViewStubs are a little different from normal Views. They start off invisible + {@link android.view.ViewStub}s are a little different from normal Views. They start off invisible and when they either are made visible or are explicitly told to inflate, they replace themselves in the layout by inflating another layout. </p> <p> - Because the ViewStub essentially disappears from the View hierarchy, the View + Because the <code>ViewStub</code> essentially disappears from the View hierarchy, the View in the binding object must also disappear to allow collection. Because the - Views are final, a ViewStubProxy object takes the place of the ViewStub, - giving the developer access to the ViewStub when it exists and also access to - the inflated View hierarchy when the ViewStub has been inflated. + Views are final, a {@link android.databinding.ViewStubProxy} object takes the place of the + <code>ViewStub</code>, giving the developer access to the ViewStub when it exists and also + access to the inflated View hierarchy when the <code>ViewStub</code> has been inflated. </p> <p> When inflating another layout, a binding must be established for the new - layout. Therefore, the ViewStubProxy must listen to the ViewStub's - OnInflateListener and establish the binding at that time. Since only one can - exist, the ViewStubProxy allows the developer to set an OnInflateListener on - it that it will call after establishing the binding. + layout. Therefore, the <code>ViewStubProxy</code> must listen to the <code>ViewStub</code>'s + {@link android.view.ViewStub.OnInflateListener} and establish the binding at that time. Since + only one can exist, the <code>ViewStubProxy</code> allows the developer to set an + <code>OnInflateListener</code> on it that it will call after establishing the binding. </p> <h3 id="advanced_binding"> @@ -1241,20 +1316,20 @@ ViewDataBinding binding = DataBindingUtil.<em>bindTo</em>(viewRoot, layoutId); <p> At times, the specific binding class won't be known. For example, a - RecyclerView Adapter operating against arbitrary layouts won't know the - specific binding class. It still must assign the binding value during the - onBindViewHolder. + {@link android.support.v7.widget.RecyclerView.Adapter} operating against arbitrary layouts + won't know the specific binding class. It still must assign the binding value during the + {@link android.support.v7.widget.RecyclerView.Adapter#onBindViewHolder}. </p> <p> In this example, all layouts that the RecyclerView binds to have an "item" - variable. The BindingHolder has a getBinding method returning the - <code>ViewDataBinding</code> base. + variable. The <code>BindingHolder</code> has a <code>getBinding</code> method returning the + {@link android.databinding.ViewDataBinding} base. </p> <pre> -<strong>public void </strong>onBindViewHolder(BindingHolder holder, <strong>int </strong>position) { - <strong>final </strong>T item = <strong>mItems</strong>.get(position); +public void onBindViewHolder(BindingHolder holder, int position) { + final T item = mItems.get(position); holder.getBinding().setVariable(BR.item, item); holder.getBinding().executePendingBindings(); } @@ -1267,7 +1342,7 @@ ViewDataBinding binding = DataBindingUtil.<em>bindTo</em>(viewRoot, layoutId); When a variable or observable changes, the binding will be scheduled to change before the next frame. There are times, however, when binding must be executed immediately. To force execution, use the - <code>executePendingBindings()</code> method. + {@link android.databinding.ViewDataBinding#executePendingBindings()} method. </p> <h4> @@ -1321,17 +1396,18 @@ namespace for the attribute does not matter, only the attribute name itself. <p> Some attributes have setters that don't match by name. For these methods, an attribute may be associated with the setter through - BindingMethods annotation. This must be associated with a class and contains - BindingMethod annotations, one for each renamed method. For example, the - <strong><code>android:tint</code></strong> attribute is really associated - with setImageTintList, not setTint. + {@link android.databinding.BindingMethods} annotation. This must be associated with + a class and contains {@link android.databinding.BindingMethod} annotations, one for + each renamed method. For example, the <strong><code>android:tint</code></strong> attribute + is really associated with {@link android.widget.ImageView#setImageTintList}, not + <code>setTint</code>. </p> <pre> @BindingMethods({ - @BindingMethod(type = <strong>"android.widget.ImageView"</strong>, - attribute = <strong>"android:tint"</strong>, - method = <strong>"setImageTintList"</strong>), + @BindingMethod(type = "android.widget.ImageView", + attribute = "android:tint", + method = "setImageTintList"), }) </pre> <p> @@ -1347,7 +1423,7 @@ namespace for the attribute does not matter, only the attribute name itself. Some attributes need custom binding logic. For example, there is no associated setter for the <strong><code>android:paddingLeft</code></strong> attribute. Instead, <code>setPadding(left, top, right, bottom)</code> exists. - A static binding adapter method with the <code>BindingAdapter</code> + A static binding adapter method with the {@link android.databinding.BindingAdapter} annotation allows the developer to customize how a setter for an attribute is called. </p> @@ -1358,9 +1434,8 @@ namespace for the attribute does not matter, only the attribute name itself. </p> <pre> - -@BindingAdapter(<strong>"android:paddingLeft"</strong>) -<strong>public static void </strong>setPaddingLeft(View view, <strong>int </strong>padding) { +@BindingAdapter("android:paddingLeft") +public static void setPaddingLeft(View view, int padding) { view.setPadding(padding, view.getPaddingTop(), view.getPaddingRight(), @@ -1382,9 +1457,9 @@ namespace for the attribute does not matter, only the attribute name itself. </p> <pre> -@BindingAdapter({<strong>"bind:imageUrl"</strong>, <strong>"bind:error"</strong>}) -<strong>public static void </strong>loadImage(ImageView view, String url, Drawable error) { - Picasso.<em>with</em>(view.getContext()).load(url).error(error).into(view); +@BindingAdapter({"bind:imageUrl", "bind:error"}) +public static void loadImage(ImageView view, String url, Drawable error) { + Picasso.with(view.getContext()).load(url).error(error).into(view); } </pre> <pre> @@ -1406,6 +1481,123 @@ app:error=“@{@drawable/venueError}”/> </li> </ul> +<p> + Binding adapter methods may optionally take the old values in their handlers. A method + taking old and new values should have all old values for the attributes come first, followed + by the new values: +</p> +<pre> +@BindingAdapter("android:paddingLeft") +public static void setPaddingLeft(View view, int oldPadding, int newPadding) { + if (oldPadding != newPadding) { + view.setPadding(newPadding, + view.getPaddingTop(), + view.getPaddingRight(), + view.getPaddingBottom()); + } +} +</pre> +<p> + Event handlers may only be used with interfaces or abstract classes with one abstract method. + For example: +</p> +<pre> +@BindingAdapter("android:onLayoutChange") +public static void setOnLayoutChangeListener(View view, View.OnLayoutChangeListener oldValue, + View.OnLayoutChangeListener newValue) { + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) { + if (oldValue != null) { + view.removeOnLayoutChangeListener(oldValue); + } + if (newValue != null) { + view.addOnLayoutChangeListener(newValue); + } + } +} +</pre> +<p> + When a listener has multiple methods, it must be split into multiple listeners. For example, + {@link android.view.View.OnAttachStateChangeListener} has two methods: + {@link android.view.View.OnAttachStateChangeListener#onViewAttachedToWindow onViewAttachedToWindow()} and + {@link android.view.View.OnAttachStateChangeListener#onViewDetachedFromWindow onViewDetachedFromWindow()}. + We must then create two interfaces to differentiate the attributes and handlers for them. +</p> + +<pre> +@TargetApi(VERSION_CODES.HONEYCOMB_MR1) +public interface OnViewDetachedFromWindow { + void onViewDetachedFromWindow(View v); +} + +@TargetApi(VERSION_CODES.HONEYCOMB_MR1) +public interface OnViewAttachedToWindow { + void onViewAttachedToWindow(View v); +} +</pre> +<p> + Because changing one listener will also affect the other, we must have three different + binding adapters, one for each attribute and one for both, should they both be set. +</p> +<pre> +@BindingAdapter("android:onViewAttachedToWindow") +public static void setListener(View view, OnViewAttachedToWindow attached) { + setListener(view, null, attached); +} + +@BindingAdapter("android:onViewDetachedFromWindow") +public static void setListener(View view, OnViewDetachedFromWindow detached) { + setListener(view, detached, null); +} + +@BindingAdapter({"android:onViewDetachedFromWindow", "android:onViewAttachedToWindow"}) +public static void setListener(View view, final OnViewDetachedFromWindow detach, + final OnViewAttachedToWindow attach) { + if (VERSION.SDK_INT >= VERSION_CODES.HONEYCOMB_MR1) { + final OnAttachStateChangeListener newListener; + if (detach == null && attach == null) { + newListener = null; + } else { + newListener = new OnAttachStateChangeListener() { + @Override + public void onViewAttachedToWindow(View v) { + if (attach != null) { + attach.onViewAttachedToWindow(v); + } + } + + @Override + public void onViewDetachedFromWindow(View v) { + if (detach != null) { + detach.onViewDetachedFromWindow(v); + } + } + }; + } + final OnAttachStateChangeListener oldListener = ListenerUtil.trackListener(view, + newListener, R.id.onAttachStateChangeListener); + if (oldListener != null) { + view.removeOnAttachStateChangeListener(oldListener); + } + if (newListener != null) { + view.addOnAttachStateChangeListener(newListener); + } + } +} +</pre> +<p> + The above example is slightly more complicated than normal because View uses add and remove + for the listener instead of a set method for {@link android.view.View.OnAttachStateChangeListener}. + The <code>android.databinding.adapters.ListenerUtil</code> class helps keep track of the previous + listeners so that they may be removed in the Binding Adaper. +</p> +<p> + By annotating the interfaces <code>OnViewDetachedFromWindow</code> and + <code>OnViewAttachedToWindow</code> with + <code>@TargetApi(VERSION_CODES.HONEYCOMB_MR1)</code>, the data binding code + generator knows that the listener should only be generated when running on Honeycomb MR1 + and new devices, the same version supported by + {@link android.view.View#addOnAttachStateChangeListener}. +</p> <h2 id="converters"> Converters </h2> @@ -1426,10 +1618,10 @@ app:error=“@{@drawable/venueError}”/> </p> <pre> -<<strong>TextView +<TextView android:text='@{userMap["lastName"]}' android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> + android:layout_height="wrap_content"/> </pre> <p> @@ -1447,10 +1639,10 @@ The <code>userMap</code> returns an Object and that Object will be automatically </p> <pre> -<<strong>View +<View android:background="@{isError ? @color/red : @color/white}" android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> + android:layout_height="wrap_content"/> </pre> <p> Here, the background takes a <code>Drawable</code>, but the color is an @@ -1462,8 +1654,8 @@ The <code>userMap</code> returns an Object and that Object will be automatically <pre> @BindingConversion -<strong>public static </strong>ColorDrawable convertColorToDrawable(<strong>int </strong>color) { - <strong>return new </strong>ColorDrawable(color); +public static ColorDrawable convertColorToDrawable(int color) { + return new ColorDrawable(color); } </pre> <p> @@ -1472,8 +1664,8 @@ The <code>userMap</code> returns an Object and that Object will be automatically </p> <pre> -<<strong>View +<View android:background="@{isError ? @drawable/error : @color/white}" android:layout_width="wrap_content" - android:layout_height="wrap_content"</strong>/> + android:layout_height="wrap_content"/> </pre> diff --git a/docs/html/tools/debugging/annotations.jd b/docs/html/tools/debugging/annotations.jd index fe9f9cc..b0d5a22 100644 --- a/docs/html/tools/debugging/annotations.jd +++ b/docs/html/tools/debugging/annotations.jd @@ -7,7 +7,12 @@ page.title=Improving Code Inspection with Annotations <h2>In this document</h2> <ol> <li><a href="#adding-nullness">Adding Nullness Annotations</a></li> - <li><a href="#res-annotations">Adding Resource Annotation</a></li> + <li><a href="#res-annotations">Adding Resource Annotations</a></li> + <li><a href="#thread-annotations">Adding Thread Annotations</a></li> + <li><a href="#value-constraint">Adding Value Constraint Annotations</a></li> + <li><a href="#permissions">Adding Permission Annotations</a></li> + <li><a href="#check-result">Adding CheckResult Annotations</a></li> + <li><a href="#call-super">Adding CallSuper Annotations</a></li> <li><a href="#enum-annotations">Creating Enumerated Annotations</a></li> </ol> @@ -70,6 +75,10 @@ values in your code, for example:</p> <dt>{@link android.support.annotation.AnyRes @AnyRes}</dt> <dd>References any type of <a href="{@docRoot}reference/android/R.html"><code>R.</code></a> resource. </dd> + + <dt><code>@UiThread</code></dt> + <dd>Calls from a UI + <a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>. </dd> </dl> <p>For a complete list of the supported annotations, either examine the contents of the @@ -85,11 +94,14 @@ development tools.</p> <p>To add annotations to your code, first add a dependency to the {@link android.support.annotation Support-Annotations} library. In Android Studio, -add the dependency to your <code>build.gradle</code> file. </p> +add the dependency using the <strong>File > Project Structure > Dependencies</strong> menu +option or your <code>build.gradle</code> file. The following example shows how to add the +{@link android.support.annotation Support-Annotations} library dependency in the +<code>build.gradle</code> file: </p> <pre> dependencies { - compile 'com.android.support:support-annotations:22.0.0' + compile 'com.android.support:support-annotations:22.2.0' } </pre> @@ -143,18 +155,20 @@ inferring nullability in Android Studio, see <h2 id="res-annotations">Adding Resource Annotations</h2> -<p>Add {@link android.support.annotation.StringRes @StringRes} annotations to check that -a resource parameter contains a +<p>Validating resource types can be useful as Android references to resources, such as +<a href="{@docRoot}guide/topics/resources/drawable-resource.html"><code>Drawables</code></a> and +<a href="{@docRoot}reference/android/R.string.html"><code>R.string</code></a> resources, are +passed as integers. Code that expects a parameter to reference a specific type of resource, for +example <a href="{@docRoot}guide/topics/resources/drawable-resource.html"><code>Drawables</code></a>, +can be passed the expected reference type of <code>int</code>, but actually reference a different +type of resource, such as a <code>R.string</code></a> resource. </p> + +<p>For example, add {@link android.support.annotation.StringRes @StringRes} annotations to check +that a resource parameter contains a <a href="{@docRoot}reference/android/R.string.html"><code>R.string</code></a> reference. During code inspection, the annotation generates a warning if a <code>R.string</code> reference is not passed in the parameter.</p> -<p>Validating resource types can be useful as Android references to -<a href="{@docRoot}guide/topics/resources/drawable-resource.html"><code>Drawables</code></a> and -<a href="{@docRoot}reference/android/R.string.html"><code>R.string</code></a> resources are both -passed as integers. Code that expects a parameter to reference a <code>Drawable</code> can be passed -the expected reference type of int, but actually reference a <code>R.string</code></a> resource. </p> - <p>This example attaches the {@link android.support.annotation.StringRes @StringRes} annotation to the <code>resId</code> parameter to validate that it is really a string resource. </p> @@ -168,11 +182,135 @@ import android.support.annotation.StringRes; <p>Annotations for the other resource types, such as {@link android.support.annotation.DrawableRes @DrawableRes}, +{@link android.support.annotation.DimenRes @DimenRes}, {@link android.support.annotation.ColorRes @ColorRes}, and {@link android.support.annotation.InterpolatorRes @InterpolatorRes} can be added using the same annotation format and run during the code inspection. </p> + + +<h2 id="thread-annotations">Adding Thread Annotations</h2> +<p>Thread annotations check if a method is called from a specific type of +<a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>. The following thread +annotations are supported: </p> +<ul> + <li><code>@UiThread</code> </li> + <li><code>@MainThread</code> </li> + <li><code>@WorkerThread</code> </li> + <li><code>@BinderThread</code> +</ul> + +<p class="note"><strong>Note:</strong> The <code>@MainThread</code> +and the <code>@UiThread</code> annotations are interchangeable so +methods calls from either thread type are allowed for these annotations. </p> + + +<p>If all methods in a class share the same threading requirement, you can add a single +<a href="{@docRoot}guide/components/processes-and-threads.html">thread</a> +annotation to the class to verify that all methods in the class are called from the same type of +<a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>. </p> + +<p>A common use of the <a href="{@docRoot}guide/components/processes-and-threads.html">thread</a> +annotation is to validate method overrides in the +<a href="{@docRoot}reference/android/os/AsyncTask.html">AsyncTask</a> class as this class performs +background operations and publishes results only on the UI +<a href="{@docRoot}guide/components/processes-and-threads.html">thread</a>. </p> + + + +<h2 id="value-constraint">Adding Value Constraint Annotations</h2> +<p>Use the <code>@IntRange</code>, +<code>@FloatRange</code>, and +<code>@Size</code> annotations to validate the values of passed +parameters. </p> + +<p>The <code>@IntRange</code> annotation validates that the parameter +value is within a specified range. The following example ensures that the <code>alpha</code> +parameter contains an integer value from 0 to 255: </p> + +<pre> +public void setAlpha(@IntRange(from=0,to=255) int alpha) { … } +</pre> + +<p>The <code>@FloatRange</code> annotation checks that the parameter +value is within a specified range of floating point values. The following example ensures that the +<code>alpha</code> parameter contains a float value from 0.0 to 1.0: </p> + +<pre> +public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...} +</pre> + +<p>The <code>@Size</code> annotation checks the size of a collection or +array, as well as the length of a string. For example, use the <code>@Size(min=1)</code> +annotation to check if a collection is not empty, and the <code>@Size(2)</code> annotation to +validate that an array contains exactly two values. The following example ensures that the +<code>location</code> array contains at least one element: </p> + +<pre> +int[] location = new int[3]; +button.getLocationOnScreen(@Size(min=1) location); +</pre> + + +<h2 id="permissions">Adding Permission Annotations</h2> +<p>Use the <code>@RequiresPermission</code> annotation to +validate the permissions of the caller of a method. To check for a single permission from a +list the valid permissions, use the <code>anyOf</code> attribute. To check for a set of +permissions, use the <code>allOf</code> attribute. The following example annotates the +<code>setWallpaper</code> method to ensure that the caller of the method has the +<code>permission.SET_WALLPAPERS</code> permission. </p> + +<pre> +@RequiresPermission(Manifest.permission.SET_WALLPAPER) +public abstract void setWallpaper(Bitmap bitmap) throws IOException; +</pre> + +<p>This example requires the caller of the +<code>updateVisitedHistory</code> method to have both read and write bookmark history permissions. </p> + +<pre> +@RequiresPermission(allOf = { + Manifest.permission.READ_HISTORY_BOOKMARKS, + Manifest.permission.WRITE_HISTORY_BOOKMARKS}) +public static final void updateVisitedHistory(ContentResolver cr, String url, boolean real) { + ... +} +</pre> + + +<h2 id="check-result">Adding CheckResults Annotations</h2> +<p>Use the <code>@CheckResults</code> annotation to +validate that a method's result or return value is actually used. The following example annotates +the <code>checkPermissions</code> method to ensure the return value of the method is actually +referenced. It also names the +<a href="{@docRoot}reference/android/content/ContextWrapper.html#enforcePermission">enforcePermission</a> +method as a method to be suggested to the developer as a replacement. </p> + + + +<pre> +@CheckResult(suggest="#enforcePermission(String,int,int,String)") +public abstract int checkPermission(@NonNull String permission, int pid, int uid); +</pre> + +{@link android.support.annotation.StringDef @StringDef} + + +<h2 id="call-super">Adding CallSuper Annotations</h2> +<p>Use the <code>@CallSuper</code> annotation to validate that an +overriding method calls the super implementation of the method. The following example annotates +the <code>onCreate</code> method to ensure that any overriding method implementations call +<code>super.onCreate()</code>. </p> + +<pre> +@CallSuper +protected void onCreate(Bundle savedInstanceState) { +} +</pre> + + + <h2 id="enum-annotations">Creating Enumerated Annotations</h2> <p>Use the {@link android.support.annotation.IntDef @IntDef} and {@link android.support.annotation.StringDef @StringDef} annotations diff --git a/docs/html/tools/debugging/debugging-memory.jd b/docs/html/tools/debugging/debugging-memory.jd index 5893ad1..fc4f4be 100644 --- a/docs/html/tools/debugging/debugging-memory.jd +++ b/docs/html/tools/debugging/debugging-memory.jd @@ -24,22 +24,22 @@ page.tags=memory,OutOfMemoryError <p>Because Android is designed for mobile devices, you should always be careful about how much -random-access memory (RAM) your application uses. Although Dalvik and ART perform -routine garbage collection (GC), this doesn’t mean you can ignore when and where your application allocates and +random-access memory (RAM) your app uses. Although Dalvik and ART perform +routine garbage collection (GC), this doesn’t mean you can ignore when and where your app allocates and releases memory. In order to provide a stable user experience that allows the system to quickly -switch between apps, it is important that your application does not needlessly consume memory when the user +switch between apps, it is important that your app does not needlessly consume memory when the user is not interacting with it.</p> <p>Even if you follow all the best practices for <a href="{@docRoot}training/articles/memory.html" >Managing Your App Memory</a> during development (which you should), you still might leak objects or introduce other memory bugs. The -only way to be certain your application is using as little memory as possible is to analyze your app’s +only way to be certain your app is using as little memory as possible is to analyze your app’s memory usage with tools. This guide shows you how to do that.</p> <h2 id="LogMessages">Interpreting Log Messages</h2> -<p>The simplest place to begin investigating your application’s memory usage is the runtime log messages. +<p>The simplest place to begin investigating your app’s memory usage is the runtime log messages. Sometimes when a GC occurs, a message is printed to <a href="{@docRoot}tools/help/logcat.html">logcat</a>. The logcat output is also available in the Device Monitor or directly in IDEs such as Eclipse and Android Studio.</p> @@ -68,8 +68,8 @@ include: <dd>A concurrent GC that frees up memory as your heap begins to fill up.</dd> <dt><code>GC_FOR_MALLOC</code></dt> -<dd>A GC caused because your application attempted to allocate memory when your heap was -already full, so the system had to stop your application and reclaim memory.</dd> +<dd>A GC caused because your app attempted to allocate memory when your heap was +already full, so the system had to stop your app and reclaim memory.</dd> <dt><code>GC_HPROF_DUMP_HEAP</code></dt> <dd>A GC that occurs when you request to create an HPROF file to analyze your heap.</dd> @@ -107,9 +107,9 @@ a memory leak.</p> <h3 id="ARTLogMessages">ART Log Messages</h3> -<p>Unlike Dalvik, ART doesn't log messqages for GCs that were not explicity requested. GCs are only +<p>Unlike Dalvik, ART doesn't log messqages for GCs that were not explicitly requested. GCs are only printed when they are they are deemed slow. More precisely, if the GC pause exceeds than 5ms or -the GC duration exceeds 100ms. If the application is not in a pause perceptible process state, +the GC duration exceeds 100ms. If the app is not in a pause perceptible process state, then none of its GCs are deemed slow. Explicit GCs are always logged.</p> <p>ART includes the following information in its garbage collection log messages:</p> @@ -131,15 +131,15 @@ What triggered the GC and what kind of collection it is. Reasons that may appear include: <dl> <dt><code>Concurrent</code></dt> -<dd>A concurrent GC which does not suspend application threads. This GC runs in a background thread +<dd>A concurrent GC which does not suspend app threads. This GC runs in a background thread and does not prevent allocations.</dd> <dt><code>Alloc</code></dt> -<dd>The GC was initiated because your application attempted to allocate memory when your heap +<dd>The GC was initiated because your app attempted to allocate memory when your heap was already full. In this case, the garbage collection occurred in the allocating thread.</dd> <dt><code>Explicit</code> -<dd>The garbage collection was explicitly requested by an application, for instance, by +<dd>The garbage collection was explicitly requested by an app, for instance, by calling {@link java.lang.System#gc()} or {@link java.lang.Runtime#gc()}. As with Dalvik, in ART it is recommended that you trust the GC and avoid requesting explicit GCs if possible. Explicit GCs are discouraged since they block the allocating thread and unnecessarily was CPU cycles. Explicit GCs @@ -153,13 +153,13 @@ RenderScript allocation objects.</dd> <dd>The collection was caused by a heap transition; this is caused by switching the GC at run time. Collector transitions consist of copying all the objects from a free-list backed space to a bump pointer space (or visa versa). Currently collector transitions only occur when an -application changes process states from a pause perceptible state to a non pause perceptible state +app changes process states from a pause perceptible state to a non pause perceptible state (or visa versa) on low RAM devices. </dd> <dt><code>HomogeneousSpaceCompact</code></dt> <dd>Homogeneous space compaction is free-list space to free-list space compaction which usually -occurs when an application is moved to a pause imperceptible process state. The main reasons for doing +occurs when an app is moved to a pause imperceptible process state. The main reasons for doing this are reducing RAM usage and defragmenting the heap. </dd> @@ -230,13 +230,39 @@ The moving GCs have a long pause which lasts for the majority of the GC duration {@code 25MB/38MB} value in the above example). If this value continues to increase and doesn't ever seem to get smaller, you could have a memory leak. Alternatively, if you are seeing GC which are for the reason "Alloc", then you are already operating near your heap capacity and can expect -OOM exceptios in the near future. </p> +OOM exceptions in the near future. </p> <h2 id="ViewHeap">Viewing Heap Updates</h2> -<p>To get a little information about what kind of memory your application is using and when, you can view -real-time updates to your app's heap in the Device Monitor:</p> +<p>To get a little information about what kind of memory your app is using and when, you +can view real-time updates to your app's heap in Android Studio's +<a href="{@docRoot}tools/studio/index.html#heap-dump">HPROF viewer</a> or in the Device Monitor:</p> +<h3>Memory Monitor in Android Studio</h3> +<p>Use Android Studio to view your app's memory use: </p> +<ul> + <li>Start your app on a connected device or emulator.</li> + <li>Open the Android run-time window, and view the free and allocated memory in the Memory + Monitor. </li> + <li>Click the Dump Java Heap icon + (<img src="{@docRoot}images/tools/studio-dump-heap-icon.png" style="vertical-align:bottom;margin:0;height:21px"/>) + in the Memory Monitor toolbar. + <p>Android Studio creates the heap snapshot file with the filename + <code>Snapshot-yyyy.mm.dd-hh.mm.ss.hprof</code> in the <em>Captures</em> tab. </p> + </li> + <li>Double-click the heap snapshot file to open the HPROF viewer. + <p class="note"><strong>Note:</strong> To convert a heap dump to standard HPROF format in + Android Studio, right-click a heap snapshot in the <em>Captures</em> view and select + <strong>Export to standard .hprof</strong>.</p> </li> + <li>Interact with your app and click the + (<img src="{@docRoot}images/tools/studio-garbage-collect.png" style="vertical-align:bottom;margin:0;height:17px"/>) + icon to cause heap allocation. + </li> + <li>Identify which actions in your app are likely causing too much allocation and determine where + in your app you should try to reduce allocations and release resources. +</ul> + +<h3>Device Monitor </h3> <ol> <li>Open the Device Monitor. <p>From your <code><sdk>/tools/</code> directory, launch the <code>monitor</code> tool.</p> @@ -254,8 +280,9 @@ GC. To see the first update, click the <strong>Cause GC</strong> button.</p> showing the <strong>[1] Update Heap</strong> and <strong>[2] Cause GC</strong> buttons. The Heap tab on the right shows the heap results.</p> -<p>Continue interacting with your application to watch your heap allocation update with each garbage -collection. This can help you identify which actions in your application are likely causing too much + +<p>Continue interacting with your app to watch your heap allocation update with each garbage +collection. This can help you identify which actions in your app are likely causing too much allocation and where you should try to reduce allocations and release resources.</p> @@ -266,14 +293,40 @@ resources.</p> <p>As you start narrowing down memory issues, you should also use the Allocation Tracker to get a better understanding of where your memory-hogging objects are allocated. The Allocation Tracker can be useful not only for looking at specific uses of memory, but also to analyze critical -code paths in an application such as scrolling.</p> +code paths in an app such as scrolling.</p> -<p>For example, tracking allocations when flinging a list in your application allows you to see all the +<p>For example, tracking allocations when flinging a list in your app allows you to see all the allocations that need to be done for that behavior, what thread they are on, and where they came from. This is extremely valuable for tightening up these paths to reduce the work they need and improve the overall smoothness of the UI.</p> -<p>To use Allocation Tracker:</p> +<p>To use the Allocation Tracker, open the Memory Monitor in Android Studio and click the +<a href="{@docRoot}tools/studio/index.html#alloc-tracker" style="vertical-align:bottom;margin:0;height:21px"> +Allocation Tracker</a> icon. You can also track allocations in the Android Device Monitor:</p> + + +<h3>Android Studio </h3> +<p>To use the <a href="{@docRoot}tools/studio/index.html#alloc-tracker">Allocation Tracker</a> in +Android Studio: </p> + +<ol> + <li>Start your app on a connected device or emulator</li> + <li>Open the Android run-tme window, and view the free and allocated memory in the Memory + Monitor. </li> + <li>Click the Allocation Tracker icon + (<img src="{@docRoot}images/tools/studio-allocation-tracker-icon.png" style="vertical-align:bottom;margin:0;height:21px"/>) in the Memory Monitor tool bar to start and stop memory + allocations. + <p>Android Studio creates the allocation file with the filename + <code>Allocations-yyyy.mm.dd-hh.mm.ss.alloc</code> in the <em>Captures</em> tab. </p> + </li> + <li>Double-click the allocation file to open the Allocation viewer. </li> + <li>Identify which actions in your app are likely causing too much allocation and determine where + in your app you should try to reduce allocations and release resources. +</ol> + + + +<h3>Device Monitor</h3> <ol> <li>Open the Device Monitor. <p>From your <code><sdk>/tools/</code> directory, launch the <code>monitor</code> tool.</p> @@ -281,7 +334,7 @@ improve the overall smoothness of the UI.</p> <li>In the DDMS window, select your app's process in the left-side panel.</li> <li>In the right-side panel, select the <strong>Allocation Tracker</strong> tab.</li> <li>Click <strong>Start Tracking</strong>.</li> -<li>Interact with your application to execute the code paths you want to analyze.</li> +<li>Interact with your app to execute the code paths you want to analyze.</li> <li>Click <strong>Get Allocations</strong> every time you want to update the list of allocations.</li> </ol> @@ -293,7 +346,7 @@ thread, in which class, in which file and at which line.</p> <img src="{@docRoot}images/tools/monitor-tracker@2x.png" width="760" alt="" /> <p class="img-caption"><strong>Figure 2.</strong> The Device Monitor tool, -showing recent application allocations and stack traces in the Allocation Tracker.</p> +showing recent app allocations and stack traces in the Allocation Tracker.</p> <p class="note"><strong>Note:</strong> You will always see some allocations from {@code @@ -458,7 +511,7 @@ with all the others.</p> </dd> <dt><code>.so mmap</code> and <code>.dex mmap</code></dt> -<dd>The RAM being used for mmapped <code>.so</code> (native) and <code>.dex</code> (Dalvik or ART) +<dd>The RAM being used for mapped <code>.so</code> (native) and <code>.dex</code> (Dalvik or ART) code. The <code>Pss Total</code> number includes platform code shared across apps; the <code>Private Clean</code> is your app’s own code. Generally, the actual mapped size will be much larger—the RAM here is only what currently needs to be in RAM for code that has been executed by @@ -544,7 +597,7 @@ window, so this can help you identify memory leaks involving dialogs or other wi </dd> <dt><code>AppContexts</code> and <code>Activities</code></dt> -<dd>The number of application {@link android.content.Context} and {@link android.app.Activity} objects that +<dd>The number of app {@link android.content.Context} and {@link android.app.Activity} objects that currently live in your process. This can be useful to quickly identify leaked {@link android.app.Activity} objects that can’t be garbage collected due to static references on them, which is common. These objects often have a lot of other allocations associated with them and so @@ -553,7 +606,7 @@ are a good way to track large memory leaks.</dd> <p class="note"><strong>Note:</strong> A {@link android.view.View} or {@link android.graphics.drawable.Drawable} object also holds a reference to the {@link android.app.Activity} that it's from, so holding a {@link android.view.View} or {@link -android.graphics.drawable.Drawable} object can also lead to your application leaking an {@link +android.graphics.drawable.Drawable} object can also lead to your app leaking an {@link android.app.Activity}.</p> </dd> @@ -573,7 +626,12 @@ android.app.Activity}.</p> HPROF. Your app's heap dump provides information about the overall state of your app's heap so you can track down problems you might have identified while viewing heap updates.</p> -<p>To retrieve your heap dump:</p> + +<p>To retrieve your heap dump from within Android Studio, use the +<a href="{@docRoot}tools/studio/index.html#me-cpu">Memory Monitor</a> and +<a href="{@docRoot}tools/studio/index.html#heap-dump">HPROF viewer</a>. + +<p>You can also still perform these procedures in the Android monitor:</p> <ol> <li>Open the Device Monitor. <p>From your <code><sdk>/tools/</code> directory, launch the <code>monitor</code> tool.</p> @@ -589,13 +647,13 @@ then click <strong>Save</strong>.</li> showing the <strong>[1] Dump HPROF file</strong> button.</p> <p>If you need to be more precise about when the dump is created, you can also create a heap dump -at the critical point in your application code by calling {@link android.os.Debug#dumpHprofData +at the critical point in your app code by calling {@link android.os.Debug#dumpHprofData dumpHprofData()}.</p> <p>The heap dump is provided in a format that's similar to, but not identical to one from the Java HPROF tool. The major difference in an Android heap dump is due to the fact that there are a large number of allocations in the Zygote process. But because the Zygote allocations are shared across -all application processes, they don’t matter very much to your own heap analysis.</p> +all app processes, they don’t matter very much to your own heap analysis.</p> <p>To analyze your heap dump, you can use a standard tool like jhat or the <a href= "http://www.eclipse.org/mat/downloads.php">Eclipse Memory Analyzer Tool</a> (MAT). However, first @@ -609,7 +667,7 @@ hprof-conv heap-original.hprof heap-converted.hprof </pre> <p class="note"><strong>Note:</strong> If you're using the version of DDMS that's integrated into -Eclipse, you do not need to perform the HPROF converstion—it performs the conversion by +Eclipse, you do not need to perform the HPROF conversation—it performs the conversion by default.</p> <p>You can now load the converted file in MAT or another heap analysis tool that understands @@ -660,7 +718,7 @@ showing what your largest objects are. Below this chart, are links to couple of <p class="note"><strong>Note:</strong> Most apps will show an instance of {@link android.content.res.Resources} near the top with a good chunk of heap, but this is - usually expected when your application uses lots of resources from your {@code res/} directory.</p> + usually expected when your app uses lots of resources from your {@code res/} directory.</p> </li> </ul> @@ -699,19 +757,19 @@ to inspect the changes in memory allocation. To compare two heap dumps using MAT <h2 id="TriggerLeaks">Triggering Memory Leaks</h2> -<p>While using the tools described above, you should aggressively stress your application code and try -forcing memory leaks. One way to provoke memory leaks in your application is to let it +<p>While using the tools described above, you should aggressively stress your app code and try +forcing memory leaks. One way to provoke memory leaks in your app is to let it run for a while before inspecting the heap. Leaks will trickle up to the top of the allocations in -the heap. However, the smaller the leak, the longer you need to run the application in order to see it.</p> +the heap. However, the smaller the leak, the longer you need to run the app in order to see it.</p> <p>You can also trigger a memory leak in one of the following ways:</p> <ol> <li>Rotate the device from portrait to landscape and back again multiple times while in different -activity states. Rotating the device can often cause an application to leak an {@link android.app.Activity}, +activity states. Rotating the device can often cause an app to leak an {@link android.app.Activity}, {@link android.content.Context}, or {@link android.view.View} object because the system -recreates the {@link android.app.Activity} and if your application holds a reference +recreates the {@link android.app.Activity} and if your app holds a reference to one of those objects somewhere else, the system can't garbage collect it.</li> -<li>Switch between your application and another application while in different activity states (navigate to +<li>Switch between your app and another app while in different activity states (navigate to the Home screen, then return to your app).</li> </ol> diff --git a/docs/html/tools/help/hprof-conv.jd b/docs/html/tools/help/hprof-conv.jd index 982f337..89d6a68 100644 --- a/docs/html/tools/help/hprof-conv.jd +++ b/docs/html/tools/help/hprof-conv.jd @@ -18,3 +18,9 @@ to specify stdin or stdout. <p> You can use "-z" to filter out zygote allocations shared by all applications. </p> + +<p class="note"><strong>Note:</strong> Android Studio provides integrated access to this conversion +process. To convert a heap dump to standard HPROF format in Android Studio, right-click a heap +snapshot in the <em>Captures</em> view and select <strong>Export to standard .hprof</strong>. </p> + + diff --git a/docs/html/tools/help/sdk-manager.jd b/docs/html/tools/help/sdk-manager.jd index 0c77395..cc95edf 100644 --- a/docs/html/tools/help/sdk-manager.jd +++ b/docs/html/tools/help/sdk-manager.jd @@ -2,30 +2,59 @@ page.title=SDK Manager @jd:body -<p>The Android SDK separates tools, platforms, and other components into packages you can - download using the SDK Manager. For example, when the SDK Tools are updated or a new version of -the Android platform is released, you can use the SDK Manager to quickly download them to -your environment.</p> +<p>The Android SDK Manager separates the SDK tools, platforms, and other components into packages +for easy access and management. You can also customize which sites the SDK Manager checks for new +or updated SDK packages and add-on tools. For example, you can configure the SDK Manager +to automatically check for updates and notify you when an installed SDK Tools package is updated. +When you receive such a notification, you can then quickly decide whether to download the changes. </p> + +<p>By default, Android Studio does not check for Android SDK updates. To enable automatic Android +SDK checking: </p> +<ol> + <li>Choose <strong>File</strong> > <strong>Settings</strong> + > <strong>Appearance & Behavior</strong> > <strong>System Settings</strong> + > <strong>Updates</strong>. </li> + <li>Check the <strong>Automatically check updates for Android SDK</strong> checkbox and select an + <ahref="{@docRoot}tools/studio/studio-config.html#update-channel">update channel</a>.</li> + + + <li>Click <strong>OK</strong> or <strong>Apply</strong> to enable the update checking. </li> +</ol> <p>You can launch the SDK Manager in one of the following ways:</p> <ul> - <li>From Eclipse (with <a href="{@docRoot}tools/help/adt.html">ADT</a>), - select <strong>Window</strong> > <strong>Android SDK Manager</strong>.</li> - <li>From Android Studio, select <strong>Tools</strong> > <strong>Android</strong> - > <strong>SDK Manager</strong>.</li> - <li>On Windows, double-click the <code>SDK Manager.exe</code> file at the root of the Android -SDK directory.</li> - <li>On Mac or Linux, open a terminal and navigate to the <code>tools/</code> directory in the -location where the Android SDK is installed, then execute <code>android sdk</code>.</li> + <li>From the Android Studio <strong>File</strong> menu: <strong>File</strong> > + <strong>Settings</strong> > <strong>Appearance & Behavior</strong> > + <strong>System Settings</strong> > <strong>Android SDK</strong>.</li> + <li>From the Android Studio <strong>Tools</strong> menu: <strong>Tools</strong> > + <strong>Android</strong> > <strong>SDK Manager</strong>.</li> + <li>From the SDK Manager icon + (<img src="{@docRoot}images/tools/sdk-manager-studio.png" style="vertical-align:sub;margin:0;height:17px" alt="" />) + in the menu bar. </li> </ul> -<p>You can select which packages you want to download by toggling the checkboxes on the left, then -click <strong>Install</strong> to install the selected packages.</p> +<p class="note"><strong>Tip:</strong> The standalone SDK Manager is still available from the +command line, but we recommend it only for use with Eclipse ADT and standalone SDK installations.</p> -<img src="{@docRoot}images/sdk_manager_packages.png" alt="" /> -<p class="img-caption"><strong>Figure 1.</strong> The Android SDK Manager shows the -SDK packages that are available, already installed, or for which an update is available.</p> +<p>By default, the SDK Manager installs the latest packages and tools. Click the checkbox next to +each additional SDK platform and tool that you want to install. Clear the +checkbox to uninstall a SDK platform or tool. Click <strong>Apply</strong> or <strong>OK</strong> +to update the packages and tools. </p> +<p class="note"><strong>Tip:</strong> When an update is available for an installed +package, a hyphen (-) appears in the checkbox next to the package. A download icon +(<img src="{@docRoot}images/tools/studio-sdk-dwnld-icon.png" style="vertical-align:sub;margin:0;height:17px" alt="" />) +also appears next +to the checkbox to indicate the pending update. An update icon +(<img src="{@docRoot}images/tools/studio-sdk-removal-icon.png" style="vertical-align:sub;margin:0;height:17px" alt="" />) appears next to the checkbox to +indicate pending removals.</p> + +<p>Click the <em>SDK Update Sites</em> tab to manage which SDK sites Android Studio checks for +tool and add-on updates. </p> + +<img src="{@docRoot}images/tools/studio-sdk-manager-packages.png" alt="" /> +<p class="img-caption"><strong>Figure 1.</strong> The Android SDK Manager shows the +SDK platforms and packages that are available and installed along with the SDK update sites.</p> <p>There are several different packages available for the Android SDK. The table below describes most of the available packages and where they're located in your SDK directory @@ -33,8 +62,6 @@ once you download them.</p> - - <h2 id="Recommended">Recommended Packages</h2> <p>Here's an outline of the packages required and those we recommend you use: @@ -42,25 +69,32 @@ once you download them.</p> <dl> <dt>SDK Tools</dt> - <dd><strong>Required.</strong> Your new SDK installation already has the latest version. Make sure -you keep this up to date.</dd> + <dd><strong>Required.</strong> Your new SDK installation installs the latest version. Be sure + to respond to the Android Studio update prompts to keep your SDK Tools up-to-date.</dd> <dt>SDK Platform-tools</dt> - <dd><strong>Required.</strong> You must install this package when you install the SDK for -the first time.</dd> + <dd><strong>Required.</strong> Your new SDK installation installs the latest stable version. + Be sure to respond to the Android Studio update prompts to keep your SDK Platform-tools + up-to-date.</dd> <dt>SDK Platform</dt> - <dd><strong>Required.</strong>You must download <em>at least one platform</em> into your + <dd><strong>Required.</strong><em> At least one platform</em> is required in your environment so you're able to compile your application. In order to provide the best user experience on the latest devices, we recommend that you use the latest platform version as your build target. You'll still be able to run your app on older versions, but you must build against the latest version in order to use new features when running on devices with the latest version of Android. - <p>To get started, download the latest Android version, plus the lowest version you plan - to support (we recommend Android 2.2 for your lowest version).</p></dd> + <p>The SDK Manager downloads the latest Android version. It also downloads the earliest version + of Android (Android 2.2 (API level 8)) that we recommend that your app support. </p></dd> <dt>System Image</dt> <dd>Recommended. Although you might have one or more Android-powered devices on which to test your app, it's unlikely you have a device for every version of Android your app supports. It's a good practice to download system images for all versions of Android your app supports and test -your app running on them with the <a href="{@docRoot}tools/devices/emulator.html">Android emulator</a>.</dd> - <dt>Android Support</dt> +your app running on them with the +<a href="{@docRoot}tools/devices/emulator.html">Android emulator</a>. Each SDK platform package +contains the supported system images. Click <strong>Show Package Details</strong> to display the available +system images for each available platform. You can also download system images when creating +Android Virtual Devices (AVDs) in the +<a href="{@docRoot}tools/help/avd-manager.html">AVD Manager</a>. </dd> + + <dt>Android Support Library</dt> <dd>Recommended. Includes a static library that allows you to use some of the latest Android APIs (such as <a href="{@docRoot}guide/components/fragments.html">fragments</a>, plus others not included in the framework at all) on devices running @@ -68,13 +102,16 @@ a platform version as old as Android 1.6. All of the activity templates availabl a new project with the <a href="{@docRoot}tools/sdk/eclipse-adt.html">ADT Plugin</a> require this. For more information, read <a href="{@docRoot}tools/support-library/index.html">Support Library</a>.</dd> - <dt>SDK Samples</dt> - <dd>Recommended. The samples give you source code that you can use to learn about -Android, load as a project and run, or reuse in your own app. Note that multiple -samples packages are available — one for each Android platform version. When -you are choosing a samples package to download, select the one whose API Level -matches the API Level of the Android platform that you plan to use.</dd> -</dl> + + <dt>Android Support Repository</dt> + <dd>Recommended. Includes local Maven repository for Support libraries.</dd> + + <dt>Google Play services</dt> + <dd>Recommended. Includes Google Play services client library and sample code.</dd> + + <dt>Google Repository</dt> + <dd>Recommended. Includes local Maven repository for Google libraries.</dd> + <p class="note"><strong>Tip:</strong> For easy access to the SDK tools from a command line, add the location of the SDK's <code>tools/</code> and @@ -82,74 +119,40 @@ location of the SDK's <code>tools/</code> and <p>The above list is not comprehensive and you can <a -href="#AddingSites">add new sites</a> to download additional packages from third-parties.</p> +href="#AddingSites">add new sites</a> to download additional packages from third parties.</p> <p>In some cases, an SDK package may require a specific minimum revision of another package or SDK tool. The development tools will notify you with warnings if there is dependency that you need to -address. The Android SDK Manager also enforces dependencies by requiring that you download any +address. The Android SDK Manager also enforces dependencies by requiring any packages that are needed by those you have selected.</p> - - <h2 id="AddingSites">Adding New Sites</h2> -<p>By default, <strong>Available Packages</strong> displays packages available from the -<em>Android Repository</em> and <em>Third party Add-ons</em>. You can add other sites that host -their own Android SDK add-ons, then download the SDK add-ons -from those sites.</p> +<p>The <em>SDK Update Sites</em> tab displays the sites that Android Studio checks for Android SDK +and third-party updates. You can add other sites that host their own Android SDK add-ons, then +download the SDK add-ons from those sites.</p> <p>For example, a mobile carrier or device manufacturer might offer additional API libraries that are supported by their own Android-powered devices. In order to develop using their libraries, you must install their Android SDK add-on, if it's not already -available under <em>Third party Add-ons</em>. </p> +available as a <em>third-party add-on</em>. </p> <p>If a carrier or device manufacturer has hosted an SDK add-on repository file -on their web site, follow these steps to add their site to the Android SDK -Manager:</p> +on their website, follow these steps to add their site to the Android SDK Manager:</p> <ol> - <li>Select <strong>Available Packages</strong> in the left panel.</li> - <li>Click <strong>Add Add-on Site</strong> and enter the URL of the -<code>repository.xml</code> file. Click <strong>OK</strong>.</li> + <li>Click the <strong>SDK Update Sites</strong> tab.</li> + <li>Click the <strong>Add</strong> icon in the tools area and enter the name and URL of the + <code>add-on</code> site.</li> + <li>Click <strong>OK</strong>.</li> + <li>Make sure the checkbox is checked in the <em>Enabled</em> column.</li> + <li>Click <strong>OK</strong> or <strong>Apply</strong>.</li> </ol> -<p>Any SDK packages available from the site will now be listed under a new item named -<strong>User Add-ons</strong>.</p> - - - - -<h2 id="troubleshooting">Troubleshooting</h2> - -<p><strong>Problems connecting to the SDK repository</strong></p> - -<p>If you are using the Android SDK Manager to download packages and are encountering -connection problems, try connecting over http, rather than https. To switch the -protocol used by the Android SDK Manager, follow these steps: </p> - -<ol> - <li>With the Android SDK Manager window open, select "Settings" in the - left pane. </li> - <li>On the right, in the "Misc" section, check the checkbox labeled "Force - https://... sources to be fetched using http://..." </li> - <li>Click <strong>Save & Apply</strong>.</li> -</ol> - - - - - - - - - - - - - - +<p>Any SDK packages available from the site appear in the <em>SDK Platforms</em> or +<em>SDK Tools</em> tabs.</p> diff --git a/docs/html/tools/performance/allocation-tracker/index.jd b/docs/html/tools/performance/allocation-tracker/index.jd index e71b584..d68f601 100644 --- a/docs/html/tools/performance/allocation-tracker/index.jd +++ b/docs/html/tools/performance/allocation-tracker/index.jd @@ -90,19 +90,24 @@ page.article=true alt="" width="400px" /> <p class="img-caption"> - <strong>Figure 1. </strong>Steps for starting Allocation Tracker. + <strong>Figure 1. </strong>Steps for starting Allocation Tracker in Android DDMS. </p> </div> <li>Connect your mobile device to your computer.</li> - <li>Open your application in Android Studio, build the source, and run it on your device.</li> + <li>Open your application in Android Studio, build the source, and run it on your device or + emulator.</li> <li>Click the <b>Android</b> button at the bottom of your Android Studio window.</li> - <li>Click the RECORD button + <li>If you are using the Android Device Monitor, click the RECORD button <img src="{@docRoot}images/tools/performance/allocation-tracker/gettingstarted_image02.png"> - (Start Allocation Tracking tooltip).</li> + (Start Allocation Tracking tooltip) in the Android DDMS tool bar. If you are using Android + Studio, click the + <img src="{@docRoot}images/tools/performance/allocation-tracker/gettingstarted_image02.png"> + icon in the <a href="{@docRoot}tools/studio/index.html#mem-cpu">Memory Monitor</a> tool + bar. </li> <li>Interact with your application.</li> @@ -119,7 +124,7 @@ page.article=true alt="" width="440px" /> <p class="img-caption"> - <strong>Figure 2. </strong>Example of Allocation Tracker output. + <strong>Figure 2. </strong>Example of Allocation Tracker output in Android DDMS. </p> </div> diff --git a/docs/html/tools/performance/comparison.jd b/docs/html/tools/performance/comparison.jd index cf4b712..f79e762 100644 --- a/docs/html/tools/performance/comparison.jd +++ b/docs/html/tools/performance/comparison.jd @@ -86,7 +86,7 @@ page.article=true <h2 id="HeapViewer">Heap Viewer</h2> <div class="figure" style=""> - <img src="{@docRoot}images/tools/performance/compare_HeapViewer.png" + <img src="{@docRoot}images/tools/studio-hprof-viewer.png" alt="" height="" /> <p class="img-caption"> @@ -94,6 +94,7 @@ page.article=true </p> </div> + <ul> <li>Shows snapshots of a number of objects allocated by type.</li> @@ -110,7 +111,7 @@ page.article=true <h2 id="AllocationTracker">Allocation Tracker</h2> <div class="figure" style=""> - <img src="{@docRoot}images/tools/performance/compare_AllocationTracker.png" + <img src="{@docRoot}images/tools/studio-allocation-tracker.png" alt=""ge height="" /> <p class="img-caption"> diff --git a/docs/html/tools/performance/heap-viewer/index.jd b/docs/html/tools/performance/heap-viewer/index.jd index 9ca0c47..bfcbe1f 100644 --- a/docs/html/tools/performance/heap-viewer/index.jd +++ b/docs/html/tools/performance/heap-viewer/index.jd @@ -75,18 +75,23 @@ page.article=true alt="" width="400px" /> <p class="img-caption"> - <strong>Figure 1. </strong>Starting Android Device Monitor. + <strong>Figure 1. </strong>Starting Memory Monitor. </p> </div> <li>Connect your mobile device to your computer.</li> - <li>Open your application in Android Studio, build the source, and run it on your device.</li> + <li>Open your application in Android Studio, build the source, and run it on your device or + emulator.</li> - <li>Start the Android Device Monitor from Android Studio: <b>Tools -> Android -> Android - Device</b> <b>Monitor</b>. + <li>Start the Android Device Monitor from Android Studio: <strong>Tools -> Android + -> Android Device Monitor</strong>. -</ol> + <p>You can also start the <a href="{@docRoot}tools/studio/index.html#mem-cpu">Memory Monitor</a> + in Android Studio: Click the <em>Android</em> tab in the lower-left corner of the application + window. The CPU and Memory Monitor views appear.</p> </li> + + </ol> </div></li> <li><div style="overflow:hidden"> @@ -102,13 +107,7 @@ page.article=true </p> </div> - <li>Make sure your device and application are showing in the <b>Devices</b> tab.</li> - - <li>Click the <b>DDMS</b> button, because the Heap Viewer is one of the DDMS tools.</li> - - <li>Click the <b>Heap</b> tab, which is where your data will appear.</li> - - <li>In the <b>Devices</b> tab, select the app you want to monitor.</li> + <li>In the device and application drop-downs, select the app you want to monitor.</li> </ol> </div></li> @@ -126,7 +125,9 @@ page.article=true </p> </div> - <li>To start monitoring, click the Update Heap button, which looks like a green can.</li> + <li>To save a heap dump, click the Dump Java Heap icon. The heap snapshot file + with the filename <code>Snapshot-yyyy.mm.dd-hh.mm.ss.hprof</code> appears in the + <em>Captures</em> tab.</li> </ol> </div></li> @@ -147,7 +148,7 @@ page.article=true <li>Note the <em>Heap updates will happen after every GC for this client.</em> message.</li> - <li>Press the <strong>Cause CG</strong> button to + <li>Click the <strong>Initiate CG</strong> icon to trigger a garbage collection event. </li> </ol> @@ -166,12 +167,10 @@ page.article=true </p> </div> - <li>Click a data type to see detailed information on its current allocations on the - heap.</li> + <li>Double-click the heap snapshot file to open the heap viewer and see detailed information + about the current allocations on the heap.</li> </ol> </div></li> - <p class="note"><b>Note:</b> To visualize allocation changes over time, combine - several snapshots of the bar graph into an animated gif or video.</p> </ul> diff --git a/docs/html/tools/performance/memory-monitor/index.jd b/docs/html/tools/performance/memory-monitor/index.jd index 756ca14..a083a14 100644 --- a/docs/html/tools/performance/memory-monitor/index.jd +++ b/docs/html/tools/performance/memory-monitor/index.jd @@ -82,37 +82,18 @@ page.article=true </p> </div> - <li>Connect your mobile device to your computer.</li> + <li>If you're using a mobile device, connect it to your computer.</li> <li>Open your application in Android Studio, build the source, - and run it on your device.</li></li> - - <li>In Android Studio, choose <b>Tools > Android > Memory Monitor.</b></li> + and run it on your device or emulator.</li> + <li>In Android Studio, choose <strong> Tools > Android > Memory Monitor</strong>. You + can also click the <em>Android</em> tab in the lower-left corner of the application + window to launch the Android runtime window. The CPU and Memory Monitor views appear.</li> + </ol> </div></li> -<li><div style="overflow:hidden"> -<hr> - <ol class="padded" start="4"> - - <div class="figure" style=""> - <img src="{@docRoot}images/tools/performance/memory-monitor/gettingstarted_image002.png" - alt="" - width="400px" /> - <p class="img-caption"> - <strong>Figure 2. </strong>Choosing the device and Activity to monitor. - </p> - </div> - - <li>This opens the Memory Monitor pane.</li> - - <li>Choose your device from the drop-down menu at the top left of the pane.</li> - - <li>Choose your Activity from the drop-down menu at the top right of the pane.</li> - - </ol> -</div></li> <li><div style="overflow:hidden"> <hr> @@ -123,7 +104,7 @@ page.article=true alt="" width="400px" /> <p class="img-caption"> - <strong>Figure 3. </strong>Allocated and free memory in Memory Monitor. + <strong>Figure 1. </strong>Allocated and free memory in Memory Monitor. </p> </div> @@ -156,7 +137,7 @@ page.article=true alt="" width="400px" /> <p class="img-caption"> - <strong>Figure 4. </strong>Forcing a GC (Garbage Collection) event. + <strong>Figure 2. </strong>Forcing a GC (Garbage Collection) event. </p> </div> diff --git a/docs/html/tools/revisions/build-tools.jd b/docs/html/tools/revisions/build-tools.jd index e8706c1..1912bb2 100644 --- a/docs/html/tools/revisions/build-tools.jd +++ b/docs/html/tools/revisions/build-tools.jd @@ -78,6 +78,17 @@ listing in the Android SDK Manager.</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=""/>Build Tools, Revision 23.0.0</a> <em>(August 2015)</em> + </p> + <div class="toggle-content-toggleme"> + <p>Added support for the Android 6.0 (API level 23) release.</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=""/>Build Tools, Revision 22.0.1</a> <em>(March 2015)</em> </p> <div class="toggle-content-toggleme"> diff --git a/docs/html/tools/revisions/gradle-plugin.jd b/docs/html/tools/revisions/gradle-plugin.jd index 90ec44a..17e6d79 100644 --- a/docs/html/tools/revisions/gradle-plugin.jd +++ b/docs/html/tools/revisions/gradle-plugin.jd @@ -40,6 +40,106 @@ href="http://tools.android.com/knownissues">http://tools.android.com/knownissues <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=""/>Android Plugin for Gradle, Revision 1.3.0</a> <em>(July 2015)</em> + </p> + + <div class="toggle-content-toggleme"> + + <dl> + <dt>Dependencies:</dt> + + <dd> + <ul> + <li>Gradle 2.2.1 or higher.</li> + <li>Build Tools 21.1.1 or higher.</li> + </ul> + </dd> + + <dt>General Notes:</dt> + <dd> + <ul> + <li>Added support for the <code>com.android.build.threadPoolSize</code> property to control + the <code>Android</code> task thread pool size from the <code>gradle.properties</code> file + or the command line. The following example sets this property to 4. +<pre> +-Pcom.android.build.threadPoolSize=4 +</pre> + </li> + <li>Set the default build behavior to exclude <code>LICENSE</code> and <code>LICENSE.txt</code> + files from APKs. To include these files in an APK, remove these files from the + <code>packagingOptions.excludes</code> property in the <code>build.gradle</code> file. + For example: +<pre> +android { + packagingOptions.excludes = [] + } +</pre> + </li> + <li>Added the <code>sourceSets</code> task to inspect the set of all available source sets. </li> + <li>Enhanced unit test support to recognize multi-flavor and + <a href="{@docRoot}tools/building/configuring-gradle.html#workBuildVariants"> + build variant</a> source folders. For example, to test an app with multi-flavors + <code>flavor1</code> and <code>flavorA</code> with the <code>Debug</code> build type, + the test source sets are: + <ul> + <li>test </li> + <li>testFlavor1 </li> + <li>testFlavorA </li> + <li>testFlavor1FlavorA </li> + <li>testFlavor1FlavorADebug </li> + </ul> + <p>Android tests already recognized multi-flavor source folders. </p> </li> + <li>Improved unit test support to:</p> + <ul> + <li>Run <code>javac</code> on main and test sources, even if the <code>useJack</code> + property is set to <code>true</code> in your build file. </li> + <li>Correctly recognize dependencies for each build type. </li> + </ul> + </li> + <li>Added support for specifying instrumentation test-runner arguments from the command line. + For example: +<pre> +./gradlew connectedCheck \ + -Pandroid.testInstrumentationRunnerArguments.size=medium \ + -Pandroid.testInstrumentationRunnerArguments.class=TestA,TestB +</pre> + </li> + <li>Added support for arbitrary additional Android Asset Packaging Tool (AAPT) parameters + in the <code>build.gradle</code> file. For example: +<pre> +android { + aaptOptions { + additionalParameters "--custom_option", "value" + } +} +</pre> + </li> + + <li>Added support for a <a href="{@docRoot}tools/studio/studio-features.html#test-module"> + test APK module</a> as a separate test module, using the + <code>targetProjectPath</code> and <code>targetVariant</code> properties to set the APK + path and target variant. + <p class="note"><strong>Note:</strong> A test APK module does not support product + flavors and can only target a single variant. Also, Jacoco is not supported yet.</p> + </li> + <li>Added resource name validation before merging resources. </li> + <li>When building an AAR (Android ARchive) package for library modules, do not provide an + automatic <code>@{applicationId}</code> placeholder in the + <a href="{@docRoot}tools/building/manifest-merge.html">manifest merger</a> settings. + Instead, use a different placeholder, such as <code>@{libApplicationId}</code> and + provide a value for it if you want to include application Ids in the archive library. </li> + + </ul> + </dd> + </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 Plugin for Gradle, Revision 1.2.0</a> <em>(April 2015)</em> </p> diff --git a/docs/html/tools/revisions/platforms.jd b/docs/html/tools/revisions/platforms.jd index 8a31beb..61bfcbb 100644 --- a/docs/html/tools/revisions/platforms.jd +++ b/docs/html/tools/revisions/platforms.jd @@ -54,19 +54,40 @@ most recent release and restart the SDK Manager. If you do not, the latest Andro packages may not be available for download.</p> -<h2 id="5.1">Android 5.1</h2> +<h2 id="6.0">Android 6.0</h2> <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="" />Revision 1</a> <em>(August 2015)</em> + </p> + + <div class="toggle-content-toggleme"> + + <p>Initial release for Android 6.0 (API level 23). For more information, see the + <a href="{@docRoot}preview/api-overview.html">M Preview API Overview</a>.</p> + <p>Dependencies:</p> + <ul> + <li>Android SDK Platform-tools r23 or higher is required.</li> + <li>Android SDK Tools 24.3.4 or higher is required.</li> + </ul> + </div> + +</div> + + +<h2 id="5.1">Android 5.1</h2> + +<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="" />Revision 1</a> <em>(March 2015)</em> </p> <div class="toggle-content-toggleme"> - <p>Initial release for Android 5.1 (API level 22).</p> - <p>Also see the - <a href="{@docRoot}about/versions/android-5.1.html">Android 5.1 APIs overview</a>.</p> + <p>Initial release for Android 5.1 (API level 22). For more information, see the + <a href="{@docRoot}about/versions/android-5.1.html">Android 5.1 API Overview</a>.</p> <p>Dependencies:</p> <ul> <li>Android SDK Platform-tools r22 or higher is required.</li> @@ -77,7 +98,6 @@ class="toggle-content-img" alt="" />Revision 1</a> <em>(March 2015)</em> </div> - <h2 id="5.0">Android 5.0</h2> <div class="toggle-content closed"> @@ -104,9 +124,8 @@ class="toggle-content-img" alt="" />Revision 1</a> <em>(October 2014)</em> <div class="toggle-content-toggleme"> - <p>Initial release for Android 5.0 (API level 21).</p> - <p>Also see the - <a href="{@docRoot}about/versions/android-5.0.html">Android 5.0 APIs overview</a>.</p> + <p>Initial release for Android 5.0 (API level 21). For more information, see the + <a href="{@docRoot}about/versions/android-5.0.html">Android 5.0 API Overview</a>.</p> <p>Dependencies:</p> <ul> <li>Android SDK Platform-tools r21 or higher is required.</li> @@ -137,7 +156,7 @@ class="toggle-content-img" alt="" />Revision 2</a> <em>(October 2014)</em> <div class="toggle-content-toggleme"> - <p>Updated the rendering library. </p> + <p>Updated the rendering library.</p> <p>Dependencies:</p> <ul> @@ -183,9 +202,8 @@ class="toggle-content-img" alt="" />Revision 2</a> <em>(December 2013)</em> <div class="toggle-content-toggleme"> - <p>Maintenance release. The system version is 4.4.2.</p> - <p>Also see the - <a href="{@docRoot}about/versions/android-4.4.html">Android 4.4 APIs overview</a>.</p> + <p>Maintenance release. The system version is 4.4.2. For more information, see the + <a href="{@docRoot}about/versions/android-4.4.html">Android 4.4 API Overview</a>.</p> <dl> <dt>Dependencies:</dt> <dd>Android SDK Platform-tools r19 or higher is required.</dd> @@ -203,9 +221,8 @@ class="toggle-content-img" alt="" />Revision 1</a> <em>(October 2013)</em> <div class="toggle-content-toggleme"> - <p>Initial release. The system version is 4.4.</p> - <p>Also see the - <a href="{@docRoot}about/versions/android-4.4.html">Android 4.4 APIs overview</a>.</p> + <p>Initial release. The system version is 4.4. For more information, see the + <a href="{@docRoot}about/versions/android-4.4.html">Android 4.4 API Overview</a>.</p> <dl> <dt>Dependencies:</dt> <dd>Android SDK Platform-tools r19 or higher is required.</dd> diff --git a/docs/html/tools/revisions/studio.jd b/docs/html/tools/revisions/studio.jd index b727d96..c922b28 100644 --- a/docs/html/tools/revisions/studio.jd +++ b/docs/html/tools/revisions/studio.jd @@ -30,7 +30,7 @@ everything you need to begin developing Android apps:</p> <a href="{@docRoot}tools/studio/index.html">Android Studio</a> guide.</p> <p>Periodic updates are pushed to Android Studio without requiring you to update your Android -project. To manually check for updates, select <strong>Help > Check for updates</strong> (on Mac, +project. To manually check for updates, select <strong>Help > Check for update</strong> (on Mac, select <strong>Android Studio > Check for updates</strong>).</p> @@ -43,6 +43,85 @@ Android Studio, as denoted by revision number. </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=""/>Android Studio v1.3.1</a> <em>(August 2015)</em> + </p> + <div class="toggle-content-toggleme"> + <p>Fixes and enhancements:</p> + <ul> + <li>Fixed support for creating an Android Wear Android Virtual Device (AVD) on Windows. </li> + <li>Updated the <em>Project Wizard</em> to use the entered project name. </li> + <li>Added support to allow the Android SDK to be stored in a read-only directory. </li> + <li>Updated Android Plugin for Gradle version to 1.3.0. </li> + <li>Fixed issues with launching a debug session from the Android Debug Bridge (adb) Unix + shell. </li> + <li>Fixed the Java package renaming message to show the correct package name. </li> + </ul> + </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 Studio v1.3.0</a> <em>(July 2015)</em> + </p> + <div class="toggle-content-toggleme"> + <p>Fixes and enhancements:</p> + <ul> + <li>Added options to enable + <a href="{@docRoot}tools/studio/studio-features.html#dev-services">developer services</a>, + such as <a href="https://developers.google.com/admob/">AdMob</a> and + <a href="{@docRoot}distribute/analyze/start.html">Analytics</a>, in your app from within + Android Studio. </li> + <li>Added additional <a href="{@docRoot}tools/debugging/annotations.html">annotations</a>, + such as <code>@RequiresPermission</code>, <code>@CheckResults</code>, and + <code>@MainThread</code>. </li> + <li>Added the capability to generate Java heap dumps and analyze thread allocations from the + <a href="{@docRoot}tools/studio/index.html#mem-cpu">Memory Monitor</a>. You can also + convert Android-specific HPROF binary format files to standard HPROF format from within + Android Studio. </li> + <li>Integrated the <a href="{@docRoot}tools/help/sdk-manager.html">SDK Manager</a> + into Android Studio to simplify package and tools access and provide update notifications. + <p class="note"><strong>Note:</strong> The standalone SDK Manager is still available from + the command line, but is recommended for use with only Eclipse ADT and standalone SDK + installations. </p> </li> + <li>Added the <code>finger</code> command in the emulator console to simulate + <a href="{@docRoot}tools/studio/studio-features.html#finger-print">fingerprint</a> + authentication. </li> + <li>Added a <code><public></code> resource declaration to designate library + resources as + <a href="{@docRoot}tools/studio/studio-features.html#private-res">public and private</a> + resources. + <p class="note"><strong>Note:</strong> Requires + <a href="{@docRoot}tools/building/plugin-for-gradle.html">Android Plugin for Gradle</a> + version 1.3 or higher. </p> </li> + <li>Added <a href="{@docRoot}tools/data-binding/guide.html">data binding</a> support to + create declarative layouts that bind your application logic to layout elements. </li> + <li>Added support for a separate + <a href="{@docRoot}tools/studio/studio-features.html#test-module">test APK module</a> + to build test APKs in Android Studio. </li> + <li>Updated the <a href="{@docRoot}tools/help/avd-manager.html">AVD Manager</a> with HAXM + optimizations and improved notifications. </li> + <li>Added 64-bit ARM and MIPS emulator support for + <a class="external-link" href="http://wiki.qemu.org/Main_Page">QEMU</a> 2.1. </li> + <li>Simplified the resolution of <a href="{@docRoot}tools/help/lint.html">lint</a> warnings + by adding quick fixes, such as the automatic generation of + <a href="{@docRoot}reference/android/os/Parcelable.html">Parcelable</a> + implementation.</li> + <li>Added <a href="{@docRoot}sdk/installing/studio-tips.html#live-templates">live template</a> + support for quick insertion of code snippets. </li> + </ul> + </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 Studio v1.2.2</a> <em>(June 2015)</em> </p> <div class="toggle-content-toggleme"> diff --git a/docs/html/tools/sdk/tools-notes.jd b/docs/html/tools/sdk/tools-notes.jd index 934b262..da8d62cb 100644 --- a/docs/html/tools/sdk/tools-notes.jd +++ b/docs/html/tools/sdk/tools-notes.jd @@ -22,9 +22,63 @@ Tools you are using, refer to the "Installed Packages" listing in the Android SD href="http://tools.android.com/knownissues">http://tools.android.com/knownissues</a>.</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=""/>SDK Tools, Revision 24.3.4</a> <em>(August 2015)</em> + </p> + + <div class="toggle-content-toggleme"> + + <dl> + <dt>Dependencies:</dt> + + <dd> + <ul> + <li>Android SDK Platform-tools revision 23 or later.</li> + </ul> + </dd> + + <dt>General Notes:</dt> + <dd> + <ul> + <li>Added support for Android 6.0 (API level 23) platform.</li> + </ul> + </dd> + + <dt>Emulator:</dt> + <dd> + <ul> + <li>Improved emulator performance on multi-core Windows desktops. + (<a href="http://b.android.com/101040">Issue 101040</a>)</li> + <li>Added support for GPU emulation on Windows and Linux platforms using the + {@code -gpu mesa} command line option.</li> + <li>Enabled support for running emulators with GPU emulation through remote desktop + services, including Chrome Remote Desktop, Windows Terminal Services, and NoMachine.</li> + <li>Added support for emulators with 280 dpi and 360 dpi screen resolutions.</li> + <li>Improved support for GLES 2.0 extensions.</li> + <li>Fixed several issues with GPU emulation support.</li> + <li>Added support for setting the storage size on emulators using Android 4.4 (API level 19) + and higher. + (<a href="http://b.android.com/75141">Issue 75141</a>)</li> + <li>Fixed problem with sending long SMS messages between emulators. + (<a href="http://b.android.com/3539">Issue 3539</a>)</li> + <li>Fixed issue with emulator getting incorrect time from location objects. + (<a href="http://b.android.com/27272">Issue 27272</a>)</li> + <li>Added handling for unusual characters in paths and file names when starting emulators. + (<a href="http://b.android.com/35889">Issue 35889</a>)</li> + </ul> + </dd> + + </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=""/>SDK Tools, Revision 24.3.3</a> <em>(June 2015)</em> </p> @@ -50,8 +104,6 @@ href="http://tools.android.com/knownissues">http://tools.android.com/knownissues </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" diff --git a/docs/html/tools/studio/index.jd b/docs/html/tools/studio/index.jd index 5041b83..43cb2fe 100644 --- a/docs/html/tools/studio/index.jd +++ b/docs/html/tools/studio/index.jd @@ -50,7 +50,7 @@ Studio features.</p> <p>For specific Android Studio how-to documentation, see the pages in the <a href= "{@docRoot}tools/workflow/index.html">Workflow</a> section, such as <a href= -"{@docRoot}tools/projects/projects-studio.html">Managing Projects from Android Studio</a> and +"{@docRoot}sdk/installing/create-project.html">Managing Projects from Android Studio</a> and <a href="{@docRoot}tools/building/building-studio.html">Building and Running from Android Studio</a>. For a summary of the latest changes to Android Studio, see the <a href="{@docRoot}tools/revisions/studio.html">Android Studio Release Notes</a>.</p> @@ -206,6 +206,49 @@ runtime window to launch the Android runtime window. Click the <strong>Memory</s <img src="{@docRoot}images/tools/studio-memory-monitor.png" srcset="{@docRoot}images/tools/studio-memory-monitor_2x.png 2x" width"635" height="171" alt="" /> <p class="img-caption"><strong>Figure 4.</strong> Monitor memory and CPU usage.</p> +<h4 id="heap-dump">Heap dump </h4> +<p>When you're monitoring memory usage in Android Studio you can, at the same time, initiate +garbage collection and dump the Java heap to a heap snapshot in an Android-specific HPROF binary +format file. The HPROF viewer displays classes, instances of each class, and a reference tree to +help you track memory usage and find memory leaks. </p> + +<img src="{@docRoot}images/tools/studio-hprof-viewer.png" alt="" /> + <p class="img-caption"><strong>Figure 5.</strong> HPROF viewer with heap dump.</p> + +<p>To create a snapshot of the Android app heap memory, click the +Dump Java Heap icon (<img src="{@docRoot}images/tools/studio-dump-heap-icon.png" style="vertical-align:bottom;margin:0;height:17px"/>) +in the Memory Monitor. Android Studio creates the heap snapshot file with the filename +<code>Snapshot-yyyy.mm.dd-hh.mm.ss.hprof</code> +in the <em>Captures</em> tab. Double-click the heap snapshot file to open the HPROF viewer.</p> + +<p>To convert a heap dump to standard HPROF format in Android Studio, right-click a heap +snapshot in the <em>Captures</em> view and select <strong>Export to standard .hprof</strong>. </p> + + + +<h4 id="alloc-tracker">Allocation tracker </h4> +<p>Android Studio allows you to track memory allocation as it monitors memory use. Tracking memory +allocation allows you to monitor where objects are being allocated when you perform certain actions. +Knowing these allocations enables you to adjust the method +calls related to those actions to optimize your app's performance and memory use. </p> + +<img src="{@docRoot}images/tools/studio-allocation-tracker.png" alt="" /> + <p class="img-caption"><strong>Figure 6.</strong> Allocation tracker.</p> + +<p>Perform the following steps to track and analyze allocations: </p> +<ol> + <li>Click the Start/Stop Allocation Tracking icon + (<img src="{@docRoot}images/tools/studio-allocation-tracker-icon.png" style="vertical-align:bottom;margin:0;height:17px"/>) in the + <a href="#mem-cpu">Memory Monitor</a>. Android Studio starts tracking memory allocations.</li> + <li>Perform the tasks whose mallocs you want to track. </li> + <li>Click the Start/Stop Allocation Tracking icon again. Android Studio stops tracking mallocs + and saves the data to a file named <code>Allocation-yyyy.mm.dd-hh.mm.ss.alloc</code>. The + resulting file appears in the <em>Captures</em> tab. </li> + <li>Double-click the file to open it in the allocation viewer. + <p>The allocation viewer allows you to view and analyze the allocations your app made while + running. </p> </li> +</ol> + <h3>Data file access</h3> <p>The Android SDK tools, such as <a href="{@docRoot}tools/help/systrace.html">Systrace</a>, diff --git a/docs/html/tools/studio/studio-config.jd b/docs/html/tools/studio/studio-config.jd index f9646b8..88835d0 100644 --- a/docs/html/tools/studio/studio-config.jd +++ b/docs/html/tools/studio/studio-config.jd @@ -8,6 +8,7 @@ page.tags=studio, configuration <h2>In this document</h2> <ol> + <li><a href="#sdk-mgr">SDK Manager</a></li> <li><a href="#update-channel">Update Channels</a></li> <li><a href="#proxy">Proxy Settings</a></li> </ol> @@ -23,7 +24,7 @@ page.tags=studio, configuration </div> -<p>During installation, Android Studio provides wizards and templates that verify your system +<p>Android Studio provides wizards and templates that verify your system requirements, such as the Java Development Kit (JDK) and available RAM, and configure default settings, such as an optimized default Android Virtual Device (AVD) emulation and updated system images. This document describes additional configuration settings you may want to use to @@ -35,6 +36,20 @@ customize your use of Android Studio. </p> <a href="{@docRoot}tools/extras/oem-usb.html">OEM USB Drivers</a>. </p> +<h2 id="sdk-mgr">SDK Manager</h2> +<p>After the initial Android Studio installation and setup, use the +<a href="{@docRoot}tools/help/sdk-manager.html">SDK Manager</a> to verify and update the tools, +platforms, packages, and other components used by your apps. You can also use the +<strong>File</strong> > <strong>Settings</strong> > +<strong>Appearance & Behavior</strong> > <strong>System Settings</strong> > +<strong>Updates</strong> to configure the SDK Manager to automatically prompt whenever updates are +available. </p> + +<p class="note"><strong>Note:</strong> You can also customize the <code>build.gradle</code> file +so each app uses a specific build chain and compilation options. For more information see, +<a href="{@docRoot}tools/building/configuring-gradle.html">Configuring Gradle Builds</a>. </p> + + <h2 id="update-channel">Update channels</h2> <p>Android Studio provides four update channels to keep Android Studio up-to-date based on your diff --git a/docs/html/tools/studio/studio-features.jd b/docs/html/tools/studio/studio-features.jd index 76eba10..44d6985 100644 --- a/docs/html/tools/studio/studio-features.jd +++ b/docs/html/tools/studio/studio-features.jd @@ -12,7 +12,11 @@ page.tags=studio, features <li><a href="#git-samples">Android Code Samples on GitHub</a></li> <li><a href="#template-support">Expanded Template and Form Factor Support</a></li> <li><a href="#project-settings">Android Studio and Project Settings</a></li> + <li><a href="#finger-print">Fingerprint Support</a></li> + <li><a href="#dev-services">Developer Services</a></li> + <li><a href="#private-res">Public and Private Resources</a></li> <li><a href="#support-apis">Editor Support for the Latest Android APIs</a></li> + <li><a href="#test-module">Test APK Module</a></li> </ol> <h2>See also</h2> @@ -40,7 +44,8 @@ and <h2 id="trans-editor">Translations Editor</h2> <p>Multi-language support is enhanced with the Translations Editor plugin so you can easily add a variety of locales to the app's translation file. With -<a href="https://tools.ietf.org/html/bcp47">BCP 47</a> support, the editor combines language and +<a class="external-link" href="https://tools.ietf.org/html/bcp47">BCP 47</a> support, the editor +combines language and region codes into a single selection for targeted localizations. Color codes indicate whether a locale is complete or still missing string translations. </p> @@ -112,6 +117,114 @@ behavior, such a UI themes, system settings, and version control. </p> +<h2 id="finger-print">Fingerprint Support</h2> +<p>Android Studio provides the {@code finger} command, allowing you to simulate, and thus validate, +fingerprint authentication for your app. After you set up your app to accept +<a href="https://developer.android.com/preview/api-overview.html#authentication">fingerprint +authentication</a>, your emulator or device should display the fingerprint authentication screen, +as shown below. </p> + + <p><img src="{@docRoot}images/tools/studio-fingerprint.png" /></p> + <p class="img-caption"><strong>Figure 6</strong> Fingerprint authentication.</p> + +<p>Open a terminal session, and telnet to the emulator. For example:</p> +<pre> +{@code telnet localhost 5554} +</pre> + +<p>Enter the <code>finger</code> command to simulate finger touch and removal: </p> + +<ul> + <li><code>finger touch <fingerprint-id></code> to simulate a finger touching the sensor</li> + <li><code>finger remove</code> to simulate finger removal </li> +</ul> + +<p>Your app should respond as if a user touched, and then removed their finger from, the +fingerprint sensor. </p> + + +<h2 id="dev-services">Developer Services</h2> +<p>Android Studio supports enabling these developer services in your app: </p> +<ul> + <li>Ads using <a href="https://developers.google.com/admob/">AdMob</a></li> + <li>Analytics <a href="https://developers.google.com/analytics/">Google Analytics</a></li> + <li>Authentication using <a href="https://developers.google.com/identity/sign-in/android/">Google + Sign-in</a> </li> + <li>Notifications using <a href="https://developers.google.com/cloud-messaging/">Google + Cloud Messaging</a> </li> +</ul> + +<p>Enabling a developer service adds the required dependencies and, when applicable, also modifies +the related configuration files. To activate the service, you must perform +service-specific updates, such as loading an ad in the <code>MainActivity</code> class for ad +display.</p> + +<p>To enable an Android developer service, select the <code>File > Project Structure</code> +menu option and click a service under the <em>Developer Services</em> sub-menu. The service +configuration page appears. In the service configuration page, click the service check box to +enable the service and click <strong>OK</strong>. Android Studio updates your library dependencies +for the selected service and, for Analytics, updates the <code>AndroidManifest.xml</code> and +other tracker configuration files. You can enable multiple services within the same app. For more +detail about starting the services, refer to each service's specific activation instructions. </p> + + + +<h2 id="private-res">Public and Private Resources</h2> +<p>By default, Android Studio treats all library resources as public: A public library resource is +available to library clients for use outside the library, and appears in code completion suggestions +and other resource references. Android Studio also, however, supports the use of private library +resources. A private library resource can only be used within the source library, and does not +appear in code completion lists and other resource references. </p> + +<p>You cannot explicitly declare a library resource as private. Instead, if you declare any library +resources as public, Android Studio assumes all the other library resources are private. </p> + +<p>An app treats all Android library resources as public unless you explicitly declare at least one +resource in the library as public. Declaring one public resource causes your app to treat all other, +undeclared resources in the library as private. </p> + +<p class="note"><strong>Note:</strong> Declaring public and private resources requires the +<a href="{@docRoot}tools/building/plugin-for-gradle.html">Android Plugin for Gradle</a> version +1.3 or higher. </p> + + +<p>To declare a resource as public and set other undeclared resources as private, add a +<code><public></code> declaration with the resource name and type in the resource file. +This example shows the public declaration for the <code>mylib_app_name</code> string resource. </p> + +<pre> +<resources> + <public name="mylib_app_name" type="string"/> +</resources> +</pre> + +<p>For large numbers of declarations, we recommended that you place the public marker declarations +in a separate file named <code>public.xml</code>. </p> + +<p>To help enforce private resource access, a <a href="{@docRoot}tools/help/lint.html">lint</a> +warning appears when a client of a library references a private resource. Many Android libraries, +such as the +<a href="{@docRoot}tools/support-library/features.html#design">Design Support Library</a> and the +<a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7 appcompat Library</a>, +declare public resources to display only resources that developers can directly reference. +</p> + +<p class="note"><strong>Note:</strong> If your app requires a private resource, copy the +private resource from the library to the location in your app where it is needed. </p> + +<p>When the build system builds an Android Archive (AAR) file, it extracts the +<code><public></code> resource declarations into a <code>public.txt</code> file, which is +packaged inside the AAR file next to the <code>R.txt</code> file. The <code>public.txt</code> file +contains a simple list of the declared public resources, describing their names and types. </p> + +<p>For a complete list of the available Android resource types, see +<a href="http://developer.android.com/guide/topics/resources/available-resources.html">Resource +Types</a></li> and +<a href="http://developer.android.com/guide/topics/resources/more-resources.html">More Resource +Types</a></li>. </p> + + + <h2 id="support-apis">Editor Support for the Latest Android APIs</h2> <p>Android Studio supports the <a href="{@docRoot}design/material/index.html">Material Design</a></li> themes, widgets, and @@ -121,3 +234,103 @@ and <code><animated-selector></code>, are supported.</p> +<h2 id="test-module">Test APK Module</h2> +<p>Android Studio supports adding a separate <code>test</code> module to your app so you can +generate a test APK. This <code>test</code> module resides at the same level as your app and +contains: the tests and instrumentation used to run the test APK on an Android device; an +<code>Android Manifest.xml</code> file for test APK configuration settings; and, a +<code>build.gradle</code> file for build settings.</p> + +<p>The <code>test</code> module cannot contain a <code>src/androidTest/</code> folder and does +not support build variants. If you have different product flavors in your main application APK, +create a different test module for each build variant.</p> + + +<p>To create a test APK module: + +<ul> + <li>Use the <strong>File > New > Module</strong> menu option to create a + <code>test</code> module consisting of the following directories and files: + <ul> + <li><code>./test/</code> </li> + <li><code>./test/build.gradle</code> </li> + <li><code>./test/src/main/java/com/android/tests/basic/MainTest.java</code> </li> + <li><code>./test/src/main/AndroidManifest.xml</code> </li> + </ul> + </li> + <li>In the <code>build.gradle</code> file, add the required properties to the + <code>android</code> block. + <ul> + <li><code>targetProjectPath ':<app name>'</code> specifies the main application APK + to test. </li> + <li><code>targetVariant ':<buildType>'</code> specifies the target build type.</li> + </ul> + <p>Here is an example of <code>build.gradle</code> file property settings: </p> + +<pre> +android { + compileSdkVersion 19 + buildToolsVersion = ‘21.1.3’ + + targetProjectPath ':app' + targetVariant 'debug' +} +</pre> + </li> + <li>Define the instrumentation entries in the manifest file. + <p>Here is an example of <code><instrumentation></code> settings in the manifest file: </p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.android.tests.basic.test"> + + <uses-sdk android:minSdkVersion="16" android:targetSdkVersion="16" /> + + <application> + >uses-library android:name="android.test.runner" /> + </application> + + <instrumentation android:name="android.test.InstrumentationTestRunner" + android:targetPackage="com.android.tests.basic" + android:handleProfiling="false" + android:functionalTest="false" + android:label="Tests for com.android.tests.basic"/> +</manifest< +</pre> + +<p class="note"><strong>Note:</strong> The <code>targetPackage</code> in the instrumentation +settings specifies the package of the test variant. </p> + + </li> + <li>In the <code>build.gradle</code> file for the tested app, include additional artifacts + that the test APK requires, such as the <code> classes.jar</code> file, by adding the + {@code publishNonDefault} property to the {@code Android} block, and assigning that property + a value of {@code true}. + <p>Here is an example of the <code>build.gradle</code> file that includes additional + artifacts: </p></li> +<pre> +android { + compileSdkVersion 19 + buildToolsVersion = ‘21.1.3’ + + publishNonDefault true +} +</pre> + </li> +</ul> + + +<p>In the {@code test} module in this example, the {@code build.gradle} file specifies the +properties for the project path and target build type variant. </p> + + <p><img src="{@docRoot}images/tools/studio-test-module.png" /></p> + <p class="img-caption"><strong>Figure 3.</strong> Test module for APK testing.</p> + + +<p class="note"><strong>Note:</strong> By default, the test module's build variant uses the +<code>debug</code> build type. You can configure additional build types using the +<code>testBuildType</code> property in the <code>defaultConfig</code> block in the main +app's <code>build.gradle</code> file. </p> + + diff --git a/docs/html/tools/support-library/features.jd b/docs/html/tools/support-library/features.jd index abe1c08..b3af7a2 100644 --- a/docs/html/tools/support-library/features.jd +++ b/docs/html/tools/support-library/features.jd @@ -17,13 +17,19 @@ page.title=Support Library Features <li><a href="#v7-mediarouter">v7 mediarouter library</a></li> <li><a href="#v7-palette">v7 palette library</a></li> <li><a href="#v7-recyclerview">v7 recyclerview library</a></li> + <li><a href="#v7-preference">v7 preference library</a></li> </ol> </li> <li><a href="#v8">v8 Support Library</a></li> <li><a href="#v13">v13 Support Library</a></li> + <li><a href="#v14-preference">v14 Preference Support Library</a></li> <li><a href="#v17-leanback">v17 Leanback Library</a></li> + <li><a href="#v17-preference">v17 Preference Library for TV</a></li> <li><a href="#annotations">Annotations Support Library</a></li> <li><a href="#design">Design Support Library</a></li> + <li><a href="#custom-tabs">Custom Tabs Support Library</a></li> + <li><a href="#percent">Percent Support Library</a></li> + <li><a href="#recommendation">Recommendation Support Library for TV</a></li> </ol> <h2>See also</h2> @@ -344,7 +350,7 @@ com.android.support:palette-v7:21.0.0 <p>The recyclerview library adds the {@link android.support.v7.widget.RecyclerView} class. This class provides support for the -<a href="{@docRoot}training/material/lists-cards.jd#RecyclerView">RecyclerView +<a href="{@docRoot}training/material/lists-cards#RecyclerView">RecyclerView widget</a>, a view for efficiently displaying large data sets by providing a limited window of data items.</p> @@ -361,6 +367,40 @@ com.android.support:recyclerview-v7:21.0.0 </pre> +<h3 id="v7-preference">v7 Preference Support Library</h3> + +<p>The +<a href="{@docRoot}reference/android/support/v7/preference/package-summary.html">preference</a> +package provides APIs to support adding preference objects, such as +{@link android.support.v7.preference.CheckBoxPreference} and +{@link android.support.v7.preference.ListPreference}, for +users to modify UI settings. </p> + +<p>The v7 Preference library adds support for interfaces, such as +{@link android.support.v7.preference.Preference.OnPreferenceChangeListener} and +{@link android.support.v7.preference.Preference.OnPreferenceClickListener}, and classes, +such as {@link android.support.v7.preference.CheckBoxPreference} and +{@link android.support.v7.preference.ListPreference}. </p> + + +<p>After you download the Android Support Libraries, this library is located in the +{@code <sdk>/extras/android/support/v7/preference} directory. For more information +on how to set up your project, follow the instructions in <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:preference-v7:23.0.0 +</pre> + + + + + + + <h2 id="v8">v8 Support Library</h2> @@ -382,7 +422,7 @@ com.android.support:recyclerview-v7:21.0.0 <p class="note"> <strong>Note:</strong> Use of RenderScript with the support library is supported with Android Studio and Gradle-based builds, as well as the Eclipse plugin and Ant build tools. The - renderscript library is located in the <code>build-tools/$VERSION/renderscript/</code> folder. + renderscript library is located in the <code>build-tools/$VERSION/renderscript/</code> folder. </p> <p>The following example shows the Gradle build script properties for this library:</p> @@ -421,6 +461,69 @@ com.android.support:support-v13:18.0.0 + + +<h2 id="v14-preference">v14 Preference Support Library</h2> + + +<p>The {@link android.support.v14.preference} package provides APIs to add support +for preference interfaces such as +{@link android.support.v14.preference.PreferenceFragment.OnPreferenceStartFragmentCallback} + and +{@link android.support.v14.preference.PreferenceFragment.OnPreferenceStartScreenCallback}, + along with classes, such as +{@link android.support.v14.preference.MultiSelectListPreference} and +{@link android.support.v14.preference.PreferenceFragment}. For detailed + information about the v14 Preference Support Library APIs, see the + <a href="{@docRoot}reference/android/support/v14/preference/package-summary.html">preference</a> + package in the API reference. +</p> + +<p>After you download the Android Support Libraries, this library is located in the +{@code <sdk>/extras/android/support/v14/} directory. The 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:preference-v14:23.0.0 +</pre> + + + + +<h2 id="v17-preference">v17 Preference Support Library for TV</h2> + + +<p>The {@link android.support.v17.preference} package provides APIs for providing preference + interfaces on TV devices, including support for the +{@link android.support.v17.preference.LeanbackListPreferenceDialogFragment.ViewHolder.OnItemClickListener} +interface and classes, such as +{@link android.support.v17.preference.BaseLeanbackPreferenceFragment} and +{@link android.support.v17.preference.LeanbackPreferenceFragment}. For detailed + information about the v17 Preference Support Library APIs, see the + <a href="{@docRoot}reference/android/support/v17/preference/package-summary.html">preference</a> + package in the API reference. +</p> + +<p>After you download the Android Support Libraries, this library is located in the +{@code <sdk>/extras/android/support/v17/} directory. The 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:preference-v17:23.0.0 +</pre> + + + + + <h2 id="v17-leanback">v17 Leanback Library</h2> <p>The {@link android.support.v17.leanback} package provides APIs to support @@ -506,3 +609,90 @@ com.android.support:design:22.2.0 </pre> + +<h2 id="custom-tabs">Custom Tabs Support Library</h2> + +<p>The +<a href="{@docRoot}reference/android/support/customtabs/package-summary.html">Custom Tabs</a> +package provides APIs to support adding and managing custom tabs in your apps. </p> + +<p>The Custom Tabs Support library adds support for various classes, such as +<a href="{@docRoot}reference/android/support/customtabs/CustomTabsService.html">Custom Tabs +Service</a> +and +<a href="{@docRoot}reference/android/support/customtabs/CustomTabsSCallback.html">Custom Tabs +Callback</a>. </p> + + +<p>After you download the Android Support Libraries, this library is located in the +{@code <sdk>/extras/android/support/customtabs} directory. For more information +on how to set up your project, follow the instructions in <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:customtabs:23.0.0 +</pre> + + + + +<h2 id="percent">Percent Support Library</h2> + +<p>The +<a href="{@docRoot}reference/android/support/percent/package-summary.html">Percent</a> +package provides APIs to support adding and managing percentage based dimensions in your app. </p> + +<p>The Percent Support library adds support for the +<a href="{@docRoot}reference/android/support/percent/PercentLayoutHelper.PercentLayoutParams.html"> +PercentLayoutHelper.PercentLayoutParams</a> interface +and various classes, such as +<a href="{@docRoot}reference/android/support/percent/PercentFrameLayout.html">PercentFrameLayout</a> +and +<a href="{@docRoot}reference/android/support/percent/PercentRelativeLayout.html"> +PercentRelativeLayout</a>. </p> + + +<p>After you download the Android Support Libraries, this library is located in the +{@code <sdk>/extras/android/support/customtabs} directory. For more information +on how to set up your project, follow the instructions in <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:percent:23.0.0 +</pre> + + + +<h2 id="recommendation">App Recommendation Support Library for TV</h2> + +<p>The +<a href="{@docRoot}reference/android/support/app/recommendation/package-summary.html">App +Recommendation</a> +package provides APIs to support adding content recommendations in your app running on TV devices. </p> + +<p>The App library adds support for annotations, such as +<a href="{@docRoot}reference/android/support/app/recommendation/ContentRecommendation.ContentMaturity.html"> +ContentRecommendation.ContentMaturity</a> and various classes, such as +<a href="{@docRoot}reference/android/support/app/recommendation/ContentRecommendation.html">ContentRecommendation</a> +and +<a href="{@docRoot}reference/android/support/app/recommendation/RecommendationExtender.html"> +RecommendationExtender</a>. </p> + + +<p>After you download the Android Support Libraries, this library is located in the +{@code <sdk>/extras/android/support/customtabs} directory. For more information +on how to set up your project, follow the instructions in <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:app.recommendation-app:23.0.0 +</pre> diff --git a/docs/html/tools/support-library/index.jd b/docs/html/tools/support-library/index.jd index 5688d8a..9dc0ed1 100644 --- a/docs/html/tools/support-library/index.jd +++ b/docs/html/tools/support-library/index.jd @@ -59,9 +59,80 @@ page.title=Support Library <p>This section provides details about the Support Library package releases.</p> + <div class="toggle-content opened"> <p id="rev21"><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" alt="" +/>Android Support Library, revision 23</a> <em>(August 2015)</em> + </p> + <div class="toggle-content-toggleme"> + <dl> + <dt>Added new support libraries:</a></dt> + <dd> + <ul> + <li><a href="features.html#custom-tabs">Custom Tabs Support library</a></li> + <li><a href="features.html#percent">Percent Support library</a></li> + <li><a href="features.html#recommendation">App Recommendation Support library for TV</a></li> + <li><a href="features.html#v7-preference">v7 Preference Support library</a></li> + <li><a href="features.html#v14-preference">v14 Preference Support library</a></li> + <li><a href="features.html#v17-preference">v17 Preference Support library for TV</a></li> + </ul> + </dd> + + </dl> + + <p>For a complete list of the Support Library changes, see the + <a href="{@docRoot}sdk/support_api_diff/23/changes.html">Support + Library API Differences Report</a>. </p> + + </div> +</div> <!-- end of collapsible section --> + + + +<div class="toggle-content closed"> + <p id="rev21"><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" +/>Android Support Library, revision 22.2.1</a> <em>(July 2015)</em> + </p> + <div class="toggle-content-toggleme"> + <dl> + <dt>Changes for <a href="features.html#design">Design Support library:</a></dt> + <dd> + <ul> + <li>Added the {@code hide()} and {@code show()} methods to the + {@link android.support.design.widget.FloatingActionButton} class for programmatic + triggering of animations. </li> + <li>Added the {@code LENGTH_INDEFINITE} constant to the + {@link android.support.design.widget.Snackbar} class for showing a snackbar + until it is dismissed or another snackbar is shown. Also, added the + {@link android.support.design.widget.Snackbar#setActionTextColor(int)} and + {@link android.support.design.widget.Snackbar#setActionTextColor(ColorStateList)} + methods. </li> + <li>Added the {@code getSelectedTabPosition()} method to the + {@link android.support.design.widget.TabLayout} class for retrieving the currently + selected tab. </li> + <li>Provided a fully fluent API for the + {@link android.support.v7.app.NotificationCompat.MediaStyle} class for method + chaining. </li> + <li>Added convenience methods to the + {@link android.support.v7.widget.RecyclerView} for batch insertion of items. </li> + </ul> + </dd> + </dl> + + <p>For a complete list of the Support Library changes, see the + <a href="{@docRoot}sdk/support_api_diff/22.2.0/changes.html">Support + Library API Differences Report</a>. </p> + + </div> +</div> <!-- end of collapsible section --> + + + +<div class="toggle-content closed"> + <p id="rev21"><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" />Android Support Library, revision 22.2.0</a> <em>(May 2015)</em> </p> <div class="toggle-content-toggleme"> @@ -143,7 +214,7 @@ page.title=Support Library {@link android.support.v4.media.session.PlaybackStateCompat.Builder#setExtras setExtras()} methods to the {@link android.support.v4.media.session.PlaybackStateCompat.Builder} class for adding - adding custom actions to a playback state. + custom actions to a playback state. </li> <li>Added the {@link android.support.v4.media.session.PlaybackStateCompat.CustomAction#fromCustomAction fromCustomAction()} and @@ -203,6 +274,9 @@ page.title=Support Library </ul> </dd> + <p>For a complete list of the Support Library changes, see the + <a href="{@docRoot}sdk/support_api_diff/22.2.0/changes.html">Support + Library API Differences Report</a>. </p> </dl> @@ -212,7 +286,6 @@ page.title=Support Library - <div class="toggle-content closed"> <p id="rev21"><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" @@ -639,7 +712,7 @@ page.title=Support Library <dt>Added <a href="{@docRoot}tools/support-library/features.html#multidex"> multidex support library</a> to support multiple <a href="https://source.android.com/devices/tech/dalvik/">Dalvik</a> Executable (DEX) files - for multi-dex file support prior to Android 5.0. </li> + for multi-dex file support prior to Android 5.0. </dt> </dl> </div> |