am 36a1bcee: Merge "Doc change: Update uses-feature and permissions docs." into froyo (4e4d0d5f) · Commits · e / os / android_frameworks_base

docs/html/guide/appendix/market-filters.jd

+353 −322

Original line number	Original line	Diff line number	Diff line
	@@ -116,7 +116,7 @@ trigger filtering on Market.</p>
	<td valign="top">		<td valign="top">

	<p>An application indicates the screen sizes that it is capable of supporting by		<p>An application indicates the screen sizes that it is capable of supporting by
	setting attributes of the <code><supports-screens></code> element. When		setting attributes of the <code><supports-screens></code> element. When
	the application is published, Market uses those attributes to determine whether		the application is published, Market uses those attributes to determine whether
	to show the application to users, based on the screen sizes of their		to show the application to users, based on the screen sizes of their
	devices. </p>		devices. </p>
	@@ -198,22 +198,34 @@ of corresponding screen size.</li>
	href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><code><uses-configuration></code></a>.</p></td>		href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><code><uses-configuration></code></a>.</p></td>
	</tr>		</tr>
	<tr>		<tr>
	<td rowspan="2" valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a></code>		<td rowspan="2" valign="top" style="white-space:nowrap;"><code><a
			href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a>
			</code>
	<!-- ##api level 4## --></td>		<!-- ##api level 4## --></td>
	<td valign="top">Device Features<br />		<td valign="top">Device Features<br />
	(<code>name</code>)</td>		(<code>name</code>)</td>
	<td valign="top"><p>An		<td valign="top"><p>An application can require certain device features to be
	application can require certain device features to be present on the device. This functionality		present on the device. This functionality was introduced in Android 2.0 (API
	was introduced in Android 2.0 (API Level 5).</p>		Level 5).</p>
	<p><strong>Example 1<br />		<p><strong>Example 1<br />
	</strong>The manifest includes <code><uses-feature android:name="android.hardware.sensor.light" /></code>, and a user is searching for apps on a device that does not have a light sensor. <strong>Result</strong>: Android Market will not show the app to the user. </p>		</strong>The manifest includes <code><uses-feature
			android:name="android.hardware.sensor.light" /></code>, and a user
			is searching for apps on a device that does not have a light sensor.
			<strong>Result</strong>: Android Market will not show the app to the user. </p>
	<p><strong>Example 2<br />		<p><strong>Example 2<br />
	</strong>The manifest does not include a <code><uses-feature></code> element. <strong>Result</strong>: Android Market will show the app to all users, unless other filters apply.</p>		</strong>The manifest does not include a <code><uses-feature></code>
	<p>For more details, see <code><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a></code>.</p>		element. <strong>Result</strong>: Android Market will show the app to all users,
	<p><em>A note about camera:</em> If an		unless other filters apply.</p>
	application requests the CAMERA permission using the <a		<p>For complete information, see <code><a
	href="{@docRoot}guide/topics/manifest/uses-permission-element.html"> <code><uses-permission></code></a> element, Market assumes that the		href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a>
	application requires the camera and all camera features (such as autofocus). For applications that require the camera and are designed to run on Android 1.5 (API Level 3), declaring the CAMERA permission is an effective way of ensuring that Market filters your app properly, since <code>uses-feature</code> filtering is not available to applications compiled against the Android 1.5 platform. For more details about requiring or requesting a camera, see the <a href="{@docRoot}guide/topics/manifest/uses-library-element.html#required"> <code>required</code></a> attribute of <code><uses-feature></code>. </p></td>		</code>.</p>
			<p><em>Filtering based on implied features:</em> In some cases, Android
			Market interprets permissions requested through
			<code><uses-permission></code> elements as feature requirements equivalent
			to those declared in <code><uses-feature></code> elements. See <a
			href="#uses-permission-filtering"><code><uses-permission></code></a>,
			below.</p>
			</td>
	</tr>		</tr>
	<tr>		<tr>
	<td valign="top">OpenGL-ES		<td valign="top">OpenGL-ES
	@@ -253,10 +265,29 @@ href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses-
	<p>For more details, see <a		<p>For more details, see <a
	href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code><uses-library></code></a>.</p></td>		href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code><uses-library></code></a>.</p></td>
	</tr>		</tr>
	<tr>		<tr id="uses-permission-filtering">
	<td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code></td>		<td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code></td>
	<td valign="top"> </td>		<td valign="top"> </td>
	<td valign="top"><em>(See the note in the description of <code><uses-feature></code>, above.)</em></td>		<td valign="top">Strictly, Android Market does not filter based on
			<code><uses-permission></code> elements. However, it does read the
			elements to determine whether the application has hardware feature requirements
			that may not have been properly declared in <code><uses-feature></code>
			elements. For example, if an application requests the <code>CAMERA</code>
			permission but does not declare a <code><uses-feature></code> element for
			<code>android.hardware.camera</code>, Android Market considers that the
			application requires a camera and should not be shown to users whose devices do
			not offer a camera.</p>
			<p>In general, if an application requests hardware-related permissions,
			Android Market assumes that the application requires the underlying hardware
			features, even though there might be no corresponding to
			<code><uses-feature></code> declarations. Android Market then sets up
			filtering based on the features implied by the <code><uses-feature></code>
			declarations.</p>
			<p>For a list of permissions that imply hardware features, see
			the documentation for the <a
			href="{@docRoot}guide/topics/manifest/uses-feature-element.html#permissions-features"><code><uses-feature></code></a>
			element.</p>
			</td>
	</tr>		</tr>
	<tr>		<tr>
	<td rowspan="2" valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code></td>		<td rowspan="2" valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code></td>

docs/html/guide/developing/eclipse-adt.jd

+2 −2

Original line number	Original line	Diff line number	Diff line
	@@ -392,11 +392,11 @@ which you could make use of library projects: </p>

	<ul>		<ul>
	<li>If you are developing multiple related applications that use some of the		<li>If you are developing multiple related applications that use some of the
	same components, you move the redundant components out of their respective		same components, you could move the redundant components out of their respective
	application projects and create a single, reuseable set of the same components		application projects and create a single, reuseable set of the same components
	in a library project. </li>		in a library project. </li>
	<li>If you are creating an application that exists in both free and paid		<li>If you are creating an application that exists in both free and paid
	versions. You move the part of the application that is common to both versions		versions, you could move the part of the application that is common to both versions
	into a library project. The two dependent projects, with their different package		into a library project. The two dependent projects, with their different package
	names, will reference the library project and provide only the difference		names, will reference the library project and provide only the difference
	between the two application versions.</li>		between the two application versions.</li>

docs/html/guide/developing/other-ide.jd

+2 −2

Original line number	Original line	Diff line number	Diff line
	@@ -555,11 +555,11 @@ which you could make use of library projects: </p>

	<ul>		<ul>
	<li>If you are developing multiple related applications that use some of the		<li>If you are developing multiple related applications that use some of the
	same components, you move the redundant components out of their respective		same components, you could move the redundant components out of their respective
	application projects and create a single, reuseable set of the same components		application projects and create a single, reuseable set of the same components
	in a library project. </li>		in a library project. </li>
	<li>If you are creating an application that exists in both free and paid		<li>If you are creating an application that exists in both free and paid
	versions. You move the part of the application that is common to both versions		versions, you could move the part of the application that is common to both versions
	into a library project. The two dependent projects, with their different package		into a library project. The two dependent projects, with their different package
	names, will reference the library project and provide only the difference		names, will reference the library project and provide only the difference
	between the two application versions.</li>		between the two application versions.</li>

docs/html/guide/topics/manifest/uses-feature-element.jd

+763 −155

File changed.

Preview size limit exceeded, changes collapsed.

docs/html/guide/topics/manifest/uses-permission-element.jd

+39 −2

Original line number	Original line	Diff line number	Diff line
	@@ -2,6 +2,38 @@ page.title=<uses-permission>
	@jd:body		@jd:body

	<dl class="xml">		<dl class="xml">

			<div class="sidebox-wrapper">
			<img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png">
			<div id="qv-sub-rule">
			<img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;">
			<p style="color:#669999;"><code style="color:#669999;"><uses-permission></code> and filtering on Android Market. </p>

			<p style="margin-top:1em;">In some cases, the permissions that you request
			through <code><uses-permission></code> can affect how
			your application is filtered by Android Market.</p>

			<p style="margin-top:1em;">If you request a hardware-related permission —
			<code>CAMERA</code>, for example — Android Market assumes that your
			application requires the underlying hardware feature and filters the application
			from devices that do not offer it.</p>

			<p style="margin-top:1em;">To control filtering, always explicitly declare
			hardware features in <code><uses-feature></code> elements, rather than
			relying on Android Market to "discover" the requirements in
			<code><uses-permission></code> elements. Then, if you want to disable
			filtering for a particular feature, you can add a
			<code>android:required="false"</code> attribute to the
			<code><uses-feature></code> declaration.</p>

			<p style="margin-top:1em;" class="caution">For a list of permissions that imply
			hardware features, see the documentation for the <a
			href="{@docRoot}guide/topics/manifest/uses-feature-element.html#permissions-features">
			<code><uses-feature></code></a> element.</p>
			</div>
			</div>


	<dt>syntax:</dt>		<dt>syntax:</dt>
	<dd><pre class="stx"><uses-permission android:<a href="#nm">name</a>="<i>string</i>" /></pre></dd>		<dd><pre class="stx"><uses-permission android:<a href="#nm">name</a>="<i>string</i>" /></pre></dd>

	@@ -10,7 +42,7 @@ page.title=<uses-permission>

	<dt>description:</dt>		<dt>description:</dt>
	<dd>Requests a permission that the application must be granted in		<dd>Requests a permission that the application must be granted in
	order for it to operate correctly. Permissions are granted when the		order for it to operate correctly. Permissions are granted by the user when the
	application is installed, not while it's running.		application is installed, not while it's running.

	<p>		<p>
	@@ -38,6 +70,11 @@ a permission name typically includes the package name as a prefix.</dd>
	<dd>API Level 1</dd>		<dd>API Level 1</dd>

	<dt>see also:</dt>		<dt>see also:</dt>
	<dd><code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code></dd>		<dd>
			<ul>
			<li><code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code></li>
			<li><code><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a></code></li>
			</ul>
			</dd>

	</dl>		</dl>