frameworks/base/docs/html/guide/topics/resources/color-list-resource.jd

   1 page.title=Color State List Resource
   2 parent.title=Resource Types
   3 parent.link=available-resources.html
   4 @jd:body
   5
   6 <div id="qv-wrapper">
   7   <div id="qv">
   8     <h2>See also</h2>
   9     <ol>
  10       <li><a href="more-resources.html#Color">Color (simple value)</a></li>
  11     </ol>
  12   </div>
  13 </div>
  14
  15
  16 <p>A {@link android.content.res.ColorStateList} is an object you can define in XML
  17 that you can apply as a color, but will actually change colors, depending on the state of
  18 the {@link android.view.View} object to which it is applied. For example, a {@link
  19 android.widget.Button} widget can exist in one of several different states (pressed, focused,
  20 or niether) and, using a color state list, you can provide a different color during each state.</p>
  21
  22 <p>You can describe the state list in an XML file. Each color is defined in an {@code
  23 &lt;item>} element inside a single {@code &lt;selector>} element. Each {@code &lt;item>}
  24 uses various attributes to describe the state in which it should be used.</p>
  25
  26 <p>During each state change, the state list is traversed top to bottom and the first item that
  27 matches the current state will be used&mdash;the selection is <em>not</em> based on the "best
  28 match," but simply the first item that meets the minimum criteria of the state.</p>
  29
  30 <p class="note"><strong>Note:</strong> If you want to provide a static color resource, use a
  31 simple <a href="more-resources.html#Color">Color</a> value.</p>
  32
  33 <dl class="xml">
  34
  35 <dt>file location:</dt>
  36 <dd><code>res/color/<em>filename</em>.xml</code><br/>
  37 The filename will be used as the resource ID.</dd>
  38
  39 <dt>compiled resource datatype:</dt>
  40 <dd>Resource pointer to a {@link android.content.res.ColorStateList}.</dd>
  41
  42 <dt>resource reference:</dt>
  43 <dd>
  44 In Java: <code>R.color.<em>filename</em></code><br/>
  45 In XML: <code>@[<em>package</em>:]color/<em>filename</em></code>
  46 </dd>
  47
  48 <dt>syntax:</dt>
  49 <dd>
  50 <pre class="stx">
  51 &lt;?xml version="1.0" encoding="utf-8"?>
  52 &lt;<a href="#selector-element">selector</a> xmlns:android="http://schemas.android.com/apk/res/android" >
  53     &lt;<a href="#item-element">item</a>
  54         android:color="<em>hex_color</em>"
  55         android:state_pressed=["true" | "false"]
  56         android:state_focused=["true" | "false"]
  57         android:state_selected=["true" | "false"]
  58         android:state_checkable=["true" | "false"]
  59         android:state_checked=["true" | "false"]
  60         android:state_enabled=["true" | "false"]
  61         android:state_window_focused=["true" | "false"] />
  62 &lt;/selector>
  63 </pre>
  64 </dd>
  65
  66 <dt>elements:</dt>
  67 <dd>
  68 <dl class="tag-list">
  69
  70   <dt id="selector-element"><code>&lt;selector&gt;</code></dt>
  71     <dd><strong>Required.</strong> This must be the root element. Contains one or more {@code
  72 &lt;item>} elements.
  73       <p class="caps">attributes:</p>
  74       <dl class="atn-list">
  75         <dt><code>xmlns:android</code></dt>
  76           <dd><em>String</em>. <strong>Required.</strong> Defines the XML namespace, which must be
  77           <code>"http://schemas.android.com/apk/res/android"</code>.
  78       </dl>
  79     </dd>
  80   <dt id="item-element"><code>&lt;item&gt;</code></dt>
  81     <dd>Defines a color to use during certain states, as described by its attributes. Must be a
  82 child of a <code>&lt;selector&gt;</code> element.
  83       <p class="caps">attributes:</p>
  84       <dl class="atn-list">
  85         <dt><code>android:color</code></dt>
  86           <dd><em>Hexadeximal color</em>. <strong>Required</strong>. The color is specified with an
  87 RGB value and optional alpha channel.
  88 <p>The value always begins with a pound (#) character and then followed by the
  89 Alpha-Red-Green-Blue information in one of the following formats:</p>
  90 <ul>
  91   <li>#<em>RGB</em></li>
  92   <li>#<em>ARGB</em></li>
  93   <li>#<em>RRGGBB</em></li>
  94   <li>#<em>AARRGGBB</em></li>
  95 </ul></dd>
  96         <dt><code>android:state_pressed</code></dt>
  97           <dd><em>Boolean</em>. "true" if this item should be used when the object is pressed (such as when a button
  98 is touched/clicked); "false" if this item should be used in the default, non-pressed state.</dd>
  99         <dt><code>android:state_focused</code></dt>
 100           <dd><em>Boolean</em>. "true" if this item should be used when the object is focused (such as when a button
 101 is highlighted using the trackball/d-pad); "false" if this item should be used in the default,
 102 non-focused state.</dd>
 103         <dt><code>android:state_selected</code></dt>
 104           <dd><em>Boolean</em>. "true" if this item should be used when the object is selected (such as when a
 105 tab is opened); "false" if this item should be used when the object is not selected.</dd>
 106         <dt><code>android:state_checkable</code></dt>
 107           <dd><em>Boolean</em>. "true" if this item should be used when the object is checkable; "false" if this
 108 item should be used when the object is not checkable. (Only useful if the object can
 109 transition between a checkable and non-checkable widget.)</dd>
 110         <dt><code>android:state_checked</code></dt>
 111           <dd><em>Boolean</em>. "true" if this item should be used when the object is checked; "false" if it
 112 should be used when the object is un-checked.</dd>
 113         <dt><code>android:state_enabled</code></dt>
 114           <dd><em>Boolean</em>. "true" if this item should be used when the object is enabled (capable of
 115 receiving touch/click events); "false" if it should be used when the object is disabled.</dd>
 116         <dt><code>android:state_window_focused</code></dt>
 117           <dd><em>Boolean</em>. "true" if this item should be used when the application window has focus (the
 118 application is in the foreground), "false" if this item should be used when the application
 119 window does not have focus (for example, if the notification shade is pulled down or a dialog appears).</dd>
 120       </dl>
 121       <p class="note"><strong>Note:</strong> Remember that the first item in the state list that
 122 matches the current state of the object will be applied. So if the first item in the list contains
 123 none of the state attributes above, then it will be applied every time, which is why your
 124 default value should always be last (as demonstrated in the following example).</p>
 125     </dd>
 126
 127 </dl>
 128 </dd> <!-- end  elements and attributes -->
 129
 130 <dt>example:</dt>
 131 <dd>XML file saved at <code>res/color/button_text.xml</code>:
 132 <pre>
 133 &lt;?xml version="1.0" encoding="utf-8"?>
 134 &lt;selector xmlns:android="http://schemas.android.com/apk/res/android">
 135     &lt;item android:state_pressed="true"
 136           android:color="#ffff0000"/> &lt;!-- pressed --&gt;
 137     &lt;item android:state_focused="true"
 138           android:color="#ff0000ff"/> &lt;!-- focused --&gt;
 139     &lt;item android:color="#ff000000"/> &lt;!-- default --&gt;
 140 &lt;/selector>
 141 </pre>
 142
 143 <p>This layout XML will apply the color list to a View:</p>
 144 <pre>
 145 &lt;Button
 146     android:layout_width="fill_parent"
 147     android:layout_height="wrap_content"
 148     android:text="@string/button_text"
 149     android:textColor="@color/button_text" />
 150 </pre>
 151 </dd> <!-- end example -->
 152
 153 <dt>see also:</dt>
 154 <dd>
 155 <ul>
 156   <li><a href="more-resources.html#Color">Color (simple value)</a></li>
 157   <li>{@link android.content.res.ColorStateList}</li>
 158   <li><a href="drawable-resource.html#StateList">State List Drawable</a></li>
 159 </ul>
 160 </dd>
 161
 162 </dl>
 163
 164