Update process importance documentation.
Also be more direct about some of the wallpaper APIs.
Change-Id: I2112898c0cd4415d6c5fd47923de682d59b8291f
diff --git a/core/java/android/app/ActivityManager.java b/core/java/android/app/ActivityManager.java
index 11b4c3a..7dce2d3 100644
--- a/core/java/android/app/ActivityManager.java
+++ b/core/java/android/app/ActivityManager.java
@@ -502,7 +502,16 @@
/**
* Return a list of the tasks that the user has recently launched, with
* the most recent being first and older ones after in order.
- *
+ *
+ * <p><b>Note: this method is only intended for debugging and presenting
+ * task management user interfaces</b>. This should never be used for
+ * core logic in an application, such as deciding between different
+ * behaviors based on the information found here. Such uses are
+ * <em>not</em> supported, and will likely break in the future. For
+ * example, if multiple applications can be actively running at the
+ * same time, assumptions made about the meaning of the data here for
+ * purposes of control flow will be incorrect.</p>
+ *
* @param maxNum The maximum number of entries to return in the list. The
* actual number returned may be smaller, depending on how many tasks the
* user has started and the maximum number the system can remember.
@@ -669,6 +678,15 @@
* can be restarted in its previous state when next brought to the
* foreground.
*
+ * <p><b>Note: this method is only intended for debugging and presenting
+ * task management user interfaces</b>. This should never be used for
+ * core logic in an application, such as deciding between different
+ * behaviors based on the information found here. Such uses are
+ * <em>not</em> supported, and will likely break in the future. For
+ * example, if multiple applications can be actively running at the
+ * same time, assumptions made about the meaning of the data here for
+ * purposes of control flow will be incorrect.</p>
+ *
* @param maxNum The maximum number of entries to return in the list. The
* actual number returned may be smaller, depending on how many tasks the
* user has started.
@@ -1016,7 +1034,10 @@
/**
* Return a list of the services that are currently running.
- *
+ *
+ * <p><b>Note: this method is only intended for debugging or implementing
+ * service management type user interfaces.</b></p>
+ *
* @param maxNum The maximum number of entries to return in the list. The
* actual number returned may be smaller, depending on how many services
* are running.
@@ -1128,6 +1149,16 @@
}
}
+ /**
+ * Return general information about the memory state of the system. This
+ * can be used to help decide how to manage your own memory, though note
+ * that polling is not recommended and
+ * {@link android.content.ComponentCallbacks2#onTrimMemory(int)
+ * ComponentCallbacks2.onTrimMemory(int)} is the preferred way to do this.
+ * Also see {@link #getMyMemoryState} for how to retrieve the current trim
+ * level of your process as needed, which gives a better hint for how to
+ * manage its memory.
+ */
public void getMemoryInfo(MemoryInfo outInfo) {
try {
ActivityManagerNative.getDefault().getMemoryInfo(outInfo);
@@ -1497,6 +1528,9 @@
* Returns a list of application processes installed on external media
* that are running on the device.
*
+ * <p><b>Note: this method is only intended for debugging or building
+ * a user-facing process management UI.</b></p>
+ *
* @return Returns a list of ApplicationInfo records, or null if none
* This list ordering is not specified.
* @hide
@@ -1511,7 +1545,10 @@
/**
* Returns a list of application processes that are running on the device.
- *
+ *
+ * <p><b>Note: this method is only intended for debugging or building
+ * a user-facing process management UI.</b></p>
+ *
* @return Returns a list of RunningAppProcessInfo records, or null if there are no
* running processes (it will not return an empty list). This list ordering is not
* specified.
@@ -1544,7 +1581,10 @@
/**
* Return information about the memory usage of one or more processes.
- *
+ *
+ * <p><b>Note: this method is only intended for debugging or building
+ * a user-facing process management UI.</b></p>
+ *
* @param pids The pids of the processes whose memory usage is to be
* retrieved.
* @return Returns an array of memory information, one for each
diff --git a/core/java/android/app/WallpaperManager.java b/core/java/android/app/WallpaperManager.java
index 6f19934..3824f44 100644
--- a/core/java/android/app/WallpaperManager.java
+++ b/core/java/android/app/WallpaperManager.java
@@ -637,6 +637,14 @@
* wallpaper it would like to use. This allows such applications to have
* a virtual wallpaper that is larger than the physical screen, matching
* the size of their workspace.
+ *
+ * <p>Note developers, who don't seem to be reading this. This is
+ * for <em>home screens</em> to tell what size wallpaper they would like.
+ * Nobody else should be calling this! Certainly not other non-home-screen
+ * apps that change the wallpaper. Those apps are supposed to
+ * <b>retrieve</b> the suggested size so they can construct a wallpaper
+ * that matches it.
+ *
* @param minimumWidth Desired minimum width
* @param minimumHeight Desired minimum height
*/
diff --git a/core/java/android/content/ComponentCallbacks2.java b/core/java/android/content/ComponentCallbacks2.java
index 85294dd..a3b4e5e 100644
--- a/core/java/android/content/ComponentCallbacks2.java
+++ b/core/java/android/content/ComponentCallbacks2.java
@@ -88,7 +88,11 @@
* should never compare to exact values of the level, since new intermediate
* values may be added -- you will typically want to compare if the value
* is greater or equal to a level you are interested in.
- *
+ *
+ * <p>To retrieve the processes current trim level at any point, you can
+ * use {@link android.app.ActivityManager#getMyMemoryState
+ * ActivityManager.getMyMemoryState(RunningAppProcessInfo)}.
+ *
* @param level The context of the trim, giving a hint of the amount of
* trimming the application may like to perform. May be
* {@link #TRIM_MEMORY_COMPLETE}, {@link #TRIM_MEMORY_MODERATE},
diff --git a/core/java/android/content/Intent.java b/core/java/android/content/Intent.java
index 6653336..d0d9bd6 100644
--- a/core/java/android/content/Intent.java
+++ b/core/java/android/content/Intent.java
@@ -1624,8 +1624,20 @@
/**
* Broadcast Action: The current system wallpaper has changed. See
* {@link android.app.WallpaperManager} for retrieving the new wallpaper.
+ * This should <em>only</em> be used to determine when the wallpaper
+ * has changed to show the new wallpaper to the user. You should certainly
+ * never, in response to this, change the wallpaper or other attributes of
+ * it such as the suggested size. That would be crazy, right? You'd cause
+ * all kinds of loops, especially if other apps are doing similar things,
+ * right? Of course. So please don't do this.
+ *
+ * @deprecated Modern applications should use
+ * {@link android.view.WindowManager.LayoutParams#FLAG_SHOW_WALLPAPER
+ * WindowManager.LayoutParams.FLAG_SHOW_WALLPAPER} to have the wallpaper
+ * shown behind their UI, rather than watching for this broadcast and
+ * rendering the wallpaper on their own.
*/
- @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
+ @Deprecated @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
public static final String ACTION_WALLPAPER_CHANGED = "android.intent.action.WALLPAPER_CHANGED";
/**
* Broadcast Action: The current device {@link android.content.res.Configuration}