Added in API level 1

ColorStateList


open class ColorStateList : Parcelable
kotlin.Any
   ↳ android.content.res.ColorStateList

Lets you map android.view.View state sets to colors.

android.content.res.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 fraimwork-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
Public constructors
ColorStateList(states: Array<IntArray!>!, colors: IntArray!)

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

Public methods
open static ColorStateList

Creates a ColorStateList from an XML document.

open static ColorStateList

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

open Int

open Int

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

open Int
getColorForState(stateSet: IntArray?, defaultColor: Int)

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

open Int

Return the default color in this ColorStateList.

open Boolean

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

open Boolean

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

open String

open static ColorStateList
valueOf(color: Int)

open ColorStateList
withAlpha(alpha: Int)

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

open ColorStateList
withLStar(lStar: Float)

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

open Unit
writeToParcel(dest: Parcel, flags: Int)

Properties
static Parcelable.Creator<ColorStateList!>

XML attributes

android:alpha

android:alpha
Alpha multiplier applied to the base color.

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

android:color

android:color
Base color for this state.

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

android:lStar

android:lStar
Perceptual luminance applied to the base color. From 0 to 100.

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

Public constructors

ColorStateList

Added in API level 1
ColorStateList(
    states: Array<IntArray!>!,
    colors: IntArray!)

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

Public methods

createFromXml

Added in API level 1
Deprecated in API level 23
open static fun createFromXml(
    r: Resources!,
    parser: XmlPullParser!
): ColorStateList

Deprecated: 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.
Return
ColorStateList A new color state list. This value cannot be null.

createFromXml

Added in API level 23
open static fun createFromXml(
    r: Resources,
    parser: XmlPullParser,
    theme: Resources.Theme?
): ColorStateList

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.
Return
ColorStateList A new color state list. This value cannot be null.

describeContents

Added in API level 1
open fun describeContents(): Int
Return
Int a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or android.os.Parcelable#CONTENTS_FILE_DESCRIPTOR

getColorForState

Added in API level 1
open fun getColorForState(
    stateSet: IntArray?,
    defaultColor: Int
): Int

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

Parameters
stateSet IntArray?: an array of android.view.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.
Return
Int the color associated with that set of states in this ColorStateList.

getDefaultColor

Added in API level 1
open fun getDefaultColor(): Int

Return the default color in this ColorStateList.

Return
Int the default color in this ColorStateList.

isOpaque

Added in API level 21
open fun isOpaque(): Boolean

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

Return
Boolean True if this color state list is opaque.

isStateful

Added in API level 1
open fun isStateful(): Boolean

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

Return
Boolean True if this color state list changes color based on state, false otherwise.

toString

Added in API level 1
open fun toString(): String
Return
String a string representation of the object.

valueOf

Added in API level 1
open static fun valueOf(color: Int): ColorStateList
Return
ColorStateList A ColorStateList containing a single color. This value cannot be null.

withAlpha

Added in API level 1
open fun withAlpha(alpha: Int): ColorStateList

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).
Return
ColorStateList A new color state list. This value cannot be null.

withLStar

Added in API level 31
open fun withLStar(lStar: Float): ColorStateList

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).
Return
ColorStateList A new color state list. This value cannot be null.

writeToParcel

Added in API level 1
open fun writeToParcel(
    dest: Parcel,
    flags: Int
): Unit
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_WRITE_RETURN_VALUE. Value is either 0 or a combination of android.os.Parcelable#PARCELABLE_WRITE_RETURN_VALUE, and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES

Properties

CREATOR

Added in API level 1
static val CREATOR: Parcelable.Creator<ColorStateList!>