1page.title=<uses-configuration>
2parent.title=The AndroidManifest.xml File
3parent.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
9keyboard / navigation control / touch screen."  Dianne says that that's what they mean and 
10that they therefore should be eliminated.  Suchi says that they mean "doesn't require a 
11keyboard / navigation control / touch screen to work."  But then what does "undefined" mean?
12Seems 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___" 
14and "undefined" attributes using the same language, which is surely wrong but may make it
15easier to update the doc when the change is made. -->
16
17<dl class="xml">
18<dt>syntax:</dt>
19<dd><pre class="stx">&lt;uses-configuration android:<a href="#five">reqFiveWayNav</a>=["true" | "false"] 
20                    android:<a href="#hard">reqHardKeyboard</a>=["true" | "false"]
21                    android:<a href="#kbd">reqKeyboardType</a>=["undefined" | "nokeys" | "qwerty" |  
22                                             "twelvekey"]
23                    android:<a href="#nav">reqNavigation</a>=["undefined" | "nonav" | "dpad" | 
24                                           "trackball" | "wheel"]
25                    android:<a href="#touch">reqTouchScreen</a>=["undefined" | "notouch" | "stylus" | 
26                                            "finger"] /&gt;</pre></dd>
27
28<dt>contained in:</dt>
29<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
30
31<dt>description:</dt>
32<dd>Indicates what hardware and software features the application requires.  
33For example, an application might specify that it requires a physical keyboard 
34or a particular navigation device, like a trackball.  The specification is
35used to avoid installing the application on devices where it will not work.
36
37<p>
38If an application can work with different device configurations, it 
39should include separate {@code &lt;uses-configuration&gt;} declarations for 
40each one.  Each declaration must be complete.  For example, if an application 
41requires a five-way navigation control, a touch screen that can be operated 
42with a finger, and either a standard QWERTY keyboard or a numeric 12-key
43keypad like those found on most phones, it would specify these requirements
44with two {@code &lt;uses-configuration&gt;} elements as follows:
45</p>
46
47<pre>&lt;uses-configuration android:reqFiveWayNav="true" android:reqTouchScreen="finger"
48                    android:reqKeyboardType="qwerty" /&gt;
49&lt;uses-configuration android:reqFiveWayNav="true" android:reqTouchScreen="finger"
50                    android:reqKeyboardType="twelvekey" /&gt;</pre></dd>
51
52<dt>attributes:</dt>
53<dd><dl class="attr">
54<dt><a name="five"></a>{@code android:reqFiveWayNav}</dt>
55<dd>Whether or not the application requires a five-way navigation control 
56&mdash; "{@code true}" if it does, and "{@code false}" if not.  A five-way
57control is one that can move the selection up, down, right, or left, and 
58also provides a way of invoking the current selection.  It could be a 
59D-pad (directional pad), trackball, or other device.  
60
61<p>
62If an application requires a directional control, but not a control of a
63particular type, it can set this attribute to "{@code true}" and ignore 
64the <code><a href="#nav">reqNavigation</a></code> attribute.  However,
65if it requires a particular type of directional control, it can ignore
66this attribute and set {@code reqNavigation} instead.
67</p></dd>
68
69<dt><a name="hard"></a>{@code android:reqHardKeyboard}</dt>
70<dd>Whether or not the application requires a hardware keyboard &mdash;
71"{@code true}" if it does, and "{@code false}" if not.</dd>
72
73<dt><a name="kbd"></a>{@code android:reqKeyboardType}</dt>
74<dd>The type of keyboard the application requires, if any at all. 
75This attribute does not distinguish between hardware and software 
76keyboards.  If a hardware keyboard of a certain type is required,
77specify the type here and also set the {@code reqHardKeyboard} attribute 
78to "{@code true}".
79
80<p>
81The value must be one of the following strings:
82</p>
83
84<table>
85<tr>
86   <th>Value</th>
87   <th>Description</th>
88</tr><tr>
89   <td>"{@code undefined}"</td>
90   <td>The application does not require a keyboard. 
91       (A keyboard requirement is not defined.)  
92       This is the default value.</td>
93</tr><tr>
94   <td>"{@code nokeys}"</td>
95   <td>The application does not require a keyboard.</td>
96</tr><tr>
97   <td>"{@code qwerty}"</td>
98   <td>The application requires a standard QWERTY keyboard.</td>
99</tr><tr>
100   <td>"{@code twelvekey}"</td>
101   <td>The application requires a twelve-key keypad, like those on most 
102       phones &mdash; with keys for the digits from {@code 0} through 
103       {@code 9} plus star ({@code *}) and pound ({@code #}) keys.</td>
104</tr>
105</table></dd>
106
107<dt><a name="nav"></a>{@code android:reqNavigation}</dt>
108<dd>The navigation device required by the application, if any.  The value 
109must be one of the following strings:
110
111<table>
112<tr>
113   <th>Value</th>
114   <th>Description</th>
115</tr><tr>
116   <td>"{@code undefined}"</td>
117   <td>The application does not require any type of navigation control. 
118       (The navigation requirement is not defined.)  
119       This is the default value.</td>
120</tr><tr>
121   <td>"{@code nonav}"</td>
122   <td>The application does not require a navigation control.</td>
123</tr><tr>
124   <td>"{@code dpad}"</td>
125   <td>The application requires a D-pad (directional pad) for navigation.</td>
126</tr><tr>
127   <td>"{@code trackball}"</td>
128   <td>The application requires a trackball for navigation.</td>
129</tr><tr>
130   <td>"{@code wheel}"</td>
131   <td>The application requires a navigation wheel.</td>
132</tr>
133</table>
134
135<p>
136If an application requires a navigational control, but the exact type of
137control doesn't matter, it can set the 
138<code><a href="#five">reqFiveWayNav</a></code> attribute to "{@code true}"
139rather than set this one.
140</p></dd>
141
142<dt><a name="touch"></a>{@code android:reqTouchScreen}</dt>
143<dd>The type of touch screen the application requires, if any at all.
144The value must be one of the following strings: 
145
146<table>
147<tr>
148   <th>Value</th>
149   <th>Description</th>
150</tr><tr>
151   <td>"{@code undefined}"</td>
152   <td>The application doesn't require a touch screen.  
153       (The touch screen requirement is undefined.)
154       This is the default value.</td>
155</tr><tr>
156   <td>"{@code notouch}"</td>
157   <td>The application doesn't require a touch screen.</td>
158</tr><tr>
159   <td>"{@code stylus}"</td>
160   <td>The application requires a touch screen that's operated with a stylus.</td>
161</tr><tr>
162   <td>"{@code finger}"</td>
163   <td>The application requires a touch screen that can be operated with a finger.</td>
164</tr>
165</table></dd>
166</dl></dd>
167
168<!-- ##api level 3## -->
169<dt>introduced in:</dt>
170<dd>API Level 3</dd>
171
172<dt>see also:</dt>
173<dd>
174  <ul>
175    <li><code><a href="{@docRoot}guide/topics/manifest/activity-element.html#config">configChanges</a></code>
176attribute of the
177<code><a href="{@docRoot}guide/topics/manifest/activity-element.html">&lt;activity&gt;</a></code> 
178element</dd></li>
179    <li>{@link android.content.pm.ConfigurationInfo}</li>
180  </ul>
181</dd>
182
183</dl>
184