Drawable resources

A drawable resource is a general concept for a graphic that can be drawn to the screen and which
you can retrieve with APIs such as getDrawable(int) or apply
to another XML resource with attributes such as android:drawable and android:icon.
There are several different types of drawables:

Note: A color resource can also be
used as a drawable in XML. For example, when creating a state list
drawable, you can reference a color resource for the android:drawable attribute (android:drawable="@color/green").

Bitmap

You can reference a bitmap file directly, using the filename as the resource ID, or create an
alias resource ID in XML.

Note: Bitmap files may be automatically optimized with lossless
image compression by the aapt tool during the build process. 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.

Bitmap file

A bitmap file is a .png, .jpg, or .gif file. Android creates a Drawable
resource for any of these files when you save them in the res/drawable/ directory.

file location:

res/drawable/filename.png (.png, .jpg, or .gif)
The filename is used as the resource ID.

Java

XML bitmap

An XML bitmap is a resource defined in XML that points to a bitmap file. The effect is an alias for a
raw bitmap file. The XML can specify additional properties for the bitmap such as dithering and tiling.

Note: You can use a <bitmap> element as a child of
an <item> element. For
example, when creating a state list or layer list,
you can exclude the android:drawable
attribute from an <item> element and nest a <bitmap> inside it
that defines the drawable item.

String. Defines the XML namespace, which must be
"http://schemas.android.com/apk/res/android". This is required only if the
<bitmap> is the root element—it is not needed when the
<bitmap> is nested inside an <item>.

android:src

Drawable resource. Required. Reference to a drawable
resource.

android:antialias

Boolean. Enables or disables antialiasing.

android:dither

Boolean. Enables or disables dithering of the bitmap if the bitmap does not
have the same pixel configuration as the screen (for instance: a ARGB 8888 bitmap with an RGB 565
screen).

android:filter

Boolean. Enables or disables bitmap filtering. Filtering is used when the
bitmap is shrunk or stretched to smooth its apperance.

android:gravity

Keyword. Defines the gravity for the bitmap. The gravity indicates where to
position the drawable in its container if the bitmap is smaller than the container.

Must be one or more (separated by '|') of the following constant values:

Value

Description

top

Put the object at the top of its container, not changing its size.

bottom

Put the object at the bottom of its container, not changing its size.

left

Put the object at the left edge of its container, not changing its size.

right

Put the object at the right edge of its container, not changing its size.

center_vertical

Place object in the vertical center of its container, not changing its size.

fill_vertical

Grow the vertical size of the object if needed so it completely fills its container.

center_horizontal

Place object in the horizontal center of its container, not changing its size.

fill_horizontal

Grow the horizontal size of the object if needed so it completely fills its container.

center

Place the object in the center of its container in both the vertical and horizontal axis, not
changing its size.

fill

Grow the horizontal and vertical size of the object if needed so it completely fills its
container. This is the default.

clip_vertical

Additional option that can be set to have the top and/or bottom edges of the child clipped to
its container's bounds. The clip is based on the vertical gravity: a top gravity clips the
bottom edge, a bottom gravity clips the top edge, and neither clips both edges.

clip_horizontal

Additional option that can be set to have the left and/or right edges of the child clipped to
its container's bounds. The clip is based on the horizontal gravity: a left gravity clips
the right edge, a right gravity clips the left edge, and neither clips both edges.

android:mipMap

Boolean. Enables or disables the mipmap hint. See setHasMipMap() for more information.
Default value is false.

android:tileMode

Keyword. Defines the tile mode. When the tile mode is enabled, the bitmap is
repeated. Gravity is ignored when the tile mode is enabled.

Must be one of the following constant values:

Value

Description

disabled

Do not tile the bitmap. This is the default value.

clamp

Replicates the edge color if the shader draws outside of its original bounds

Nine-Patch

A NinePatch is a PNG image in which you can define stretchable regions
that Android scales when content within the View exceeds the normal image bounds. You
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 accommodate the content, the Nine-Patch image
is also 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.

Same as with a normal bitmap, you can reference a Nine-Patch file directly
or from a resource defined by XML.

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

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

<item>

Defines a drawable to place in the layer drawable, in a position defined by its attributes.
Must be a child of a <layer-list> element. Accepts child <bitmap>
elements.

attributes:

android:drawable

Drawable resource. Required. Reference to a drawable
resource.

android:id

Resource ID. A unique resource ID for this drawable. To create a new resource
ID for this item, use the form:
"@+id/name". The plus symbol indicates that this should be created as a new
ID. You can use this identifier to
retrieve and modify the drawable with View.findViewById() or Activity.findViewById().

android:top

Integer. The top offset in pixels.

android:right

Integer. The right offset in pixels.

android:bottom

Integer. The bottom offset in pixels.

android:left

Integer. The left offset in pixels.

All drawable items are scaled to fit the size of the containing View, by default. Thus,
placing your images in a layer list at different positions might increase the size of the View and
some images scale as appropriate. To avoid
scaling items in the list, use a <bitmap> element inside the <item> element to specify the drawable and define the gravity to something that does not
scale, such as "center". For example, the following <item> defines an item
that scales to fit its container View:

<item android:drawable="@drawable/image" />

To avoid scaling, the following example uses a <bitmap> element with centered
gravity:

Notice that this example uses a nested <bitmap> element to define the drawable
resource for each item with a "center" gravity. This ensures that none of the images are scaled to
fit the size of the container, due to resizing caused by the offset images.

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 neither) and, using a state list drawable, you can provide a different background 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 is used—the selection is not based on the "best
match," but simply the first item that meets the minimum criteria of the state.

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 remains constant as the state
changes (the size is the maximum of all of the states); "false" if the size varies 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 has input focus
(such as when the user selects a text input); "false" if this item should be used in the default,
non-focused state.

android:state_hovered

Boolean. "true" if this item should be used when the object is being hovered
by a cursor; "false" if this item should be used in the default, non-hovered state. Often, this
drawable may be the same drawable used for the "focused" state.

Introduced in API level 14.

android:state_selected

Boolean. "true" if this item should be used when the object is the current
user selection when navigating with a directional control (such as when navigating through a list
with a d-pad); "false" if this item should be used when the object is not selected.

The selected state is used when focus (android:state_focused) is not sufficient
(such as when list view has focus and an item within it is selected with a d-pad).

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_activated

Boolean. "true" if this item should be used when the object is activated as
the persistent selection (such as to "highlight" the previously selected list item in a persistent
navigation view); "false" if it should be used when the object is not activated.

Introduced in API level 11.

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 Android applies the first item in the state list that
matches the current state of the object. So, if the first item in the list contains
none of the state attributes above, then it is applied every time, which is why your
default value should always be last (as demonstrated in the following example).

Level list

A Drawable that manages a number of alternate Drawables, each assigned a maximum numerical
value. Setting the level value of the drawable with setLevel() loads the drawable resource in the
level list that has a android:maxLevel value greater than or equal to the value
passed to the method.

Transition drawable

A TransitionDrawable is a drawable object
that can cross-fade between the two drawable resources.

Each drawable is represented by an <item> element inside a single <transition> element. No more than two items are supported. To transition forward, call
startTransition(). To
transition backward, call reverseTransition().

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

<item>

Defines a drawable to use as part of the drawable transition.
Must be a child of a <transition> element. Accepts child <bitmap>
elements.

attributes:

android:drawable

Drawable resource. Required. Reference to a drawable
resource.

android:id

Resource ID. A unique resource ID for this drawable. To create a new resource
ID for this item, use the form:
"@+id/name". The plus symbol indicates that this should be created as a new
ID. You can use this identifier to
retrieve and modify the drawable with View.findViewById() or Activity.findViewById().

Clip drawable

A drawable defined in XML that clips another drawable based on this Drawable's current level. You
can control how much the child drawable gets clipped in width and height based on the level, as well
as a gravity to control where it is placed in its overall container. Most often used to implement
things like progress bars.

String. Required. Defines the XML namespace, which must be
"http://schemas.android.com/apk/res/android".

android:drawable

Drawable resource. Required. Reference to a drawable
resource to be clipped.

android:clipOrientation

Keyword. The orientation for the clip.

Must be one of the following constant values:

Value

Description

horizontal

Clip the drawable horizontally.

vertical

Clip the drawable vertically.

android:gravity

Keyword. Specifies where to clip within the drawable.

Must be one or more (separated by '|') of the following constant values:

Value

Description

top

Put the object at the top of its container, not changing its size. When clipOrientation is "vertical", clipping occurs at the bottom of the drawable.

bottom

Put the object at the bottom of its container, not changing its size. When clipOrientation is "vertical", clipping occurs at the top of the drawable.

left

Put the object at the left edge of its container, not changing its size. This is the
default. When clipOrientation is "horizontal", clipping occurs at the right side of
the drawable. This is the default.

right

Put the object at the right edge of its container, not changing its size. When clipOrientation is "horizontal", clipping occurs at the left side of
the drawable.

center_vertical

Place object in the vertical center of its container, not changing its size. Clipping behaves
the same as when gravity is "center".

fill_vertical

Grow the vertical size of the object if needed so it completely fills its container. When clipOrientation is "vertical", no clipping occurs because the drawable fills the
vertical space (unless the drawable level is 0, in which case it's not visible).

center_horizontal

Place object in the horizontal center of its container, not changing its size.
Clipping behaves the same as when gravity is "center".

fill_horizontal

Grow the horizontal size of the object if needed so it completely fills its container. When
clipOrientation is "horizontal", no clipping occurs because the drawable fills the
horizontal space (unless the drawable level is 0, in which case it's not visible).

center

Place the object in the center of its container in both the vertical and horizontal axis, not
changing its size. When clipOrientation is "horizontal", clipping occurs on the left and right. When clipOrientation is "vertical", clipping occurs on the top and bottom.

fill

Grow the horizontal and vertical size of the object if needed so it completely fills its
container. No clipping occurs because the drawable fills the
horizontal and vertical space (unless the drawable level is 0, in which case it's not
visible).

clip_vertical

Additional option that can be set to have the top and/or bottom edges of the child clipped to
its container's bounds. The clip is based on the vertical gravity: a top gravity clips the
bottom edge, a bottom gravity clips the top edge, and neither clips both edges.

clip_horizontal

Additional option that can be set to have the left and/or right edges of the child clipped to
its container's bounds. The clip is based on the horizontal gravity: a left gravity clips
the right edge, a right gravity clips the left edge, and neither clips both edges.

String. Required. Defines the XML namespace, which must be
"http://schemas.android.com/apk/res/android".

android:drawable

Drawable resource. Required. Reference to a drawable
resource.

android:scaleGravity

Keyword. Specifies the gravity position after scaling.

Must be one or more (separated by '|') of the following constant values:

Value

Description

top

Put the object at the top of its container, not changing its size.

bottom

Put the object at the bottom of its container, not changing its size.

left

Put the object at the left edge of its container, not changing its size. This is the
default.

right

Put the object at the right edge of its container, not changing its size.

center_vertical

Place object in the vertical center of its container, not changing its size.

fill_vertical

Grow the vertical size of the object if needed so it completely fills its container.

center_horizontal

Place object in the horizontal center of its container, not changing its size.

fill_horizontal

Grow the horizontal size of the object if needed so it completely fills its container.

center

Place the object in the center of its container in both the vertical and horizontal axis, not
changing its size.

fill

Grow the horizontal and vertical size of the object if needed so it completely fills its
container.

clip_vertical

Additional option that can be set to have the top and/or bottom edges of the child clipped to
its container's bounds. The clip is based on the vertical gravity: a top gravity clips the
bottom edge, a bottom gravity clips the top edge, and neither clips both edges.

clip_horizontal

Additional option that can be set to have the left and/or right edges of the child clipped to
its container's bounds. The clip is based on the horizontal gravity: a left gravity clips
the right edge, a right gravity clips the left edge, and neither clips both edges.

android:scaleHeight

Percentage. The scale height, expressed as a percentage of the drawable's
bound. The value's format is XX%. For instance: 100%, 12.5%, etc.

android:scaleWidth

Percentage. The scale width, expressed as a percentage of the drawable's
bound. The value's format is XX%. For instance: 100%, 12.5%, etc.

String. Required. Defines the XML namespace, which must be
"http://schemas.android.com/apk/res/android".

android:shape

Keyword. Defines the type of shape. Valid values are:

Value

Desciption

"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 is overridden by android:innerRadius. Default value is 9.

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

<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 is 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 1, or else no corners are 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 1, but then override each and every corner with the values you really
want, providing zero ("0dp") where you don't want rounded corners.

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

android:centerY

Float. The relative Y-position for the center of the gradient (0 - 1.0).

android:centerColor

Color. Optional color that comes between the start and end colors, as a
hexadecimal value or color resource.

Note: The shape scales to the size of the container
View proportionate to the dimensions defined here, by default. When you use the shape in an ImageView, you can restrict scaling by setting the android:scaleType to "center".

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