Initial draft of high-level multi-display APIs.
This patch introduces the ability to create a Context that
is bound to a Display. The context gets its configuration and
metrics from that display and is able to provide a WindowManager
that is bound to the display.
To make it easier to use, we also add a new kind of Dialog
called a Presentation. Presentation takes care of setting
up the context as needed and watches for significant changes
in the display configuration. If the display is removed,
then the presentation simply dismisses itself.
Change-Id: Idc54b4ec84b1ff91505cfb78910cf8cd09696d7d
diff --git a/core/java/android/view/WindowManager.java b/core/java/android/view/WindowManager.java
index f30952c..7412f39 100644
--- a/core/java/android/view/WindowManager.java
+++ b/core/java/android/view/WindowManager.java
@@ -16,6 +16,8 @@
package android.view;
+import android.app.Presentation;
+import android.content.Context;
import android.content.pm.ActivityInfo;
import android.graphics.PixelFormat;
import android.os.IBinder;
@@ -29,6 +31,17 @@
* The interface that apps use to talk to the window manager.
* <p>
* Use <code>Context.getSystemService(Context.WINDOW_SERVICE)</code> to get one of these.
+ * </p><p>
+ * Each window manager instance is bound to a particular {@link Display}.
+ * To obtain a {@link WindowManager} for a different display, use
+ * {@link Context#createDisplayContext} to obtain a {@link Context} for that
+ * display, then use <code>Context.getSystemService(Context.WINDOW_SERVICE)</code>
+ * to get the WindowManager.
+ * </p><p>
+ * The simplest way to show a window on another display is to create a
+ * {@link Presentation}. The presentation will automatically obtain a
+ * {@link WindowManager} and {@link Context} for that display.
+ * </p>
*
* @see android.content.Context#getSystemService
* @see android.content.Context#WINDOW_SERVICE
@@ -49,12 +62,24 @@
}
/**
- * Use this method to get the default Display object.
- *
- * @return default Display object
+ * Returns the {@link Display} upon which this {@link WindowManager} instance
+ * will create new windows.
+ * <p>
+ * Despite the name of this method, the display that is returned is not
+ * necessarily the primary display of the system (see {@link Display#DEFAULT_DISPLAY}).
+ * The returned display could instead be a secondary display that this
+ * window manager instance is managing. Think of it as the display that
+ * this {@link WindowManager} instance uses by default.
+ * </p><p>
+ * To create windows on a different display, you need to obtain a
+ * {@link WindowManager} for that {@link Display}. (See the {@link WindowManager}
+ * class documentation for more information.)
+ * </p>
+ *
+ * @return The display that this window manager is managing.
*/
public Display getDefaultDisplay();
-
+
/**
* Special variation of {@link #removeView} that immediately invokes
* the given view hierarchy's {@link View#onDetachedFromWindow()