2d-graphics.jd revision 293b850da6780184e6014e661841f1f3051b0af2
1page.title=2D Graphics 2parent.title=2D and 3D Graphics 3parent.link=index.html 4@jd:body 5 6 7<div id="qv-wrapper"> 8 <div id="qv"> 9 <h2>In this document</h2> 10 <ol> 11 <li><a href="#drawables">Drawables</a> 12 <ol> 13 <li><a href="#drawables-from-images">Creating from resource images</a></li> 14 <li><a href="#drawables-from-xml">Creating from resource XML</a></li> 15 </ol> 16 </li> 17 <li><a href="#shape-drawable">Shape Drawable</a></li> 18 <!-- <li><a href="#state-list">StateListDrawable</a></li> --> 19 <li><a href="#nine-patch">Nine-patch</a></li> 20 <li><a href="#tween-animation">Tween Animation</a></li> 21 <li><a href="#frame-animation">Frame Animation</a></li> 22 </ol> 23 </div> 24</div> 25 26<p>Android offers a custom 2D graphics library for drawing and animating shapes and images. 27The {@link android.graphics.drawable} and {@link android.view.animation} 28packages are where you'll find the common classes used for drawing and animating in two-dimensions. 29</p> 30 31<p>This document offers an introduction to drawing graphics in your Android application. 32We'll discuss the basics of using Drawable objects to draw 33graphics, how to use a couple subclasses of the Drawable class, and how to 34create animations that either tween (move, stretch, rotate) a single graphic 35or animate a series of graphics (like a roll of film).</p> 36 37 38<h2 id="drawables">Drawables</h2> 39 40<p>A {@link android.graphics.drawable.Drawable} is a general abstraction for "something that can be drawn." 41You'll discover that the Drawable class extends to define a variety of specific kinds of drawable graphics, 42including {@link android.graphics.drawable.BitmapDrawable}, {@link android.graphics.drawable.ShapeDrawable}, 43{@link android.graphics.drawable.PictureDrawable}, {@link android.graphics.drawable.LayerDrawable}, and several more. 44Of course, you can also extend these to define your own custom Drawable objects that behave in unique ways.</p> 45 46<p>There are three ways to define and instantiate a Drawable: using an image saved in your project resources; 47using an XML file that defines the Drawable properties; or using the normal class constructors. Below, we'll discuss 48each the first two techniques (using constructors is nothing new for an experienced developer).</p> 49 50 51<h3 id="drawables-from-images">Creating from resource images</h3> 52 53<p>A simple way to add graphics to your application is by referencing an image file from your project resources. 54Supported file types are PNG (preferred), JPG (acceptable) and GIF (discouraged). This technique would 55obviously be preferred for application icons, logos, or other graphics such as those used in a game.</p> 56 57<p>To use an image resource, just add your file to the <code>res/drawable/</code> directory of your project. 58From there, you can reference it from your code or your XML layout. 59Either way, it is referred using a resource ID, which is the file name without the file type 60extension (E.g., <code>my_image.png</code> is referenced as <var>my_image</var>).</p> 61 62<p class="note"><strong>Note:</strong> Image resources placed in <code>res/drawable/</code> may be 63automatically optimized with lossless image compression by the 64<code>aapt</code> tool during the build process. For example, a true-color PNG that does 65not require more than 256 colors may be converted to an 8-bit PNG with a color palette. This 66will result in an image of equal quality but which requires less memory. So be aware that the 67image binaries placed in this directory can change during the build. If you plan on reading 68an image as a bit stream in order to convert it to a bitmap, put your images in the <code>res/raw/</code> 69folder instead, where they will not be optimized.</p> 70 71<h4>Example code</h4> 72<p>The following code snippet demonstrates how to build an {@link android.widget.ImageView} that uses an image 73from drawable resources and add it to the layout.</p> 74<pre> 75LinearLayout mLinearLayout; 76 77protected void onCreate(Bundle savedInstanceState) { 78 super.onCreate(savedInstanceState); 79 80 // Create a LinearLayout in which to add the ImageView 81 mLinearLayout = new LinearLayout(this); 82 83 // Instantiate an ImageView and define its properties 84 ImageView i = new ImageView(this); 85 i.setImageResource(R.drawable.my_image); 86 i.setAdjustViewBounds(true); // set the ImageView bounds to match the Drawable's dimensions 87 i.setLayoutParams(new Gallery.LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT)); 88 89 // Add the ImageView to the layout and set the layout as the content view 90 mLinearLayout.addView(i); 91 setContentView(mLinearLayout); 92} 93</pre> 94<p>In other cases, you may want to handle your image resource as a 95{@link android.graphics.drawable.Drawable} object. 96To do so, create a Drawable from the resource like so: 97<pre> 98Resources res = mContext.getResources(); 99Drawable myImage = res.getDrawable(R.drawable.my_image); 100</pre> 101 102<p class="warning"><strong>Note:</strong> Each unique resource in your project can maintain only one 103state, no matter how many different objects you may instantiate for it. For example, if you instantiate two 104Drawable objects from the same image resource, then change a property (such as the alpha) for one of the 105Drawables, then it will also affect the other. So when dealing with multiple instances of an image resource, 106instead of directly transforming the Drawable, you should perform a <a href="#tween-animation">tween animation</a>.</p> 107 108 109<h4>Example XML</h4> 110<p>The XML snippet below shows how to add a resource Drawable to an 111{@link android.widget.ImageView} in the XML layout (with some red tint just for fun). 112<pre> 113<ImageView 114 android:layout_width="wrap_content" 115 android:layout_height="wrap_content" 116 android:tint="#55ff0000" 117 android:src="@drawable/my_image"/> 118</pre> 119<p>For more information on using project resources, read about 120 <a href="{@docRoot}guide/topics/resources/index.html">Resources and Assets</a>.</p> 121 122 123<h3 id="drawables-from-xml">Creating from resource XML</h3> 124 125<p>By now, you should be familiar with Android's principles of developing a 126<a href="{@docRoot}guide/topics/ui/index.html">User Interface</a>. Hence, you understand the power 127and flexibility inherent in defining objects in XML. This philosophy caries over from Views to Drawables. 128If there is a Drawable object that you'd like to create, which is not initially dependent on variables defined by 129your application code or user interaction, then defining the Drawable in XML is a good option. 130Even if you expect your Drawable to change its properties during the user's experience with your application, 131you should consider defining the object in XML, as you can always modify properties once it is instantiated.</p> 132 133<p>Once you've defined your Drawable in XML, save the file in the <code>res/drawable/</code> directory of 134your project. Then, retrieve and instantiate the object by calling 135{@link android.content.res.Resources#getDrawable(int) Resources.getDrawable()}, passing it the resource ID 136of your XML file. (See the <a href="#drawable-xml-example">example below</a>.)</p> 137 138<p>Any Drawable subclass that supports the <code>inflate()</code> method can be defined in 139XML and instantiated by your application. 140Each Drawable that supports XML inflation utilizes specific XML attributes that help define the object 141properties (see the class reference to see what these are). See the class documentation for each 142Drawable subclass for information on how to define it in XML. 143 144<h4 id="drawable-xml-example">Example</h4> 145<p>Here's some XML that defines a TransitionDrawable:</p> 146<pre> 147<transition xmlns:android="http://schemas.android.com/apk/res/android"> 148 <item android:drawable="@drawable/image_expand"> 149 <item android:drawable="@drawable/image_collapse"> 150</transition> 151</pre> 152 153<p>With this XML saved in the file <code>res/drawable/expand_collapse.xml</code>, 154the following code will instantiate the TransitionDrawable and set it as the content of an ImageView:</p> 155<pre> 156Resources res = mContext.getResources(); 157TransitionDrawable transition = (TransitionDrawable) res.getDrawable(R.drawable.expand_collapse); 158ImageView image = (ImageView) findViewById(R.id.toggle_image); 159image.setImageDrawable(transition); 160</pre> 161<p>Then this transition can be run forward (for 1 second) with:</p> 162<pre>transition.startTransition(1000);</pre> 163 164<p>Refer to the Drawable classes listed above for more information on the XML attributes supported by each.</p> 165 166 167 168<h2 id="shape-drawable">Shape Drawable</h2> 169 170<p>When you want to dynamically draw some two-dimensional graphics, a {@link android.graphics.drawable.ShapeDrawable} 171object will probably suit your needs. With a ShapeDrawable, you can programmatically draw 172primitive shapes and style them in any way imaginable.</p> 173 174<p>A ShapeDrawable is an extension of {@link android.graphics.drawable.Drawable}, so you can use one where ever 175a Drawable is expected — perhaps for the background of a View, set with 176{@link android.view.View#setBackgroundDrawable(android.graphics.drawable.Drawable) setBackgroundDrawable()}. 177Of course, you can also draw your shape as its own custom {@link android.view.View}, 178to be added to your layout however you please. 179Because the ShapeDrawable has its own <code>draw()</code> method, you can create a subclass of View that 180draws the ShapeDrawable during the <code>View.onDraw()</code> method. 181Here's a basic extension of the View class that does just this, to draw a ShapeDrawable as a View:</p> 182<pre> 183public class CustomDrawableView extends View { 184 private ShapeDrawable mDrawable; 185 186 public CustomDrawableView(Context context) { 187 super(context); 188 189 int x = 10; 190 int y = 10; 191 int width = 300; 192 int height = 50; 193 194 mDrawable = new ShapeDrawable(new OvalShape()); 195 mDrawable.getPaint().setColor(0xff74AC23); 196 mDrawable.setBounds(x, y, x + width, y + height); 197 } 198 199 protected void onDraw(Canvas canvas) { 200 mDrawable.draw(canvas); 201 } 202} 203</pre> 204 205<p>In the constructor, a ShapeDrawable is defines as an {@link android.graphics.drawable.shapes.OvalShape}. 206It's then given a color and the bounds of the shape are set. If you do not set the bounds, then the 207shape will not be drawn, whereas if you don't set the color, it will default to black.</p> 208<p>With the custom View defined, it can be drawn any way you like. With the sample above, we can 209draw the shape programmatically in an Activity:</p> 210<pre> 211CustomDrawableView mCustomDrawableView; 212 213protected void onCreate(Bundle savedInstanceState) { 214 super.onCreate(savedInstanceState); 215 mCustomDrawableView = new CustomDrawableView(this); 216 217 setContentView(mCustomDrawableView); 218} 219</pre> 220 221<p>If you'd like to draw this custom drawable from the XML layout instead of from the Activity, 222then the CustomDrawable class must override the {@link android.view.View#View(android.content.Context, android.util.AttributeSet) View(Context, AttributeSet)} constructor, which is called when 223instantiating a View via inflation from XML. Then add a CustomDrawable element to the XML, 224like so:</p> 225<pre> 226<com.example.shapedrawable.CustomDrawableView 227 android:layout_width="fill_parent" 228 android:layout_height="wrap_content" 229 /> 230</pre> 231 232<p>The ShapeDrawable class (like many other Drawable types in the {@link android.graphics.drawable} package) 233allows you to define various properties of the drawable with public methods. 234Some properties you might want to adjust include 235alpha transparency, color filter, dither, opacity and color.</p> 236 237<p>You can also define primitive drawable shapes using XML. For more information, see the 238section about Shape Drawables in the <a 239href="{@docRoot}guide/topics/resources/drawable-resource.html#Shape">Drawable Resources</a> 240document.</p> 241 242<!-- TODO 243<h2 id="state-list">StateListDrawable</h2> 244 245<p>A StateListDrawable is an extension of the DrawableContainer class, making it little different. 246The primary distinction is that the 247StateListDrawable manages a collection of images for the Drawable, instead of just one. 248This means that it can switch the image when you want, without switching objects. However, the 249intention of the StateListDrawable is to automatically change the image used based on the state 250of the object it's attached to. 251--> 252 253<h2 id="nine-patch">Nine-patch</h2> 254 255<p>A {@link android.graphics.drawable.NinePatchDrawable} graphic is a stretchable bitmap image, which Android 256will automatically resize to accommodate the contents of the View in which you have placed it as the background. 257An example use of a NinePatch is the backgrounds used by standard Android buttons — 258buttons must stretch to accommodate strings of various lengths. A NinePatch drawable is a standard PNG 259image that includes an extra 1-pixel-wide border. It must be saved with the extension <code>.9.png</code>, 260and saved into the <code>res/drawable/</code> directory of your project. 261</p> 262<p> 263 The border is used to define the stretchable and static areas of 264 the image. You indicate a stretchable section by drawing one (or more) 1-pixel-wide 265 black line(s) in the left and top part of the border (the other border pixels should 266 be fully transparent or white). You can have as many stretchable sections as you want: 267 their relative size stays the same, so the largest sections always remain the largest. 268</p> 269<p> 270 You can also define an optional drawable section of the image (effectively, 271 the padding lines) by drawing a line on the right and bottom lines. 272 If a View object sets the NinePatch as its background and then specifies the 273 View's text, it will stretch itself so that all the text fits inside only 274 the area designated by the right and bottom lines (if included). If the 275 padding lines are not included, Android uses the left and top lines to 276 define this drawable area. 277</p> 278<p>To clarify the difference between the different lines, the left and top lines define 279which pixels of the image are allowed to be replicated in order to stretch the image. 280The bottom and right lines define the relative area within the image that the contents 281of the View are allowed to lie within.</p> 282<p> 283 Here is a sample NinePatch file used to define a button: 284</p> 285 <img src="{@docRoot}images/ninepatch_raw.png" alt="" /> 286 287<p>This NinePatch defines one stretchable area with the left and top lines 288and the drawable area with the bottom and right lines. In the top image, the dotted grey 289lines identify the regions of the image that will be replicated in order to stretch the image. The pink 290rectangle in the bottom image identifies the region in which the contents of the View are allowed. 291If the contents don't fit in this region, then the image will be stretched so that they do. 292</p> 293 294<p>The <a href="{@docRoot}guide/developing/tools/draw9patch.html">Draw 9-patch</a> tool offers 295 an extremely handy way to create your NinePatch images, using a WYSIWYG graphics editor. It 296even raises warnings if the region you've defined for the stretchable area is at risk of 297producing drawing artifacts as a result of the pixel replication. 298</p> 299 300<h3>Example XML</h3> 301 302<p>Here's some sample layout XML that demonstrates how to add a NinePatch image to a 303couple of buttons. (The NinePatch image is saved as <code>res/drawable/my_button_background.9.png</code> 304<pre> 305<Button id="@+id/tiny" 306 android:layout_width="wrap_content" 307 android:layout_height="wrap_content" 308 android:layout_alignParentTop="true" 309 android:layout_centerInParent="true" 310 android:text="Tiny" 311 android:textSize="8sp" 312 android:background="@drawable/my_button_background"/> 313 314<Button id="@+id/big" 315 android:layout_width="wrap_content" 316 android:layout_height="wrap_content" 317 android:layout_alignParentBottom="true" 318 android:layout_centerInParent="true" 319 android:text="Biiiiiiig text!" 320 android:textSize="30sp" 321 android:background="@drawable/my_button_background"/> 322</pre> 323<p>Note that the width and height are set to "wrap_content" to make the button fit neatly around the text. 324</p> 325 326<p>Below are the two buttons rendered from the XML and NinePatch image shown above. 327Notice how the width and height of the button varies with the text, and the background image 328stretches to accommodate it. 329</p> 330 331<img src="{@docRoot}images/ninepatch_examples.png" alt=""/> 332 333 334<h2 id="tween-animation">Tween Animation</h2> 335 336<p>A tween animation can perform a series of simple transformations (position, size, rotation, and transparency) on 337the contents of a View object. So, if you have a TextView object, you can move, rotate, grow, or shrink the text. 338If it has a background image, the background image will be transformed along with the text. 339The {@link android.view.animation animation package} provides all the classes used in a tween animation.</p> 340 341<p>A sequence of animation instructions defines the tween animation, defined by either XML or Android code. 342Like defining a layout, an XML file is recommended because it's more readable, reusable, and swappable 343than hard-coding the animation. In the example below, we use XML. (To learn more about defining an animation 344in your application code, instead of XML, refer to the 345{@link android.view.animation.AnimationSet} class and other {@link android.view.animation.Animation} subclasses.)</p> 346 347<p>The animation instructions define the transformations that you want to occur, when they will occur, 348and how long they should take to apply. Transformations can be sequential or simultaneous — 349for example, you can have the contents of a TextView move from left to right, and then 350rotate 180 degrees, or you can have the text move and rotate simultaneously. Each transformation 351takes a set of parameters specific for that transformation (starting size and ending size 352for size change, starting angle and ending angle for rotation, and so on), and 353also a set of common parameters (for instance, start time and duration). To make 354several transformations happen simultaneously, give them the same start time; 355to make them sequential, calculate the start time plus the duration of the preceding transformation. 356</p> 357 358<p>The animation XML file belongs in the <code>res/anim/</code> directory of your Android project. 359The file must have a single root element: this will be either a single <code><alpha></code>, 360<code><scale></code>, <code><translate></code>, <code><rotate></code>, interpolator element, 361or <code><set></code> element that holds groups of these elements (which may include another 362<code><set></code>). By default, all animation instructions are applied simultaneously. 363To make them occur sequentially, you must specify the <code>startOffset</code> attribute, as shown in the example below. 364</p> 365 366<p>The following XML from one of the ApiDemos is used to stretch, 367then simultaneously spin and rotate a View object. 368</p> 369<pre> 370<set android:shareInterpolator="false"> 371 <scale 372 android:interpolator="@android:anim/accelerate_decelerate_interpolator" 373 android:fromXScale="1.0" 374 android:toXScale="1.4" 375 android:fromYScale="1.0" 376 android:toYScale="0.6" 377 android:pivotX="50%" 378 android:pivotY="50%" 379 android:fillAfter="false" 380 android:duration="700" /> 381 <set android:interpolator="@android:anim/decelerate_interpolator"> 382 <scale 383 android:fromXScale="1.4" 384 android:toXScale="0.0" 385 android:fromYScale="0.6" 386 android:toYScale="0.0" 387 android:pivotX="50%" 388 android:pivotY="50%" 389 android:startOffset="700" 390 android:duration="400" 391 android:fillBefore="false" /> 392 <rotate 393 android:fromDegrees="0" 394 android:toDegrees="-45" 395 android:toYScale="0.0" 396 android:pivotX="50%" 397 android:pivotY="50%" 398 android:startOffset="700" 399 android:duration="400" /> 400 </set> 401</set> 402</pre> 403<p>Screen coordinates (not used in this example) are (0,0) at the upper left hand corner, 404and increase as you go down and to the right.</p> 405 406<p>Some values, such as pivotX, can be specified relative to the object itself or relative to the parent. 407Be sure to use the proper format for what you want ("50" for 50% relative to the parent, or "50%" for 50% 408relative to itself).</p> 409 410<p>You can determine how a transformation is applied over time by assigning an 411{@link android.view.animation.Interpolator}. Android includes 412several Interpolator subclasses that specify various speed curves: for instance, 413{@link android.view.animation.AccelerateInterpolator} tells 414a transformation to start slow and speed up. Each one has an attribute value that can be applied in the XML.</p> 415 416<p>With this XML saved as <code>hyperspace_jump.xml</code> in the <code>res/anim/</code> directory of the 417project, the following Java code will reference it and apply it to an {@link android.widget.ImageView} object 418from the layout. 419</p> 420<pre> 421ImageView spaceshipImage = (ImageView) findViewById(R.id.spaceshipImage); 422Animation hyperspaceJumpAnimation = AnimationUtils.loadAnimation(this, R.anim.hyperspace_jump); 423spaceshipImage.startAnimation(hyperspaceJumpAnimation); 424</pre> 425 426<p>As an alternative to <code>startAnimation()</code>, you can define a starting time for the animation with 427<code>{@link android.view.animation.Animation#setStartTime(long) Animation.setStartTime()}</code>, 428then assign the animation to the View with 429<code>{@link android.view.View#setAnimation(android.view.animation.Animation) View.setAnimation()}</code>. 430</p> 431 432<p>For more information on the XML syntax, available tags and attributes, see <a 433href="{@docRoot}guide/topics/resources/animation-resource.html">Animation Resources</a>.</p> 434 435<p class="note"><strong>Note:</strong> Regardless of how your animation may move or resize, the bounds of the 436View that holds your animation will not automatically adjust to accommodate it. Even so, the animation will still 437be drawn beyond the bounds of its View and will not be clipped. However, clipping <em>will occur</em> 438if the animation exceeds the bounds of the parent View.</p> 439 440 441<h2 id="frame-animation">Frame Animation</h2> 442 443<p>This is a traditional animation in the sense that it is created with a sequence of different 444images, played in order, like a roll of film. The {@link android.graphics.drawable.AnimationDrawable} 445class is the basis for frame animations.</p> 446 447<p>While you can define the frames of an animation in your code, using the 448{@link android.graphics.drawable.AnimationDrawable} class API, it's more simply accomplished with a single XML 449file that lists the frames that compose the animation. Like the tween animation above, the XML file for this kind 450of animation belongs in the <code>res/drawable/</code> directory of your Android project. In this case, 451the instructions are the order and duration for each frame of the animation.</p> 452 453<p>The XML file consists of an <code><animation-list></code> element as the root node and a series 454of child <code><item></code> nodes that each define a frame: a drawable resource for the frame and the frame duration. 455Here's an example XML file for a frame-by-frame animation:</p> 456<pre> 457<animation-list xmlns:android="http://schemas.android.com/apk/res/android" 458 android:oneshot="true"> 459 <item android:drawable="@drawable/rocket_thrust1" android:duration="200" /> 460 <item android:drawable="@drawable/rocket_thrust2" android:duration="200" /> 461 <item android:drawable="@drawable/rocket_thrust3" android:duration="200" /> 462</animation-list> 463</pre> 464 465<p>This animation runs for just three frames. By setting the <code>android:oneshot</code> attribute of the 466list to <var>true</var>, it will cycle just once then stop and hold on the last frame. If it is set <var>false</var> then 467the animation will loop. With this XML saved as <code>rocket_thrust.xml</code> in the <code>res/drawable/</code> directory 468of the project, it can be added as the background image to a View and then called to play. Here's an example Activity, 469in which the animation is added to an {@link android.widget.ImageView} and then animated when the screen is touched:</p> 470<pre> 471AnimationDrawable rocketAnimation; 472 473public void onCreate(Bundle savedInstanceState) { 474 super.onCreate(savedInstanceState); 475 setContentView(R.layout.main); 476 477 ImageView rocketImage = (ImageView) findViewById(R.id.rocket_image); 478 rocketImage.setBackgroundResource(R.drawable.rocket_thrust); 479 rocketAnimation = (AnimationDrawable) rocketImage.getBackground(); 480} 481 482public boolean onTouchEvent(MotionEvent event) { 483 if (event.getAction() == MotionEvent.ACTION_DOWN) { 484 rocketAnimation.start(); 485 return true; 486 } 487 return super.onTouchEvent(event); 488} 489</pre> 490<p>It's important to note that the <code>start()</code> method called on the AnimationDrawable cannot be 491called during the <code>onCreate()</code> method of your Activity, because the AnimationDrawable is not yet fully attached 492to the window. If you want to play the animation immediately, without 493requiring interaction, then you might want to call it from the 494<code>{@link android.app.Activity#onWindowFocusChanged(boolean) onWindowFocusChanged()}</code> method in 495your Activity, which will get called when Android brings your window into focus.</p> 496 497<p>For more information on the XML syntax, available tags and attributes, see <a 498href="{@docRoot}guide/topics/resources/animation-resource.html">Animation Resources</a>.</p> 499 500