Merge "Fix issue #5755172: Soft menu key disappears when menu is open" into ics-mr1
diff --git a/Android.mk b/Android.mk
index 80e681c..371c370 100644
--- a/Android.mk
+++ b/Android.mk
@@ -448,6 +448,8 @@
resources/samples/MultiResolution "Multiple Resolutions" \
-samplecode $(sample_dir)/NFCDemo \
resources/samples/NFCDemo "NFC Demo" \
+ -samplecode $(sample_dir)/training/multiscreen/newsreader \
+ resources/samples/newsreader "News Reader" \
-samplecode $(sample_dir)/NotePad \
resources/samples/NotePad "Note Pad" \
-samplecode $(sample_dir)/SpellChecker/SampleSpellCheckerService \
diff --git a/core/java/android/text/TextLine.java b/core/java/android/text/TextLine.java
index 303a30e..1e8a2f7 100644
--- a/core/java/android/text/TextLine.java
+++ b/core/java/android/text/TextLine.java
@@ -886,7 +886,7 @@
spanFlags = new int[length];
}
- int count = 0;
+ numberOfSpans = 0;
for (int i = 0; i < length; i++) {
final E span = allSpans[i];
@@ -896,14 +896,13 @@
final int spanFlag = spanned.getSpanFlags(span);
- spans[i] = span;
- spanStarts[i] = spanStart;
- spanEnds[i] = spanEnd;
- spanFlags[i] = spanFlag;
+ spans[numberOfSpans] = span;
+ spanStarts[numberOfSpans] = spanStart;
+ spanEnds[numberOfSpans] = spanEnd;
+ spanFlags[numberOfSpans] = spanFlag;
- count++;
+ numberOfSpans++;
}
- numberOfSpans = count;
}
public boolean hasSpansIntersecting(int start, int end) {
@@ -926,6 +925,7 @@
}
public void recycle() {
+ // The spans array is guaranteed to be not null when numberOfSpans is > 0
for (int i = 0; i < numberOfSpans; i++) {
spans[i] = null; // prevent a leak: no reference kept when TextLine is recycled
}
diff --git a/docs/html/images/training/button.png b/docs/html/images/training/button.png
new file mode 100755
index 0000000..1a7944f
--- /dev/null
+++ b/docs/html/images/training/button.png
Binary files differ
diff --git a/docs/html/images/training/button_with_marks.png b/docs/html/images/training/button_with_marks.png
new file mode 100755
index 0000000..06e0720
--- /dev/null
+++ b/docs/html/images/training/button_with_marks.png
Binary files differ
diff --git a/docs/html/images/training/buttons_stretched.png b/docs/html/images/training/buttons_stretched.png
new file mode 100755
index 0000000..bb67419
--- /dev/null
+++ b/docs/html/images/training/buttons_stretched.png
Binary files differ
diff --git a/docs/html/images/training/layout-hvga.png b/docs/html/images/training/layout-hvga.png
new file mode 100644
index 0000000..b340300
--- /dev/null
+++ b/docs/html/images/training/layout-hvga.png
Binary files differ
diff --git a/docs/html/images/training/relativelayout1.png b/docs/html/images/training/relativelayout1.png
new file mode 100644
index 0000000..0b593dc
--- /dev/null
+++ b/docs/html/images/training/relativelayout1.png
Binary files differ
diff --git a/docs/html/images/training/relativelayout2.png b/docs/html/images/training/relativelayout2.png
new file mode 100644
index 0000000..341b286
--- /dev/null
+++ b/docs/html/images/training/relativelayout2.png
Binary files differ
diff --git a/docs/html/resources/resources-data.js b/docs/html/resources/resources-data.js
index 18f1547..d96bfde7 100644
--- a/docs/html/resources/resources-data.js
+++ b/docs/html/resources/resources-data.js
@@ -558,6 +558,16 @@
}
},
{
+ tags: ['sample', 'new', 'bestpractices'],
+ path: 'samples/newsreader/index.html',
+ title: {
+ en: 'News Reader'
+ },
+ description: {
+ en: 'A sample app demonstrating best practices to support multiple screen sizes and densities.'
+ }
+ },
+ {
tags: ['sample', 'data'],
path: 'samples/NFCDemo/index.html',
title: {
diff --git a/docs/html/resources/samples/images/NewsReader.png b/docs/html/resources/samples/images/NewsReader.png
new file mode 100644
index 0000000..f44c649
--- /dev/null
+++ b/docs/html/resources/samples/images/NewsReader.png
Binary files differ
diff --git a/docs/html/shareables/training/NewsReader.zip b/docs/html/shareables/training/NewsReader.zip
new file mode 100644
index 0000000..7dda41c
--- /dev/null
+++ b/docs/html/shareables/training/NewsReader.zip
Binary files differ
diff --git a/docs/html/training/multiple-apks/api.jd b/docs/html/training/multiple-apks/api.jd
new file mode 100644
index 0000000..292e5d0
--- /dev/null
+++ b/docs/html/training/multiple-apks/api.jd
@@ -0,0 +1,379 @@
+page.title=Creating Multiple APKs for Different API Levels
+parent.title=Creating and Maintaining Multiple APKs
+parent.link=index.html
+
+trainingnavtop=true
+next.title=Creating Multiple APKs for Different Screen Sizes
+next.link=screensize.html
+
+@jd:body
+
+<style type="text/css">
+.blueCell { background-color: #9fc5e8;}
+.greenCell { background-color: #b6d7a8;}
+.redCell { background-color: #ea9999;}
+.blackCell { background-color: #000000;}
+</style>
+
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#Confirm">Confirm You Need Multiple APKs</a></li>
+ <li><a href="#ChartReqs">Chart Your Requirements</a></li>
+ <li><a href="#CreateLibrary">Put All Common Code and Resources in a Library Project</a></li>
+ <li><a href="#CreateAPKs">Create New APK Projects</a></li>
+ <li><a href="#AdjustManifests">Adjust the Manifests</a></li>
+ <li><a href="#PreLaunch">Go Over Pre-launch Checklist</a></li>
+</ol>
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+<ul>
+ <li><a href="http://developer.android.com/guide/market/publishing/multiple-apks.html">Multiple APK
+Support</a></li>
+ <li><a
+href="http://android-developers.blogspot.com/2010/07/how-to-have-your-cupcake-and-eat-it-too.html">
+How to have your (Cup)cake and eat it too</a></li>
+</ul>
+
+</div>
+</div>
+
+
+<p>When developing your Android application to take advantage of multiple APKs on Android Market,
+it’s important to adopt some good practices from the get-go, and prevent unnecessary headaches
+further into the development process. This lesson shows you how to create multiple APKs of your
+app, each covering a slightly different range of API levels. You will also gain some tools
+necessary to make maintaining a multiple APK codebase as painless as possible.</p>
+
+
+<h2 id="Confirm">Confirm You Need Multiple APKs</h2>
+
+<p>When trying to create an application that works across multiple generations of the Android
+platform, naturally you want your application to take advantage of new features on new devices,
+without sacrificing backwards compatibility. It may seem at the outset as though multiple APK
+support is the best solution, but this often isn’t the case. The <a
+href="{@docRoot}guide/market/publishing/multiple-apks.html#ApiLevelOptions">Using Single APK
+Instead</a> section of the multiple APK developer guide includes some useful information on how to
+accomplish this with a single APK, including use of our support library. You can also learn how to
+write code that runs only at certain API levels in a single APK, without resorting to
+computationally expensive techniques like reflection from <a
+href="http://android-developers.blogspot.com/2010/07/how-to-have-your-cupcake-and-eat-it-too.html">
+this article</a>.</p>
+
+<p>If you can manage it, confining your application to a single APK has several
+advantages, including:</p>
+
+<ul>
+<li>Publishing and testing are easier</li>
+<li>There’s only one codebase to maintain</li>
+<li>Your application can adapt to device configuration changes</li>
+<li>App restore across devices just works</li>
+<li>You don’t have to worry about market preference, behavior from "upgrades" from one APK to the
+next, or which APK goes with which class of devices
+</ul>
+
+<p>The rest of this lesson assumes that you’ve researched the topic, studiously absorbed the
+material in the resources linked, and determined that multiple APKs are the right path for your
+application.</p>
+
+<h2 id="ChartReqs">Chart Your Requirements</h2>
+
+<p>Start off by creating a simple chart to quickly determine how many APKs you need, and what API
+range each APK covers. For handy reference, the <a
+href="{@docRoot}resources/dashboard/platform-versions.html">Platform Versions</a> page of the
+Android Developer website provides data about the relative number of active devices running a given
+version of the Android platform. Also, although it sounds easy at first, keeping track of which set
+of API levels each APK is going to target gets difficult rather quickly, especially if there’s going
+to be some overlap (there often is). Fortunately, it’s easy to chart out your requirements quickly,
+easily, and have an easy reference for later.</p>
+
+<p>In order to create your multiple APK chart, start out with a row of cells representing the
+various API levels of the Android platform. Throw an extra cell at the end to represent future
+versions of Android.</p>
+<table cellpadding="10" cellspacing="0" border="1">
+ <tbody>
+ <tr>
+ <td>3</td>
+ <td>4</td>
+ <td>5</td>
+ <td>6</td>
+ <td>7</td>
+ <td>8</td>
+ <td>9</td>
+ <td>10</td>
+ <td>11</td>
+ <td>12</td>
+ <td>13</td>
+ <td>+</td>
+ </tr>
+ </tbody>
+</table>
+
+<p>Now just color in the chart such that each color represents an APK. Here’s one example of how
+you might apply each APK to a certain range of API levels.</p>
+
+<table cellpadding="10" cellspacing="0" border="1">
+ <tbody>
+ <tr>
+ <td class="blueCell">3</td>
+ <td class="blueCell">4</td>
+ <td class="blueCell">5</td>
+ <td class="blueCell">6</td>
+ <td class="greenCell">7</td>
+ <td class="greenCell">8</td>
+ <td class="greenCell">9</td>
+ <td class="greenCell">10</td>
+ <td class="redCell">11</td>
+ <td class="redCell">12</td>
+ <td class="redCell">13</td>
+ <td class="redCell">+</td>
+ </tr>
+ </tbody>
+</table>
+
+<p>Once you’ve created this chart, distribute it to your team. Team communication on your project
+just got immediately simpler, since instead of asking "How’s the APK for API levels 3 to 6, er, you
+know, the Android 1.x one. How’s that coming along?" You can simply say "How’s the Blue APK coming
+along?"</p>
+
+<h2 id="CreateLibrary">Put All Common Code and Resources in a Library Project</h2>
+<p>Whether you’re modifying an existing Android application or starting one from scratch, this is
+the first thing that you should do to the codebase, and by the far the most important. Everything
+that goes into the library project only needs to be updated once (think language-localized strings,
+color themes, bugs fixed in shared code), which improves your development time and reduces the
+likelihood of mistakes that could have been easily avoided.</p>
+
+<p class="note"><strong>Note:</strong> While the implementation details of how to create and
+include library projects are beyond the scope of this lesson, you can get up to speed quickly on
+their creation at the following links:</p>
+<ul>
+<li><a
+href="{@docRoot}guide/developing/projects/projects-eclipse.html#SettingUpLibraryProject">Setting up
+a library project (Eclipse)</a></li>
+<li><a
+href="{@docRoot}guide/developing/projects/projects-cmdline.html#SettingUpLibraryProject">Setting up
+a library project (Command line)</a></li>
+</ul>
+
+
+<p>If you’re converting an existing application to use multiple APK support,
+scour your codebase for every localized string file, list of values, theme
+colors, menu icons and layout that isn’t going to change across APKs, and put
+it all in the library project. Code that isn’t going to change much should
+also go in the library project. You’ll likely find yourself extending these
+classes to add a method or two from APK to APK.</p>
+
+<p>If, on the other hand, you’re creating the application from scratch, try as
+much as possible to write code in the library project <em>first</em>, then only move it down to an
+individual APK if necessary. This is much easier to manage in the long run than adding it to one,
+then another, then another, then months later trying to figure out whether this blob can be moved up
+to the library section without screwing anything up.</p>
+
+<h2 id="CreateAPKs">Create New APK Projects</h2>
+<p>There should be a separate Android project for each APK you’re going to release. For easy
+organization, place the library project and all related APK projects under the same parent folder.
+Also remember that each APK needs to have the same package name, although they don’t necessarily
+need to share the package name with the library. If you were to have 3 APKs following the scheme
+described earlier, your root directory might look like this:</p>
+
+<pre class="no-pretty-print classic">
+alexlucas:~/code/multi-apks-root$ ls
+foo-blue
+foo-green
+foo-lib
+foo-red
+</pre>
+
+<p>Once the projects are created, add the library project as a reference to each APK project. If
+possible, define your starting Activity in the library project, and extend that Activity in your APK
+project. Having a starting activity defined in the library project gives you a chance to put all
+your application initialization in one place, so that each individual APK doesn’t have to
+re-implement "universal" tasks like initializing Analytics, running licensing checks, and any other
+initialization procedures that don’t change much from APK to APK.</p>
+
+
+<h2 id="AdjustManifests">Adjust the Manifests</h2>
+<p>When a user downloads an application which uses multiple APKs through Android Market, the correct
+APK to use is chosen using two simple rules:</p>
+<ul>
+<li>The manifest has to show that particular APK is eligible</li>
+<li>Of the eligible APKs, highest version number wins</li>
+</ul>
+<p>
+By way of example, let’s take the set of multiple APKs described earlier, and assume that we haven’t
+set a max API level for any of the APKs. Taken individually, the possible range of each APK would
+look like this:</p>
+<table cellpadding="10" cellspacing="0" border="1">
+ <tbody>
+ <tr>
+ <td class="blueCell">3</td>
+ <td class="blueCell">4</td>
+ <td class="blueCell">5</td>
+ <td class="blueCell">6</td>
+ <td class="blueCell">7</td>
+ <td class="blueCell">8</td>
+ <td class="blueCell">9</td>
+ <td class="blueCell">10</td>
+ <td class="blueCell">11</td>
+ <td class="blueCell">12</td>
+ <td class="blueCell">13</td>
+ <td class="blueCell">+</td>
+ </tr>
+ <tr>
+ <td class="blackCell">3</td>
+ <td class="blackCell">4</td>
+ <td class="blackCell">5</td>
+ <td class="blackCell">6</td>
+ <td class="greenCell">7</td>
+ <td class="greenCell">8</td>
+ <td class="greenCell">9</td>
+ <td class="greenCell">10</td>
+ <td class="greenCell">11</td>
+ <td class="greenCell">12</td>
+ <td class="greenCell">13</td>
+ <td class="greenCell">+</td>
+ </tr>
+ <tr>
+ <td class="blackCell">3</td>
+ <td class="blackCell">4</td>
+ <td class="blackCell">5</td>
+ <td class="blackCell">6</td>
+ <td class="blackCell">7</td>
+ <td class="blackCell">8</td>
+ <td class="blackCell">9</td>
+ <td class="blackCell">10</td>
+ <td class="redCell">11</td>
+ <td class="redCell">12</td>
+ <td class="redCell">13</td>
+ <td class="redCell">+</td>
+ </tr>
+ </tbody>
+</table>
+<p>
+Because it is required that an APK with a higher minSdkVersion also have a
+higher version code, we know that in terms of versionCode values, red ≥
+green ≥ blue. Therefore we can effectively collapse the chart to look like this:</p>
+<table cellpadding="10" cellspacing="0" border="1">
+ <tbody>
+ <tr>
+ <td class="blueCell">3</td>
+ <td class="blueCell">4</td>
+ <td class="blueCell">5</td>
+ <td class="blueCell">6</td>
+ <td class="greenCell">7</td>
+ <td class="greenCell">8</td>
+ <td class="greenCell">9</td>
+ <td class="greenCell">10</td>
+ <td class="redCell">11</td>
+ <td class="redCell">12</td>
+ <td class="redCell">13</td>
+ <td class="redCell">+</td>
+ </tr>
+ </tbody>
+</table>
+
+<p>
+Now, let’s further assume that the Red APK has some requirement on it that the other two don’t. The
+Market Filters page of the Android Developer guide has a whole list of possible culprits. For the
+sake of example, let’s assume that red requires a front-facing camera. In fact, the entire point of
+the red APK is to combine the front-facing camera with sweet new functionality that was added in API
+11. But, it turns out, not all devices that support API 11 even HAVE front-facing cameras! The
+horror!</p>
+
+<p>Fortunately, if a user is browsing Market from one such device, Android Market will look at the
+manifest, see that Red lists the front-facing camera as a requirement, and quietly ignore it, having
+determined that Red and that device are not a match made in digital heaven. It will then see that
+Green is not only forward-compatible with devices with API 11 (since no maxSdkVersion was defined),
+but also doesn’t care whether or not there’s a front-facing camera! The app can still be downloaded
+from Android Market by the user, because despite the whole front-camera mishap, there was still an
+APK that supported that particular API level.</p>
+
+<p> In order to keep all your APKs on separate "tracks", it’s important to have a good version code
+scheme. The recommended one can be found on the <a
+href="{@docRoot}guide/market/publishing/multiple-apks.html#VersionCodes">Version Codes</a> area of
+our developer guide. Since the example set of APKs is only dealing with one of 3 possible
+dimensions, it would be sufficient to separate each APK by 1000, set the first couple digits to the
+minSdkVersion for that particular APK, and increment from there. This might look like:</p>
+
+<p>Blue: 03001, 03002, 03003, 03004...<br />
+Green: 07001, 07002, 07003, 07004...<br />
+Red:11001, 11002, 11003, 11004...</p>
+
+<p> Putting this all together, your Android Manifests would likely look something like the following:</p>
+<p>Blue:</p>
+<pre>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ android:versionCode="03001" android:versionName="1.0" package="com.example.foo">
+ <uses-sdk android:minSdkVersion="3" />
+ ...
+</pre>
+
+<p>Green:</p>
+<pre>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ android:versionCode="07001" android:versionName="1.0" package="com.example.foo">
+ <uses-sdk android:minSdkVersion="7" />
+ ...
+</pre>
+
+<p>Red:</p>
+<pre>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ android:versionCode="11001" android:versionName="1.0" package="com.example.foo">
+ <uses-sdk android:minSdkVersion="11" />
+ ...
+</pre>
+
+<h2 id="PreLaunch">Go Over Pre-launch Checklist</h2>
+<p> Before uploading to Android Market, double-check the following items. Remember that these are specifically relevant to multiple APKs, and in no way represent a complete checklist for all applications being uploaded to Android Market.</p>
+
+<ul>
+<li>All APKs must have the same package name</li>
+<li>All APKs must be signed with the same certificate</li>
+<li>If the APKs overlap in platform version, the one with the higher minSdkVersion must have a higher version code</li>
+<li>Double check your manifest filters for conflicting information (an APK that only supports cupcake on XLARGE screens isn’t going to be seen by anybody)</li>
+<li>Each APK's manifest must be unique across at least one of supported screen, openGL texture, or platform version</li>
+<li>Try to test each APK on at least one device. Barring that, you have one of the most customizable device emulators in the business sitting on your development machine. Go nuts!</li>
+</ul>
+
+<p>It’s also worth inspecting the compiled APK before pushing to market, to make sure there aren’t
+any surprises that could hide your application in Market. This is actually quite simple using the
+"aapt" tool. Aapt (the Android Asset Packaging Tool) is part of the build process for creating and
+packaging your Android applications, and is also a very handy tool for inspecting them. </p>
+
+<pre class="no-pretty-print classic">
+>aapt dump badging
+package: name='com.example.hello' versionCode='1' versionName='1.0'
+sdkVersion:'11'
+uses-permission:'android.permission.SEND_SMS'
+application-label:'Hello'
+application-icon-120:'res/drawable-ldpi/icon.png'
+application-icon-160:'res/drawable-mdpi/icon.png'
+application-icon-240:'res/drawable-hdpi/icon.png'
+application: label='Hello' icon='res/drawable-mdpi/icon.png'
+launchable-activity: name='com.example.hello.HelloActivity' label='Hello' icon=''
+uses-feature:'android.hardware.telephony'
+uses-feature:'android.hardware.touchscreen'
+main
+supports-screens: 'small' 'normal' 'large' 'xlarge'
+supports-any-density: 'true'
+locales: '--_--'
+densities: '120' '160' '240'
+</pre>
+
+<p>When you examine aapt output, be sure to check that you don’t have conflicting values for
+supports-screens and compatible-screens, and that you don’t have unintended "uses-feature" values
+that were added as a result of permissions you set in the manifest. In the example above, the APK
+won’t be visible to very many devices.</p>
+<p>Why? By adding the required permission SEND_SMS, the feature requirement of android.hardware.telephony was implicitly added. Since API 11 is Honeycomb (the version of Android optimized specifically for tablets), and no Honeycomb devices have telephony hardware in them, Market will filter out this APK in all cases, until future devices come along which are higher in API level AND possess telephony hardware.
+</p>
+<p>Fortunately this is easily fixed by adding the following to your manifest:</p>
+<pre>
+<uses-feature android:name="android.hardware.telephony" android:required="false" />
+</pre>
+<p>Once you’ve completed the pre-launch checklist, upload your APKs to Android Market. It may take a bit for the application to show up when browsing Android Market, but when it does, perform one last check. Download the application onto any test devices you may have, to make sure that the APKs are targeting the intended devices. Congratulations, you’re done!</p>
diff --git a/docs/html/training/multiple-apks/index.jd b/docs/html/training/multiple-apks/index.jd
new file mode 100644
index 0000000..eee926c
--- /dev/null
+++ b/docs/html/training/multiple-apks/index.jd
@@ -0,0 +1,72 @@
+page.title=Creating and Maintaining Multiple APKs
+
+trainingnavtop=true
+startpage=true
+next.title=Creating Multiple APKs for Different API Levels
+next.link=api.html
+
+@jd:body
+
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- Required platform, tools, add-ons, devices, knowledge, etc. -->
+<h2>Dependencies and prerequisites</h2>
+
+<ul>
+ <li>Android 1.0 and higher</li>
+ <li>You must have an <a href="http://market.android.com/publish">Android Market</a> publisher
+account</li>
+</ul>
+
+<!-- related docs (NOT javadocs) -->
+<h2>You should also read</h2>
+<ul>
+ <li><a href="http://developer.android.com/guide/market/publishing/multiple-apks.html">Multiple APK
+Support</a></li>
+</ul>
+
+</div>
+</div>
+
+<p>Multiple APK support is a feature in Android Market that allows you to publish multiple APKs
+under the same application listing. Each APK is a complete instance of your application, optimized
+to target specific device configurations. Each APK can target a specific set of GL
+textures, API levels, screen sizes, or some combination thereof.</p>
+
+<p>This class shows you how to write your multiple APK application using any one of these
+configuration variables. Each lesson covers basics about how to organize your codebase and target
+the right devices, as well as the smart way to avoid pitfalls such as unnecessary redundancy across
+your codebase, and making mistakes in your manifest that could render an APK invisible to all
+devices in Android Market. By going through any of these lessons, you'll know how to develop
+multiple APKs the smart way, make sure they're targeting the devices you want them to,
+and know how to catch mistakes <em>before</em> your app goes live.</p>
+
+
+
+<h2>Lessons</h2>
+
+<dl>
+ <dt><b><a href="api.html">Creating Multiple APKs for Different API Levels</a></b></dt>
+ <dd>Learn how to target different versions of the Android platform using multiple APKs. Also
+learn how to organize your codebase, what to do with your manifest, and how to investigate your APK
+configuration using the <code>aapt</code> tool before pushing live.</dd>
+
+ <dt><b><a href="screensize.html">Creating Multiple APKs for Different Screen Sizes</a></b></dt>
+ <dd>Learn how to target Android devices by screen size using multiple APKs. Also learn how to
+organize your codebase, what to do with your manifest, and how to investigate your APK configuration
+using the <code>aapt</code> tool before pushing live.</dd>
+
+ <dt><b><a href="texture.html">Creating Multiple APKs for Different GL Textures</a></b></dt>
+ <dd>Learn how to target Android devices based on their support for GL texture. Also learn
+how to organize your codebase, what to do with your manifest, and how to investigate your APK
+configuration using the <code>aapt</code> tool before pushing live.</dd>
+
+ <dt><b><a href="multiple.html">Creating Multiple APKs with 2+ Dimensions</a></b></dt>
+ <dd>Learn how to target different Android devices based on more than one configuration
+variable (screen size, API version, GL texture). Examples in the lesson target using a combination
+of API level and screen size. Also learn how to organize your codebase, what to do with your
+manifest, and how to investigate your APK configuration using the <code>aapt</code> tool before
+pushing live.</dd>
+</dl>
diff --git a/docs/html/training/multiple-apks/multiple.jd b/docs/html/training/multiple-apks/multiple.jd
new file mode 100644
index 0000000..f872379
--- /dev/null
+++ b/docs/html/training/multiple-apks/multiple.jd
@@ -0,0 +1,475 @@
+page.title=Creating Multiple APKs with 2+ Dimensions
+parent.title=Creating and Maintaining Multiple APKs
+parent.link=index.html
+
+trainingnavtop=true
+previous.title=Creating Multiple APKs for Different GL Textures
+previous.link=texture.html
+
+@jd:body
+
+<style>
+.blueCell { background-color: #9fc5e8;}
+.greenCell { background-color: #b6d7a8;}
+.redCell { background-color: #ea9999;}
+.purpleCell { background-color: #b4a7d6;}
+.blackCell { background-color: #000000;}
+</style>
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#Confirm">Confirm You Need Multiple APKs</a></li>
+ <li><a href="#ChartReqs">Chart Your Requirements</a></li>
+ <li><a href="#CreateLibrary">Put All Common Code and Resources in a Library Project.</a></li>
+ <li><a href="#CreateAPKs">Create New APK Projects</a></li>
+ <li><a href="#AdjustManifests">Adjust the Manifests</a></li>
+ <li><a href="#PreLaunch">Go Over Pre-launch Checklist</a></li>
+</ol>
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+<ul>
+ <li><a href="http://developer.android.com/guide/market/publishing/multiple-apks.html">Multiple APK
+Support</a></li>
+</ul>
+
+</div>
+</div>
+
+<p>When developing your Android application to take advantage of multiple APKs on Android Market,
+it’s important to adopt some good practices from the get-go, and prevent unnecessary headaches
+further into the development process. This lesson shows you how to create multiple APKs of your
+app, each covering a different class of screen size. You will also gain some tools necessary to
+make maintaining a multiple APK codebase as painless as possible.</p>
+
+
+<h2 id="Confirm">Confirm You Need Multiple APKs</h2>
+
+<p>When trying to create an application that works across the huge range of available Android
+devices, naturally you want your application look its best on each individual device. You want to
+take advantage of the space of large screens but still work on small ones, to use new Android API
+features or visual textures available on cutting edge devices but not abandon older ones. It may
+seem at the outset as though multiple APK support is the best solution, but this often isn’t the
+case. The <a href="{@docRoot}guide/market/publishing/multiple-apks.html#ApiLevelOptions">Using
+Single APK Instead</a> section of the multiple APK guide includes some useful information on how to
+accomplish all of this with a single APK, including use of our <a
+href="http://android-developers.blogspot.com/2011/03/fragments-for-all.html">support library</a>,
+and links to resources throughout the Android Developer guide.</p>
+
+<p>If you can manage it, confining your application to a single APK has several advantages,
+including:</p>
+
+<ul>
+<li>Publishing and Testing are easier</li>
+<li>There’s only one codebase to maintain</li>
+<li>Your application can adapt to device configuration changes</li>
+<li>App restore across devices just works</li>
+<li>You don’t have to worry about market preference, behavior from "upgrades" from one APK to the
+next, or which APK goes with which class of devices</li>
+</ul>
+
+<p>The rest of this lesson assumes that you’ve researched the topic, studiously absorbed the
+material in the resources linked, and determined that multiple APKs are the right path for your
+application.</p>
+
+
+<h2 id="ChartReqs">Chart Your Requirements</h2>
+
+<p>Start off by creating a simple chart to quickly determine how many APKs you need, and what screen
+size(s) each APK covers. Fortunately, it’s easy to chart out your requirements quickly, easily, and
+have an easy reference for later. Let’s say you want to split your APKs across two dimensions, API
+and screen size. Create a table with a row and column for each possible pair of values, and color
+in some "blobs", each color representing one APK.</p>
+
+<table cellpadding="10" cellspacing="0" border="1">
+ <tbody>
+ <tr>
+ <td>3</td>
+ <td>4</td>
+ <td>5</td>
+ <td>6</td>
+ <td>7</td>
+ <td>8</td>
+ <td>9</td>
+ <td>10</td>
+ <td>11</td>
+ <td>12</td>
+ <td>+</td>
+ </tr>
+ <tr>
+ <td>small</td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ </tr>
+ <tr>
+ <td>normal</td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ </tr>
+ <tr>
+ <td>large</td>
+ <td class="greenCell"></td>
+ <td class="greenCell"></td>
+ <td class="greenCell"></td>
+ <td class="greenCell"></td>
+ <td class="greenCell"></td>
+ <td class="greenCell"></td>
+ <td class="greenCell"></td>
+ <td class="greenCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ </tr>
+ <tr>
+ <td>large</td>
+ <td class="redCell"></td>
+ <td class="redCell"></td>
+ <td class="redCell"></td>
+ <td class="redCell"></td>
+ <td class="redCell"></td>
+ <td class="redCell"></td>
+ <td class="redCell"></td>
+ <td class="redCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ </tr>
+ </tbody>
+</table>
+
+<p>
+Above is an example with four APKs. Blue is for all small/normal screen devices, Green is for large
+screen devices, and Red is for xlarge screen devices, all with an API range of 3-10. Purple is a
+special case, as it’s for all screen sizes, but only for API 11 and up. More importantly, just by
+glancing at this chart, you immediately know which APK covers any given API/screen-size combo. To
+boot, you also have swanky codenames for each one, since "Have we tested red on the ?" is a lot
+easier to ask your cubie than "Have we tested the 3-to-10 xlarge APK against the Xoom?" Print this
+chart out and hand it to every person working on your codebase. Life just got a lot easier.</p>
+
+<h2 id="CreateLibrary">Put All Common Code and Resources in a Library Project.</h2>
+
+<p>Whether you’re modifying an existing Android application or starting one from scratch, this is
+the first thing that you should do to the codebase, and by the far the most important. Everything
+that goes into the library project only needs to be updated once (think language-localized strings,
+color themes, bugs fixed in shared code), which improves your development time and reduces the
+likelihood of mistakes that could have been easily avoided.</p>
+
+<p class="note"><strong>Note:</strong> While the implementation details of how to create and
+include library projects are beyond the scope of this lesson, you can get up to speed quickly on
+their creation at the following links:</p>
+<ul>
+<li><a
+href="{@docRoot}guide/developing/projects/projects-eclipse.html#SettingUpLibraryProject">Setting up
+a library project (Eclipse)</a></li>
+<li><a
+href="{@docRoot}guide/developing/projects/projects-cmdline.html#SettingUpLibraryProject">Setting up
+a library project (Command line)</a></li>
+</ul>
+
+<p>If you’re converting an existing application to use multiple APK support,
+scour your codebase for every localized string file, list of values, theme
+colors, menu icons and layout that isn’t going to change across APKs, and put
+it all in the library project. Code that isn’t going to change much should
+also go in the library project. You’ll likely find yourself extending these
+classes to add a method or two from APK to APK.</p>
+
+<p>If, on the other hand, you’re creating the application from scratch, try as
+much as possible to write code in the library project <em>first</em>, then only move it down to an
+individual APK if necessary. This is much easier to manage in the long run than adding it to one,
+then another, then another, then months later trying to figure out whether this blob can be moved up
+to the library section without screwing anything up.</p>
+
+<h2 id="CreateAPKs">Create New APK Projects</h2>
+<p>There should be a separate Android project for each APK you’re going to release. For easy
+organization, place the library project and all related APK projects under the same parent folder.
+Also remember that each APK needs to have the same package name, although they don’t necessarily
+need to share the package name with the library. If you were to have 3 APKs following the scheme
+described earlier, your root directory might look like this:</p>
+
+<pre class="no-pretty-print classic">
+alexlucas:~/code/multi-apks-root$ ls
+foo-blue
+foo-green
+foo-lib
+foo-purple
+foo-red
+</pre>
+
+<p>Once the projects are created, add the library project as a reference to each APK project. If
+possible, define your starting Activity in the library project, and extend that Activity in your APK
+project. Having a starting activity defined in the library project gives you a chance to put all
+your application initialization in one place, so that each individual APK doesn’t have to
+re-implement "universal" tasks like initializing Analytics, running licensing checks, and any other
+initialization procedures that don’t change much from APK to APK.</p>
+
+
+<h2 id="AdjustManifests">Adjust the Manifests</h2>
+<p>When a user downloads an application which uses multiple APKs through Android Market, the correct
+APK to use is chosen using two simple rules:
+
+<ul>
+<li>The manifest has to show that particular APK is eligible</li>
+<li>Of the eligible APKs, highest version number wins.</li>
+</ul>
+
+<p>By way of example, let’s take the set of multiple APKs described earlier, and assume that each
+APK has been set to support all screen sizes larger than its "target" screen size. Let’s look at
+the sample chart from earlier:</p>
+
+<table cellpadding="10" cellspacing="0" border="1">
+ <tbody>
+ <tr>
+ <td>3</td>
+ <td>4</td>
+ <td>5</td>
+ <td>6</td>
+ <td>7</td>
+ <td>8</td>
+ <td>9</td>
+ <td>10</td>
+ <td>11</td>
+ <td>12</td>
+ <td>+</td>
+ </tr>
+ <tr>
+ <td>small</td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ </tr>
+ <tr>
+ <td>normal</td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="blueCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ </tr>
+ <tr>
+ <td>large</td>
+ <td class="greenCell"></td>
+ <td class="greenCell"></td>
+ <td class="greenCell"></td>
+ <td class="greenCell"></td>
+ <td class="greenCell"></td>
+ <td class="greenCell"></td>
+ <td class="greenCell"></td>
+ <td class="greenCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ </tr>
+ <tr>
+ <td>large</td>
+ <td class="redCell"></td>
+ <td class="redCell"></td>
+ <td class="redCell"></td>
+ <td class="redCell"></td>
+ <td class="redCell"></td>
+ <td class="redCell"></td>
+ <td class="redCell"></td>
+ <td class="redCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ <td class="purpleCell"></td>
+ </tr>
+ </tbody>
+</table>
+<p>Since it’s okay for coverage to overlap, we can describe the area covered by each APK like
+so:</p>
+<ul>
+<li>Blue covers all screens, minSDK 3.</li>
+<li>Green covers Large screens and higher, minSDK 3.</li>
+<li>Red covers XLarge screens (generally tablets), minSDK of 9.</li>
+<li>Purple covers all screens, minSDK of 11.</li>
+</ul>
+<p>Note that there’s a <em>lot</em> of overlap in those rules. For instance, an
+XLarge device with API 11 can conceivably run any one of the 4 APKs specified.
+However, by using the "highest version number wins" rule, we can set an order of
+preference as follows:</p>
+<p>
+Purple ≥ Red ≥ Green ≥ Blue
+</p><p>
+Why allow all the overlap? Let’s pretend that the Purple APK has some requirement on it that the
+other two don’t. The <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters page</a>
+of the Android Developer guide has a whole list of possible culprits. For the sake of example,
+let’s assume that Purple requires a front-facing camera. In fact, the entire point of Purple is to
+use entertaining things with the front-facing camera! But, it turns out, not all API 11+ devices
+even HAVE front-facing cameras! The horror!</p>
+
+<p>Fortunately, if a user is browsing Market from one such device, Android Market will look at the
+manifest, see that Purple lists the front-facing camera as a requirement, and quietly ignore it,
+having determined that Purple and that device are not a match made in digital heaven. It will then
+see that Red is not only compatible with xlarge devices, but also doesn’t care whether or not
+there’s a front-facing camera! The app can still be downloaded from Android Market by the user,
+because despite the whole front-camera mishap, there was still an APK that supported that particular
+API level.</p>
+
+<p> In order to keep all your APKs on separate "tracks", it’s important to have a good version code
+scheme. The recommended one can be found on the <a
+href="{@docRoot}guide/market/publishing/multiple-apks.html#VersionCodes">Version Codes</a> area of
+our developer guide. It’s worth reading the whole section, but the basic gist is for this set of
+APKs, we’d use two digits to represent the minSDK, two to represent the min/max screen size, and 3
+to represent the build number. That way, when the device upgraded to a new version of Android,
+(say, from 10 to 11), any APKs that are now eligible and preferred over the currently installed one
+would be seen by the device as an "upgrade". The version number scheme, when applied to the example
+set of APKs, might look like:</p>
+
+<p>Blue: 0304001, 0304002, 0304003...<br />
+Green: 0334001, 0334002, 0334003<br />
+Red: 0344001, 0344002, 0344003...<br />
+Purple: 1104001, 1104002, 1104003...<br />
+</p>
+
+<p> Putting this all together, your Android Manifests would likely look something like the
+following:</p>
+<p>Blue:</p>
+<pre>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ android:versionCode="0304001" android:versionName="1.0" package="com.example.foo">
+ <uses-sdk android:minSdkVersion="3" />
+ <supports-screens android:smallScreens="true"
+ android:normalScreens="true"
+ android:largeScreens="true"
+ android:xlargeScreens="true" />
+ ...
+</pre>
+
+<p>Green:</p>
+<pre>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ android:versionCode="0334001" android:versionName="1.0" package="com.example.foo">
+ <uses-sdk android:minSdkVersion="3" />
+ <supports-screens android:smallScreens="false"
+ android:normalScreens="false"
+ android:largeScreens="true"
+ android:xlargeScreens="true" />
+ ...
+</pre>
+
+<p>Red:</p>
+<pre>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ android:versionCode="0344001" android:versionName="1.0" package="com.example.foo">
+ <uses-sdk android:minSdkVersion="3" />
+ <supports-screens android:smallScreens="false"
+ android:normalScreens="false"
+ android:largeScreens="false"
+ android:xlargeScreens="true" />
+ ...
+</pre>
+
+<p>Purple:</p>
+<pre>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ android:versionCode="1104001" android:versionName="1.0" package="com.example.foo">
+ <uses-sdk android:minSdkVersion="11" />
+ <supports-screens android:smallScreens="true"
+ android:normalScreens="true"
+ android:largeScreens="true"
+ android:xlargeScreens="true" />
+ ...
+</pre>
+
+<p>
+Note that technically, multiple APK’s will work with either the supports-screens tag, or the
+compatible-screens tag. Supports-screens is generally preferred, and it’s generally a really bad
+idea to use both- It makes things needlessly complicated, and increases the opportunity for errors.
+ Also note that instead of taking advantage of the default values (small and normal are always true
+by default), the manifests explicitly set the value for each screen size. This can save you
+headaches down the line - By way of example, a manifest with a target SDK of < 9 will have xlarge
+automatically set to false, since that size didn’t exist yet. So be explicit!
+</p>
+
+<h2 id="PreLaunch">Go Over Pre-launch Checklist</h2>
+<p> Before uploading to Android Market, double-check the following items. Remember that these are
+specifically relevant to multiple APKs, and in no way represent a complete checklist for all
+applications being uploaded to Android Market.</p>
+<ul>
+<li>All APKs must have the same package name.</li>
+<li>All APKs must be signed with the same certificate.</li>
+<li>If the APKs overlap in platform version, the one with the higher minSdkVersion must have a
+higher version code.</li>
+<li>Every screen size you want your APK to support, set to true in the manifest. Every screen size
+you want it to avoid, set to false.</li>
+<li>Double check your manifest filters for conflicting information (an APK that only supports
+cupcake on XLARGE screens isn’t going to be seen by anybody)</li>
+<li>Each APK's manifest must be unique across at least one of supported screen, OpenGL texture, or
+platform version.</li>
+<li>Try to test each APK on at least one device. Barring that, you have one of the most
+customizable device emulators in the business sitting on your development machine. Go nuts!</li>
+</ul>
+
+<p>It’s also worth inspecting the compiled APK before pushing to market, to make sure there aren’t
+any surprises that could hide your application in Market. This is actually quite simple using the
+"aapt" tool. Aapt (the Android Asset Packaging Tool) is part of the build process for creating and
+packaging your Android applications, and is also a very handy tool for inspecting them. </p>
+
+<pre class="no-pretty-print classic">
+>aapt dump badging
+package: name='com.example.hello' versionCode='1' versionName='1.0'
+sdkVersion:'11'
+uses-permission:'android.permission.SEND_SMS'
+application-label:'Hello'
+application-icon-120:'res/drawable-ldpi/icon.png'
+application-icon-160:'res/drawable-mdpi/icon.png'
+application-icon-240:'res/drawable-hdpi/icon.png'
+application: label='Hello' icon='res/drawable-mdpi/icon.png'
+launchable-activity: name='com.example.hello.HelloActivity' label='Hello' icon=''
+uses-feature:'android.hardware.telephony'
+uses-feature:'android.hardware.touchscreen'
+main
+supports-screens: 'xlarge'
+supports-any-density: 'true'
+locales: '--_--'
+densities: '120' '160' '240'
+</pre>
+
+<p>When you examine aapt output, be sure to check that you don’t have conflicting values for
+supports-screens and compatible-screens, and that you don’t have unintended "uses-feature" values
+that were added as a result of permissions you set in the manifest. In the example above, the APK
+will be invisible to most, if not all devices.</p>
+<p>Why? By adding the required permission SEND_SMS, the feature requirement of android.hardware.telephony was implicitly added. Since most (if not all) xlarge devices are tablets without telephony hardware in them, Market will filter out this APK in these cases, until future devices come along which are both large enough to report as xlarge screen size, and possess telephony hardware.
+</p>
+<p>Fortunately this is easily fixed by adding the following to your manifest:<p>
+<pre>
+<uses-feature android:name="android.hardware.telephony" android:required="false" />
+</pre>
+
+<p>Once you’ve completed the pre-launch checklist, upload your APKs to Android Market. It may take a bit for the application to show up when browsing Android Market, but when it does, perform one last check. Download the application onto any test devices you may have to make sure that the APKs are targeting the intended devices. Congratulations, you’re done!</p>
diff --git a/docs/html/training/multiple-apks/screensize.jd b/docs/html/training/multiple-apks/screensize.jd
new file mode 100644
index 0000000..28611ec
--- /dev/null
+++ b/docs/html/training/multiple-apks/screensize.jd
@@ -0,0 +1,355 @@
+page.title=Creating Multiple APKs for Different Screen Sizes
+parent.title=Creating and Maintaining Multiple APKs
+parent.link=index.html
+
+trainingnavtop=true
+previous.title=Creating Multiple APKs for Different API Levels
+previous.link=api.html
+next.title=Creating Multiple APKs for Different GL Textures
+next.link=texture.html
+
+@jd:body
+
+<style type="text/css">
+.blueCell { background-color: #9fc5e8;}
+.greenCell { background-color: #b6d7a8;}
+.redCell { background-color: #ea9999;}
+.blackCell { background-color: #000000;}
+</style>
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#Confirm">Confirm You Need Multiple APKs</a></li>
+ <li><a href="#ChartReqs">Chart Your Requirements</a></li>
+ <li><a href="#CreateLibrary">Put All Common Code and Resources in a Library Project.</a></li>
+ <li><a href="#CreateAPKs">Create New APK Projects</a></li>
+ <li><a href="#AdjustManifests">Adjust the Manifests</a></li>
+ <li><a href="#PreLaunch">Go Over Pre-launch Checklist</a></li>
+</ol>
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+<ul>
+ <li><a href="http://developer.android.com/guide/market/publishing/multiple-apks.html">Multiple APK
+Support</a></li>
+ <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li>
+</ul>
+
+</div>
+</div>
+
+
+<p>When developing your Android application to take advantage of multiple APKs on Android Market,
+it’s important to adopt some good practices from the get-go, and prevent unnecessary headaches
+further into the development process. This lesson shows you how to create multiple APKs of your
+app, each covering a different class of screen size. You will also gain some tools necessary to
+make maintaining a multiple APK codebase as painless as possible.</p>
+
+
+<h2 id="Confirm">Confirm You Need Multiple APKs</h2>
+
+<p>When trying to create an application that works across multiple sizes of Android devices,
+naturally you want your application to take advantage of all the available space on larger devices,
+without sacrificing compatibility or usability on the smaller screens. It may seem at the outset as
+though multiple APK support is the best solution, but this often isn’t the case. The <a
+href="{@docRoot}guide/market/publishing/multiple-apks.html#ApiLevelOptions">Using Single APK
+Instead</a> section of the multiple APK developer guide includes some useful information on how to
+accomplish this with a single APK, including use of our support library. You should also read the
+guide to <a href="{@docRoot}guide/practices/screens_support.html">supporting multiple screens</a>,
+and there’s even a <a
+href="http://android-developers.blogspot.com/2011/03/fragments-for-all.html">support library</a> you
+can download using the Android SDK, which lets you use fragments on pre-Honeycomb devices (making
+multiple-screen support in a single APK much easier).</p>
+
+<p>If you can manage it, confining your application to a single APK has several advantages,
+including:</p>
+
+<ul>
+<li>Publishing and testing are easier</li>
+<li>There’s only one codebase to maintain</li>
+<li>Your application can adapt to device configuration changes</li>
+<li>App restore across devices just works</li>
+<li>You don’t have to worry about market preference, behavior from "upgrades" from one APK to the
+next, or which APK goes with which class of devices</li>
+</ul>
+
+<p>The rest of this lesson assumes that you’ve researched the topic, studiously absorbed the
+material in the resources linked, and determined that multiple APKs are the right path for your
+application.</p>
+
+<h2 id="ChartReqs">Chart Your Requirements</h2>
+
+<p>Start off by creating a simple chart to quickly determine how many APKs you need, and what screen
+size(s) each APK covers. Fortunately, it’s easy to chart out your requirements quickly and easily,
+and have a reference for later. Start out with a row of cells representing the various screen sizes
+available on the Android platform.</p>
+
+<table cellpadding="10" cellspacing="0" border="1">
+ <tbody>
+ <tr>
+ <td>small</td>
+ <td>normal</td>
+ <td>large</td>
+ <td>xlarge</td>
+ </tr>
+ </tbody>
+</table>
+<p>
+Now just color in the chart such that each color represents an APK. Here’s one example of how you
+might apply each APK to a certain range of screen sizes.</p>
+
+<table cellpadding="10" cellspacing="0" border="1">
+ <tbody>
+ <tr>
+ <td class="blueCell">small</td>
+ <td class="blueCell">normal</td>
+ <td class="greenCell">large</td>
+ <td class="redCell">xlarge</td>
+ </tr>
+ </tbody>
+</table>
+<p>
+Depending on your needs, you could also have two APKs, "small and everything else" or "xlarge and
+everything else". Coloring in the chart also makes intra-team communication easier—You can
+now simply refer to each APK as "blue", "green", or "red", no matter how many different screen types
+it covers.</p>
+
+<h2 id="CreateLibrary">Put All Common Code and Resources in a Library Project.</h2>
+<p>Whether you’re modifying an existing Android application or starting one from scratch, this is
+the first thing that you should do to the codebase, and by the far the most important. Everything
+that goes into the library project only needs to be updated once (think language-localized strings,
+color themes, bugs fixed in shared code), which improves your development time and reduces the
+likelihood of mistakes that could have been easily avoided.</p>
+
+<p class="note"><strong>Note:</strong> While the implementation details of how to create and
+include library projects are beyond the scope of this lesson, you can get up to speed quickly on
+their creation at the following links:</p>
+<ul>
+<li><a
+href="{@docRoot}guide/developing/projects/projects-eclipse.html#SettingUpLibraryProject">Setting up
+a library project (Eclipse)</a></li>
+<li><a
+href="{@docRoot}guide/developing/projects/projects-cmdline.html#SettingUpLibraryProject">Setting up
+a library project (Command line)</a></li>
+</ul>
+
+
+
+<p>If you’re converting an existing application to use multiple APK support,
+scour your codebase for every localized string file, list of values, theme
+colors, menu icons and layout that isn’t going to change across APKs, and put
+it all in the library project. Code that isn’t going to change much should
+also go in the library project. You’ll likely find yourself extending these
+classes to add a method or two from APK to APK.</p>
+
+<p>If, on the other hand, you’re creating the application from scratch, try as
+much as possible to write code in the library project <em>first</em>, then only move it down to an
+individual APK if necessary. This is much easier to manage in the long run than adding it to one,
+then another, then another, then months later trying to figure out whether this blob can be moved up
+to the library section without screwing anything up.</p>
+
+
+
+<h2 id="CreateAPKs">Create New APK Projects</h2>
+<p>There should be a separate Android project for each APK you’re going to release. For easy
+organization, place the library project and all related APK projects under the same parent folder.
+Also remember that each APK needs to have the same package name, although they don’t necessarily
+need to share the package name with the library. If you were to have 3 APKs following the scheme
+described earlier, your root directory might look like this:</p>
+
+<pre class="no-pretty-print classic">
+alexlucas:~/code/multi-apks-root$ ls
+foo-blue
+foo-green
+foo-lib
+foo-red
+</pre>
+
+<p>Once the projects are created, add the library project as a reference to each APK project. If
+possible, define your starting Activity in the library project, and extend that Activity in your APK
+project. Having a starting activity defined in the library project gives you a chance to put all
+your application initialization in one place, so that each individual APK doesn’t have to
+re-implement "universal" tasks like initializing Analytics, running licensing checks, and any other
+initialization procedures that don’t change much from APK to APK.</p>
+
+
+<h2 id="AdjustManifests">Adjust the Manifests</h2>
+<p>When a user downloads an application which uses multiple APKs through Android Market, the correct
+APK to use is chosen using two simple rules:</p>
+<ul>
+<li>The manifest has to show that particular APK is eligible</li>
+<li>Of the eligible APKs, highest version number wins</li>
+</ul>
+
+<p>
+By way of example, let’s take the set of multiple APKs described earlier, and assume that each APK
+has been set to support all screen sizes larger than its "target" screen size. Taken individually,
+the possible range of each APK would look like this:
+</p>
+<table cellpadding="10" cellspacing="0" border="1">
+ <tbody>
+ <tr>
+ <td class="blueCell">small</td>
+ <td class="blueCell">normal</td>
+ <td class="blueCell">large</td>
+ <td class="blueCell">xlarge</td>
+ </tr>
+ <tr>
+ <td class="blackCell">small</td>
+ <td class="blackCell">normal</td>
+ <td class="greenCell">large</td>
+ <td class="greenCell">xlarge</td>
+ </tr>
+ <tr>
+ <td class="blackCell">small</td>
+ <td class="blackCell">normal</td>
+ <td class="blackCell">large</td>
+ <td class="redCell">xlarge</td>
+ </tr>
+ </tbody>
+</table>
+<p>
+However, by using the "highest version number wins" rule, if we set the versionCode attribute in
+each APK such that red ≥ green ≥ blue, the chart effectively collapses down to this:</p>
+<table cellpadding="10" cellspacing="0" border="1">
+ <tbody>
+ <tr>
+ <td class="blueCell">small</td>
+ <td class="blueCell">normal</td>
+ <td class="greenCell">large</td>
+ <td class="redCell">xlarge</td>
+ </tr>
+ </tbody>
+</table>
+<p>
+Now, let’s further assume that the Red APK has some requirement on it that the other two don’t. The
+<a href="{@docRoot}guide/appendix/market-filters.html">Market Filters page</a> of the Android
+Developer guide has a whole list of possible culprits. For the sake of example, let’s assume that
+red requires a front-facing camera. In fact, the entire point of the red APK is to use the extra
+available screen space to do entertaining things with that front-facing camera. But, it turns out,
+not all xlarge devices even HAVE front-facing cameras! The horror!</p>
+
+<p>Fortunately, if a user is browsing Market from one such device, Android Market will look at the
+manifest, see that Red lists the front-facing camera as a requirement, and quietly ignore it, having
+determined that Red and that device are not a match made in digital heaven. It will then see that
+Green is not only compatible with xlarge devices, but also doesn’t care whether or not there’s a
+front-facing camera! The app can still be downloaded from Android Market by the user, because
+despite the whole front-camera mishap, there was still an APK that supported that particular screen
+size.</p>
+
+<p> In order to keep all your APKs on separate "tracks", it’s important to have a good version code
+scheme. The recommended one can be found on the <a
+href="{@docRoot}guide/market/publishing/multiple-apks.html#VersionCodes">Version Codes</a> area of
+our developer guide. Since the example set of APKs is only dealing with one of 3 possible
+dimensions, it would be sufficient to separate each APK by 1000 and increment from there. This
+might look like:</p>
+
+<p>Blue: 1001, 1002, 1003, 1004...<br />
+Green: 2001, 2002, 2003, 2004...<br />
+Red:3001, 3002, 3003, 3004...</p>
+
+<p> Putting this all together, your Android Manifests would likely look something like the
+following:</p>
+
+<p>Blue:</p>
+<pre>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ android:versionCode="1001" android:versionName="1.0" package="com.example.foo">
+ <supports-screens android:smallScreens="true"
+ android:normalScreens="true"
+ android:largeScreens="true"
+ android:xlargeScreens="true" />
+ ...
+</pre>
+
+<p>Green:</p>
+<pre>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ android:versionCode="2001" android:versionName="1.0" package="com.example.foo">
+ <supports-screens android:smallScreens="false"
+ android:normalScreens="false"
+ android:largeScreens="true"
+ android:xlargeScreens="true" />
+ ...
+</pre>
+
+<p>Red:</p>
+<pre>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ android:versionCode="3001" android:versionName="1.0" package="com.example.foo">
+ <supports-screens android:smallScreens="false"
+ android:normalScreens="false"
+ android:largeScreens="false"
+ android:xlargeScreens="true" />
+ ...
+</pre>
+<p>
+Note that technically, multiple APK’s will work with either the supports-screens
+tag, or the compatible-screens tag. Supports-screens is generally preferred,
+and it’s generally a really bad idea to use both tags in the same manifest. It
+makes things needlessly complicated, and increases the opportunity for errors.
+Also note that instead of taking advantage of the default values (small and
+normal are always true by default), the manifests explicitly set the value for
+each screen size. This can save you headaches down the line. For instance, a manifest with a
+target SDK of < 9 will have xlarge automatically set to false, since that size didn’t exist yet.
+So be explicit!
+</p>
+
+<h2 id="PreLaunch">Go Over Pre-launch Checklist</h2>
+<p> Before uploading to Android Market, double-check the following items. Remember that these are
+specifically relevant to multiple APKs, and in no way represent a complete checklist for all
+applications being uploaded to Android Market.</p>
+<ul>
+<li>All APKs must have the same package name</li>
+<li>All APKs must be signed with the same certificate</li>
+<li>Every screen size you want your APK to support, set to true in the manifest. Every screen size
+you want it to avoid, set to false</li>
+<li>Double check your manifest filters for conflicting information (an APK that only supports
+cupcake on XLARGE screens isn’t going to be seen by anybody)</li>
+<li>Each APK's manifest must be unique across at least one of supported screen, openGL texture, or
+platform version</li>
+<li>Try to test each APK on at least one device. Barring that, you have one of the most
+customizable device emulators in the business sitting on your development machine. Go nuts!</li>
+</ul>
+
+<p>It’s also worth inspecting the compiled APK before pushing to market, to make sure there aren’t
+any surprises that could hide your application in Market. This is actually quite simple using the
+"aapt" tool. Aapt (the Android Asset Packaging Tool) is part of the build process for creating and
+packaging your Android applications, and is also a very handy tool for inspecting them. </p>
+
+<pre class="no-pretty-print classic">
+>aapt dump badging
+package: name='com.example.hello' versionCode='1' versionName='1.0'
+sdkVersion:'11'
+uses-permission:'android.permission.SEND_SMS'
+application-label:'Hello'
+application-icon-120:'res/drawable-ldpi/icon.png'
+application-icon-160:'res/drawable-mdpi/icon.png'
+application-icon-240:'res/drawable-hdpi/icon.png'
+application: label='Hello' icon='res/drawable-mdpi/icon.png'
+launchable-activity: name='com.example.hello.HelloActivity' label='Hello' icon=''
+uses-feature:'android.hardware.telephony'
+uses-feature:'android.hardware.touchscreen'
+main
+supports-screens: 'xlarge'
+supports-any-density: 'true'
+locales: '--_--'
+densities: '120' '160' '240'
+</pre>
+
+<p>When you examine aapt output, be sure to check that you don’t have conflicting values for
+supports-screens and compatible-screens, and that you don’t have unintended "uses-feature" values
+that were added as a result of permissions you set in the manifest. In the example above, the APK
+will be invisible to most, if not all devices.</p>
+<p>Why? By adding the required permission SEND_SMS, the feature requirement of android.hardware.telephony was implicitly added. Since most (if not all) xlarge devices are tablets without telephony hardware in them, Market will filter out this APK in these cases, until future devices come along which are both large enough to report as xlarge screen size, and possess telephony hardware.
+</p>
+<p>Fortunately this is easily fixed by adding the following to your
+manifest:</p>
+<pre>
+<uses-feature android:name="android.hardware.telephony" android:required="false" />
+</pre>
+<p>Once you’ve completed the pre-launch checklist, upload your APKs to Android Market. It may take a bit for the application to show up when browsing Android Market, but when it does, perform one last check. Download the application onto any test devices you may have to make sure that the APKs are targeting the intended devices. Congratulations, you’re done!</p>
diff --git a/docs/html/training/multiple-apks/texture.jd b/docs/html/training/multiple-apks/texture.jd
new file mode 100644
index 0000000..6f75ef3
--- /dev/null
+++ b/docs/html/training/multiple-apks/texture.jd
@@ -0,0 +1,299 @@
+page.title=Creating Multiple APKs for Different GL Textures
+parent.title=Creating and Maintaining Multiple APKs
+parent.link=index.html
+
+trainingnavtop=true
+previous.title=Creating Multiple APKs for Different Screen Sizes
+previous.link=screensize.html
+next.title=Creating Multiple APKs with 2+ Dimensions
+next.link=multiple.html
+
+@jd:body
+
+<style type="text/css">
+.blueCell { background-color: #9fc5e8;}
+.greenCell { background-color: #b6d7a8;}
+.redCell { background-color: #ea9999;}
+</style>
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#Confirm">Confirm You Need Multiple APKs</a></li>
+ <li><a href="#ChartReqs">Chart Your Requirements</a></li>
+ <li><a href="#CreateLibrary">Put All Common Code and Resources in a Library Project</a></li>
+ <li><a href="#CreateAPKs">Create New APK Projects</a></li>
+ <li><a href="#AdjustManifests">Adjust the Manifests</a></li>
+ <li><a href="#PreLaunch">Go Over Pre-launch Checklist</a></li>
+</ol>
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+<ul>
+ <li><a href="http://developer.android.com/guide/market/publishing/multiple-apks.html">Multiple APK
+Support</a></li>
+</ul>
+
+</div>
+</div>
+
+<p>When developing your Android application to take advantage of multiple APKs on Android Market, it’s important to adopt some good practices from the get-go, and prevent unnecessary headaches further into the development process. This lesson shows you how to create multiple APKs of your app, each supporting a different subset of OpenGL texture formats. You will also gain some tools necessary to make maintaining a multiple APK codebase as painless as possible.</p>
+
+
+<h2 id="Confirm">Confirm You Need Multiple APKs</h2>
+
+<p>When trying to create an application that works across all available Android-powered
+devices, naturally you want your application look its best on each individual device, regardless of
+the fact they don’t all support the same set of GL textures. It may seem at the outset as though
+multiple APK support is the best solution, but this often isn’t the case. The <a
+href="{@docRoot}guide/market/publishing/multiple-apks.html#ApiLevelOptions">Using Single APK
+Instead</a> section of the multiple APK developer guide includes some useful information on how to
+accomplish this with a single APK, including how to <a
+href="{@docRoot}guide/market/publishing/multiple-apks.html#TextureOptions">detect supported texture
+formats at runtime</a>. Depending on your situation, it might be easier to bundle all formats with
+your application, and simply pick which one to use at runtime.</p>
+
+<p>If you can manage it, confining your application to a single APK has several advantages,
+including:</p>
+<ul>
+<li>Publishing and Testing are easier</li>
+<li>There’s only one codebase to maintain</li>
+<li>Your application can adapt to device configuration changes</li>
+<li>App restore across devices just works</li>
+<li>You don’t have to worry about market preference, behavior from "upgrades" from one APK to the
+next, or which APK goes with which class of devices</li>
+</ul>
+
+<p>The rest of this lesson assumes that you’ve researched the topic, studiously absorbed the
+material in the resources linked, and determined that multiple APKs are the right path for your
+application.</p>
+
+
+<h2 id="ChartReqs">Chart Your Requirements</h2>
+
+<p>The Android Developer Guide provides a handy reference of some of common supported textures on
+the <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">supports-gl-texture
+page</a>. This page also contains some hints as to which phones (or families of phones) support
+particular texture formats. Note that it’s generally a good idea for one of your APKs to support
+ETC1, as that texture format is supported by all Android-powered devices that support the OpenGL ES
+2.0 spec.</p>
+
+<p>Since most Android-powered devices support more than one texture format, you need to establish an
+order of preference. Create a chart including all the formats that your application is going to
+support. The left-most cell is going to be the lowest priority (It will probably be ETC1, a really
+solid default in terms of performance and compatibility). Then color in the chart such that each
+cell represents an APK.</p>
+<table cellpadding="10" cellspacing="0" border="1">
+ <tbody>
+ <tr>
+ <td class="blueCell">ETC1</td>
+ <td class="greenCell">ATI</td>
+ <td class="redCell">PowerVR</td>
+ </tr>
+ </tbody>
+</table>
+
+<p>
+Coloring in the chart does more than just make this guide less monochromatic - It also has a way of
+making intra-team communication easier- You can now simply refer to each APK as "blue", "green", or
+"red", instead of "The one that supports ETC1 texture formats", etc.</p>
+
+<h2 id="CreateLibrary">Put All Common Code and Resources in a Library Project</h2>
+<p>Whether you’re modifying an existing Android application or starting one from scratch, this is
+the first thing that you should do to the codebase, and by the far the most important. Everything
+that goes into the library project only needs to be updated once (think language-localized strings,
+color themes, bugs fixed in shared code), which improves your development time and reduces the
+likelihood of mistakes that could have been easily avoided.</p>
+
+<p class="note"><strong>Note:</strong> While the implementation details of how to create and
+include library projects are beyond the scope of this lesson, you can get up to speed quickly on
+their creation at the following links:</p>
+<ul>
+<li><a
+href="{@docRoot}guide/developing/projects/projects-eclipse.html#SettingUpLibraryProject">Setting up
+a library project (Eclipse)</a></li>
+<li><a
+href="{@docRoot}guide/developing/projects/projects-cmdline.html#SettingUpLibraryProject">Setting up
+a library project (Command line)</a></li>
+</ul>
+
+<p>If you’re converting an existing application to use multiple APK support,
+scour your codebase for every localized string file, list of values, theme
+colors, menu icons and layout that isn’t going to change across APKs, and put
+it all in the library project. Code that isn’t going to change much should
+also go in the library project. You’ll likely find yourself extending these
+classes to add a method or two from APK to APK.</p>
+
+<p>If, on the other hand, you’re creating the application from scratch, try as
+much as possible to write code in the library project <em>first</em>, then only move it down to an
+individual APK if necessary. This is much easier to manage in the long run than adding it to one,
+then another, then another, then months later trying to figure out whether this blob can be moved up
+to the library section without screwing anything up.</p>
+
+<h2 id="CreateAPKs">Create New APK Projects</h2>
+<p>There should be a separate Android project for each APK you’re going to release. For easy
+organization, place the library project and all related APK projects under the same parent folder.
+Also remember that each APK needs to have the same package name, although they don’t necessarily
+need to share the package name with the library. If you were to have 3 APKs following the scheme
+described earlier, your root directory might look like this:</p>
+
+<pre class="no-pretty-print classic">
+alexlucas:~/code/multi-apks-root$ ls
+foo-blue
+foo-green
+foo-lib
+foo-red
+</pre>
+
+
+<p>Once the projects are created, add the library project as a reference to each APK project. If
+possible, define your starting Activity in the library project, and extend that Activity in your APK
+project. Having a starting activity defined in the library project gives you a chance to put all
+your application initialization in one place, so that each individual APK doesn’t have to
+re-implement "universal" tasks like initializing Analytics, running licensing checks, and any other
+initialization procedures that don’t change much from APK to APK.</p>
+
+
+<h2 id="AdjustManifests">Adjust the Manifests</h2>
+<p>When a user downloads an application which uses multiple APKs through Android Market, the correct
+APK to use is chosen using some simple rules:</p>
+
+<ul>
+<li>The manifest has to show that particular APK is eligible</li>
+<li>Of the eligible APKs, highest version number wins</li>
+<li>If <em>any</em> of the texture formats listed in your APK are supported by the device on market,
+that device is considered eligible</li>
+</ul>
+
+<p>With regards to GL Textures, that last rule is important. It means that you should, for
+instance, be <em>very</em> careful about using different GL formats in the same application. If you
+were to use PowerVR 99% of the time, but use ETC1 for, say, your splash screen... Then your manifest
+would necessarily indicate support for both formats. A device that <em>only</em> supported ETC1
+would be deemed compatible, your app would download, and the user would see some thrilling crash
+messages. The common case is going to be that if you’re using multiple APKs specifically to target
+different devices based on GL texture support, it’s going to be one texture format per APK.</p>
+
+<p>This actually makes texture support a little bit different than the other two multiple APK
+dimensions, API level and screen size. Any given device only has one API level, and one screen
+size, and it’s up to the APK to support a range of them. With textures, the APK will generally
+support one texture, and the device will support many. There will often be overlap in terms of one
+device supporting many APKs, but the solution is the same: Version codes.</p>
+
+<p>By way of example, take a few devices, and see how many of the APKs defined earlier fit each
+device.</p>
+<table cellpadding="10" cellspacing="0" border="1">
+ <tbody>
+ <tr>
+ <td>FooPhone</td>
+ <td>Nexus S</td>
+ <td>Evo</td>
+ </tr>
+ <tr>
+ <td class="blueCell">ETC1</td>
+ <td class="blueCell">ETC1</td>
+ <td class="blueCell">ETC1</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td class="greenCell">PowerVR</td>
+ <td class="redCell">ATI TC</td>
+ </tr>
+ </tbody>
+</table>
+<p> Assuming that PowerVR and ATI formats are both preferred over ETC1 when available, than
+according to the "highest version number wins" rule, if we set the versionCode attribute in each APK
+such that red ≥ green ≥ blue, then both Red and Green will always be chosen over Blue on
+devices which support them, and should a device ever come along which supports both Red and Green,
+red will be chosen.
+</p>
+
+<p> In order to keep all your APKs on separate "tracks," it’s important to have a good version code
+scheme. The recommended one can be found on the Version Codes area of our developer guide. Since
+the example set of APKs is only dealing with one of 3 possible dimensions, it would be sufficient to
+separate each APK by 1000 and increment from there. This might look like:</p>
+
+<p>Blue: 1001, 1002, 1003, 1004...<br />
+Green: 2001, 2002, 2003, 2004...<br />
+Red:3001, 3002, 3003, 3004...</p>
+
+<p> Putting this all together, your Android Manifests would likely look something like the
+following:</p>
+<p>Blue:</p>
+<pre>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ android:versionCode="1001" android:versionName="1.0" package="com.example.foo">
+ <supports-gl-texture android:name="GL_OES_compressed_ETC1_RGB8_texture" />
+ ...
+</pre>
+
+<p>Green:</p>
+<pre>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ android:versionCode="2001" android:versionName="1.0" package="com.example.foo">
+ <supports-gl-texture android:name="GL_AMD_compressed_ATC_texture" />
+ ...
+</pre>
+
+<p>Red:</p>
+<pre>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ android:versionCode="3001" android:versionName="1.0" package="com.example.foo">
+ <supports-gl-texture android:name="GL_IMG_texture_compression_pvrtc" />
+ ...
+</pre>
+
+<h2 id="PreLaunch">Go Over Pre-launch Checklist</h2>
+<p>Before uploading to Android Market, double-check the following items. Remember that these are
+specifically relevant to multiple APKs, and in no way represent a complete checklist for all
+applications being uploaded to Android Market.</p>
+
+<ul>
+<li>All APKs must have the same package name</li>
+<li>All APKs must be signed with the same certificate</li>
+<li>Double check your manifest filters for conflicting information (an APK that only supports
+cupcake on XLARGE screens isn’t going to be seen by anybody)</li>
+<li>Each APK's manifest must be unique across at least one of supported screen, OpenGL texture, or
+platform version</li>
+<li>Try to test each APK on at least one device. Barring that, you have one of the most
+customizable device emulators in the business sitting on your development machine. Go nuts!</li>
+</ul>
+
+<p>It’s also worth inspecting the compiled APK before pushing to market, to make sure there aren’t
+any surprises that could hide your application in Market. This is actually quite simple using the
+"aapt" tool. Aapt (the Android Asset Packaging Tool) is part of the build process for creating and
+packaging your Android applications, and is also a very handy tool for inspecting them. </p>
+
+<pre class="no-pretty-print classic">
+>aapt dump badging
+package: name='com.example.hello' versionCode='1' versionName='1.0'
+sdkVersion:'11'
+uses-permission:'android.permission.SEND_SMS'
+application-label:'Hello'
+application-icon-120:'res/drawable-ldpi/icon.png'
+application-icon-160:'res/drawable-mdpi/icon.png'
+application-icon-240:'res/drawable-hdpi/icon.png'
+application: label='Hello' icon='res/drawable-mdpi/icon.png'
+launchable-activity: name='com.example.hello.HelloActivity' label='Hello' icon=''
+uses-feature:'android.hardware.telephony'
+uses-feature:'android.hardware.touchscreen'
+main
+supports-screens: 'xlarge'
+supports-any-density: 'true'
+locales: '--_--'
+densities: '120' '160' '240'
+</pre>
+
+<p>When you examine aapt output, be sure to check that you don’t have conflicting values for
+supports-screens and compatible-screens, and that you don’t have unintended "uses-feature" values
+that were added as a result of permissions you set in the manifest. In the example above, the APK
+will be invisible to most, if not all devices.</p>
+<p>Why? By adding the required permission SEND_SMS, the feature requirement of android.hardware.telephony was implicitly added. Since most (if not all) xlarge devices are tablets without telephony hardware in them, Market will filter out this APK in these cases, until future devices come along which are both large enough to report as xlarge screen size, and possess telephony hardware.
+</p>
+<p>Fortunately this is easily fixed by adding the following to your manifest:</p>
+<pre>
+<uses-feature android:name="android.hardware.telephony" android:required="false" />
+</pre>
+<p>Once you’ve completed the pre-launch checklist, upload your APKs to Android Market. It may take a bit for the application to show up when browsing Android Market, but when it does, perform one last check. Download the application onto any test devices you may have to make sure that the APKs are targeting the intended devices. Congratulations, you’re done!</p>
diff --git a/docs/html/training/multiscreen/adaptui.jd b/docs/html/training/multiscreen/adaptui.jd
new file mode 100644
index 0000000..34e9d7d
--- /dev/null
+++ b/docs/html/training/multiscreen/adaptui.jd
@@ -0,0 +1,258 @@
+page.title=Implementing Adaptative UI Flows
+parent.title=Designing for Multiple Screens
+parent.link=index.html
+
+trainingnavtop=true
+previous.title=Supporting Different Screen Densities
+previous.link=screendensities.html
+
+@jd:body
+
+
+<!-- This is the training bar -->
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>This lesson teaches you to</h2>
+
+<ol>
+ <li><a href="#TaskDetermineCurLayout">Determine the Current Layout</a></li>
+ <li><a href="#TaskReactToLayout">React According to Current Layout</a></li>
+ <li><a href="#TaskReuseFrag">Reuse Fragments in Other Activities</a></li>
+ <li><a href="#TaskHandleConfigChanges">Handle Screen Configuration Changes</a></li>
+</ol>
+
+<h2>You should also read</h2>
+
+<ul>
+ <li><a href="{@docRoot}guide/practices/tablets-and-handsets.html">Supporting Tablets and
+Handsets</a></li>
+</ul>
+
+<h2>Try it out</h2>
+
+<div class="download-box">
+<a href="http://developer.android.com/shareables/training/NewsReader.zip" class="button">Download
+ the sample app</a>
+<p class="filename">NewsReader.zip</p>
+</div>
+
+
+</div>
+</div>
+
+<p>Depending on the layout that your application is currently showing, the UI
+flow may be different. For example, if your application is in the dual-pane
+mode, clicking on an item on the left pane will simply display the content on
+the right pane; if it is in single-pane mode, the content should be displayed
+on its own (in a different activity).</p>
+
+
+<h2 id="TaskDetermineCurLayout">Determine the Current Layout</h2>
+
+<p>Since your implementation of each layout will be a little different, one of
+the first things you will probably have to do is determine what layout the user is currently
+viewing. For example, you might want to know whether the user is in "single
+pane" mode or "dual pane" mode. You can do that by querying if a given view
+exists and is visible:</p>
+
+<pre class="prettyprint">
+public class NewsReaderActivity extends FragmentActivity {
+ boolean mIsDualPane;
+
+ @Override
+ public void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.main_layout);
+
+ View articleView = findViewById(R.id.article);
+ mIsDualPane = articleView != null &&
+ articleView.getVisibility() == View.VISIBLE;
+ }
+}
+</pre>
+
+<p>Notice that this code queries whether the "article" pane is available or not,
+which is much more flexible than hard-coding a query for a specific layout.</p>
+
+<p>Another example of how you can adapt to the existence of different
+components is to check whether they are available before performing an operation on
+them. For example, in the News Reader sample app, there is a button that opens a
+menu, but that button only exists when running on versions older than Android 3.0 (because it's
+function is taken over by the {@link android.app.ActionBar} on API level 11+). So, to add the event
+listener for this button, you can do:</p>
+
+<pre class="prettyprint">
+Button catButton = (Button) findViewById(R.id.categorybutton);
+OnClickListener listener = /* create your listener here */;
+if (catButton != null) {
+ catButton.setOnClickListener(listener);
+}
+</pre>
+
+
+<h2 id="TaskReactToLayout">React According to Current Layout</h2>
+
+<p>Some actions may have a different result depending on the current layout.
+For example, in the News Reader sample, clicking on a headline from the
+headlines list opens the article in the right hand-side pane if the UI
+is in dual pane mode, but will launch a separate activity if the UI is in
+single-pane mode:</p>
+
+<pre>
+@Override
+public void onHeadlineSelected(int index) {
+ mArtIndex = index;
+ if (mIsDualPane) {
+ /* display article on the right pane */
+ mArticleFragment.displayArticle(mCurrentCat.getArticle(index));
+ } else {
+ /* start a separate activity */
+ Intent intent = new Intent(this, ArticleActivity.class);
+ intent.putExtra("catIndex", mCatIndex);
+ intent.putExtra("artIndex", index);
+ startActivity(intent);
+ }
+}
+</pre>
+
+<p>Likewise, if the app is in dual-pane mode, it should set up the action bar
+with tabs for navigation, whereas if the app is in single-pane mode, it should set
+up navigation with a spinner widget. So your code should also check which case is
+appropriate:</p>
+
+<pre>
+final String CATEGORIES[] = { "Top Stories", "Politics", "Economy", "Technology" };
+
+public void onCreate(Bundle savedInstanceState) {
+ ....
+ if (mIsDualPane) {
+ /* use tabs for navigation */
+ actionBar.setNavigationMode(android.app.ActionBar.NAVIGATION_MODE_TABS);
+ int i;
+ for (i = 0; i < CATEGORIES.length; i++) {
+ actionBar.addTab(actionBar.newTab().setText(
+ CATEGORIES[i]).setTabListener(handler));
+ }
+ actionBar.setSelectedNavigationItem(selTab);
+ }
+ else {
+ /* use list navigation (spinner) */
+ actionBar.setNavigationMode(android.app.ActionBar.NAVIGATION_MODE_LIST);
+ SpinnerAdapter adap = new ArrayAdapter<String>(this,
+ R.layout.headline_item, CATEGORIES);
+ actionBar.setListNavigationCallbacks(adap, handler);
+ }
+}
+</pre>
+
+
+<h2 id="TaskReuseFrag">Reuse Fragments in Other Activities</h2>
+
+<p>A recurring pattern in designing for multiple screens is having a portion of
+your interface that's implemented as a pane on some screen configurations and
+as a separate activity on other configurations. For example, in the News Reader
+sample, the news article text is presented in the right side pane on
+large screens, but is a separate activity on smaller screens.</p>
+
+<p>In cases like this, you can usually avoid code duplication by reusing the
+same {@link android.app.Fragment} subclass in several activities. For example,
+<code>ArticleFragment</code>
+is used in the dual-pane layout:</p>
+
+{@sample development/samples/training/multiscreen/newsreader/res/layout/twopanes.xml all}
+
+<p>And reused (without a layout) in the activity layout for smaller screens
+(<code>ArticleActivity</code>):</p>
+
+<pre>
+ArticleFragment frag = new ArticleFragment();
+getSupportFragmentManager().beginTransaction().add(android.R.id.content, frag).commit();
+</pre>
+
+<p>Naturally, this has the same effect as declaring the fragment in an XML
+layout, but in this case an XML layout is unnecessary work because the article fragment
+is the only component of this activity.</p>
+
+<p>One very important point to keep in mind when designing your fragments is
+to not create a strong coupling to a specific activity. You can usually do that
+by defining an interface that abstracts all the ways in which the fragment
+needs to interact with its host activity, and then the host activity
+implements that interface:</p>
+
+<p>For example, the News Reader app's <code>HeadlinesFragment</code> does precisely that:</p>
+
+<pre>
+public class HeadlinesFragment extends ListFragment {
+ ...
+ OnHeadlineSelectedListener mHeadlineSelectedListener = null;
+
+ /* Must be implemented by host activity */
+ public interface OnHeadlineSelectedListener {
+ public void onHeadlineSelected(int index);
+ }
+ ...
+
+ public void setOnHeadlineSelectedListener(OnHeadlineSelectedListener listener) {
+ mHeadlineSelectedListener = listener;
+ }
+}
+</pre>
+
+<p>Then, when the user selects a headline, the fragment notifies the listener specified by the host
+activity (as opposed to notifying a specific hard-coded activity):</p>
+
+<pre>
+public class HeadlinesFragment extends ListFragment {
+ ...
+ @Override
+ public void onItemClick(AdapterView<?> parent,
+ View view, int position, long id) {
+ if (null != mHeadlineSelectedListener) {
+ mHeadlineSelectedListener.onHeadlineSelected(position);
+ }
+ }
+ ...
+}
+</pre>
+
+<p>This technique is discussed further in the guide to <a
+href="{@docRoot}guide/practices/tablets-and-handsets.html">Supporting Tablets and Handsets</a>.</p>
+
+
+<h2 id="TaskHandleConfigChanges">Handle Screen Configuration Changes</h2>
+
+<p>If you are using separate activities to implement separate parts of your interface,
+you have to keep in mind that it may be necessary to react to certain
+configuration changes (such as a rotation change) in order to keep your
+interface consistent.</p>
+
+<p>For example, on a typical 7" tablet running Android 3.0 or higher, the News Reader sample uses a
+separate activity to display the news article when running in portrait mode,
+but uses a two-pane layout when in landscape mode.</p>
+
+<p>This means that when the user is in portrait mode and the activity for viewing an article is
+onscreen, you need to detect that the orientation changed to landscape and
+react appropriately by ending the activity and return to the main activity so the content can
+display in the two-pane layout:</p>
+
+<pre>
+public class ArticleActivity extends FragmentActivity {
+ int mCatIndex, mArtIndex;
+
+ @Override
+ protected void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ mCatIndex = getIntent().getExtras().getInt("catIndex", 0);
+ mArtIndex = getIntent().getExtras().getInt("artIndex", 0);
+
+ // If should be in two-pane mode, finish to return to main activity
+ if (getResources().getBoolean(R.bool.has_two_panes)) {
+ finish();
+ return;
+ }
+ ...
+}
+</pre>
+
+
diff --git a/docs/html/training/multiscreen/index.jd b/docs/html/training/multiscreen/index.jd
new file mode 100644
index 0000000..a986cef
--- /dev/null
+++ b/docs/html/training/multiscreen/index.jd
@@ -0,0 +1,87 @@
+page.title=Designing for Multiple Screens
+
+trainingnavtop=true
+startpage=true
+next.title=Supporting Different Screen Sizes
+next.link=screensizes.html
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>Dependencies and prerequisites</h2>
+
+<ul>
+ <li>Android 1.6 or higher (2.1+ for the sample app)</li>
+ <li>Basic knowledge of <a
+href="http://developer.android.com/guide/topics/fundamentals/activities.html">Activities</a> and
+<a href="http://developer.android.com/guide/topics/fundamentals/fragments.html">Fragments</a></li>
+ <li>Experience building an Android <a
+href="http://developer.android.com/guide/topics/ui/index.html"> User Interface</a></li>
+ <li>Several features require the use of the <a
+href="{@docRoot}sdk/compatibility-library.html">support library</a></li>
+</ul>
+
+<h2>You should also read</h2>
+
+<ul>
+ <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li>
+</ul>
+
+<h2>Try it out</h2>
+
+<div class="download-box">
+<a href="http://developer.android.com/shareables/training/NewsReader.zip" class="button">Download
+ the sample app</a>
+<p class="filename">NewsReader.zip</p>
+</div>
+
+</div>
+</div>
+
+<p>Android powers hundreds of device types with several different screen sizes,
+ranging from small phones to large TV sets. Therefore, it’s important
+that you design your application to be compatible with all screen sizes so it’s available to as many
+users as possible.</p>
+
+<p>But being compatible with different device types is not enough. Each screen
+size offers different possibilities and challenges for user interaction, so in
+order to truly satisfy and impress your users, your application must go beyond merely
+<em>supporting</em> multiple screens: it must <em>optimize</em> the user
+experience for each screen configuration.</p>
+
+<p>This class shows you how to implement a user interface that's
+optimized for several screen configurations.</p>
+
+<p>The code in each lesson comes from a sample application that demonstrates best practices in
+optimizing for multiple screens. You can download the sample (to the right) and use it as a source
+of reusable code for your own application.</p>
+
+<p class="note"><strong>Note:</strong> This class and the associated sample use the <a
+href="{@docRoot}sdk/compatibility-library.html">support library</a> in order to use the {@link
+android.app.Fragment} APIs on versions lower than Android 3.0. You must download and add the
+library to your application in order to use all APIs in this class.</p>
+
+
+<h2>Lessons</h2>
+
+<dl>
+ <dt><b><a href="screensizes.html">Supporting Different Screen Sizes</a></b></dt>
+ <dd>This lesson walks you through how to design layouts that adapts
+ several different screen sizes (using flexible dimensions for
+ views, {@link android.widget.RelativeLayout}, screen size and orientation qualifiers,
+ alias filters, and nine-patch bitmaps).</dd>
+
+ <dt><b><a href="screendensities.html">Supporting Different Screen
+ Densities</a></b></dt>
+ <dd>This lesson shows you how to support screens that have different
+ pixel densities (using density-independent pixels and providing
+ bitmaps appropriate for each density).</dd>
+
+ <dt><b><a href="adaptui.html">Implementing Adaptative UI Flows</a></b></dt>
+ <dd>This lesson shows you how to implement your UI flow in a way
+ that adapts to several screen size/density combinations
+ (run-time detection of active layout, reacting according to
+ current layout, handling screen configuration changes).</dd>
+</dl>
diff --git a/docs/html/training/multiscreen/screendensities.jd b/docs/html/training/multiscreen/screendensities.jd
new file mode 100644
index 0000000..7d6ff44
--- /dev/null
+++ b/docs/html/training/multiscreen/screendensities.jd
@@ -0,0 +1,127 @@
+page.title=Supporting Different Densities
+parent.title=Designing for Multiple Screens
+parent.link=index.html
+
+trainingnavtop=true
+previous.title=Supporting Different Screen Sizes
+previous.link=screensizes.html
+next.title=Implementing Adaptative UI Flows
+next.link=adaptui.html
+
+@jd:body
+
+
+<!-- This is the training bar -->
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#TaskUseDP">Use Density-independent Pixels</a></li>
+ <li><a href="#TaskProvideAltBmp">Provide Alternative Bitmaps</a></li>
+</ol>
+
+<h2>You should also read</h2>
+
+<ul>
+ <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li>
+ <li><a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design
+Guidelines</a></li>
+</ul>
+
+<h2>Try it out</h2>
+
+<div class="download-box">
+<a href="http://developer.android.com/shareables/training/NewsReader.zip" class="button">Download
+ the sample app</a>
+<p class="filename">NewsReader.zip</p>
+</div>
+
+
+</div>
+</div>
+
+<p>This lesson shows you how to support different screen densities
+by providing different resources and using resolution-independent units of
+measurements.</p>
+
+<h2 id="TaskUseDP">Use Density-independent Pixels</h2>
+
+<p>One common pitfall you must avoid when designing your layouts is using
+absolute pixels to define distances or sizes. Defining layout dimensions with
+pixels is a problem because different screens have different pixel densities,
+so the same number of pixels may correspond to different physical sizes on
+different devices. Therefore, when specifying dimensions, always use either
+<code>dp</code> or <code>sp</code> units. A <code>dp</code> is a density-independent pixel
+that corresponds to the physical size of a pixel at 160 dpi. An <code>sp</code> is the same
+base unit, but is scaled by the user's preferred text size (it’s a
+scale-independent pixel), so you should use this measurement unit when defining
+text size (but never for layout sizes).</p>
+
+<p>For example, when you specify spacing between two views, use <code>dp</code>
+rather than <code>px</code>:</p>
+
+<pre>
+<Button android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:text="@string/clickme"
+ android:layout_marginTop="20dp" />
+</pre>
+
+<p>When specifying text size, always use <code>sp</code>:</p>
+
+<pre>
+<TextView android:layout_width="match_parent"
+ android:layout_height="wrap_content"
+ android:textSize="20sp" />
+</pre>
+
+
+<h2 id="TaskProvideAltBmp">Provide Alternative Bitmaps</h2>
+
+<p>Since Android runs in devices with a wide variety of screen densities,
+you should always provide your bitmap resources tailored to each of
+the generalized density buckets: low, medium, high and extra-high density.
+This will help you achieve good graphical quality and performance on all
+screen densities.</p>
+
+<p>To generate these images, you should start with your raw resource in
+vector format and generate the images for each density using the following
+size scale:</p>
+
+<p><ul>
+ <li><code>xhdpi</code>: 2.0
+ <li><code>hdpi</code>: 1.5
+ <li><code>mdpi</code>: 1.0 (baseline)
+ <li><code>ldpi</code>: 0.75
+</ul></p>
+
+<p>This means that if you generate a 200x200 image for <code>xhdpi</code>
+devices, you should generate the same resource in 150x150 for <code>hdpi</code>,
+100x100 for <code>mdpi</code> and finally a 75x75 image for <code>ldpi</code>
+devices.</p>
+
+<p>Then, place the generated image files in the appropriate subdirectory
+under <code>res/</code> and the system will pick the correct one automatically
+based on the screen density of the device your application is running on:</p>
+
+<pre class="classic no-pretty-print">
+MyProject/
+ res/
+ drawable-xhdpi/
+ awesomeimage.png
+ drawable-hdpi/
+ awesomeimage.png
+ drawable-mdpi/
+ awesomeimage.png
+ drawable-ldpi/
+ awesomeimage.png
+</pre>
+
+<p>Then, any time you reference <code>@drawable/awesomeimage</code>, the system selects the
+appropriate bitmap based on the screen's dpi.</p>
+
+<p>For more tips and guidelines for creating icon assets for your application, see the <a
+href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design
+Guidelines</a>.</p>
+
diff --git a/docs/html/training/multiscreen/screensizes.jd b/docs/html/training/multiscreen/screensizes.jd
new file mode 100644
index 0000000..2db0b67
--- /dev/null
+++ b/docs/html/training/multiscreen/screensizes.jd
@@ -0,0 +1,376 @@
+page.title=Supporting Different Screen Sizes
+parent.title=Designing for Multiple Screens
+parent.link=index.html
+
+trainingnavtop=true
+next.title=Supporting Different Screen Densities
+next.link=screendensities.html
+
+@jd:body
+
+
+<!-- This is the training bar -->
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#TaskUseWrapMatchPar">Use "wrap_content" and "match_parent"</a></li>
+ <li><a href="#TaskUseRelativeLayout">Use RelativeLayout</a></li>
+ <li><a href="#TaskUseSizeQuali">Use Size Qualifiers</a></li>
+ <li><a href="#TaskUseSWQuali">Use the Smallest-width Qualifier</a></li>
+ <li><a href="#TaskUseAliasFilters">Use Layout Aliases</a></li>
+ <li><a href="#TaskUseOriQuali">Use Orientation Qualifiers</a></li>
+ <li><a href="#TaskUse9Patch">Use Nine-patch Bitmaps</a></li>
+</ol>
+
+<h2>You should also read</h2>
+
+<ul>
+ <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li>
+</ul>
+
+<h2>Try it out</h2>
+
+<div class="download-box">
+<a href="http://developer.android.com/shareables/training/NewsReader.zip" class="button">Download
+ the sample app</a>
+<p class="filename">NewsReader.zip</p>
+</div>
+
+</div>
+</div>
+
+<p>This lesson shows you how to support different screen sizes by:</p>
+<ul>
+ <li>Ensuring your layout can be adequately resized to fit the screen</li>
+ <li>Providing appropriate UI layout according to screen configuration</li>
+ <li>Ensuring the correct layout is applied to the correct screen</li>
+ <li>Providing bitmaps that scale correctly</li>
+</ul>
+
+
+<h2 id="TaskUseWrapMatchPar">Use "wrap_content" and "match_parent"</h2>
+
+<p>To ensure that your layout is flexible and adapts to different screen sizes,
+you should use <code>"wrap_content"</code> and <code>"match_parent"</code> for the width
+and height of some view components. If you use <code>"wrap_content"</code>, the width
+or height of the view is set to the minimum size necessary to fit the content
+within that view, while <code>"match_parent"</code> (also known as
+<code>"fill_parent"</code> before API level 8) makes the component expand to match the size of its
+parent view.</p>
+
+<p>By using the <code>"wrap_content"</code> and <code>"match_parent"</code> size values instead of
+hard-coded sizes, your views either use only the space required for that
+view or expand to fill the available space, respectively. For example:</p>
+
+{@sample development/samples/training/multiscreen/newsreader/res/layout/onepane_with_bar.xml all}
+
+<p>Notice how the sample uses <code>"wrap_content"</code> and <code>"match_parent"</code>
+for component sizes rather than specific dimensions. This allows the layout
+to adapt correctly to different screen sizes and orientations.</p>
+
+<p>For example, this is what this layout looks like in portrait and landscape
+mode. Notice that the sizes of the components adapt automatically to the
+width and height:</p>
+
+<img src="{@docRoot}images/training/layout-hvga.png" />
+<p class="img-caption"><strong>Figure 1.</strong> The News Reader sample app in portrait (left)
+and landscape (right).</p>
+
+
+<h2 id="TaskUseRelativeLayout">Use RelativeLayout</h2>
+
+<p>You can construct fairly complex layouts using nested instances of {@link
+android.widget.LinearLayout} and
+combinations of <code>"wrap_content"</code> and <code>"match_parent"</code> sizes.
+However, {@link android.widget.LinearLayout} does not allow you to precisely control the
+spacial relationships of child views; views in a {@link android.widget.LinearLayout} simply line up
+side-by-side. If you need child views to be oriented in variations other than a straight line, a
+better solution is often to use a {@link android.widget.RelativeLayout}, which allows
+you to specify your layout in terms of the spacial relationships between
+components. For instance, you can align one child view on the left side and another view on
+the right side of the screen.</p>
+
+<p>For example:</p>
+
+<pre>
+<?xml version="1.0" encoding="utf-8"?>
+<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
+ android:layout_width="match_parent"
+ android:layout_height="match_parent">
+ <TextView
+ android:id="@+id/label"
+ android:layout_width="match_parent"
+ android:layout_height="wrap_content"
+ android:text="Type here:"/>
+ <EditText
+ android:id="@+id/entry"
+ android:layout_width="match_parent"
+ android:layout_height="wrap_content"
+ android:layout_below="@id/label"/>
+ <Button
+ android:id="@+id/ok"
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:layout_below="@id/entry"
+ android:layout_alignParentRight="true"
+ android:layout_marginLeft="10dp"
+ android:text="OK" />
+ <Button
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:layout_toLeftOf="@id/ok"
+ android:layout_alignTop="@id/ok"
+ android:text="Cancel" />
+</RelativeLayout>
+</pre>
+
+<p>Figure 2 shows how this layout appears on a QVGA screen.</p>
+
+<img src="{@docRoot}images/training/relativelayout1.png" />
+<p class="img-caption"><strong>Figure 2.</strong> Screenshot on a QVGA screen (small screen).</p>
+
+<p>Figure 3 shows how it appears on a larger screen.</p>
+
+<img src="{@docRoot}images/training/relativelayout2.png" />
+<p class="img-caption"><strong>Figure 3.</strong> Screenshot on a WSVGA screen (large screen).</p>
+
+<p>Notice that although the size of the components changed, their
+spatial relationships are preserved as specified by the {@link
+android.widget.RelativeLayout.LayoutParams}.</p>
+
+
+<h2 id="TaskUseSizeQuali">Use Size Qualifiers</h2>
+
+<p>There's only so much mileage you can get from a flexible layout or relative layout
+like the one in the previous sections. While those layouts adapt to
+different screens by stretching the space within and around components, they
+may not provide the best user experience for each screen size. Therefore, your
+application should not only implement flexible layouts, but should also provide
+several alternative layouts to target different screen configurations. You do
+so by using <a href="http://developer.android.com/guide/practices/screens_support.html#qualifiers">configuration qualifiers</a>, which allows the runtime
+to automatically select the appropriate resource based on the current device’s
+configuration (such as a different layout design for different screen sizes).</p>
+
+<p>For example, many applications implement the "two pane" pattern for large
+screens (the app might show a list of items on one pane and the content on
+another pane). Tablets and TVs are large enough for both panes to fit
+simultaneously on screen, but phone screens have to show them separately. So,
+to implement these layouts, you could have the following files:</p>
+
+<ul>
+ <li><code>res/layout/main.xml</code>, single-pane (default) layout:
+
+{@sample development/samples/training/multiscreen/newsreader/res/layout/onepane.xml all}
+</li>
+ <li><code>res/layout-xlarge/main.xml</code>, two-pane layout:
+
+{@sample development/samples/training/multiscreen/newsreader/res/layout/twopanes.xml all}
+</li>
+</ul>
+
+<p>Notice the <code>xlarge</code> qualifier in the directory name of the second layout. This layout
+will be selected on devices with screens classified as extra-large (for example, 10" tablets). The
+other layout (without qualifiers) will be selected for smaller devices.</p>
+
+
+<h2 id="TaskUseSWQuali">Use the Smallest-width Qualifier</h2>
+
+<p>One of the difficulties developers had in pre-3.2 Android devices was the
+"large" screen size bin, which encompasses the Dell Streak, the original Galaxy
+Tab, and 7" tablets in general. However, many applications may want to show
+different layouts for different devices in this category (such as for 5" and 7" devices), even
+though they are all considered to be "large" screens. That's why Android introduced the
+"Smallest-width" qualifier (amongst others) in Android 3.2.</p>
+
+<p>The Smallest-width qualifier allows you to target screens that have a certain minimum
+width given in dp. For example, the typical 7" tablet has a minimum width of
+600 dp, so if you want your UI to have two panes on those screens (but a single
+list on smaller screens), you can use the same two layouts from the previous section for single
+and two-pane layouts, but instead of the <code>xlarge</code> size qualifier, use
+<code>sw600dp</code> to indicate the two-pane layout is for screens on which the smallest-width
+is 600 dp:</p>
+
+<ul>
+ <li><code>res/layout/main.xml</code>, single-pane (default) layout:
+
+{@sample development/samples/training/multiscreen/newsreader/res/layout/onepane.xml all}
+</li>
+ <li><code>res/layout-sw600dp/main.xml</code>, two-pane layout:
+
+{@sample development/samples/training/multiscreen/newsreader/res/layout/twopanes.xml all}
+</li>
+</ul>
+
+<p>This means that devices whose smallest width is greater than or equal to
+600dp will select the <code>layout-sw600dp/main.xml</code> (two-pane) layout,
+while smaller screens will select the <code>layout/main.xml</code> (single-pane)
+layout.</p>
+
+<p>However, this won't work well on pre-3.2 devices, because they don't
+recognize <code>sw600dp</code> as a size qualifier, so you still have to use the <code>xlarge</code>
+qualifier as well. So, you should have a file named
+<code>res/layout-xlarge/main.xml</code>
+which is identical to <code>res/layout-sw600dp/main.xml</code>. In the next section
+you'll see a technique that allows you to avoid duplicating the layout files this way.</p>
+
+
+<h2 id="TaskUseAliasFilters">Use Layout Aliases</h2>
+
+<p>The smallest-width qualifier is available only on Android 3.2 and above.
+Therefore, you should also still use the abstract size bins (small, normal,
+large and xlarge) to be compatible with earlier versions. For example, if you
+want to design your UI so that it shows a single-pane UI on phones but a
+multi-pane UI on 7" tablets and larger devices, you'd have to supply these
+files:</p>
+
+<p><ul>
+<li><code>res/layout/main.xml:</code> single-pane layout</li>
+<li><code>res/layout-xlarge:</code> multi-pane layout</li>
+<li><code>res/layout-sw600dp:</code> multi-pane layout</li>
+</ul></p>
+
+<p>The last two files are identical, because one of them will be matched by
+Android 3.2 devices, and the other one is for the benefit of tablets with
+earlier versions of Android.</p>
+
+<p>To avoid this duplication of the same file for tablets (and the maintenance
+headache resulting from it), you can use alias files. For example, you can define the following
+layouts:</p>
+
+<ul>
+<li><code>res/layout/main.xml</code>, single-pane layout</li>
+<li><code>res/layout/main_twopanes.xml</code>, two-pane layout</li>
+</ul>
+
+<p>And add these two files:</p>
+
+<p><ul>
+<li><code>res/values-xlarge/layout.xml</code>:
+<pre>
+<resources>
+ <item name="main" type="layout">@layout/main_twopanes</item>
+</resources>
+</pre>
+</li>
+
+<li><code>res/values-sw600dp/layout.xml</code>:
+<pre>
+<resources>
+ <item name="main" type="layout">@layout/main_twopanes</item>
+</resources>
+</pre>
+
+</li>
+</ul></p>
+
+<p>These latter two files have identical content, but they don’t actually define
+the layout. They merely set up {@code main} to be an alias to {@code main_twopanes}. Since
+these files have <code>xlarge</code> and <code>sw600dp</code> selectors, they are
+applied to tablets regardless of Android version (pre-3.2 tablets match
+{@code xlarge}, and post-3.2 will match <code>sw600dp</code>).</p>
+
+
+<h2 id="TaskUseOriQuali">Use Orientation Qualifiers</h2>
+
+<p>Some layouts work well in both landscape and portrait orientations, but most of them can
+benefit from adjustments. In the News Reader sample app, here is how the layout
+behaves in each screen size and orientation:</p>
+
+<p><ul>
+<li><b>small screen, portrait:</b> single pane, with logo</li>
+<li><b>small screen, landscape:</b> single pane, with logo</li>
+<li><b>7" tablet, portrait:</b> single pane, with action bar</li>
+<li><b>7" tablet, landscape:</b> dual pane, wide, with action bar</li>
+<li><b>10" tablet, portrait:</b> dual pane, narrow, with action bar</li>
+<li><b>10" tablet, landscape:</b> dual pane, wide, with action bar</li>
+</ul></p>
+
+<p>So each of these layouts is defined in an XML file in the
+<code>res/layout/</code> directory. To then assign each layout to the various screen
+configurations, the app uses layout aliases to match them to
+each configuration:</p>
+
+<p><code>res/layout/onepane.xml:</code></p>
+{@sample development/samples/training/multiscreen/newsreader/res/layout/onepane.xml all}
+
+<p><code>res/layout/onepane_with_bar.xml:</code></p>
+{@sample development/samples/training/multiscreen/newsreader/res/layout/onepane_with_bar.xml all}
+
+<p><code>res/layout/twopanes.xml</code>:</p>
+{@sample development/samples/training/multiscreen/newsreader/res/layout/twopanes.xml all}
+
+<p><code>res/layout/twopanes_narrow.xml</code>:</p>
+{@sample development/samples/training/multiscreen/newsreader/res/layout/twopanes_narrow.xml all}
+
+<p>Now that all possible layouts are defined, it's just a matter of mapping the correct layout to
+each configuration using the configuration qualifiers. You can now do it using the layout alias
+technique:</p>
+
+<p><code>res/values/layouts.xml</code>:</p>
+{@sample development/samples/training/multiscreen/newsreader/res/values/layouts.xml all}
+
+<p><code>res/values-sw600dp-land/layouts.xml</code>:</p>
+{@sample development/samples/training/multiscreen/newsreader/res/values-sw600dp-land/layouts.xml
+all}
+
+<p><code>res/values-sw600dp-port/layouts.xml</code>:</p>
+{@sample development/samples/training/multiscreen/newsreader/res/values-sw600dp-port/layouts.xml
+all}
+
+<p><code>res/values-xlarge-land/layouts.xml</code>:</p>
+{@sample development/samples/training/multiscreen/newsreader/res/values-xlarge-land/layouts.xml all}
+
+<p><code>res/values-xlarge-port/layouts.xml</code>:</p>
+{@sample development/samples/training/multiscreen/newsreader/res/values-xlarge-port/layouts.xml all}
+
+
+
+<h2 id="TaskUse9Patch">Use Nine-patch Bitmaps</h2>
+
+<p>Supporting different screen sizes usually means that your image resources
+must also be capable of adapting to different sizes. For example, a button
+background must fit whichever button shape it is applied to.</p>
+
+<p>If you use simple images on components that can change size, you will
+quickly notice that the results are somewhat less than impressive, since the
+runtime will stretch or shrink your images uniformly. The solution is using nine-patch bitmaps,
+which are specially
+formatted PNG files that indicate which areas can and cannot be stretched.</p>
+
+<p>Therefore, when designing bitmaps that will be used on components with
+variable size, always use nine-patches. To convert a bitmap into a nine-patch,
+you can start with a regular image (figure 4, shown with in 4x zoom for clarity).</p>
+
+<img src="{@docRoot}images/training/button.png" />
+<p class="img-caption"><strong>Figure 4.</strong> <code>button.png</code></p>
+
+<p>And then run it through the <ode
+href="{@docRoot}guide/developing/tools/draw9patch.html"><code>draw9patch</code></a> utility of the
+SDK (which is located in the <code>tools/</code> directory), in which you can mark the areas that
+should be stretched by drawing pixels along the left and top borders. You can also mark the area
+that should hold the content by drawing pixels along the right and bottom borders, resulting in
+figure 5.</p>
+
+<img src="{@docRoot}images/training/button_with_marks.png" />
+<p class="img-caption"><strong>Figure 5.</strong> <code>button.9.png</code></p>
+
+<p>Notice the black pixels along the borders. The ones on the top and left
+borders indicate the places where the image can be stretched, and the ones on
+the right and bottom borders indicate where the content should be
+placed.</p>
+
+<p>Also, notice the <code>.9.png</code> extension. You must use this
+extension, since this is how the framework detects that this is a nine-patch
+image, as opposed to a regular PNG image.</p>
+
+<p>When you apply this background to a component (by setting
+<code>android:background="@drawable/button"</code>), the framework stretches
+the image correctly to accommodate the size of the button, as shown in various sizes in figure
+6.</p>
+
+<img src="{@docRoot}images/training/buttons_stretched.png" />
+<p class="img-caption"><strong>Figure 6.</strong> A button using the <code>button.9.png</code>
+nine-patch in various sizes.</p>
+
diff --git a/media/libstagefright/rtsp/AAMRAssembler.cpp b/media/libstagefright/rtsp/AAMRAssembler.cpp
index b1f6e9a..328cadf 100644
--- a/media/libstagefright/rtsp/AAMRAssembler.cpp
+++ b/media/libstagefright/rtsp/AAMRAssembler.cpp
@@ -79,13 +79,17 @@
}
static size_t getFrameSize(bool isWide, unsigned FT) {
- static const size_t kFrameSizeNB[8] = {
- 95, 103, 118, 134, 148, 159, 204, 244
+ static const size_t kFrameSizeNB[9] = {
+ 95, 103, 118, 134, 148, 159, 204, 244, 39
};
- static const size_t kFrameSizeWB[9] = {
- 132, 177, 253, 285, 317, 365, 397, 461, 477
+ static const size_t kFrameSizeWB[10] = {
+ 132, 177, 253, 285, 317, 365, 397, 461, 477, 40
};
+ if (FT == 15) {
+ return 1;
+ }
+
size_t frameSize = isWide ? kFrameSizeWB[FT] : kFrameSizeNB[FT];
// Round up bits to bytes and add 1 for the header byte.
@@ -161,8 +165,8 @@
unsigned FT = (toc >> 3) & 0x0f;
if ((toc & 3) != 0
- || (mIsWide && FT > 8)
- || (!mIsWide && FT > 7)) {
+ || (mIsWide && FT > 9 && FT != 15)
+ || (!mIsWide && FT > 8 && FT != 15)) {
queue->erase(queue->begin());
++mNextExpectedSeqNo;
diff --git a/media/libstagefright/rtsp/ARTSPConnection.cpp b/media/libstagefright/rtsp/ARTSPConnection.cpp
index 4f0363b..380b3dc 100644
--- a/media/libstagefright/rtsp/ARTSPConnection.cpp
+++ b/media/libstagefright/rtsp/ARTSPConnection.cpp
@@ -659,6 +659,7 @@
}
AString line;
+ ssize_t lastDictIndex = -1;
for (;;) {
if (!receiveLine(&line)) {
break;
@@ -668,7 +669,21 @@
break;
}
- LOGV("line: %s", line.c_str());
+ LOGV("line: '%s'", line.c_str());
+
+ if (line.c_str()[0] == ' ' || line.c_str()[0] == '\t') {
+ // Support for folded header values.
+
+ if (lastDictIndex < 0) {
+ // First line cannot be a continuation of the previous one.
+ return false;
+ }
+
+ AString &value = response->mHeaders.editValueAt(lastDictIndex);
+ value.append(line);
+
+ continue;
+ }
ssize_t colonPos = line.find(":");
if (colonPos < 0) {
@@ -681,9 +696,12 @@
key.tolower();
line.erase(0, colonPos + 1);
- line.trim();
- response->mHeaders.add(key, line);
+ lastDictIndex = response->mHeaders.add(key, line);
+ }
+
+ for (size_t i = 0; i < response->mHeaders.size(); ++i) {
+ response->mHeaders.editValueAt(i).trim();
}
unsigned long contentLength = 0;
