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, aButton
widget can exist in one of several different states (pressed, focused, or niether) 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 isnot 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 is 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_hovered=["true" | "false"] android:state_selected=["true" | "false"] android:state_checkable=["true" | "false"] android:state_checked=["true" | "false"] android:state_enabled=["true" | "false"] android:state_activated=["true" | "false"] android:state_window_focused=["true" | "false"] /> </selector>
elements:
-
Defines a drawable to use during certain states, as described by its attributes. Must be a child of a
<selector>
element.attributes:
- Drawable resource. Required. Reference to a drawable resource.
- Boolean. "true" if this item should be used when the object is pressed (such as when a button/checkbox is touched/clicked); "false" if this item should be used in the default, non-pressed state.
- 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.
-
Boolean. "true" if this item should be used when the object is being hovered by a cursor(sunch as checkbox/button textcolor); "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.
-
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). - 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.)
- 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.
- Boolean. "true" if this item should be used when the object is enabled (capable of receiving touch/click events and also capable of subitem of listview text); "false" if it should be used when the object is disabled.
-
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.
- 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).
android:drawable
android:state_pressed
android:state_focused
android:state_hovered
android:state_selected
android:state_checkable
android:state_checked
android:state_enabled
android:state_activated
android:state_window_focused
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).
<item>
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:state_hovered="true" android:drawable="@drawable/button_focused" /> <!-- hovered --> <item android:drawable="@drawable/button_normal" /> <!-- default --> </selector>
This layout XML applies the state list drawable to a Button:
<Button android:layout_height="wrap_content" android:layout_width="wrap_content" android:background="@drawable/button" />