From 2a3aa2d343820be9e05101a25b955d525e9bfa54 Mon Sep 17 00:00:00 2001 From: Rich Slogar Date: Wed, 18 Mar 2015 15:58:42 -0700 Subject: docs: studio 1.2 updates Change-Id: I893af7af0f686d0eeab11f881256c0cf26eb4605 --- docs/html/images/tools/studio-add-icon.png | Bin 0 -> 265 bytes .../images/tools/studio-debug-settings-icon.png | Bin 0 -> 660 bytes .../images/tools/studio-inspections-config.png | Bin 104566 -> 92539 bytes docs/html/images/tools/studio-memory-monitor.png | Bin 46138 -> 20762 bytes docs/html/images/tools/studio-memory-monitor2x.png | Bin 0 -> 44133 bytes docs/html/sdk/installing/studio-tips.jd | 60 +++- docs/html/tools/building/building-cmdline.jd | 17 +- docs/html/tools/debugging/annotations.jd | 241 ++++++++++++++++ docs/html/tools/debugging/improving-w-lint.jd | 1 + docs/html/tools/studio/index.jd | 320 ++++++++++++++++----- docs/html/tools/tools_toc.cs | 1 + 11 files changed, 549 insertions(+), 91 deletions(-) create mode 100644 docs/html/images/tools/studio-add-icon.png create mode 100644 docs/html/images/tools/studio-debug-settings-icon.png create mode 100644 docs/html/images/tools/studio-memory-monitor2x.png create mode 100644 docs/html/tools/debugging/annotations.jd diff --git a/docs/html/images/tools/studio-add-icon.png b/docs/html/images/tools/studio-add-icon.png new file mode 100644 index 000000000000..3ff49f6b965f Binary files /dev/null and b/docs/html/images/tools/studio-add-icon.png differ diff --git a/docs/html/images/tools/studio-debug-settings-icon.png b/docs/html/images/tools/studio-debug-settings-icon.png new file mode 100644 index 000000000000..ee9c7a17cea8 Binary files /dev/null and b/docs/html/images/tools/studio-debug-settings-icon.png differ diff --git a/docs/html/images/tools/studio-inspections-config.png b/docs/html/images/tools/studio-inspections-config.png index e41afa16b519..15a5a5ba9f81 100644 Binary files a/docs/html/images/tools/studio-inspections-config.png and b/docs/html/images/tools/studio-inspections-config.png differ diff --git a/docs/html/images/tools/studio-memory-monitor.png b/docs/html/images/tools/studio-memory-monitor.png index 796daf0841fa..58147b7443f4 100644 Binary files a/docs/html/images/tools/studio-memory-monitor.png and b/docs/html/images/tools/studio-memory-monitor.png differ diff --git a/docs/html/images/tools/studio-memory-monitor2x.png b/docs/html/images/tools/studio-memory-monitor2x.png new file mode 100644 index 000000000000..7c3d6c4024b7 Binary files /dev/null and b/docs/html/images/tools/studio-memory-monitor2x.png differ diff --git a/docs/html/sdk/installing/studio-tips.jd b/docs/html/sdk/installing/studio-tips.jd index 69c188c836f0..a40050fe1380 100644 --- a/docs/html/sdk/installing/studio-tips.jd +++ b/docs/html/sdk/installing/studio-tips.jd @@ -36,8 +36,8 @@ This section notes a few of the key features to help you work quickly and effici

Smart Rendering

With smart rendering, Android Studio displays links for quick fixes to rendering errors. For example, if you add a button to the layout without specifying the width and -height atttributes, Android Studio displays the rendering message Automatically -add all missing attributs. Clicking the message adds the missing attributes to the layout.

+height attributes, Android Studio displays the rendering message Automatically +add all missing attributes. Clicking the message adds the missing attributes to the layout.

Bitmap rendering in the debugger

@@ -82,7 +82,50 @@ window. Clicking Designer on the right side of the window revea with a layout hierarchy and a list of properties for each view in the layout.

-

Working with IntelliJ

+

Annotations

+

Android Studio provides coding assistance for using annotations from the +{@link android.support.annotation Support-Annotations} library, part of the +Support Repository. + +Adding a dependency for this library enables you to decorate your code with annotations to help +catch bugs, such as null pointer exceptions and resource type conflicts. You can also create +enumerated annotations to, for example, check that a passed parameter value matches a value from +a defined set of constants. For more information, see +Improving Code Inspection with +Annotations. +

+ + +

Java class decompiling

+

Android Studio allows you to look at what’s inside Java libraries when you don’t have access +to the source code.

+ +

The decompiler is built into Android Studio for easy access. To use this feature, right-click +a class, method, or field from a library for which you do not have source file access and select +decompile.

The decompiled source code appears.

+ +

To adjust the Java decompiler settings, select +File > Settings > Other Settings > Java Decompiler.

+ + +

Debugging and performance enhancements

+

Android Studio offers debugging and performance enhancements such as:

+ + + + +

Working with IntelliJ-based Coding Practices

This section list just a few of the code editing practices you should consider using when creating Android Studio apps.

@@ -114,23 +157,17 @@ individual classes.

you can set a scope to identify all code related to a specific action bar.

-

External annotations

-

Specify annotations within the code or from an external annotation file. The Android Studio -IDE keeps track of the restrictions and validates compliance, for example setting the data type -of a string as not null.

- -

Injecting languages

With language injection, the Android Studio IDE allows you to work with islands of different languages embedded in the source code. This extends the syntax, error highlighting and coding assistance to the embedded language. This can be especially useful for checking regular expression -values inline, and validating XML and SQL statments.

+values inline, and validating XML and SQL statements.

Code folding

This allows you to selectively hide and display sections of the code for readability. For example, resource expressions or code for a nested class can be folded or hidden in to one line -to make the outer class structure easier to read. The inner clas can be later expanded for +to make the outer class structure easier to read. The inner class can be later expanded for updates.

@@ -140,6 +177,7 @@ updates.

reference. Pressing {@code F1} with the preview image or icon selected displays resource asset details, such as the dp settings.

+

Quick F1 documentation

You can now inspect theme attributes using View > Quick Documentation (F1), diff --git a/docs/html/tools/building/building-cmdline.jd b/docs/html/tools/building/building-cmdline.jd index ec00b507cccf..33798a521821 100644 --- a/docs/html/tools/building/building-cmdline.jd +++ b/docs/html/tools/building/building-cmdline.jd @@ -34,9 +34,9 @@ parent.link=index.html -

By default, there are two build types to build your application using the gradle.build settings: +

By default, there are two build types to build your application using the Gradle build settings: one for debugging your application — debug — and one for building your - final package for release — release mode. Regardless of which way you build type + final package for release — release mode. Regardless of which build type your modules use, the app 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.

@@ -48,23 +48,24 @@ parent.link=index.html development device. You cannot distribute an application that is signed with a debug key. When you build using the release build type, the .apk file is unsigned, so you must manually sign it with your own private key, using Keytool and Jarsigner settings in the - module's gradle.build file.

+ module's build.gradle file.

It's important that you read and understand Signing Your Applications, 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 + 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.

If you don't have Gradle, you can obtain it from the Gradle - home page. Install it and make sure it is in your executable PATH. Before calling Ant, you + home page. Install it and make sure it is in your executable PATH. Before calling Gradle, you need to declare the JAVA_HOME environment variable to specify the path to where the JDK is installed.

-

Note: When installing JDK on Windows, the default is to install - in the "Program Files" directory. This location will cause ant to fail, because of - the space. To fix the problem, you can specify the JAVA_HOME variable like this: +

Note: When using ant and installing JDK on Windows, + the default is to install in the "Program Files" directory. This location will cause + ant to fail, because of the space. To fix the problem, you can specify the JAVA_HOME + variable like this: 

set JAVA_HOME=c:\Progra~1\Java\<jdkdir>

The easiest solution, however, is to install JDK in a non-space directory, for example:

diff --git a/docs/html/tools/debugging/annotations.jd b/docs/html/tools/debugging/annotations.jd new file mode 100644 index 000000000000..fe9f9cc59c98 --- /dev/null +++ b/docs/html/tools/debugging/annotations.jd @@ -0,0 +1,241 @@ +page.title=Improving Code Inspection with Annotations +@jd:body + +
+ +
+ +

Using code inspections tools such as lint can help +you find problems and improve your code, but inspection tools can only infer so much. Android +resource ids, for example, use an {@code int} to identify strings, graphics, colors and other +resource types, so inspection tools cannot tell when you have specified a string resource where +you should have specified a color. This situation means that your app may render incorrectly or +fail to run at all, even if you use code inspection.

+ +

Annotations allow you to provide hints to code inspections tools like {@code lint}, to help +detect these, more subtle code problems. They are added as metadata tags that you attach to +variables, parameters, and return values to inspect method return values, passed parameters, and +local variables and fields. When used with code inspections tools, annotations can help you detect +problems, such as null pointer exceptions and resource type +conflicts.

+ +

For more information on enabling lint inspections +and running lint, +see Improving Your Code with lint.

+ +

Android supports a variety of annotations for insertion in the methods, parameters, and return +values in your code, for example:

+ +
+
{@link android.support.annotation.Nullable @Nullable}
+
Can be null.
+ +
{@link android.support.annotation.NonNull @NonNull}
+
Cannot be null.
+ +
{@link android.support.annotation.StringRes @StringRes}
+
References a R.string + resource.
+ +
{@link android.support.annotation.DrawableRes @DrawableRes}
+
References a + Drawable + resource.
+ +
{@link android.support.annotation.ColorRes @ColorRes}
+
References a Color + resource.
+ +
{@link android.support.annotation.InterpolatorRes @InterpolatorRes}
+
References a + Interpolator + resource.
+ +
{@link android.support.annotation.AnyRes @AnyRes}
+
References any type of R. + resource.
+
+ +

For a complete list of the supported annotations, either examine the contents of the +{@link android.support.annotation Support-Annotations} library or use the +auto-complete feature to display the available options for the import +android.support.annotation. statement. The + SDK Manager packages the +{@link android.support.annotation Support-Annotations} library in the Android Support Repository +for use with Android Studio and in the Android +Support Library for use with other Android +development tools.

+ + +

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 build.gradle file.

+ +
+dependencies {
+    compile 'com.android.support:support-annotations:22.0.0'
+}
+
+ + +

The {@link android.support.annotation Support-Annotations} library is decorated with the +supported annotations so using this library's methods and resources automatically checks the code +for potential problems.

+ +

If you include annotations in a library and use the +Android Plugin for Gradle +to build an Android ARchive (AAR) artifact of that library, the annotations are included as part +of the artifact in XML format in the annotations.zip file.

+ +

To start a code inspection from Android Studio, which includes validating annotations and +automatic lint checking, select +Analyze > Inspect Code from the menu options. Android Studio displays conflict +messages throughout the code to indication annotation conflicts and suggest possible +resolutions.

+ + +

Adding Nullness Annotations

+

Add {@link android.support.annotation.Nullable @Nullable} and +{@link android.support.annotation.NonNull @NonNull} annotations to check +the nullness of a given variable, parameter, or return value. For example, if a local variable +that contains a null value is passed as a parameter to a method with the +{@link android.support.annotation.NonNull @NonNull} annotation +attached to that parameter, building the code generates a warning indicating a non-null conflict.

+ +

This example attaches the {@link android.support.annotation.NonNull @NonNull} annotation to +the context and attrs parameters to check that the passed parameter +values are not null.

+ +
+import android.support.annotation.NonNull;
+...
+
+    /** Add support for inflating the <fragment> tag. */
+    @NonNull
+    @Override
+    public View onCreateView(String name, @NonNull Context context,
+      @NonNull AttributeSet attrs) {
+      ...
+      }
+...
+
+ +

Note: Android Studio supports running a nullability analysis to +automatically infer and insert nullness annotations in your code. For more information about +inferring nullability in Android Studio, see +Annotations in Android Studio.

+ + +

Adding Resource Annotations

+

Add {@link android.support.annotation.StringRes @StringRes} annotations to check that +a resource parameter contains a +R.string +reference. During code inspection, the annotation generates a warning if a R.string +reference is not passed in the parameter.

+ +

Validating resource types can be useful as Android references to +Drawables and +R.string resources are both +passed as integers. Code that expects a parameter to reference a Drawable can be passed +the expected reference type of int, but actually reference a R.string resource.

+ +

This example attaches the {@link android.support.annotation.StringRes @StringRes} +annotation to the resId parameter to validate that it is really a string resource.

+ +
+import android.support.annotation.StringRes;
+...
+    public abstract void setTitle(@StringRes int resId);
+    ...
+
+ + +

Annotations for the other resource types, such as +{@link android.support.annotation.DrawableRes @DrawableRes}, +{@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.

+ + +

Creating Enumerated Annotations

+

Use the {@link android.support.annotation.IntDef @IntDef} and +{@link android.support.annotation.StringDef @StringDef} annotations +so you can create enumerated annotations of integer and string sets to validate other types of code +references, such as passing references to a set of constants.

+ +

The following example illustrates the steps to create an enumerated annotation that ensures +a value passed as a method parameter references one of the defined constants.

+ +
+import android.support.annotation.IntDef;
+...
+public abstract class ActionBar {
+    ...
+    //Define the list of accepted constants
+    @IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS})
+
+    //Tell the compiler not to store annotation data in the .class file
+    @Retention(RetentionPolicy.SOURCE)
+
+    //Declare the NavigationMode annotation
+    public @interface NavigationMode {}
+
+    //Declare the constants
+    public static final int NAVIGATION_MODE_STANDARD = 0;
+    public static final int NAVIGATION_MODE_LIST = 1;
+    public static final int NAVIGATION_MODE_TABS = 2;
+
+    //Decorate the target methods with the annotation
+    @NavigationMode
+    public abstract int getNavigationMode();
+
+    //Attach the annotation
+    public abstract void setNavigationMode(@NavigationMode int mode);
+
+
+ +

When you build this code, a warning is generated if the mode parameter does +not reference one of the defined constants (NAVIGATION_MODE_STANDARD, +NAVIGATION_MODE_LIST, or NAVIGATION_MODE_TABS).

+ +

You can also define an annotation with a flag to check if a parameter +or return value references a valid pattern. This example creates the +DisplayOptions annotation with a list of valid DISPLAY_ constants.

+ +
+import android.support.annotation.IntDef;
+...
+
+@IntDef(flag=true, value={
+        DISPLAY_USE_LOGO,
+        DISPLAY_SHOW_HOME,
+        DISPLAY_HOME_AS_UP,
+        DISPLAY_SHOW_TITLE,
+        DISPLAY_SHOW_CUSTOM
+})
+@Retention(RetentionPolicy.SOURCE)
+public @interface DisplayOptions {}
+
+...
+
+ +

When you build code with an annotation flag, a warning is generated if the decorated parameter +or return value does not reference a valid pattern.

+ + diff --git a/docs/html/tools/debugging/improving-w-lint.jd b/docs/html/tools/debugging/improving-w-lint.jd index ff94b7f6bc93..8f74f46a613f 100644 --- a/docs/html/tools/debugging/improving-w-lint.jd +++ b/docs/html/tools/debugging/improving-w-lint.jd @@ -22,6 +22,7 @@ parent.link=index.html

See Also

  1. lint (reference)
    2. +
  2. Using Android Annotations
diff --git a/docs/html/tools/studio/index.jd b/docs/html/tools/studio/index.jd index b3d0ad7892d8..96e4316998da 100644 --- a/docs/html/tools/studio/index.jd +++ b/docs/html/tools/studio/index.jd @@ -18,7 +18,7 @@ page.title=Android Studio Overview

See also

    -
  1. IntelliJ FAQ on migrating to IntelliJ IDEA
    2. +
  2. IntelliJ FAQ on migrating to IntelliJ IDEA
@@ -26,8 +26,7 @@ page.title=Android Studio Overview

Android Studio is the official IDE for Android application development, -based on IntelliJ IDEA. +based on IntelliJ IDEA. On top of the capabilities you expect from IntelliJ, Android Studio offers:

@@ -38,10 +37,9 @@ Android Studio offers:

  • Rich layout editor with support for drag and drop theme editing
  • {@code lint} tools to catch performance, usability, version compatibility, and other problems
  • ProGuard and app-signing capabilities
    • -
  • Built-in support for Google Cloud Platform, making it easy to integrate Google Cloud - Messaging and App Engine
    • +
  • Built-in support for + Google Cloud Platform, + making it easy to integrate Google Cloud Messaging and App Engine
  • And much more
    • @@ -62,17 +60,17 @@ Studio.

    Project and File Structure

    -

    Android Project View

    -

    By default, Android Studio displays your profile files in the Android project view. This +

    Android project view

    +

    By default, Android Studio displays your project files in the Android project view. This view shows a flattened version of your project's structure that provides quick access to the key source files of Android projects and helps you work with the Gradle-based build system. -The Android project view:

    +The Android project view:

    For example, Android project view groups all the instances of the ic_launcher.png resource for different screen densities under the same element.

    Note: The project structure on disk differs from this flattened -representation. To switch to back to the segregated project view, select Project from -the Project drop-down.

    +representation. To switch to back to the segregated project view, select Project +from the Project drop-down.

    -

    Android Studio Project and Directory Structure

    -

    When you use the Project view of a new project in Android Studio, you +

    Other Android Studio views

    +

    When you use the Project view in Android Studio, you should notice that the project structure appears different than you may be used to in Eclipse. Each instance of Android Studio contains a project with one or more application modules. Each application module folder contains the complete source sets for that module, including @@ -113,11 +112,28 @@ module's {@code src/main} directory for source code updates, the gradle.build fi specification and the files under {@code src/androidTest} directory for test case creation.

    -

    Figure 3. Android Studio project structure

    +

    Figure 3. View Android Studio Project + structure.

    + +

    You can also customize the view of the project files to focus on specific aspects of your app +development:

    + + + +

    For example, selecting the Problems view of your project displays links to the +source files containing any recognized coding and syntax errors, such as missing a XML element +closing tag in a layout file.

    For more information, see -IntelliJ project organization and -Managing Projects.

    +IntelliJ project organization +and Managing Projects.

    @@ -156,7 +172,7 @@ To configure custom build settings in an Android Studio project, see Configuring Gradle Builds.

    -

    Application ID for Package Identification

    +

    Application ID for package identification

    With the Android build system, the applicationId attribute is used to uniquely identify application packages for publishing. The application ID is set in the android section of the build.gradle file. @@ -243,6 +259,30 @@ Manager (HAXM) emulator accelerator and creates a default emulator for quick app

    For more information, see Managing AVDs.

    +

    Inline debugging

    +

    Use inline debugging to enhance your code walk-throughs in the debugger view +with inline verification of references, expressions, and variable values. Inline debug information +includes:

    + + +

    To enable inline debugging, in the Debug window click the Settings icon + and select the +check box for Show Values In Editor.

    + +

    Memory and CPU monitor

    +

    Android Studio provides a memory and CPU monitor view so you can more easily monitor your +app's performance and memory usage to track CPU usage, find deallocated objects, locate memory +leaks, and track the amount of memory the connected device is using. With your app running on a +device or emulator, click the Android tab in the lower left corner of the +runtime window to launch the Android runtime window. Click the Memory or +CPU tab.

    +

    Memory Monitor

    Android Studio provides a memory monitor view so you can more easily monitor your @@ -250,18 +290,29 @@ app's memory usage to find deallocated objects, locate memory leaks and track th memory the connected device is using. With your app running on a device or emulator, click the Memory Monitor tab in the lower right corner to launch the memory monitor.

    - -

    Figure 5. Memory Monitor

    + +

    Figure 4. Monitor memory and CPU usage.

    + + +

    Data file access

    +

    The Android SDK tools, such as Systrace, +logcat, and +Traceview, generate performance and debugging +data for detailed app analysis.

    +

    To view the available generated data files, click Captures in the left +corner of the runtime window. In the list of the generated files, double-click a file to view +the data. Right-click any .hprof files to convert them to a standard +.hprof file format.

    -

    Code Inspections

    -

    In Android Studio, the configured lint and -other IDE inspections run automatically whenever you compile your program. In addition to the +

    Code inspections

    +

    In Android Studio, the configured lint +and other IDE inspections run automatically whenever you compile your program. In addition to the configured {@code lint} checks, additional -IntelliJ code inspections -run to streamline code review.

    +IntelliJ code inspections and annotation validation run to streamline code +review.

    Android Studio enables several lint checks @@ -269,10 +320,10 @@ to ensure: