Merge "Update documentation for speech APIs." into jb-mr2-docs
diff --git a/core/java/android/content/ComponentCallbacks.java b/core/java/android/content/ComponentCallbacks.java
index dad60b0..b96c8d3 100644
--- a/core/java/android/content/ComponentCallbacks.java
+++ b/core/java/android/content/ComponentCallbacks.java
@@ -22,6 +22,11 @@
* The set of callback APIs that are common to all application components
* ({@link android.app.Activity}, {@link android.app.Service},
* {@link ContentProvider}, and {@link android.app.Application}).
+ *
+ * <p class="note"><strong>Note:</strong> You should also implement the {@link
+ * ComponentCallbacks2} interface, which provides the {@link
+ * ComponentCallbacks2#onTrimMemory} callback to help your app manage its memory usage more
+ * effectively.</p>
*/
public interface ComponentCallbacks {
/**
@@ -29,26 +34,35 @@
* component is running. Note that, unlike activities, other components
* are never restarted when a configuration changes: they must always deal
* with the results of the change, such as by re-retrieving resources.
- *
+ *
* <p>At the time that this function has been called, your Resources
* object will have been updated to return resource values matching the
* new configuration.
- *
+ *
+ * <p>For more information, read <a href="{@docRoot}guide/topics/resources/runtime-changes.html"
+ * >Handling Runtime Changes</a>.
+ *
* @param newConfig The new device configuration.
*/
void onConfigurationChanged(Configuration newConfig);
-
+
/**
* This is called when the overall system is running low on memory, and
- * would like actively running process to try to tighten their belt. While
+ * actively running processes should trim their memory usage. While
* the exact point at which this will be called is not defined, generally
- * it will happen around the time all background process have been killed,
- * that is before reaching the point of killing processes hosting
+ * it will happen when all background process have been killed.
+ * That is, before reaching the point of killing processes hosting
* service and foreground UI that we would like to avoid killing.
- *
- * <p>Applications that want to be nice can implement this method to release
- * any caches or other unnecessary resources they may be holding on to.
- * The system will perform a gc for you after returning from this method.
+ *
+ * <p>You should implement this method to release
+ * any caches or other unnecessary resources you may be holding on to.
+ * The system will perform a garbage collection for you after returning from this method.
+ * <p>Preferably, you should implement {@link ComponentCallbacks2#onTrimMemory} from
+ * {@link ComponentCallbacks2} to incrementally unload your resources based on various
+ * levels of memory demands. That API is available for API level 14 and higher, so you should
+ * only use this {@link #onLowMemory} method as a fallback for older versions, which can be
+ * treated the same as {@link ComponentCallbacks2#onTrimMemory} with the {@link
+ * ComponentCallbacks2#TRIM_MEMORY_COMPLETE} level.</p>
*/
void onLowMemory();
}
diff --git a/core/java/android/content/ComponentCallbacks2.java b/core/java/android/content/ComponentCallbacks2.java
index a3b4e5e..b78548b 100644
--- a/core/java/android/content/ComponentCallbacks2.java
+++ b/core/java/android/content/ComponentCallbacks2.java
@@ -18,7 +18,68 @@
/**
* Extended {@link ComponentCallbacks} interface with a new callback for
- * finer-grained memory management.
+ * finer-grained memory management. This interface is available in all application components
+ * ({@link android.app.Activity}, {@link android.app.Service},
+ * {@link ContentProvider}, and {@link android.app.Application}).
+ *
+ * <p>You should implement {@link #onTrimMemory} to incrementally release memory based on current
+ * system constraints. Using this callback to release your resources helps provide a more
+ * responsive system overall, but also directly benefits the user experience for
+ * your app by allowing the system to keep your process alive longer. That is,
+ * if you <em>don't</em> trim your resources based on memory levels defined by this callback,
+ * the system is more likely to kill your process while it is cached in the least-recently used
+ * (LRU) list, thus requiring your app to restart and restore all state when the user returns to it.
+ *
+ * <p>The values provided by {@link #onTrimMemory} do not represent a single linear progression of
+ * memory limits, but provide you different types of clues about memory availability:</p>
+ * <ul>
+ * <li>When your app is running:
+ * <ol>
+ * <li>{@link #TRIM_MEMORY_RUNNING_MODERATE} <br>The device is beginning to run low on memory.
+ * Your app is running and not killable.
+ * <li>{@link #TRIM_MEMORY_RUNNING_LOW} <br>The device is running much lower on memory.
+ * Your app is running and not killable, but please release unused resources to improve system
+ * performance (which directly impacts your app's performance).
+ * <li>{@link #TRIM_MEMORY_RUNNING_CRITICAL} <br>The device is running extremely low on memory.
+ * Your app is not yet considered a killable process, but the system will begin killing
+ * background processes if apps do not release resources, so you should release non-critical
+ * resources now to prevent performance degradation.
+ * </ol>
+ * </li>
+ * <li>When your app's visibility changes:
+ * <ol>
+ * <li>{@link #TRIM_MEMORY_UI_HIDDEN} <br>Your app's UI is no longer visible, so this is a good
+ * time to release large resources that are used only by your UI.
+ * </ol>
+ * </li>
+ * <li>When your app's process resides in the background LRU list:
+ * <ol>
+ * <li>{@link #TRIM_MEMORY_BACKGROUND} <br>The system is running low on memory and your process is
+ * near the beginning of the LRU list. Although your app process is not at a high risk of being
+ * killed, the system may already be killing processes in the LRU list, so you should release
+ * resources that are easy to recover so your process will remain in the list and resume
+ * quickly when the user returns to your app.
+ * <li>{@link #TRIM_MEMORY_MODERATE} <br>The system is running low on memory and your process is
+ * near the middle of the LRU list. If the system becomes further constrained for memory, there's a
+ * chance your process will be killed.
+ * <li>{@link #TRIM_MEMORY_COMPLETE} <br>The system is running low on memory and your process is
+ * one of the first to be killed if the system does not recover memory now. You should release
+ * absolutely everything that's not critical to resuming your app state.
+ * <p>To support API levels lower than 14, you can use the {@link #onLowMemory} method as a
+ * fallback that's roughly equivalent to the {@link ComponentCallbacks2#TRIM_MEMORY_COMPLETE} level.
+ * </li>
+ * </ol>
+ * <p class="note"><strong>Note:</strong> When the system begins
+ * killing processes in the LRU list, although it primarily works bottom-up, it does give some
+ * consideration to which processes are consuming more memory and will thus provide more gains in
+ * memory if killed. So the less memory you consume while in the LRU list overall, the better
+ * your chances are to remain in the list and be able to quickly resume.</p>
+ * </li>
+ * </ul>
+ * <p>More information about the different stages of a process lifecycle (such as what it means
+ * to be placed in the background LRU list) is provided in the <a
+ * href="{@docRoot}guide/components/processes-and-threads.html#Lifecycle">Processes and Threads</a>
+ * document.
*/
public interface ComponentCallbacks2 extends ComponentCallbacks {
diff --git a/docs/html/guide/topics/manifest/uses-sdk-element.jd b/docs/html/guide/topics/manifest/uses-sdk-element.jd
index 18e479f..07b08f6 100644
--- a/docs/html/guide/topics/manifest/uses-sdk-element.jd
+++ b/docs/html/guide/topics/manifest/uses-sdk-element.jd
@@ -1,4 +1,4 @@
-fpage.title=<uses-sdk>
+page.title=<uses-sdk>
page.tags="api levels","sdk version","minsdkversion","targetsdkversion","maxsdkversion"
@jd:body
diff --git a/docs/html/samples/index.jd b/docs/html/samples/index.jd
index 028fbe9..3ea5245 100644
--- a/docs/html/samples/index.jd
+++ b/docs/html/samples/index.jd
@@ -1,77 +1,11 @@
page.title=Samples
-header.hide=1
@jd:body
-<style>
-div.landing-cell,
-div.cell-icon {
- height:150px;
-}
-div.cell-icon {
- float:left;
- margin-right:20px;
-}
-div.cell-icon img {
- margin:0;
-}
-</style>
-<div class="landing-banner">
-
-<div class="col-6" style="min-height:0">
- <img src="{@docRoot}images/google/google-services.png" alt="" width="340" height="193" />
-</div>
-<div class="col-6">
-
- <h1 itemprop="name" style="margin-bottom:0;">Samples</h1>
- <p itemprop="description">Some intro here. Overview of Samples, where to get them,
- links to related tools and SDK, and what's new in samples. </p>
-
-</div>
-</div>
-<div> </div>
-
-
-
-
-<div style="margin-top:10px">
-<div class="col-6 normal-links" style="margin-left:0">
-
-<div class="landing-cell">
- <div class="cell-icon">
- <img src="{@docRoot}images/google/maps-pin.png" width="40" >
- </div>
- <h4><a href="{@docRoot}google/play-services/maps.html"
- >Google Maps</a></h4>
- <p>The power of Google Maps is available to your app
- with an embeddable map view. You can customize the map with
- markers and overlays, control the user's perspective, draw lines
- and shapes, and much more.</p>
+<div id="samples">
+<p>Some kind of sample sorting will appear here.</p>
</div>
-</div><!-- col-6 -->
-
-
-
-<div class="col-6" style="margin-right:0">
-
-<div class="landing-cell">
- <div class="cell-icon">
- <img src="{@docRoot}images/google/iab-99c.png" width="40" />
- </div>
- <h4><a href="{@docRoot}google/play/billing/index.html"
- >Google Play In-App Billing</a></h4>
- <p>Build an app with a steady revenue stream that keeps users engaged
- by offering new content or virtual goods directly in your app. All transactions are handled
- by Google Play Store for a simple user experience.
- </p>
-</div>
-
-</div><!-- col-6 -->
-
-</div><!-- margin wrapper -->
-
-
-
-
+<script>
+</script>
diff --git a/docs/html/samples/topic.jd b/docs/html/samples/topic.jd
new file mode 100644
index 0000000..cac9b10
--- /dev/null
+++ b/docs/html/samples/topic.jd
@@ -0,0 +1,26 @@
+page.title=Samples
+@jd:body
+
+
+<div id="samples">
+</div>
+
+
+
+<script>
+ $(document).ready(showSamples);
+
+ /** Display links and other information about samples that match the
+ group specified by the URL */
+ function showSamples() {
+ var group = getGroup();
+ $("#body-content h1").html(group);
+ $("#samples").html("<p>OK, here are some samples about <b>" + group + "</b>.</p>");
+ }
+
+ /** Return the group provided by the URL */
+ function getGroup() {
+ var hashParts = location.hash.split('t=');
+ return hashParts[1];
+ }
+</script>