From 582dcac856268f13121d5775497c5e1ca13e47af Mon Sep 17 00:00:00 2001 From: Alan Viverette Date: Mon, 16 May 2016 12:37:55 -0400 Subject: [PATCH] Update docs for ColorStateList to include alpha Bug: 28760030 Change-Id: I309364002220b9896f5ddf29dabde79636a722e9 --- .../android/content/res/ColorStateList.java | 82 +++++++++++++++---- 1 file changed, 67 insertions(+), 15 deletions(-) diff --git a/core/java/android/content/res/ColorStateList.java b/core/java/android/content/res/ColorStateList.java index fb5bfd363ce22..273522a94af3f 100644 --- a/core/java/android/content/res/ColorStateList.java +++ b/core/java/android/content/res/ColorStateList.java @@ -46,29 +46,81 @@ import java.util.Arrays; /** * * Lets you map {@link android.view.View} state sets to colors. - * + *

* {@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. + * + * + *

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 {@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. + * + * + *

Item attributes

+ *

+ * 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" />
+ *
+ * + * + *

Developer guide

+ *

+ * 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";