am 43810507: Merge change Ic8231560 into eclair (f37314c2) · Commits · e / os / android_frameworks_base

docs/html/guide/appendix/api-levels.jd

+11 −6

Original line number	Original line	Diff line number	Diff line
	@@ -123,7 +123,9 @@ application to use manifest elements or behaviors defined in the target
	API Level, rather than being restricted to using only those defined		API Level, rather than being restricted to using only those defined
	for the minimum API Level.</li>		for the minimum API Level.</li>
	<li><code>android:maxSdkVersion</code> — Specifies the maximum API Level		<li><code>android:maxSdkVersion</code> — Specifies the maximum API Level
	on which the application is able to run.</li>		on which the application is able to run. <strong>Important:</strong> Please read the <a
			href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a>
			documentation before using this attribute. </li>
	</ul>		</ul>

	<p>For example, to specify the minimum system API Level that an application		<p>For example, to specify the minimum system API Level that an application
	@@ -133,10 +135,11 @@ attribute. The value of <code>android:minSdkVersion</code> would be the integer
	corresponding to the API Level of the earliest version of the Android platform		corresponding to the API Level of the earliest version of the Android platform
	under which the application can run. </p>		under which the application can run. </p>

	<p>When the user attempts to install an application, the Android system first		<p>When the user attempts to install an application, or when revalidating an
	checks the <code><uses-sdk></code> attributes in the application's		appplication after a system update, the Android system first checks the
	manifest and compares them against its own internal API Level. The system		<code><uses-sdk></code> attributes in the application's manifest and
	allows the installation to begin only if these conditions are met:</p>		compares the values against its own internal API Level. The system allows the
			installation to begin only if these conditions are met:</p>

	<ul>		<ul>
	<li>If a <code>android:minSdkVersion</code> attribute is declared, its value		<li>If a <code>android:minSdkVersion</code> attribute is declared, its value
	@@ -145,7 +148,9 @@ the system assumes that the application requires API Level 1. </li>
	<li>If a <code>android:maxSdkVersion</code> attribute is declared, its value		<li>If a <code>android:maxSdkVersion</code> attribute is declared, its value
	must be equal to or greater than the system's API Level integer.		must be equal to or greater than the system's API Level integer.
	If not declared, the system assumes that the application		If not declared, the system assumes that the application
	has no maximum API Level. </li>		has no maximum API Level. Please read the <a
			href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a>
			documentation for more information about how the system handles this attribute.</li>
	</ul>		</ul>

	<p>When declared in an application's manifest, a <code><uses-sdk></code>		<p>When declared in an application's manifest, a <code><uses-sdk></code>

docs/html/guide/publishing/versioning.jd

+8 −1

Original line number	Original line	Diff line number	Diff line
	@@ -141,9 +141,16 @@ element in the application's manifest, with one or more of these attributes: </p
	<li><code>android:minSdkVersion</code> — The minimum version		<li><code>android:minSdkVersion</code> — The minimum version
	of the Android platform on which the application will run, specified		of the Android platform on which the application will run, specified
	by the platform's API Level identifier. </li>		by the platform's API Level identifier. </li>
			<li><code>android:targetSdkVersion</code> — Specifies the API Level
			on which the application is designed to run. In some cases, this allows the
			application to use manifest elements or behaviors defined in the target
			API Level, rather than being restricted to using only those defined
			for the minimum API Level.</li>
	<li><code>android:maxSdkVersion</code> — The maximum version		<li><code>android:maxSdkVersion</code> — The maximum version
	of the Android platform on which the application is designed to run,		of the Android platform on which the application is designed to run,
	specified by the platform's API Level identifier. </li>		specified by the platform's API Level identifier. <strong>Important:</strong> Please read the <a
			href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a>
			documentation before using this attribute. </li>
	</ul>		</ul>

	<p>When preparing to install your application, the system checks the value of this		<p>When preparing to install your application, the system checks the value of this

docs/html/guide/topics/manifest/supports-screens-element.jd

+1 −1

Original line number	Original line	Diff line number	Diff line
	@@ -84,7 +84,7 @@ The screen density is expressed as dots-per-inch (dpi).</p>
	<dt>see also:</dt>		<dt>see also:</dt>
	<dd>		<dd>
	<ul>		<ul>
	<li><a href="{@docRoot}guide/practices/screens_suppport.html">Multiple Screens Support</a></li>		<li><a href="{@docRoot}guide/practices/screens_support.html">Multiple Screens Support</a></li>
	<li>{@link android.util.DisplayMetrics}</li>		<li>{@link android.util.DisplayMetrics}</li>
	</ul>		</ul>
	</dd>		</dd>

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

+95 −41

Original line number	Original line	Diff line number	Diff line
	@@ -5,8 +5,8 @@ page.title=<uses-sdk>
	<dt>syntax:</dt>		<dt>syntax:</dt>
	<dd><pre>		<dd><pre>
	<uses-sdk android:<a href="#min">minSdkVersion</a>="<i>integer</i>"		<uses-sdk android:<a href="#min">minSdkVersion</a>="<i>integer</i>"
	android:<a href="#max">maxSdkVersion</a>="<i>integer</i>"		android:<a href="#target">targetSdkVersion</a>="<i>integer</i>"
	android:<a href="#target">targetSdkVersion</a>="<i>integer</i>" /></pre></dd>		android:<a href="#max">maxSdkVersion</a>="<i>integer</i>" /></pre></dd>

	<dt>contained in:</dt>		<dt>contained in:</dt>
	<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd>		<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd>
	@@ -17,19 +17,31 @@ by means of an API Level integer. The API Level expressed by an application will
	API Level of a given Android system, which may vary among different Android devices.		API Level of a given Android system, which may vary among different Android devices.
	</p>		</p>

	<p>		<p>Despite its name, this element is used to specify the API Level, <em>not</em>
	Despite its name, this element is used to specify the API Level, <em>not</em> the		the version number of the SDK (software development kit) or Android platform.
	version number of the SDK (software development kit). The API Level is always		The API Level is always a single integer. You cannot derive the API Level from
	a single integer; the SDK version may be split into major and minor components		its associated Android version number (for example, it is not the same as the
	(such as 1.5). You cannot derive the API Level from the SDK version number		major version or the sum of the major and minor versions).</p>
	(for example, it is not the same as the major version or the sum of the major
	and minor versions).</p>

	<p>For more information, read about		<p>For more information, read about
	<a href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a> and		<a href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a> and
	<a href="{@docRoot}guide/publishing/versioning.html">Versioning Your Applications</a>.		<a href="{@docRoot}guide/publishing/versioning.html">Versioning Your Applications</a>.
	</p></dd>		</p></dd>

			<div class="sidebox-wrapper" xstyle="margin-bottom:2em;margin-top:.5em;width:90%;">
			<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;">Android Market and <uses-sdk> attributes</p>
			<p>Android Market filters the applications that are visible to users, so
			that users can only see and download applications that are compatible with their
			devices. One of the ways Market filters applications is by Android
			version-compatibility. To do this, Market checks the <code><uses-sdk></code>
			attributes in each application's manifest to establish its version-compatibility
			range, then shows or hides the application based on a comparison with the API
			Level of the user's Android system version. </p>
			</div>
			</div>

	<dt>attributes:</dt>		<dt>attributes:</dt>

	@@ -41,43 +53,85 @@ and minor versions).</p>
	the application if the system's API Level is lower than the value specified in		the application if the system's API Level is lower than the value specified in
	this attribute. You should always declare this attribute.		this attribute. You should always declare this attribute.

	<p class="caution"><strong>Caution:</strong>		<p class="caution"><strong>Caution:</strong> If you do not declare this
	If you do not declare this attribute, then a value of "1" is assumed, which		attribute, the system assumes a default value of "1", which indicates that your
	indicates that your application is compatible with all versions of Android. If your		application is compatible with all versions of Android. If your application is
	application is <em>not</em> compatible with all versions (for instance, it uses APIs		<em>not</em> compatible with all versions (for instance, it uses APIs introduced
	introduced in API Level 3) and you have not declared the proper <code>minSdkVersion</code>,		in API Level 3) and you have not declared the proper <code>android:minSdkVersion</code>,
	then when installed on a system with an API Level less than 3, the application will crash		then when installed on a system with an API Level less than 3, the application
	during runtime when attempting to access the unavailable APIs. For this reason,		will crash during runtime when attempting to access the unavailable APIs. For
	be certain to declare the appropriate API Level		this reason, be certain to declare the appropriate API Level in the
	in the <code>minSdkVersion</code> attribute.</p>		<code>minSdkVersion</code> attribute.</p>
	</dd>

	<dt><a name="max"></a>{@code android:maxSdkVersion}</dt>
	<dd>An integer designating the maximum API Level on which the application is
	designed to run. The Android system will prevent the user from installing the
	application if the system's API Level is higher than the value specified
	in this attribute.

	<p>Introduced in: API Level 4</p>
	</dd>		</dd>

	<dt><a name="target"></a>{@code android:targetSdkVersion}</dt>		<dt><a name="target"></a>{@code android:targetSdkVersion}</dt>
	<dd>An integer designating the API Level that the application is targetting.		<dd>An integer designating the API Level that the application is targetting.

	<p>With this attribute set, the application says that it is able to run on		<p>With this attribute set, the application says that it is able to run on
	older versions (down to {@code minSdkVersion}), but was explicitly tested to work		older versions (down to {@code minSdkVersion}), but was explicitly tested to
	with the version specified here.		work with the version specified here. Specifying this target version allows the
	Specifying this target version allows the platform to disable compatibility		platform to disable compatibility settings that are not required for the target
	settings that are not required for the target version (which may otherwise be turned on		version (which may otherwise be turned on in order to maintain
	in order to maintain forward-compatibility) or enable newer features that are not		forward-compatibility) or enable newer features that are not available to older
	available to older applications. This does not mean that you can program different		applications. This does not mean that you can program different features for
	features for different versions of the platform—it simply informs the platform that you		different versions of the platform—it simply informs the platform that you
	have tested against the target version and the platform should not perform any extra		have tested against the target version and the platform should not perform any
	work to maintain forward-compatibility with the target version.</p>		extra work to maintain forward-compatibility with the target version.</p>

	<p>Introduced in: API Level 4</p>		<p>Introduced in: API Level 4</p>
	</dd>		</dd>

			<dt><a name="max"></a>{@code android:maxSdkVersion}</dt>
			<dd>An integer designating the maximum API Level on which the application is
			designed to run.

			<p>In Android 1.5, 1.6, 2.0, and 2.0.1, the system checks the value of this
			attribute when installing an application and when revalidating the application
			after a system update. In either case, if the application's
			<code>android:maxSdkVersion</code> attribute is lower than the API Level used by
			the system itself, then the system will not allow the application to be
			installed. In the case of revalidation after system update, this effectively
			removes your application from the device.

			<p>To illustrate how this attribute can affect your application after system
			updates, consider the following example: </p>

			<p>An application declaring <code>android:maxSdkVersion="5"</code> in its
			manifest is published on Android Market. A user whose device is running Android
			1.6 (API Level 4) downloads and installs the app. After a few weeks, the user
			receives an over-the-air system update to Android 2.0 (API Level 5). After the
			update is installed, the system checks the application's
			<code>android:maxSdkVersion</code> and successfully revalidates it. The
			application functions as normal. However, some time later, the device receives
			another system update, this time to Android 2.0.1 (API Level 6). After the
			update, the system can no longer revalidate the application because the system's
			own API Level (6) is now higher than the maximum supported by the application
			(5). The system prevents the application from being visible to the user, in
			effect removing it from the device.</p>

			<p class="warning"><strong>Warning:</strong> Declaring this attribute is not
			recommended. First, there is no need to set the attribute as means of blocking
			deployment of your application onto new versions of the Android platform as they
			are released. By design, new versions of the platform are fully
			backward-compatible. Your application should work properly on new versions,
			provided it uses only standard APIs and follows development best practices.
			Second, note that in some cases, declaring the attribute can <strong>result in
			your application being removed from users' devices after a system
			update</strong> to a higher API Level. Most devices on which your appplication
			is likely to be installed will receive periodic system updates over the air, so
			you should consider their effect on your application before setting this
			attribute.</p>

			<p style="margin-bottom:1em;">Introduced in: API Level 4</p>

			<div class="special">Future versions of Android (beyond Android 2.0.1) will no
			longer check or enforce the <code>android:maxSdkVersion</code> attribute during
			installation or revalidation. Android Market will continue to use the attribute
			as a filter, however, when presenting users with applications available for
			download. </div>
			</dd>


	</dl></dd>		</dl></dd>

	<!-- ##api level indication## -->		<!-- ##api level indication## -->

docs/html/sdk/android-1.6.jd

+6 −6

Original line number	Original line	Diff line number	Diff line
	@@ -74,7 +74,7 @@ Android 1.6 platform.</p>

	<p>API related:</p>		<p>API related:</p>
	<ul>		<ul>
	<li>Properly exposes CDMA-related constants {@link android.telephony.TelephonyManager}: <code>DATA_ACTIVITY_DORMANT</code>,		<li>Properly exposes CDMA-related constants in {@link android.telephony.TelephonyManager android.telephony.TelephonyManager}: <code>DATA_ACTIVITY_DORMANT</code>,
	<code>PHONE_TYPE_CDMA</code>, <code>NETWORK_TYPE_CDMA</code>,		<code>PHONE_TYPE_CDMA</code>, <code>NETWORK_TYPE_CDMA</code>,
	<code>NETWORK_TYPE_EVDO_0</code>, <code>NETWORK_TYPE_EVDO_A</code>, and		<code>NETWORK_TYPE_EVDO_0</code>, <code>NETWORK_TYPE_EVDO_A</code>, and
	<code>NETWORK_TYPE_1xRTT</code>.</li>		<code>NETWORK_TYPE_1xRTT</code>.</li>
	@@ -362,15 +362,15 @@ determining the density of the current device screen.</li>
	<li>New attributes for the		<li>New attributes for the
	<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element:		<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element:
	<ul>		<ul>
	<li><code>maxSdkVersion</code>: This indicates the maximum API Level on which an application is		<li><code>targetSdkVersion</code>: Indicates the API Level that the application is targeting.
	designed to run. If an application declares this attribute, the Android system prevents the user
	from installing the application if the system's API Level is higher than the value specified in
	this attribute. </li>
	<li><code>targetSdkVersion</code>: This indicates the API Level that the application is targeting.
	It is able to run on older versions (down to minSdkVersion), but was explicitly tested to		It is able to run on older versions (down to minSdkVersion), but was explicitly tested to
	work with the version specified here. Specifying this version allows the platform to		work with the version specified here. Specifying this version allows the platform to
	disable compatibility code that is not required or enable newer features that are not		disable compatibility code that is not required or enable newer features that are not
	available to older applications. </li>		available to older applications. </li>
			<li><code>maxSdkVersion</code>: Indicates the maximum API Level on which an application is
			designed to run. <strong>Important:</strong> Please read the <a
			href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a>
			documentation before using this attribute. </li>
	</ul>		</ul>
	</li>		</li>