ColorStateList
open class ColorStateList : Parcelable
kotlin.Any | |
↳ | android.content.res.ColorStateList |
Lets you map android.view.View
state sets to colors.
android.content.res.ColorStateList
s 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>
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 | |
---|---|
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 |
createFromXml(r: Resources!, parser: XmlPullParser!) Creates a ColorStateList from an XML document. |
open static ColorStateList |
createFromXml(r: Resources, parser: XmlPullParser, theme: Resources.Theme?) Creates a ColorStateList from an XML document using given a set of |
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 |
open Int |
Return the default color in this |
open Boolean |
isOpaque() Indicates whether this color state list is opaque, which means that every color returned from |
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 |
toString() |
open static ColorStateList | |
open 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). |
open 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). |
open Unit |
writeToParcel(dest: Parcel, flags: Int) |
Properties | |
---|---|
static Parcelable.Creator<ColorStateList!> |
XML attributes
android:alpha
android:alpha
May be a floating point value, such as "1.2
".
android:color
android:color
May be a color value, in the form of "rgb
", "argb
", "rrggbb
", or "aarrggbb
".
android:lStar
android:lStar
May be a floating point value, such as "1.2
".
Public constructors
ColorStateList
ColorStateList(
states: Array<IntArray!>!,
colors: IntArray!)
Creates a ColorStateList that returns the specified mapping from states to colors.
Public methods
createFromXml
open static funcreateFromXml(
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
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
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 |
getChangingConfigurations
open fun getChangingConfigurations(): Int
Returns a mask of the configuration parameters for which this color state list may change, requiring that it be re-created.
See Also
getColorForState
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
open fun getDefaultColor(): Int
Return the default color in this ColorStateList
.
Return | |
---|---|
Int |
the default color in this ColorStateList . |
isOpaque
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
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. |
See Also
toString
open fun toString(): String
Return | |
---|---|
String |
a string representation of the object. |
valueOf
open static fun valueOf(color: Int): ColorStateList
Return | |
---|---|
ColorStateList |
A ColorStateList containing a single color. This value cannot be null . |
withAlpha
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
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
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 |