Merge "Docs: update state list drawable with state_activated and revise selected/focused" into ics-mr0

Author: scottamain

docs/html/guide/topics/resources/drawable-resource.jd

@@ -646,6 +646,7 @@ In XML: <code>@[<em>package</em>:]drawable/<em>filename</em></code>
         android:state_checkable=["true" | "false"]
         android:state_checked=["true" | "false"]
         android:state_enabled=["true" | "false"]
+        android:state_activated=["true" | "false"]
         android:state_window_focused=["true" | "false"] />
 &lt;/selector>
 </pre>
@@ -690,17 +691,20 @@ child of a <code>&lt;selector&gt;</code> element.
           <dd><em>Boolean</em>. "true" if this item should be used when the object is pressed (such as when a button
 is touched/clicked); "false" if this item should be used in the default, non-pressed state.</dd>
         <dt><code>android:state_focused</code></dt>
-          <dd><em>Boolean</em>. "true" if this item should be used when the object is focused (such as when a button
-is highlighted using the trackball/d-pad); "false" if this item should be used in the default,
+          <dd><em>Boolean</em>. "true" if this item should be used when the object has input focus
+(such as when the user selects a text input); "false" if this item should be used in the default,
 non-focused state.</dd>
         <dt><code>android:state_hovered</code></dt>
           <dd><em>Boolean</em>. "true" if this item should be used when the object is being hovered
 by a cursor; "false" if this item should be used in the default, non-hovered state. Often, this
 drawable may be the same drawable used for the "focused" state.
           <p>Introduced in API level 14.</p></dd>
         <dt><code>android:state_selected</code></dt>
-          <dd><em>Boolean</em>. "true" if this item should be used when the object is selected (such as when a
-tab is opened); "false" if this item should be used when the object is not selected.</dd>
+          <dd><em>Boolean</em>. "true" if this item should be used when the object is the current
+user selection when navigating with a directional control (such as when navigating through a list
+with a d-pad); "false" if this item should be used when the object is not selected.
+<p>The selected state is used when focus (<code>android:state_focused</code>) is not sufficient
+(such as when list view has focus and an item within it is selected with a d-pad).</p></dd>
         <dt><code>android:state_checkable</code></dt>
           <dd><em>Boolean</em>. "true" if this item should be used when the object is checkable; "false" if this
 item should be used when the object is not checkable. (Only useful if the object can
@@ -709,8 +713,14 @@ transition between a checkable and non-checkable widget.)</dd>
           <dd><em>Boolean</em>. "true" if this item should be used when the object is checked; "false" if it
 should be used when the object is un-checked.</dd>
         <dt><code>android:state_enabled</code></dt>
-          <dd><em>Boolean</em>. "true" if this item should be used when the object is enabled (capable of
-receiving touch/click events); "false" if it should be used when the object is disabled.</dd>
+          <dd><em>Boolean</em>. "true" if this item should be used when the object is enabled
+(capable of receiving touch/click events); "false" if it should be used when the object is
+disabled.</dd>
+        <dt><code>android:state_activated</code></dt>
+          <dd><em>Boolean</em>. "true" if this item should be used when the object is activated as
+the persistent selection (such as to "highlight" the previously selected list item in a persistent
+navigation view); "false" if it should be used when the object is not activated.
+<p>Introduced in API level 11.</p></dd>
         <dt><code>android:state_window_focused</code></dt>
           <dd><em>Boolean</em>. "true" if this item should be used when the application window has focus (the
 application is in the foreground), "false" if this item should be used when the application