Home | History | Annotate | Download | only in manifest
      1 page.title=<uses-configuration>
      2 parent.title=The AndroidManifest.xml File
      3 parent.link=manifest-intro.html
      4 @jd:body
      5 
      6 <!-- ##api level 3##  see comment below -->
      7 
      8 <!-- the "no___" values are nonsensical if they mean "doesn't work on devices with a
      9 keyboard / navigation control / touch screen."  Dianne says that that's what they mean and
     10 that they therefore should be eliminated.  Suchi says that they mean "doesn't require a
     11 keyboard / navigation control / touch screen to work."  But then what does "undefined" mean?
     12 Seems like some API change is in the works, either eliminating the "no___" values or
     13 "undefined".  Since it's unclear what the change will be, I've chosen to document the "no___"
     14 and "undefined" attributes using the same language, which is surely wrong but may make it
     15 easier to update the doc when the change is made... Nov 2013, this still seems unresolved. -->
     16 
     17 <dl class="xml">
     18 <dt>syntax:</dt>
     19 <dd><pre class="stx">&lt;uses-configuration
     20   android:<a href="#five">reqFiveWayNav</a>=["true" | "false"]
     21   android:<a href="#hard">reqHardKeyboard</a>=["true" | "false"]
     22   android:<a href="#kbd">reqKeyboardType</a>=["undefined" | "nokeys" | "qwerty" | "twelvekey"]
     23   android:<a href="#nav">reqNavigation</a>=["undefined" | "nonav" | "dpad" | "trackball" | "wheel"]
     24   android:<a href="#touch">reqTouchScreen</a>=["undefined" | "notouch" | "stylus" | "finger"] /&gt;</pre></dd>
     25 
     26 <dt>contained in:</dt>
     27 <dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
     28 
     29 <dt>description:</dt>
     30 <dd itemprop="description">Indicates what hardware and software features the application requires.
     31 For example, an application might specify that it requires a physical keyboard
     32 or a particular navigation device, like a trackball.  The specification is
     33 used to avoid installing the application on devices where it will not work.
     34 
     35 <p class="note"><strong>Note: Most apps should not use this manifest tag.</strong> You should
     36 <em>always</em> support input with a directional pad (d-pad) in order to assist sight-impaired
     37 users and support devices that provide d-pad input in addition to or instead of touch. For
     38 information about how to support d-pad input in your app, read <a href=
     39 "{@docRoot}guide/topics/ui/accessibility/apps.html#focus-nav">Enabling Focus Navigation</a>. If
     40 your app absolutely cannot function without a touchscreen, then instead use the <a href=
     41 "{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> tag to
     42 declare the required touchscreen type, ranging from {@code "android.hardware.faketouch"} for basic
     43 touch-style events to more advanced touch types such as {@code
     44 "android.hardware.touchscreen.multitouch.jazzhand"} for distinct input from multiple fingers.</p>
     45 
     46 
     47 <dt>attributes:</dt>
     48 <dd><dl class="attr">
     49 <dt><a name="five"></a>{@code android:reqFiveWayNav}</dt>
     50 <dd>Whether or not the application requires a five-way navigation control
     51 &mdash; "{@code true}" if it does, and "{@code false}" if not.  A five-way
     52 control is one that can move the selection up, down, right, or left, and
     53 also provides a way of invoking the current selection.  It could be a
     54 D-pad (directional pad), trackball, or other device.
     55 
     56 <p>
     57 If an application requires a directional control, but not a control of a
     58 particular type, it can set this attribute to "{@code true}" and ignore
     59 the <code><a href="#nav">reqNavigation</a></code> attribute.  However,
     60 if it requires a particular type of directional control, it can ignore
     61 this attribute and set {@code reqNavigation} instead.
     62 </p></dd>
     63 
     64 <dt><a name="hard"></a>{@code android:reqHardKeyboard}</dt>
     65 <dd>Whether or not the application requires a hardware keyboard &mdash;
     66 "{@code true}" if it does, and "{@code false}" if not.</dd>
     67 
     68 <dt><a name="kbd"></a>{@code android:reqKeyboardType}</dt>
     69 <dd>The type of keyboard the application requires, if any at all.
     70 This attribute does not distinguish between hardware and software
     71 keyboards.  If a hardware keyboard of a certain type is required,
     72 specify the type here and also set the {@code reqHardKeyboard} attribute
     73 to "{@code true}".
     74 
     75 <p>
     76 The value must be one of the following strings:
     77 </p>
     78 
     79 <table>
     80 <tr>
     81    <th>Value</th>
     82    <th>Description</th>
     83 </tr><tr>
     84    <td>"{@code undefined}"</td>
     85    <td>The application does not require a keyboard.
     86        (A keyboard requirement is not defined.)
     87        This is the default value.</td>
     88 </tr><tr>
     89    <td>"{@code nokeys}"</td>
     90    <td>The application does not require a keyboard.</td>
     91 </tr><tr>
     92    <td>"{@code qwerty}"</td>
     93    <td>The application requires a standard QWERTY keyboard.</td>
     94 </tr><tr>
     95    <td>"{@code twelvekey}"</td>
     96    <td>The application requires a twelve-key keypad, like those on most
     97        phones &mdash; with keys for the digits from {@code 0} through
     98        {@code 9} plus star ({@code *}) and pound ({@code #}) keys.</td>
     99 </tr>
    100 </table></dd>
    101 
    102 <dt><a name="nav"></a>{@code android:reqNavigation}</dt>
    103 <dd>The navigation device required by the application, if any.  The value
    104 must be one of the following strings:
    105 
    106 <table>
    107 <tr>
    108    <th>Value</th>
    109    <th>Description</th>
    110 </tr><tr>
    111    <td>"{@code undefined}"</td>
    112    <td>The application does not require any type of navigation control.
    113        (The navigation requirement is not defined.)
    114        This is the default value.</td>
    115 </tr><tr>
    116    <td>"{@code nonav}"</td>
    117    <td>The application does not require a navigation control.</td>
    118 </tr><tr>
    119    <td>"{@code dpad}"</td>
    120    <td>The application requires a D-pad (directional pad) for navigation.</td>
    121 </tr><tr>
    122    <td>"{@code trackball}"</td>
    123    <td>The application requires a trackball for navigation.</td>
    124 </tr><tr>
    125    <td>"{@code wheel}"</td>
    126    <td>The application requires a navigation wheel.</td>
    127 </tr>
    128 </table>
    129 
    130 <p>
    131 If an application requires a navigational control, but the exact type of
    132 control doesn't matter, it can set the
    133 <code><a href="#five">reqFiveWayNav</a></code> attribute to "{@code true}"
    134 rather than set this one.
    135 </p></dd>
    136 
    137 <dt><a name="touch"></a>{@code android:reqTouchScreen}</dt>
    138 <dd>The type of touch screen the application requires, if any at all.
    139 The value must be one of the following strings:
    140 
    141 <table>
    142 <tr>
    143    <th>Value</th>
    144    <th>Description</th>
    145 </tr><tr>
    146    <td>"{@code undefined}"</td>
    147    <td>The application doesn't require a touch screen.
    148        (The touch screen requirement is undefined.)
    149        This is the default value.</td>
    150 </tr><tr>
    151    <td>"{@code notouch}"</td>
    152    <td>The application doesn't require a touch screen.</td>
    153 </tr><tr>
    154    <td>"{@code stylus}"</td>
    155    <td>The application requires a touch screen that's operated with a stylus.</td>
    156 </tr><tr>
    157    <td>"{@code finger}"</td>
    158    <td>The application requires a touch screen that can be operated with a finger.
    159 
    160       <p class="note"><strong>Note:</strong> If some type of touch input is required for your app,
    161       you should instead use the
    162       <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code
    163       <uses-feature>}</a> tag to declare the required touchscreen
    164       type, beginning with {@code "android.hardware.faketouch"} for basic touch-style events.</p>
    165    </td>
    166 </tr>
    167 </table></dd>
    168 </dl></dd>
    169 
    170 <!-- ##api level 3## -->
    171 <dt>introduced in:</dt>
    172 <dd>API Level 3</dd>
    173 
    174 <dt>see also:</dt>
    175 <dd>
    176   <ul>
    177     <li><code><a href="{@docRoot}guide/topics/manifest/activity-element.html#config">configChanges</a></code>
    178 attribute of the
    179 <code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code>
    180 element</dd></li>
    181     <li>{@link android.content.pm.ConfigurationInfo}</li>
    182   </ul>
    183 </dd>
    184 
    185 </dl>
    186