Added in API level 1

Summary: XML Attrs | Inherited Constants | Fields | Ctors | Methods | Inherited Methods

ColorStateList

---

Kotlin |Java

public class ColorStateList
extends Object implements Parcelable

java.lang.Object
↳	android.content.res.ColorStateList

---

Lets you map View state sets to colors.

ColorStateLists are created from XML resource files defined in the "color" subdirectory directory of an application's resource directory. The XML file contains a single "selector" element with a number of "item" elements inside. For example:

 <selector xmlns:android="http://schemas.android.com/apk/res/android">
   <item android:state_focused="true"
           android:color="@color/sample_focused" />
   <item android:state_pressed="true"
           android:state_enabled="false"
           android:color="@color/sample_disabled_pressed" />
   <item android:state_enabled="false"
           android:color="@color/sample_disabled_not_pressed" />
   <item android:color="@color/sample_default" />
 </selector>
 

This defines a set of state spec / color pairs where each state spec specifies a set of states that a view must either be in or not be in and the color specifies the color associated with that spec.

State specs

Each item defines a set of state spec and color pairs, where the state spec is a series of attributes set to either true or false to represent inclusion or exclusion. If an attribute is not specified for an item, it may be any value.

For example, the following item will be matched whenever the focused state is set; any other states may be set or unset:

 <item android:state_focused="true"
         android:color="@color/sample_focused" />
 

Typically, a color state list will reference framework-defined state attributes such as android:state_focused or android:state_enabled; however, app-defined attributes may also be used.

Note: The list of state specs will be matched against in the order that they appear in the XML file. For this reason, more-specific items should be placed earlier in the file. An item with no state spec is considered to match any set of states and is generally useful as a final item to be used as a default.

If an item with no state spec is placed before other items, those items will be ignored.

Item attributes

Each item must define an android:color attribute, which may be an HTML-style hex color, a reference to a color resource, or -- in API 23 and above -- a theme attribute that resolves to a color.

Starting with API 23, items may optionally define an android:alpha attribute to modify the base color's opacity. This attribute takes a either floating-point value between 0 and 1 or a theme attribute that resolves as such. The item's overall color is calculated by multiplying by the base color's alpha channel by the alpha value. For example, the following item represents the theme's accent color at 50% opacity:

 <item android:state_enabled="false"
         android:color="?android:attr/colorAccent"
         android:alpha="0.5" />
 

Starting with API 31, items may optionally define an android:lStar attribute to modify the base color's perceptual luminance. This attribute takes either a floating-point value between 0 and 100 or a theme attribute that resolves as such. The item's overall color is calculated by converting the base color to an accessibility friendly color space and setting its L* to the value specified on the lStar attribute. For example, the following item represents the theme's accent color at 50% perceptual luminance:

 <item android:state_enabled="false"
         android:color="?android:attr/colorAccent"
         android:lStar="50" />
 

Developer guide

For more information, see the guide to Color State List Resource.

Summary

XML attributes
android:alpha	Alpha multiplier applied to the base color.
android:color	Base color for this state.
android:lStar	Perceptual luminance applied to the base color.

Inherited constants

From interface android.os.Parcelable int CONTENTS_FILE_DESCRIPTOR Descriptor bit used with describeContents(): indicates that the Parcelable object's flattened representation includes a file descriptor. int PARCELABLE_WRITE_RETURN_VALUE Flag for use with writeToParcel(Parcel, int): the object being written is a return value, that is the result of a function such as "Parcelable someFunction()", "void someFunction(out Parcelable)", or "void someFunction(inout Parcelable)".

Fields
public static final Creator<ColorStateList>	CREATOR

Public constructors
ColorStateList(int[][] states, int[] colors) Creates a ColorStateList that returns the specified mapping from states to colors.

Public methods
static ColorStateList	createFromXml(Resources r, XmlPullParser parser) This method was deprecated in API level 23. Use #createFromXml(Resources, XmlPullParser parser, Theme)
static ColorStateList	createFromXml(Resources r, XmlPullParser parser, Resources.Theme theme) Creates a ColorStateList from an XML document using given a set of Resources and a Theme.
int	describeContents() Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.
int	getChangingConfigurations() Returns a mask of the configuration parameters for which this color state list may change, requiring that it be re-created.
int	getColorForState(int[] stateSet, int defaultColor) Return the color associated with the given set of View states.
int	getDefaultColor() Return the default color in this ColorStateList.
boolean	isOpaque() Indicates whether this color state list is opaque, which means that every color returned from getColorForState(int[], int) has an alpha value of 255.
boolean	isStateful() Indicates whether this color state list contains at least one state spec and the first spec is not empty (e.g. match-all).
String	toString() Returns a string representation of the object.
static ColorStateList	valueOf(int color)
ColorStateList	withAlpha(int alpha) Creates a new ColorStateList that has the same states and colors as this one but where each color has the specified alpha value (0-255).
ColorStateList	withLStar(float lStar) Creates a new ColorStateList that has the same states and colors as this one but where each color has the specified perceived luminosity value (0-100).
void	writeToParcel(Parcel dest, int flags) Flatten this object in to a Parcel.

Inherited methods
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
From interface android.os.Parcelable abstract int describeContents() Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. abstract void writeToParcel(Parcel dest, int flags) Flatten this object in to a Parcel.

XML attributes

android:alpha

Alpha multiplier applied to the base color.

May be a floating point value, such as "1.2".

android:color

Base color for this state.

May be a color value, in the form of "#rgb", "#argb", "#rrggbb", or "#aarrggbb".

android:lStar

Perceptual luminance applied to the base color. From 0 to 100.

May be a floating point value, such as "1.2".

Fields

CREATOR

Added in API level 1

public static final Creator<ColorStateList> CREATOR

Public constructors

ColorStateList

Added in API level 1

public ColorStateList (int[][] states, 
                int[] colors)

Creates a ColorStateList that returns the specified mapping from states to colors.

Parameters
states	int
colors	int

Public methods

createFromXml

Added in API level 1
Deprecated in API level 23

public static ColorStateList createFromXml (Resources r, 
                XmlPullParser parser)

This method was deprecated in API level 23.
Use #createFromXml(Resources, XmlPullParser parser, Theme)

Creates a ColorStateList from an XML document.

Parameters
r	Resources: Resources against which the ColorStateList should be inflated.
parser	XmlPullParser: Parser for the XML document defining the ColorStateList.

Returns
ColorStateList	A new color state list. This value cannot be null.

Throws
IOException
XmlPullParserException

createFromXml

Added in API level 23

public static ColorStateList createFromXml (Resources r, 
                XmlPullParser parser, 
                Resources.Theme theme)

Creates a ColorStateList from an XML document using given a set of Resources and a Theme.

Parameters
r	Resources: Resources against which the ColorStateList should be inflated. This value cannot be null.
parser	XmlPullParser: Parser for the XML document defining the ColorStateList. This value cannot be null.
theme	Resources.Theme: Optional theme to apply to the color state list, may be null.

Returns
ColorStateList	A new color state list. This value cannot be null.

Throws
IOException
XmlPullParserException

describeContents

Added in API level 1

public int describeContents ()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. For example, if the object will include a file descriptor in the output of writeToParcel(android.os.Parcel, int), the return value of this method must include the CONTENTS_FILE_DESCRIPTOR bit.

Returns
int	a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or CONTENTS_FILE_DESCRIPTOR

getChangingConfigurations

Added in API level 23

public int getChangingConfigurations ()

Returns a mask of the configuration parameters for which this color state list may change, requiring that it be re-created.

Returns

int

a mask of the changing configuration parameters, as defined by ActivityInfo Value is either 0 or a combination of ActivityInfo.CONFIG_MCC, ActivityInfo.CONFIG_MNC, ActivityInfo.CONFIG_LOCALE, ActivityInfo.CONFIG_TOUCHSCREEN, ActivityInfo.CONFIG_KEYBOARD, ActivityInfo.CONFIG_KEYBOARD_HIDDEN, ActivityInfo.CONFIG_NAVIGATION, ActivityInfo.CONFIG_ORIENTATION, ActivityInfo.CONFIG_SCREEN_LAYOUT, ActivityInfo.CONFIG_UI_MODE, ActivityInfo.CONFIG_SCREEN_SIZE, ActivityInfo.CONFIG_SMALLEST_SCREEN_SIZE, ActivityInfo.CONFIG_DENSITY, ActivityInfo.CONFIG_LAYOUT_DIRECTION, ActivityInfo.CONFIG_COLOR_MODE, ActivityInfo.CONFIG_FONT_SCALE, ActivityInfo.CONFIG_GRAMMATICAL_GENDER, ActivityInfo.CONFIG_ASSETS_PATHS, and ActivityInfo.CONFIG_RESOURCES_UNUSED

See also:

• ActivityInfo

getColorForState

Added in API level 1

public int getColorForState (int[] stateSet, 
                int defaultColor)

Return the color associated with the given set of View states.

Parameters
stateSet	int: an array of View states This value may be null.
defaultColor	int: the color to return if there's no matching state spec in this ColorStateList that matches the stateSet.

Returns
int	the color associated with that set of states in this ColorStateList.

getDefaultColor

Added in API level 1

public int getDefaultColor ()

Return the default color in this ColorStateList.

Returns
int	the default color in this ColorStateList.

isOpaque

Added in API level 21

public boolean isOpaque ()

Indicates whether this color state list is opaque, which means that every color returned from getColorForState(int[], int) has an alpha value of 255.

Returns
boolean	True if this color state list is opaque.

isStateful

Added in API level 1

public boolean isStateful ()

Indicates whether this color state list contains at least one state spec and the first spec is not empty (e.g. match-all).

Returns
boolean	True if this color state list changes color based on state, false otherwise.

See also:

• getColorForState(int[], int)

toString

Added in API level 1

public String toString ()

Returns a string representation of the object.

Returns
String	a string representation of the object.

valueOf

Added in API level 1

public static ColorStateList valueOf (int color)

Parameters
color	int

Returns
ColorStateList	A ColorStateList containing a single color. This value cannot be null.

withAlpha

Added in API level 1

public ColorStateList withAlpha (int alpha)

Creates a new ColorStateList that has the same states and colors as this one but where each color has the specified alpha value (0-255).

Parameters
alpha	int: The new alpha channel value (0-255).

Returns
ColorStateList	A new color state list. This value cannot be null.

withLStar

Added in API level 31

public ColorStateList withLStar (float lStar)

Creates a new ColorStateList that has the same states and colors as this one but where each color has the specified perceived luminosity value (0-100).

Parameters
lStar	float: Target perceptual luminance (0-100).

Returns
ColorStateList	A new color state list. This value cannot be null.

writeToParcel

Added in API level 1

public void writeToParcel (Parcel dest, 
                int flags)

Flatten this object in to a Parcel.

Parameters
dest	Parcel: The Parcel in which the object should be written. This value cannot be null.
flags	int: Additional flags about how the object should be written. May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE. Value is either 0 or a combination of Parcelable.PARCELABLE_WRITE_RETURN_VALUE, and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES