From b4bab2d0ee39e0e78506f1b46643d776944d5299 Mon Sep 17 00:00:00 2001 From: Hemal Patel Date: Mon, 15 Aug 2016 14:31:42 -0700 Subject: Docs: Added contents for Vector Drawables Added contents to give an overview of VectorDrawables and AnimatedVectorDrawables. For better understanding, added two graphic files to explain the overall working of the XML file and the graphic that is rendered as an output of the XML file. Bug: 28072772 Change-Id: I9b6513c4b6e5aec59f45155963ff732fdd7b5784 --- docs/html/guide/topics/graphics/2d-graphics.jd | 371 +++++++++++++++++++++---- 1 file changed, 321 insertions(+), 50 deletions(-) (limited to 'docs/html/guide') diff --git a/docs/html/guide/topics/graphics/2d-graphics.jd b/docs/html/guide/topics/graphics/2d-graphics.jd index 9cae53c06910..d7dd0381f2a8 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

    - -

    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. +

    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 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 -- cgit v1.2.3-59-g8ed1b