* {@link 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: - * + * "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/testcolor1"/> - * <item android:state_pressed="true" android:state_enabled="false" android:color="@color/testcolor2" /> - * <item android:state_enabled="false" android:color="@color/testcolor3" /> - * <item android:color="@color/testcolor5"/> + * <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. The list of state specs will be processed in order of the items in the XML 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. Note that if you have such an item before any other items - * in the list then any subsequent items will end up being ignored. - *
For more information, see the guide to Color State - * List Resource.
+ * with that spec. + * + * + *+ * Each item defines a set of state spec and color pairs, where the state spec is a series of + * attributes set to either {@code true} or {@code 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 + * {@link android.R.attr#state_focused android:state_focused} or + * {@link android.R.attr#state_enabled 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 if placed before other items, those items + * will be ignored. + * + * + *
+ * Each item must define an {@link android.R.attr#color 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 {@link android.R.attr#alpha 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 {@code 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" /> + *+ * + * + *
+ * For more information, see the guide to + * Color State + * List Resource. + * + * @attr ref android.R.styleable#ColorStateListItem_alpha + * @attr ref android.R.styleable#ColorStateListItem_color */ public class ColorStateList extends ComplexColor implements Parcelable { private static final String TAG = "ColorStateList";