clarification to the uses-configuration tag to discourage its use.

Change-Id: I5ee9ca93e8debaf2dfb8f1018b77af4486f1e516

1 files changed, 44 insertions, 40 deletions

diff --git a/docs/html/guide/topics/manifest/uses-configuration-element.jd b/docs/html/guide/topics/manifest/uses-configuration-element.jd
index 810975e..e9a0ba4 100644
--- a/docs/html/guide/topics/manifest/uses-configuration-element.jd
+++ b/docs/html/guide/topics/manifest/uses-configuration-element.jd
@@ -6,18 +6,18 @@ parent.link=manifest-intro.html
 <!-- ##api level 3##  see comment below -->
 
 <!-- the "no___" values are nonsensical if they mean "doesn't work on devices with a
-keyboard / navigation control / touch screen."  Dianne says that that's what they mean and 
-that they therefore should be eliminated.  Suchi says that they mean "doesn't require a 
+keyboard / navigation control / touch screen."  Dianne says that that's what they mean and
+that they therefore should be eliminated.  Suchi says that they mean "doesn't require a
 keyboard / navigation control / touch screen to work."  But then what does "undefined" mean?
 Seems like some API change is in the works, either eliminating the "no___" values or
-"undefined".  Since it's unclear what the change will be, I've chosen to document the "no___" 
+"undefined".  Since it's unclear what the change will be, I've chosen to document the "no___"
 and "undefined" attributes using the same language, which is surely wrong but may make it
-easier to update the doc when the change is made. -->
+easier to update the doc when the change is made... Nov 2013, this still seems unresolved. -->
 
 <dl class="xml">
 <dt>syntax:</dt>
 <dd><pre class="stx">&lt;uses-configuration
-  android:<a href="#five">reqFiveWayNav</a>=["true" | "false"] 
+  android:<a href="#five">reqFiveWayNav</a>=["true" | "false"]
   android:<a href="#hard">reqHardKeyboard</a>=["true" | "false"]
   android:<a href="#kbd">reqKeyboardType</a>=["undefined" | "nokeys" | "qwerty" | "twelvekey"]
   android:<a href="#nav">reqNavigation</a>=["undefined" | "nonav" | "dpad" | "trackball" | "wheel"]
@@ -27,38 +27,35 @@ easier to update the doc when the change is made. -->
 <dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
 
 <dt>description:</dt>
-<dd>Indicates what hardware and software features the application requires.  
-For example, an application might specify that it requires a physical keyboard 
+<dd>Indicates what hardware and software features the application requires.
+For example, an application might specify that it requires a physical keyboard
 or a particular navigation device, like a trackball.  The specification is
 used to avoid installing the application on devices where it will not work.
 
-<p>
-If an application can work with different device configurations, it 
-should include separate {@code &lt;uses-configuration&gt;} declarations for 
-each one.  Each declaration must be complete.  For example, if an application 
-requires a five-way navigation control, a touch screen that can be operated 
-with a finger, and either a standard QWERTY keyboard or a numeric 12-key
-keypad like those found on most phones, it would specify these requirements
-with two {@code &lt;uses-configuration&gt;} elements as follows:
-</p>
+<p class="note"><strong>Note: Most apps should not use this manifest tag.</strong> You should
+<em>always</em> support input with a directional pad (d-pad) in order to assist sight-impaired
+users and support devices that provide d-pad input in addition to or instead of touch. For
+information about how to support d-pad input in your app, read <a href=
+"{@docRoot}guide/topics/ui/accessibility/apps.html#focus-nav">Enabling Focus Navigation</a>. If
+your app absolutely cannot function without a touchscreen, then instead use the <a href=
+"{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code &lt;uses-feature&gt;}</a> tag to
+declare the required touchscreen type, ranging from {@code "android.hardware.faketouch"} for basic
+touch-style events to more advanced touch types such as {@code
+"android.hardware.touchscreen.multitouch.jazzhand"} for distinct input from multiple fingers.</p>
 
-<pre>&lt;uses-configuration android:reqFiveWayNav="true" android:reqTouchScreen="finger"
-                    android:reqKeyboardType="qwerty" /&gt;
-&lt;uses-configuration android:reqFiveWayNav="true" android:reqTouchScreen="finger"
-                    android:reqKeyboardType="twelvekey" /&gt;</pre></dd>
 
 <dt>attributes:</dt>
 <dd><dl class="attr">
 <dt><a name="five"></a>{@code android:reqFiveWayNav}</dt>
-<dd>Whether or not the application requires a five-way navigation control 
+<dd>Whether or not the application requires a five-way navigation control
 &mdash; "{@code true}" if it does, and "{@code false}" if not.  A five-way
-control is one that can move the selection up, down, right, or left, and 
-also provides a way of invoking the current selection.  It could be a 
-D-pad (directional pad), trackball, or other device.  
+control is one that can move the selection up, down, right, or left, and
+also provides a way of invoking the current selection.  It could be a
+D-pad (directional pad), trackball, or other device.
 
 <p>
 If an application requires a directional control, but not a control of a
-particular type, it can set this attribute to "{@code true}" and ignore 
+particular type, it can set this attribute to "{@code true}" and ignore
 the <code><a href="#nav">reqNavigation</a></code> attribute.  However,
 if it requires a particular type of directional control, it can ignore
 this attribute and set {@code reqNavigation} instead.
@@ -69,10 +66,10 @@ this attribute and set {@code reqNavigation} instead.
 "{@code true}" if it does, and "{@code false}" if not.</dd>
 
 <dt><a name="kbd"></a>{@code android:reqKeyboardType}</dt>
-<dd>The type of keyboard the application requires, if any at all. 
-This attribute does not distinguish between hardware and software 
+<dd>The type of keyboard the application requires, if any at all.
+This attribute does not distinguish between hardware and software
 keyboards.  If a hardware keyboard of a certain type is required,
-specify the type here and also set the {@code reqHardKeyboard} attribute 
+specify the type here and also set the {@code reqHardKeyboard} attribute
 to "{@code true}".
 
 <p>
@@ -85,8 +82,8 @@ The value must be one of the following strings:
    <th>Description</th>
 </tr><tr>
    <td>"{@code undefined}"</td>
-   <td>The application does not require a keyboard. 
-       (A keyboard requirement is not defined.)  
+   <td>The application does not require a keyboard.
+       (A keyboard requirement is not defined.)
        This is the default value.</td>
 </tr><tr>
    <td>"{@code nokeys}"</td>
@@ -96,14 +93,14 @@ The value must be one of the following strings:
    <td>The application requires a standard QWERTY keyboard.</td>
 </tr><tr>
    <td>"{@code twelvekey}"</td>
-   <td>The application requires a twelve-key keypad, like those on most 
-       phones &mdash; with keys for the digits from {@code 0} through 
+   <td>The application requires a twelve-key keypad, like those on most
+       phones &mdash; with keys for the digits from {@code 0} through
        {@code 9} plus star ({@code *}) and pound ({@code #}) keys.</td>
 </tr>
 </table></dd>
 
 <dt><a name="nav"></a>{@code android:reqNavigation}</dt>
-<dd>The navigation device required by the application, if any.  The value 
+<dd>The navigation device required by the application, if any.  The value
 must be one of the following strings:
 
 <table>
@@ -112,8 +109,8 @@ must be one of the following strings:
    <th>Description</th>
 </tr><tr>
    <td>"{@code undefined}"</td>
-   <td>The application does not require any type of navigation control. 
-       (The navigation requirement is not defined.)  
+   <td>The application does not require any type of navigation control.
+       (The navigation requirement is not defined.)
        This is the default value.</td>
 </tr><tr>
    <td>"{@code nonav}"</td>
@@ -132,14 +129,14 @@ must be one of the following strings:
 
 <p>
 If an application requires a navigational control, but the exact type of
-control doesn't matter, it can set the 
+control doesn't matter, it can set the
 <code><a href="#five">reqFiveWayNav</a></code> attribute to "{@code true}"
 rather than set this one.
 </p></dd>
 
 <dt><a name="touch"></a>{@code android:reqTouchScreen}</dt>
 <dd>The type of touch screen the application requires, if any at all.
-The value must be one of the following strings: 
+The value must be one of the following strings:
 
 <table>
 <tr>
@@ -147,7 +144,7 @@ The value must be one of the following strings:
    <th>Description</th>
 </tr><tr>
    <td>"{@code undefined}"</td>
-   <td>The application doesn't require a touch screen.  
+   <td>The application doesn't require a touch screen.
        (The touch screen requirement is undefined.)
        This is the default value.</td>
 </tr><tr>
@@ -158,7 +155,14 @@ The value must be one of the following strings:
    <td>The application requires a touch screen that's operated with a stylus.</td>
 </tr><tr>
    <td>"{@code finger}"</td>
-   <td>The application requires a touch screen that can be operated with a finger.</td>
+   <td>The application requires a touch screen that can be operated with a finger.
+
+      <p class="note"><strong>Note:</strong> If some type of touch input is required for your app,
+      you should instead use the
+      <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code
+      &lt;uses-feature>}</a> tag to declare the required touchscreen
+      type, beginning with {@code "android.hardware.faketouch"} for basic touch-style events.</p>
+   </td>
 </tr>
 </table></dd>
 </dl></dd>
@@ -172,7 +176,7 @@ The value must be one of the following strings:
   <ul>
     <li><code><a href="{@docRoot}guide/topics/manifest/activity-element.html#config">configChanges</a></code>
 attribute of the
-<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code> 
+<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
 element</dd></li>
     <li>{@link android.content.pm.ConfigurationInfo}</li>
   </ul>