diff --git a/docs/html/guide/topics/graphics/2d-graphics.jd b/docs/html/guide/topics/graphics/2d-graphics.jd index 9cae53c06910f..d7dd0381f2a8f 100644 --- a/docs/html/guide/topics/graphics/2d-graphics.jd +++ b/docs/html/guide/topics/graphics/2d-graphics.jd @@ -21,6 +21,7 @@ parent.link=index.html
  • Shape Drawable
  • Nine-patch
    • +
  • Vector Drawables

    • See also

    @@ -428,58 +429,66 @@ state of the object it's attached to. --> -

    Nine-patch

    +

    Nine-patch

    -

    A {@link android.graphics.drawable.NinePatchDrawable} graphic is a stretchable bitmap -image, which Android - will automatically resize to accommodate the contents of the View in which you have -placed it as the background. - An example use of a NinePatch is the backgrounds used by standard Android buttons — - buttons must stretch to accommodate strings of various lengths. A NinePatch drawable is a -standard PNG - image that includes an extra 1-pixel-wide border. It must be saved with the extension - .9.png, - and saved into the res/drawable/ directory of your project. -

    -

    - The border is used to define the stretchable and static areas of - the image. You indicate a stretchable section by drawing one (or more) 1-pixel-wide - black line(s) in the left and top part of the border (the other border pixels should - be fully transparent or white). You can have as many stretchable sections as you want: - their relative size stays the same, so the largest sections always remain the largest. -

    -

    - You can also define an optional drawable section of the image (effectively, - the padding lines) by drawing a line on the right and bottom lines. - If a View object sets the NinePatch as its background and then specifies the - View's text, it will stretch itself so that all the text fits inside only - the area designated by the right and bottom lines (if included). If the - padding lines are not included, Android uses the left and top lines to - define this drawable area. -

    -

    To clarify the difference between the different lines, the left and top lines define - which pixels of the image are allowed to be replicated in order to stretch the image. - The bottom and right lines define the relative area within the image that the contents - of the View are allowed to lie within.

    -

    - Here is a sample NinePatch file used to define a button: -

    - - -

    This NinePatch defines one stretchable area with the left and top lines - and the drawable area with the bottom and right lines. In the top image, the dotted grey - lines identify the regions of the image that will be replicated in order to stretch the -image. The pink - rectangle in the bottom image identifies the region in which the contents of the View are -allowed. - If the contents don't fit in this region, then the image will be stretched so that they -do. +

    + A {@link android.graphics.drawable.NinePatchDrawable} graphic is a + stretchable bitmap image, which Android will automatically resize to + accommodate the contents of the View in which you have placed it as the + background. An example use of a NinePatch is the backgrounds used by + standard Android buttons — buttons must stretch to accommodate strings of + various lengths. A NinePatch drawable is a standard PNG image that includes + an extra 1-pixel-wide border. It must be saved with the extension + .9.png, and saved into the res/drawable/ directory + of your project.

    -

    The Draw 9-patch tool offers - an extremely handy way to create your NinePatch images, using a WYSIWYG graphics editor. It -even raises warnings if the region you've defined for the stretchable area is at risk of -producing drawing artifacts as a result of the pixel replication. +

    + The border is used to define the stretchable and static areas of the image. + You indicate a stretchable section by drawing one (or more) 1-pixel-wide + black line(s) in the left and top part of the border (the other border + pixels should be fully transparent or white). You can have as many + stretchable sections as you want: their relative size stays the same, so the + largest sections always remain the largest. +

    + +

    + You can also define an optional drawable section of the image (effectively, + the padding lines) by drawing a line on the right and bottom lines. If a + View object sets the NinePatch as its background and then specifies the + View's text, it will stretch itself so that all the text fits inside only + the area designated by the right and bottom lines (if included). If the + padding lines are not included, Android uses the left and top lines to + define this drawable area. +

    + +

    + To clarify the difference between the different lines, the left and top + lines define which pixels of the image are allowed to be replicated in order + to stretch the image. The bottom and right lines define the relative area + within the image that the contents of the View are allowed to lie within. +

    + +

    + Here is a sample NinePatch file used to define a button: +

    + +

    + This NinePatch defines one stretchable area with the left and top lines and + the drawable area with the bottom and right lines. In the top image, the + dotted grey lines identify the regions of the image that will be replicated + in order to stretch the image. The pink rectangle in the bottom image + identifies the region in which the contents of the View are allowed. If the + contents don't fit in this region, then the image will be stretched so that + they do. +

    + +

    + The Draw 9-patch tool + offers an extremely handy way to create your NinePatch images, using a + WYSIWYG graphics editor. It even raises warnings if the region you've + defined for the stretchable area is at risk of producing drawing artifacts + as a result of the pixel replication.

    Example XML

    @@ -516,3 +525,265 @@ stretches to accommodate it.

    + +

    + Vector Drawables +

    + +

    + A {@link android.graphics.drawable.VectorDrawable} graphic replaces multiple + PNG assets with a single vector graphic. The vector graphic is defined in an + XML file as a set of points, lines, and curves along with its associated + color information. +

    + +

    + The major advantage of using a vector graphic is image scalability. Using + vector graphics resizes the same file for different screen densities without + loss of image quality. This results in smaller APK files and less developer + maintenance. You can also use vector images for animation by using multiple + XML files instead of multiple images for each display resolution. +

    + +

    + Let's go through an example to understand the benefits. An image of size 100 + x 100 dp may render good quality on a smaller display resolution. On larger + devices, the app might want to use a 400 x 400 dp version of the image. + Normally, developers create multiple versions of an asset to cater to + different screen densities. This approach consumes more development efforts, + and results in a larger APK, which takes more space on the device. +

    + +

    + As of Android 5.0 (API level 21), there are two classes that support vector + graphics as a drawable resource: {@link + android.graphics.drawable.VectorDrawable} and {@link + android.graphics.drawable.AnimatedVectorDrawable}. For more information + about using the VectorDrawable and the AnimatedVectorDrawable classes, read + the About VectorDrawable class and + About AnimatedVectorDrawable + class sections. +

    + +

    About VectorDrawable class

    +

    + {@link android.graphics.drawable.VectorDrawable} defines a static drawable + object. Similar to the SVG format, each vector graphic is defined as a tree + hierachy, which is made up of path and group objects. + Each path contains the geometry of the object's outline and + group contains details for transformation. All paths are drawn + in the same order as they appear in the XML file. +

    + + +

    + Figure 1. Sample hierarchy of a vector drawable asset +

    + + +

    + The Vector Asset + Studio tool offers a simple way to add a vector graphic to the project + as an XML file. +

    + +

    + Example XML +

    + +

    + Here is a sample VectorDrawable XML file that renders an image + of a battery in the charging mode. +

    + +
    +<!-- res/drawable/battery_charging.xml -->
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    <!-- intrinsic size of the drawable -->
+    android:height="24dp"
+    android:width="24dp"
+    <!-- size of the virtual canvas -->
+    android:viewportWidth="24.0"
+    android:viewportHeight="24.0">
+   <group
+         android:name="rotationGroup"
+         android:pivotX="10.0"
+         android:pivotY="10.0"
+         android:rotation="15.0" >
+      <path
+        android:name="vect"
+        android:fillColor="#FF000000"
+        android:pathData="M15.67,4H14V2h-4v2H8.33C7.6,4 7,4.6 7,5.33V9h4.93L13,7v2h4V5.33C17,4.6 16.4,4 15.67,4z"
+        android:fillAlpha=".3"/>
+      <path
+        android:name="draw"
+        android:fillColor="#FF000000"
+        android:pathData="M13,12.5h2L11,20v-5.5H9L11.93,9H7v11.67C7,21.4 7.6,22 8.33,22h7.33c0.74,0 1.34,-0.6 1.34,-1.33V9h-4v3.5z"/>
+   </group>
+</vector>
+
    + +

    This XML renders the following image: +

    + + + +

    + About AnimatedVectorDrawable class +

    + +

    + {@link android.graphics.drawable.AnimatedVectorDrawable + AnimatedVectorDrawable} adds animation to the properties of a vector + graphic. You can define an animated vector graphic as three separate + resource files or as a single XML file defining the entire drawable. Let's + look at both the approaches for better understanding: Multiple XML files and Single + XML file. +

    + +

    + Multiple XML files +

    +

    + By using this approach, you can define three separate XML files: + +

    +

    + +
    + Example of multiple XML files +
    +

    + The following XML files demonstrate the animation of a vector graphic. + +

    +

    +

    + Single XML file +

    + +

    + By using this approach, you can merge the related XML files into a single + XML file through the XML Bundle Format. At the time of building the app, the + aapt tag creates separate resources and references them in the + animated vector. This approach requires Build Tools 24 or higher, and the + output is backward compatible. +

    + +
    + Example of a single XML file +
    +
    +<animated-vector
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:aapt="http://schemas.android.com/aapt">
+    <aapt:attr name="android:drawable">
+        <vector
+            android:width="24dp"
+            android:height="24dp"
+            android:viewportWidth="24"
+            android:viewportHeight="24">
+            <path
+                android:name="root"
+                android:strokeWidth="2"
+                android:strokeLineCap="square"
+                android:strokeColor="?android:colorControlNormal"
+                android:pathData="M4.8,13.4 L9,17.6 M10.4,16.2 L19.6,7" />
+        </vector>
+    </aapt:attr>
+    <target android:name="root">
+        <aapt:attr name="android:animation">
+            <objectAnimator
+                android:propertyName="pathData"
+                android:valueFrom="M4.8,13.4 L9,17.6 M10.4,16.2 L19.6,7"
+                android:valueTo="M6.4,6.4 L17.6,17.6 M6.4,17.6 L17.6,6.4"
+                android:duration="300"
+                android:interpolator="@android:interpolator/fast_out_slow_in"
+                android:valueType="pathType" />
+        </aapt:attr>
+    </target>
+</animated-vector>
+
    \ No newline at end of file diff --git a/docs/html/images/guide/topics/graphics/ic_battery_charging_80_black_24dp.png b/docs/html/images/guide/topics/graphics/ic_battery_charging_80_black_24dp.png new file mode 100644 index 0000000000000..44a4e8688e87a Binary files /dev/null and b/docs/html/images/guide/topics/graphics/ic_battery_charging_80_black_24dp.png differ diff --git a/docs/html/images/guide/topics/graphics/vectorpath.png b/docs/html/images/guide/topics/graphics/vectorpath.png new file mode 100644 index 0000000000000..592bab67ecd93 Binary files /dev/null and b/docs/html/images/guide/topics/graphics/vectorpath.png differ