Resource Types >

Drawable Resources

See also

  1. 2D Graphics

A drawable resource is a general concept for a graphic that you can retrieve with getDrawable(int) and draw on the screen. There are several different types of drawables:

Bitmap File
A bitmap graphic file (.png, .jpg, or .gif). A BitmapDrawable.
Nine-Patch File
A PNG file with stretchable regions to allow image resizing based on content (.9.png). A NinePatchDrawable.
State List
An XML file that references different bitmap graphics for different states (for example, to use a different image when a button is pressed). A StateListDrawable.
Color
A resource defined in XML that specifies a rectangle of color, with optionally rounded corners. A PaintDrawable.
Shape
An XML file that defines a geometric shape, including colors and gradients. A ShapeDrawable.

Documentation for the AnimationDrawable resource is in the Animation Resource document.

Bitmap File

A basic bitmap image. Android supports basic bitmap files in a few different formats: .png (preferred), .jpg (acceptable), .gif (discouraged).

Note: Bitmap files may be automatically optimized with lossless image compression by the aapt tool. For example, a true-color PNG that does not require more than 256 colors may be converted to an 8-bit PNG with a color palette. This will result in an image of equal quality but which requires less memory. So be aware that the image binaries placed in this directory can change during the build. If you plan on reading an image as a bit stream in order to convert it to a bitmap, put your images in the res/raw/ folder instead, where they will not be optimized.

file location:
res/drawable/filename.png (.png, .jpg, or .gif)
The filename will be used as the resource ID.
compiled resource datatype:
Resource pointer to a BitmapDrawable.
resource reference:
In Java: R.drawable.filename
In XML: @[package:]drawable/filename
example:
With an image saved at res/drawable/myimage.png, this layout XML will apply the image to a View: 
<ImageView
    android:layout_height="wrap_content"
    android:layout_width="wrap_content"
    android:src="@drawable/myimage" />

This application code will retrieve the image as a Drawable:

Resources res = getResources();
Drawable drawable = res.getDrawable(R.drawable.myimage);
see also:

Nine-Patch File

A NinePatch is a PNG image in which you can define stretchable regions that Android will scale when content within the View exceeds the normal image bounds. You will typically assign this type of image as the background of a View that has at least one dimension set to "wrap_content", and when the View grows to accomodate the content, the Nine-Patch image will also be scaled to match the size of the View. An example use of a Nine-Patch image is the background used by Android's standard Button widget, which must stretch to accommodate the text (or image) inside the button.

For a complete discussion about how to define a Nine-Patch file with stretchable regions, see the 2D Graphics document.

file location:
res/drawable/filename.9.png
The filename will be used as the resource ID.
compiled resource datatype:
Resource pointer to a NinePatchDrawable.
resource reference:
In Java: R.drawable.filename
In XML: @[package:]drawable/filename
example:
With an image saved at res/drawable/myninepatch.9.png, this layout XML will apply the Nine-Patch to a View: 
<Button
    android:layout_height="wrap_content"
    android:layout_width="wrap_content"
    android:background="@drawable/myninepatch" />
see also:

State List

A StateListDrawable is a drawable object defined in XML that uses a several different images to represent the same graphic, depending on the state of the object. For example, a Button widget can exist in one of several different states (pressed, focused, or niether) and, using a state list drawable, you can provide a different button image for each state.

You can describe the state list in an XML file. Each graphic is represented by an <item> element inside a single <selector> element. Each <item> uses various attributes to describe the state in which it should be used as the graphic for the drawable.

During each state change, the state list is traversed top to bottom and the first item that matches the current state will be used—the selection is not based on the "best match," but simply the first item that meets the minimum criteria of the state.

file location:
res/drawable/filename.xml
The filename will be used as the resource ID.
compiled resource datatype:
Resource pointer to a StateListDrawable.
resource reference:
In Java: R.drawable.filename
In XML: @[package:]drawable/filename
syntax:
<?xml version="1.0" encoding="utf-8"?>
<selector xmlns:android="http://schemas.android.com/apk/res/android"
    android:constantSize=["true" | "false"]
    android:dither=["true" | "false"]
    android:variablePadding=["true" | "false"] >
    <item
        android:drawable="@[package:]drawable/drawable_resource"
        android:state_pressed=["true" | "false"]
        android:state_focused=["true" | "false"]
        android:state_selected=["true" | "false"]
        android:state_active=["true" | "false"]
        android:state_checkable=["true" | "false"]
        android:state_checked=["true" | "false"]
        android:state_enabled=["true" | "false"]
        android:state_window_focused=["true" | "false"] /> 
</selector>
elements:
<selector>
Required. This must be the root element. Contains one or more <item> elements.

attributes:

xmlns:android
String. Required. Defines the XML namespace, which must be "http://schemas.android.com/apk/res/android".
android:constantSize
Boolean. "true" if the drawable's reported internal size will remain constant as the state changes (the size will be the maximum of all of the states); "false" if the size will vary based on the current state. Default is false.
android:dither
Boolean. "true" to enable dithering of the bitmap if the bitmap does not have the same pixel configuration as the screen (for instance, an ARGB 8888 bitmap with an RGB 565 screen); "false" to disable dithering. Default is true.
android:variablePadding
Boolean. "true" if the drawable's padding should change based on the current state that is selected; "false" if the padding should stay the same (based on the maximum padding of all the states). Enabling this feature requires that you deal with performing layout when the state changes, which is often not supported. Default is false.
<item>
Defines a drawable to use during certain states, as described by its attributes. Must be a child of a <selector> element.

attributes:

android:drawable
Drawable resource. Required. Reference to a drawable resource.
android:state_pressed
Boolean. "true" if this item should be used when the object is pressed (such as when a button is touched/clicked); "false" if this item should be used in the default, non-pressed state.
android:state_focused
Boolean. "true" if this item should be used when the object is focused (such as when a button is highlighted using the trackball/d-pad); "false" if this item should be used in the default, non-focused state.
android:state_selected
Boolean. "true" if this item should be used when the object is selected (such as when a tab is opened); "false" if this item should be used when the object is not selected.
android:state_checkable
Boolean. "true" if this item should be used when the object is checkable; "false" if this item should be used when the object is not checkable. (Only useful if the object can transition between a checkable and non-checkable widget.)
android:state_checked
Boolean. "true" if this item should be used when the object is checked; "false" if it should be used when the object is un-checked.
android:state_enabled
Boolean. "true" if this item should be used when the object is enabled (capable of receiving touch/click events); "false" if it should be used when the object is disabled.
android:state_window_focused
Boolean. "true" if this item should be used when the application window has focus (the application is in the foreground), "false" if this item should be used when the application window does not have focus (for example, if the notification shade is pulled down or a dialog appears).

Note:Remember that the first item in the state list that matches the current state of the object will be applied. So if the first item in the list contains none of the state attributes above, then it will be applied every time, which is why your default value should always be last (as demonstrated in the following example).

example:
XML file saved at res/drawable/button.xml: 
<?xml version="1.0" encoding="utf-8"?>
<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:state_pressed="true"
          android:drawable="@drawable/button_pressed" /> <!-- pressed -->
    <item android:state_focused="true"
          android:drawable="@drawable/button_focused" /> <!-- focused -->
    <item android:drawable="@drawable/button_normal" /> <!-- default -->
</selector>

This layout XML will apply the drawable to a View:

<ImageView
    android:layout_height="wrap_content"
    android:layout_width="wrap_content"
    android:src="@drawable/button" />
see also:

Color

This is a color defined in XML that's used as a drawable to fill a rectangular space, with optionally rounded corners. This kind of drawable behaves like a color fill.

Note: A color drawable is a simple resource that is referenced using the value provided in the name attribute (not the name of the XML file). As such, you can combine a color drawable resources with other simple resources in the one XML file, under one <resources> element.

file location:
res/drawable/filename.png
The filename is arbitrary. The element's name will be used as the resource ID.
compiled resource datatype:
Resource pointer to a PaintDrawable.
resource reference:
In Java: R.drawable.color_name
In XML: @[package:]drawable/color_name
syntax:
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <drawable
        name="color_name"
        >color</drawable>
</resources>
elements:
<resources>
Required. This must be the root node.

No attributes.

<drawable>
A color to use as a drawable rectangle. The value can be any valid hexadecimal color value or a color resource. A color value always begins with a pound (#) character, followed by the Alpha-Red-Green-Blue information in one of the following formats: #RGB, #RRGGBB, #ARGB, or #AARRGGBB.

attributes:

name
String. Required. A name for the color. This name will be used as the resource ID.
example:
XML file saved at res/drawable/colors.xml: 
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <drawable name="solid_red">#f00</drawable>
    <drawable name="solid_blue">#0000ff</drawable>
</resources>

This layout XML will apply a color drawable to a View:

<TextView
    android:layout_width="fill_parent"
    android:layout_height="wrap_content"
    android:background="@drawable/solid_blue" />

This application code will get a color drawable and apply it to a View:

Resources res =  getResources();
Drawable redDrawable = res.getDrawable(R.drawable.solid_red);

TextView tv = (TextView) findViewByID(R.id.text);
tv.setBackground(redDrawable);
see also:

Shape

This is a generic shape defined in XML.

file location:
res/drawable/filename.xml
The filename will be used as the resource ID.
compiled resource datatype:
Resource pointer to a ShapeDrawable.
resource reference:
In Java: R.drawable.filename
In XML: @[package:]drawable/filename
syntax:
<?xml version="1.0" encoding="utf-8"?>
<shape xmlns:android="http://schemas.android.com/apk/res/android"
    android:shape=["rectangle" | "oval" | "line" | "ring"] >
    <gradient
        android:angle="integer"
        android:centerX="integer"
        android:centerY="integer"
        android:centerColor="integer"
        android:endColor="color"
        android:gradientRadius="integer"
        android:startColor="color"
        android:type=["linear" | "radial" | "sweep"]
        android:usesLevel=["true" | "false"] />
    <solid
        android:color="color" />
    <stroke
        android:width="integer"
        android:color="color"
        android:dashWidth="integer"
        android:dashGap="integer" />
    <padding
        android:left="integer"
        android:top="integer"
        android:right="integer"
        android:bottom="integer" />
    <corners
        android:radius="integer"
        android:topLeftRadius="integer"
        android:topRightRadius="integer"
        android:bottomLeftRadius="integer"
        android:bottomRightRadius="integer" />
</shape>
elements:
<shape>
Required. This must be the root element.

attributes:

android:shape
Keyword. Defines the type of shape. Valid values are:
ValueDesciption
"rectangle" A rectangle that fills the containing View. This is the default shape.
"oval" An oval shape that fits the dimensions of the containing View.
"line" A horizontal line that spans the width of the containing View. This shape requires the <stroke> element to define the width of the line.
"ring" A ring shape.

The following attributes are used only when android:shape="ring":

android:innerRadius
Dimension. The radius for the inner part of the ring (the hole in the middle), as a dimension value or dimension resource.
android:innerRadiusRatio
Float. The radius for the inner part of the ring, expressed as a ratio of the ring's width. For instance, if android:innerRadiusRatio="5", then the inner radius equals the ring's width divided by 5. This value will be overridden by android:innerRadius. Default value is 9.
android:thickness
Dimension. The thickness of the ring, as a dimension value or dimension resource.
android:thicknessRatio
Float. The thickness of the ring, expressed as a ratio of the ring's width. For instance, if android:thicknessRatio="2", then the thickness equals the ring's width divided by 2. This value will be overridden by android:innerRadius. Default value is 3.
android:useLevel
Boolean. "true" if this is used as a LevelListDrawable. This should normally be "false" or your shape may not appear.
<gradient>
Specifies a gradient color for the shape.

attributes:

android:angle
Integer. The angle for the gradient, in degrees. 0 is left to right, 90 is bottom to top. It must be a multiple of 45. Default is 0.
android:centerX
Float. The relative X-position for the center of the gradient (0 - 1.0). Does not apply when android:type="linear".
android:centerY
Float. The relative Y-position for the center of the gradient (0 - 1.0). Does not apply when android:type="linear".
android:centerColor
Color. Optional color that comes between the start and end colors, as a hexadecimal value or color resource.
android:endColor
Color. The ending color, as a hexadecimal value or color resource.
android:gradientRadius
Float. The radius for the gradient. Only applied when android:type="radial".
android:startColor
Color. The starting color, as a hexadecimal value or color resource.
android:type
Keyword. The type of gradient pattern to apply. Valid values are:
ValueDescription
"linear" A linear gradient. This is the default.
"radial" A radial gradient. The start color is the center color.
"sweep" A sweeping line gradient.
android:useLevel
Boolean. "true" if this is used as a LevelListDrawable.
<solid>
A solid color to fill the shape.

attributes:

android:color
Color. The color to apply to the shape, as a hexadecimal value or color resource.
<stroke>
A stroke line for the shape.

attributes:

android:width
Dimension. The thickness of the line, as a dimension value or dimension resource.
android:color
Color. The color of the line, as a hexadecimal value or color resource.
android:dashGap
Dimension. The distance between line dashes, as a dimension value or dimension resource. Only valid if android:dashWidth is set.
android:dashWidth
Dimension. The size of each dash line, as a dimension value or dimension resource. Only valid if android:dashGap is set.
<padding>
Padding to apply to the containing View element (this pads the position of the View content, not the shape).

attributes:

android:left
Dimension. Left padding, as a dimension value or dimension resource.
android:top
Dimension. Top padding, as a dimension value or dimension resource.
android:right
Dimension. Right padding, as a dimension value or dimension resource.
android:bottom
Dimension. Bottom padding, as a dimension value or dimension resource.
<corners>
Creates rounded corners for the shape. Applies only when the shape is a rectangle.

attributes:

android:radius
Dimension. The radius for all corners, as a dimension value or dimension resource. This will be overridden for each corner by the following attributes.
android:topLeftRadius
Dimension. The radius for the top-left corner, as a dimension value or dimension resource.
android:topRightRadius
Dimension. The radius for the top-right corner, as a dimension value or dimension resource.
android:bottomLeftRadius
Dimension. The radius for the bottom-left corner, as a dimension value or dimension resource.
android:bottomRightRadius
Dimension. The radius for the bottom-right corner, as a dimension value or dimension resource.

Note: Every corner must (initially) be provided a corner radius greater than zero, or else no corners will be rounded. If you want specific corners to not be rounded, a work-around is to use android:radius to set a default corner radius greater than zero, but then override each and every corner with the values you really want, providing zero ("0dp") where you don't want rounded corners.

example:
XML file saved at res/drawable/gradient_box.xml: 
<?xml version="1.0" encoding="utf-8"?>
<shape xmlns:android="http://schemas.android.com/apk/res/android"
    android:shape="rectangle">
    <gradient 
        android:startColor="#FFFF0000" 
        android:endColor="#80FF00FF"
        android:angle="45"/>
    <padding android:left="7dp" 
        android:top="7dp"
        android:right="7dp" 
        android:bottom="7dp" />
    <corners android:radius="8dp" />
</shape>

This layout XML will apply the shape drawable to a View:

<TextView
    android:background="@drawable/gradient_box"
    android:layout_height="wrap_content"
    android:layout_width="wrap_content" />

This application code will get the shape drawable and apply it to a View:

Resources res = getResources();
Drawable shape = res. getDrawable(R.drawable.gradient_box);

TextView tv = (TextView)findViewByID(R.id.textview);
tv.setBackground(shape);
↑ Go to top

← Back to Resource Types