Merge "docs: add getting started doc and version notes for HC preview" into honeycomb (924e3528) · Commits · e / os / android_frameworks_base

docs/html/sdk/android-3.0.jd

0 → 100644

+668 −0

File added.

Preview size limit exceeded, changes collapsed.

docs/html/sdk/preview/start.jd

0 → 100644

+265 −0

Original line number	Original line	Diff line number	Diff line
			page.title=Getting Started with the Android 3.0 Preview
			@jd:body

			<p>Welcome to Android 3.0!</p>

			<p>Android 3.0 is the next major release of the Android platform and is optimized for tablet
			devices. We're offering a preview SDK so you can get a head-start developing
			applications for it or simply optimize your existing application for upcoming
			tablets.</p>


			<h3>What is the preview SDK?</h3>

			<p>The Android 3.0 preview SDK is an early look at the upcoming version of Android 3.0, for
			developers only.</p>

			<p>The preview SDK includes:</p>
			<ul>
			<li>An early Android 3.0 system image for use in the Android emulator</li>
			<li>An Android 3.0 library with non-final APIs</li>
			<li>A new WXGA emulator skin for an extra large Android Virtual Device</li>
			<li>New documentation for Android 3.0, including a complete API reference, new developer guides,
			and an API differences report between Android 3.0 and 2.3.</li>
			</ul>

			<div class="note">
			<p><strong>Be aware that:</strong></p>
			<ul>
			<li>The APIs in the preview SDK are <strong>not final</strong>. Some APIs may change in behavior
			or availability when the final SDK is made available.</li>
			<li>You <strong>cannot</strong> publish an application that's built against the preview
			SDK—you can only run an application built against the preview SDK on the Android
			emulator.</li>
			<li>The documentation on <a href="http://developer.android.com">developer.android.com</a>
			does <strong>not</strong> include the Android 3.0 documentation—to read the API reference and
			developer guides for Android 3.0, you must install the Android 3.0 preview documentation from
			the AVD and SDK Manager.</li>
			</ul>
			</div>



			<h3>How do I start?</h3>

			<ol>
			<li><a href="#Setup">Set up the preview SDK</a></li>
			<li>Then choose your app adventure:
			<ol type="a">
			<li><a href="#Optimize">Optimize Your App for Tablets</a>
			<p>When you have an existing application and you want to maintain compatibility with
			older versions of Android.</p>
			</li>
			<li><a href="#Upgrade">Upgrade or Develop a New App for Tablets</a>
			<p>When you want to upgrade your application to use APIs introduced in Android 3.0 or
			create an all new application targeted to tablet devices.</p></li>
			</ol>
			</li>
			</ol>




			<h2 id="Setup">Set Up the Preview SDK</h2>

			<p>To start using the Android 3.0 preview SDK, set up your existing Android SDK with the new
			platform:</p>
			<p>(If you don't have an existing SDK, <a href="{@docRoot}sdk/index.html">download it
			now</a>.)</p>
			<ol>
			<li><a href="{@docRoot}sdk/adding-components.html#launching">Launch the Android SDK and AVD
			Manager</a> and install the following:
			<ul>
			<li>SDK Platform Android 3.0 Preview</li>
			<li>Android SDK Tools, revision 9</li>
			<li>Documentation for Android 'Honeycomb' Preview</li>
			<li>Samples for SDK API Honeycomb Preview</li>
			</ul>
			</li>
			<li><a href="{@docRoot}guide/developing/other-ide.html#AVD">Create an AVD</a> for tablets: set
			the target to "Android 3.0 (Preview)" and the skin to "WXGA".</li>
			</ol>


			<h3>About Emulator Performance</h3>

			<p>Because the Android emulator must simulate the ARM instruction set architecture on your
			computer and the WXGA screen is significantly larger than what the emulator
			normally handles, emulator performance is much slower than usual.</p>

			<p>We're working hard to resolve the performance issues and it will improve in future releases.
			Unfortunately, the emulator will perform slowly during your trial with the preview SDK. Please
			continue to use the emulator to evaluate your application's appearance and functionality on Android
			3.0.</p>

			<p class="note"><strong>Tip:</strong> To improve the startup time for the emulator, enable
			snapshots for the AVD when you create it with the SDK and AVD Manager (there's a checkbox in
			the GUI). Then, start the AVD from the manager and check <b>Launch from snapshot</b> and <b>Save to
			snapshot</b>. This way, when you close the emulator, a snapshot of the AVD state is saved and
			used to quickly relaunch the AVD next time. However, when you choose to save a snapshot, the
			emulator will be slow to close, so you might want to enable <b>Save to
			snapshot</b> only for the first time you launch the AVD.</p>



			<h2 id="Optimize">Optimize Your Application for Tablets</h2>

			<p>If you've already developed an application for Android, there are a few things you can do
			to optimize it for a tablet experience, without changing the minimum platform version required (you
			don't need to change the manifest {@code minSdkVersion}).</p>

			<p class="note"><strong>Note:</strong> All Android applications are forward-compatible, so
			there's nothing you <em>have to</em> do—if your application is a good citizen of the Android
			APIs, your app should work fine on devices running Android 3.0. However, in order to provide users
			a better experience when running your app on an Android 3.0 tablet, we recommend that you update
			your application to adapt to the new system theme and add optimize your application for larger
			screens.</p>

			<p>Here's what you can do to optimize your application for tablets running Android
			3.0:</p>

			<ol>
			<li><b>Test your current application on Android 3.0</b>
			<ol>
			<li>Build your application as-is and install it on your WXGA AVD (created above).</li>
			<li>Perform your usual tests to be sure everything works and looks as expected.</li>
			</ol>
			</li>

			<li><b>Apply the new "Holographic" theme to your application</b>
			<ol>
			<li>Open your manifest file and update the <a
			href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element to
			set {@code android:targetSdkVersion} to {@code "Honeycomb"}. For example:
			<pre>
			<manifest ... >
			<uses-sdk android:minSdkVersion="4"
			android:targetSdkVersion="Honeycomb" />
			<application ... >
			...
			<application>
			</manifest>
			</pre>
			<p class="note"><strong>Note:</strong> The API Level value "Honeycomb" is a provisional API
			Level that is valid only while testing against the preview SDK. You
			<strong>should not</strong> publish your application using this API Level. When the final version of
			the Android 3.0 SDK is made available, you must change this value to the real API Level that will be
			specified for Android 3.0. For more information, read about <a
			href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a>.</p>
			<p>By targeting the Android 3.0 platform, the system automatically applies the Holographic theme
			to each of your activities, when running on an Android 3.0 device.</p>
			</li>
			<li>Continue to build against your application's {@code minSdkVersion}, but install it
			on the Android 3.0 AVD. Perform more testing on your application to be sure that your user interface
			works well with the Holographic theme.
			<p class="note"><strong>Note:</strong> If you've applied themes to your activities already,
			they will override the Holographic theme that the system applies when you set the {@code
			android:targetSdkVersion} to {@code "Honeycomb"}.
			Once the Android 3.0 APIs are finalized and an official API Level is assigned, you can use
			the <a href="{@docRoot}guide/topics/resources/providing-resources.html#VersionQualifier">system
			version qualifier</a> to provide an alternative theme that's based on the Holographic theme when
			your application is running on Android 3.0.</p>
			</ol>
			</li>

			<li><b>Supply alternative layout resources for xlarge screens</b>
			<p>As discussed in the guide to <a
			href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>, Android
			2.3 and above support the <code>xlarge</code> resource qualifier, which you should use to supply
			alternative layouts for extra large screens.</p>
			<p>By providing alternative layouts for some of your activities when running on extra large
			screens, you can improve the user experience of your application on a tablet without using any
			new APIs.</p>
			<p>For example, here are some things to consider when creating a new layout for tables:</p>
			<ul>
			<li>Landscape layout: The "normal" orientation for tablets is usually landscape (wide), so
			you should be sure that your activities offer an appropriate layout for such a wide viewing
			area.</li>
			<li>Button position: Consider whether the position of the most common buttons in your UI are
			easily accessible while holding a tablet with two hands.</li>
			</ul>
			</li>
			</ol>

			<p>In general, always be sure that your application follows the <a
			href="{@docRoot}guide/practices/screens_support.html#screen-independence">Best Practices
			for Screen Independence</a>.</p>




			<h2 id="Upgrade">Upgrade or Develop a New App for Tablets</h2>

			<p>If you want to develop something truly for tablets running Android 3.0, then you need to use new
			APIs available in Android 3.0. This section introduces some of the new features that you
			should use.</p>

			<p>The first thing to do when you create a project with the Android 3.0 preview is set the <a
			href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element to
			use {@code "Honeycomb"} for the {@code android:minSdkVersion}. For example:</p>

			<pre>
			<manifest ... >
			<uses-sdk android:minSdkVersion="Honeycomb" />
			<application ... >
			...
			<application>
			</manifest>
			</pre>

			<p class="note"><strong>Note:</strong> The API Level value "Honeycomb" is a provisional API
			Level that is valid only while building and testing against the preview SDK. You
			<strong>cannot</strong> publish your application using this API Level. When the final version of the
			Android 3.0 SDK is made available, you must change this value to the real API Level that is
			specified for Android 3.0. For more information, read about <a
			href="{@docRoot}guide/appendix/api-levels.html">Android API Levels</a>.</p>

			<p>Be sure that the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
			<uses-sdk>}</a> element appears <strong>before</strong> the <a
			href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a>
			element.</p>

			<p>By targeting the Android 3.0 platform (and declaring it before <a
			href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a>),
			the system automatically applies the new Holographic theme to each of your
			activities.</p>



			<h3>Publishing your app for tablets only</h3>

			<p>Additionally, you should decide whether your application is for <em>only</em> tablet devices
			(specifically, <em>xlarge</em> devices) or for devices of all sizes that may run Android 3.0.</p>

			<p>If your application is <em>only</em> for tablets (<em>xlarge</em> screens; not for mobile
			devices/phones), then you should include the <a
			href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
			<supports-screens>}</a> element in your manifest with all sizes except for xlarge declared
			false. For example:</p>

			<pre>
			<manifest ... >
			<uses-sdk android:minSdkVersion="Honeycomb" />
			<supports-screens android:smallScreens="false"
			android:normalScreens="false"
			android:largeScreens="false"
			android:xlargeScreens="true" />
			<application ... >
			...
			<application>
			</manifest>
			</pre>

			<p>With this declaration, you indicate that your application does not support any screen size except
			extra large. External services such as Android Market may use this to filter your application
			from devices that do not have an extra large screen.</p>

			<p>Otherwise, if you want your application to be available to both small devices (phones) and large
			devices (tablets), do <em>not</em> include the <a
			href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
			<supports-screens>}</a> element.</p>

			<div class="special">
			<p>To learn more about some of the new APIs,
			see the <a href="{@docRoot}sdk/android-3.0.html">Android 3.0 Platform</a> document.</p>
			</div>

docs/html/sdk/sdk_toc.cs

+3 −3

Original line number	Original line	Diff line number	Diff line
	@@ -42,11 +42,11 @@
	<ul>		<ul>
	<li><a href="<?cs var:toroot ?>sdk/preview/start.html">Getting Started</a> <span class="new">new!</span></li>		<li><a href="<?cs var:toroot ?>sdk/preview/start.html">Getting Started</a> <span class="new">new!</span></li>
	<li class="toggle-list">		<li class="toggle-list">
	<div><a href="<?cs var:toroot ?>sdk/preview/platform.html">		<div><a href="<?cs var:toroot ?>sdk/android-3.0.html">
	<span class="en">Android 3.0 Platform</span></a> <span class="new">new!</span></div>		<span class="en">Android 3.0 Platform</span></a> <span class="new">new!</span></div>
	<ul>		<ul>
	<li><a href="<?cs var:toroot ?>sdk/preview/highlights.html">Platform Highlights</a></li>		<li><a href="<?cs var:toroot ?>sdk/api_diff/honeycomb/changes.html">API Differences Report
	<li><a href="<?cs var:toroot ?>sdk/api_diff/honeycomb/changes.html">API Differences Report »</a></li>		»</a></li>
	</ul>		</ul>
	</li>		</li>
	</ul>		</ul>