Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am 91d60268: am a48de700: Merge "clarification to the uses-configuration tag to discourage its use." into klp-docs

Browse Source 
* commit '91d6026894cd118f1fa1236c28c8384272ea7421':
  clarification to the uses-configuration tag to discourage its use.
This commit is contained in:
Scott Main
2013-11-14 11:25:19 -08:00
committed by Android Git Automerger
parent be20c89731 91d6026894
commit bcad854065
1 changed files with 44 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

84
docs/html/guide/topics/manifest/uses-configuration-element.jd
View File

@@ -6,18 +6,18 @@ parent.link=manifest-intro.html
<!-- ##api level 3## see comment below --> <!-- ##api level 3## see comment below -->
<!-- the "no___" values are nonsensical if they mean "doesn't work on devices with a <!-- 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 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 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? 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 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 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"> <dl class="xml">
<dt>syntax:</dt> <dt>syntax:</dt>
<dd><pre class="stx">&lt;uses-configuration <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="#hard">reqHardKeyboard</a>=["true" | "false"]
android:<a href="#kbd">reqKeyboardType</a>=["undefined" | "nokeys" | "qwerty" | "twelvekey"] android:<a href="#kbd">reqKeyboardType</a>=["undefined" | "nokeys" | "qwerty" | "twelvekey"]
android:<a href="#nav">reqNavigation</a>=["undefined" | "nonav" | "dpad" | "trackball" | "wheel"] 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> <dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
<dt>description:</dt> <dt>description:</dt>
<dd>Indicates what hardware and software features the application requires. <dd>Indicates what hardware and software features the application requires.
For example, an application might specify that it requires a physical keyboard For example, an application might specify that it requires a physical keyboard
or a particular navigation device, like a trackball. The specification is or a particular navigation device, like a trackball. The specification is
used to avoid installing the application on devices where it will not work. used to avoid installing the application on devices where it will not work.
<p> <p class="note"><strong>Note: Most apps should not use this manifest tag.</strong> You should
If an application can work with different device configurations, it <em>always</em> support input with a directional pad (d-pad) in order to assist sight-impaired
should include separate {@code &lt;uses-configuration&gt;} declarations for users and support devices that provide d-pad input in addition to or instead of touch. For
each one. Each declaration must be complete. For example, if an application information about how to support d-pad input in your app, read <a href=
requires a five-way navigation control, a touch screen that can be operated "{@docRoot}guide/topics/ui/accessibility/apps.html#focus-nav">Enabling Focus Navigation</a>. If
with a finger, and either a standard QWERTY keyboard or a numeric 12-key your app absolutely cannot function without a touchscreen, then instead use the <a href=
keypad like those found on most phones, it would specify these requirements "{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code &lt;uses-feature&gt;}</a> tag to
with two {@code &lt;uses-configuration&gt;} elements as follows: declare the required touchscreen type, ranging from {@code "android.hardware.faketouch"} for basic
</p> 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> <dt>attributes:</dt>
<dd><dl class="attr"> <dd><dl class="attr">
<dt><a name="five"></a>{@code android:reqFiveWayNav}</dt> <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 &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 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 also provides a way of invoking the current selection. It could be a
D-pad (directional pad), trackball, or other device. D-pad (directional pad), trackball, or other device.
<p> <p>
If an application requires a directional control, but not a control of a 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, the <code><a href="#nav">reqNavigation</a></code> attribute. However,
if it requires a particular type of directional control, it can ignore if it requires a particular type of directional control, it can ignore
this attribute and set {@code reqNavigation} instead. 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> "{@code true}" if it does, and "{@code false}" if not.</dd>
<dt><a name="kbd"></a>{@code android:reqKeyboardType}</dt> <dt><a name="kbd"></a>{@code android:reqKeyboardType}</dt>
<dd>The type of keyboard the application requires, if any at all. <dd>The type of keyboard the application requires, if any at all.
This attribute does not distinguish between hardware and software This attribute does not distinguish between hardware and software
keyboards. If a hardware keyboard of a certain type is required, 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}". to "{@code true}".
<p> <p>
@@ -85,8 +82,8 @@ The value must be one of the following strings:
<th>Description</th> <th>Description</th>
</tr><tr> </tr><tr>
<td>"{@code undefined}"</td> <td>"{@code undefined}"</td>
<td>The application does not require a keyboard. <td>The application does not require a keyboard.
(A keyboard requirement is not defined.) (A keyboard requirement is not defined.)
This is the default value.</td> This is the default value.</td>
</tr><tr> </tr><tr>
<td>"{@code nokeys}"</td> <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> <td>The application requires a standard QWERTY keyboard.</td>
</tr><tr> </tr><tr>
<td>"{@code twelvekey}"</td> <td>"{@code twelvekey}"</td>
<td>The application requires a twelve-key keypad, like those on most <td>The application requires a twelve-key keypad, like those on most
phones &mdash; with keys for the digits from {@code 0} through phones &mdash; with keys for the digits from {@code 0} through
{@code 9} plus star ({@code *}) and pound ({@code #}) keys.</td> {@code 9} plus star ({@code *}) and pound ({@code #}) keys.</td>
</tr> </tr>
</table></dd> </table></dd>
<dt><a name="nav"></a>{@code android:reqNavigation}</dt> <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: must be one of the following strings:
<table> <table>
@@ -112,8 +109,8 @@ must be one of the following strings:
<th>Description</th> <th>Description</th>
</tr><tr> </tr><tr>
<td>"{@code undefined}"</td> <td>"{@code undefined}"</td>
<td>The application does not require any type of navigation control. <td>The application does not require any type of navigation control.
(The navigation requirement is not defined.) (The navigation requirement is not defined.)
This is the default value.</td> This is the default value.</td>
</tr><tr> </tr><tr>
<td>"{@code nonav}"</td> <td>"{@code nonav}"</td>
@@ -132,14 +129,14 @@ must be one of the following strings:
<p> <p>
If an application requires a navigational control, but the exact type of 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}" <code><a href="#five">reqFiveWayNav</a></code> attribute to "{@code true}"
rather than set this one. rather than set this one.
</p></dd> </p></dd>
<dt><a name="touch"></a>{@code android:reqTouchScreen}</dt> <dt><a name="touch"></a>{@code android:reqTouchScreen}</dt>
<dd>The type of touch screen the application requires, if any at all. <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> <table>
<tr> <tr>
@@ -147,7 +144,7 @@ The value must be one of the following strings:
<th>Description</th> <th>Description</th>
</tr><tr> </tr><tr>
<td>"{@code undefined}"</td> <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.) (The touch screen requirement is undefined.)
This is the default value.</td> This is the default value.</td>
</tr><tr> </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> <td>The application requires a touch screen that's operated with a stylus.</td>
</tr><tr> </tr><tr>
<td>"{@code finger}"</td> <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> </tr>
</table></dd> </table></dd>
</dl></dd> </dl></dd>
@@ -172,7 +176,7 @@ The value must be one of the following strings:
<ul> <ul>
<li><code><a href="{@docRoot}guide/topics/manifest/activity-element.html#config">configChanges</a></code> <li><code><a href="{@docRoot}guide/topics/manifest/activity-element.html#config">configChanges</a></code>
attribute of the 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> element</dd></li>
<li>{@link android.content.pm.ConfigurationInfo}</li> <li>{@link android.content.pm.ConfigurationInfo}</li>
</ul> </ul>