Add documentation for overscan flag.
Change-Id: Ibed06f23b2011a66021344384150e9d4ba6e61ed
diff --git a/core/java/android/view/WindowManager.java b/core/java/android/view/WindowManager.java
index bf330f3..792188b 100644
--- a/core/java/android/view/WindowManager.java
+++ b/core/java/android/view/WindowManager.java
@@ -612,10 +612,23 @@
/** Window flag: allow window to extend outside of the screen. */
public static final int FLAG_LAYOUT_NO_LIMITS = 0x00000200;
- /** Window flag: Hide all screen decorations (e.g. status bar) while
+ /**
+ * Window flag: Hide all screen decorations (e.g. status bar) while
* this window is displayed. This allows the window to use the entire
* display space for itself -- the status bar will be hidden when
- * an app window with this flag set is on the top layer. */
+ * an app window with this flag set is on the top layer.
+ *
+ * <p>This flag can be controlled in your theme through the
+ * {@link android.R.attr#windowFullscreen} attribute; this attribute
+ * is automatically set for you in the standard fullscreen themes
+ * such as {@link android.R.style#Theme_NoTitleBar_Fullscreen},
+ * {@link android.R.style#Theme_Black_NoTitleBar_Fullscreen},
+ * {@link android.R.style#Theme_Light_NoTitleBar_Fullscreen},
+ * {@link android.R.style#Theme_Holo_NoActionBar_Fullscreen},
+ * {@link android.R.style#Theme_Holo_Light_NoActionBar_Fullscreen},
+ * {@link android.R.style#Theme_DeviceDefault_NoActionBar_Fullscreen}, and
+ * {@link android.R.style#Theme_DeviceDefault_Light_NoActionBar_Fullscreen}.</p>
+ */
public static final int FLAG_FULLSCREEN = 0x00000400;
/** Window flag: Override {@link #FLAG_FULLSCREEN and force the
@@ -697,6 +710,17 @@
* to actually see the wallpaper behind it; this flag just ensures
* that the wallpaper surface will be there if this window actually
* has translucent regions.
+ *
+ * <p>This flag can be controlled in your theme through the
+ * {@link android.R.attr#windowShowWallpaper} attribute; this attribute
+ * is automatically set for you in the standard wallpaper themes
+ * such as {@link android.R.style#Theme_Wallpaper},
+ * {@link android.R.style#Theme_Wallpaper_NoTitleBar},
+ * {@link android.R.style#Theme_Wallpaper_NoTitleBar_Fullscreen},
+ * {@link android.R.style#Theme_Holo_Wallpaper},
+ * {@link android.R.style#Theme_Holo_Wallpaper_NoTitleBar},
+ * {@link android.R.style#Theme_DeviceDefault_Wallpaper}, and
+ * {@link android.R.style#Theme_DeviceDefault_Wallpaper_NoTitleBar}.</p>
*/
public static final int FLAG_SHOW_WALLPAPER = 0x00100000;
@@ -763,9 +787,38 @@
*/
public static final int FLAG_HARDWARE_ACCELERATED = 0x01000000;
- /** Window flag: allow window contents to extend in to the screen's
+ /**
+ * Window flag: allow window contents to extend in to the screen's
* overscan area, if there is one. The window should still correctly
* position its contents to take the overscan area into account.
+ *
+ * <p>This flag can be controlled in your theme through the
+ * {@link android.R.attr#windowOverscan} attribute; this attribute
+ * is automatically set for you in the standard overscan themes
+ * such as {@link android.R.style#Theme_NoTitleBar_Overscan},
+ * {@link android.R.style#Theme_Black_NoTitleBar_Overscan},
+ * {@link android.R.style#Theme_Light_NoTitleBar_Overscan},
+ * {@link android.R.style#Theme_Holo_NoActionBar_Overscan},
+ * {@link android.R.style#Theme_Holo_Light_NoActionBar_Overscan},
+ * {@link android.R.style#Theme_DeviceDefault_NoActionBar_Overscan}, and
+ * {@link android.R.style#Theme_DeviceDefault_Light_NoActionBar_Overscan}.</p>
+ *
+ * <p>When this flag is enabled for a window, its normal content may be obscured
+ * to some degree by the overscan region of the display. To ensure key parts of
+ * that content are visible to the user, you can use
+ * {@link View#setFitsSystemWindows(boolean) View.setFitsSystemWindows(boolean)}
+ * to set the point in the view hierarchy where the appropriate offsets should
+ * be applied. (This can be done either by directly calling this function, using
+ * the {@link android.R.attr#fitsSystemWindows} attribute in your view hierarchy,
+ * or implementing you own {@link View#fitSystemWindows(android.graphics.Rect)
+ * View.fitSystemWindows(Rect)} method).</p>
+ *
+ * <p>This mechanism for positioning content elements is identical to its equivalent
+ * use with layout and {@link View#setSystemUiVisibility(int)
+ * View.setSystemUiVisibility(int)}; here is an example layout that will correctly
+ * position its UI elements with this overscan flag is set:</p>
+ *
+ * {@sample development/samples/ApiDemos/res/layout/overscan_activity.xml complete}
*/
public static final int FLAG_LAYOUT_IN_OVERSCAN = 0x02000000;
@@ -1091,6 +1144,11 @@
* {@link #SOFT_INPUT_ADJUST_UNSPECIFIED},
* {@link #SOFT_INPUT_ADJUST_RESIZE}, or
* {@link #SOFT_INPUT_ADJUST_PAN}.
+ * </ul>
+ *
+ *
+ * <p>This flag can be controlled in your theme through the
+ * {@link android.R.attr#windowSoftInputMode} attribute.</p>
*/
public int softInputMode;
diff --git a/core/res/res/values/attrs.xml b/core/res/res/values/attrs.xml
index c73ff81..4a1d12d 100644
--- a/core/res/res/values/attrs.xml
+++ b/core/res/res/values/attrs.xml
@@ -310,16 +310,19 @@
<attr name="windowFrame" format="reference" />
<!-- Flag indicating whether there should be no title on this window. -->
<attr name="windowNoTitle" format="boolean" />
- <!-- Flag indicating whether this window should fill the entire screen. -->
+ <!-- Flag indicating whether this window should fill the entire screen. Corresponds
+ to {@link android.view.WindowManager.LayoutParams#FLAG_FULLSCREEN}. -->
<attr name="windowFullscreen" format="boolean" />
- <!-- Flag indicating whether this window should extend into overscan region. -->
+ <!-- Flag indicating whether this window should extend into overscan region. Corresponds
+ to {@link android.view.WindowManager.LayoutParams#FLAG_LAYOUT_IN_OVERSCAN}. -->
<attr name="windowOverscan" format="boolean" />
<!-- Flag indicating whether this is a floating window. -->
<attr name="windowIsFloating" format="boolean" />
<!-- Flag indicating whether this is a translucent window. -->
<attr name="windowIsTranslucent" format="boolean" />
<!-- Flag indicating that this window's background should be the
- user's current wallpaper. -->
+ user's current wallpaper. Corresponds
+ to {@link android.view.WindowManager.LayoutParams#FLAG_SHOW_WALLPAPER}. -->
<attr name="windowShowWallpaper" format="boolean" />
<!-- This Drawable is overlaid over the foreground of the Window's content area, usually
to place a shadow below the title. -->
@@ -355,7 +358,8 @@
<attr name="windowSplitActionBar" format="boolean" />
<!-- Defines the default soft input state that this window would
- like when it is displayed. -->
+ like when it is displayed. Corresponds
+ to {@link android.view.WindowManager.LayoutParams#softInputMode}. -->
<attr name="windowSoftInputMode">
<!-- Not specified, use what the system thinks is best. This
is the default. -->
diff --git a/core/res/res/values/themes.xml b/core/res/res/values/themes.xml
index 411419b..e1750af 100644
--- a/core/res/res/values/themes.xml
+++ b/core/res/res/values/themes.xml
@@ -398,14 +398,17 @@
<item name="android:windowNoTitle">true</item>
</style>
- <!-- Variant of {@link #Theme} that has no title bar and no status bar -->
+ <!-- Variant of {@link #Theme} that has no title bar and no status bar. This theme
+ sets {@link android.R.attr#windowFullscreen} to true. -->
<style name="Theme.NoTitleBar.Fullscreen">
<item name="android:windowFullscreen">true</item>
<item name="android:windowContentOverlay">@null</item>
</style>
<!-- Variant of {@link #Theme} that has no title bar and no status bar and extending
- into the display overscan region. -->
+ into the display overscan region. This theme
+ sets {@link android.R.attr#windowFullscreen} and {@link android.R.attr#windowOverscan}
+ to true. -->
<style name="Theme.NoTitleBar.Overscan">
<item name="android:windowFullscreen">true</item>
<item name="android:windowOverscan">true</item>
@@ -498,14 +501,17 @@
</style>
<!-- Variant of {@link #Theme_Light} that has no title bar and
- no status bar -->
+ no status bar. This theme
+ sets {@link android.R.attr#windowFullscreen} to true. -->
<style name="Theme.Light.NoTitleBar.Fullscreen">
<item name="android:windowFullscreen">true</item>
<item name="android:windowContentOverlay">@null</item>
</style>
<!-- Variant of {@link #Theme_Light} that has no title bar and
- no status bar and extending into the display overscan region. -->
+ no status bar and extending into the display overscan region. This theme
+ sets {@link android.R.attr#windowFullscreen} and {@link android.R.attr#windowOverscan}
+ to true. -->
<style name="Theme.Light.NoTitleBar.Overscan">
<item name="android:windowFullscreen">true</item>
<item name="android:windowOverscan">true</item>
@@ -527,14 +533,17 @@
</style>
<!-- Variant of {@link #Theme_Black} that has no title bar and
- no status bar -->
+ no status bar. This theme
+ sets {@link android.R.attr#windowFullscreen} to true. -->
<style name="Theme.Black.NoTitleBar.Fullscreen">
<item name="android:windowFullscreen">true</item>
<item name="android:windowContentOverlay">@null</item>
</style>
<!-- Variant of {@link #Theme_Black} that has no title bar and
- no status bar and extending into the display overscan region. -->
+ no status bar and extending into the display overscan region. This theme
+ sets {@link android.R.attr#windowFullscreen} and {@link android.R.attr#windowOverscan}
+ to true. -->
<style name="Theme.Black.NoTitleBar.Overscan">
<item name="android:windowFullscreen">true</item>
<item name="android:windowOverscan">true</item>
@@ -1584,14 +1593,17 @@
</style>
<!-- Variant of the holographic (dark) theme that has no title bar and fills
- the entire screen -->
+ the entire screen. This theme
+ sets {@link android.R.attr#windowFullscreen} to true. -->
<style name="Theme.Holo.NoActionBar.Fullscreen">
<item name="android:windowFullscreen">true</item>
<item name="android:windowContentOverlay">@null</item>
</style>
<!-- Variant of the holographic (dark) theme that has no title bar and fills
- the entire screen and extends into the display overscan region. -->
+ the entire screen and extends into the display overscan region. This theme
+ sets {@link android.R.attr#windowFullscreen} and {@link android.R.attr#windowOverscan}
+ to true. -->
<style name="Theme.Holo.NoActionBar.Overscan">
<item name="android:windowFullscreen">true</item>
<item name="android:windowOverscan">true</item>
@@ -1605,14 +1617,17 @@
</style>
<!-- Variant of the holographic (light) theme that has no title bar and fills
- the entire screen -->
+ the entire screen. This theme
+ sets {@link android.R.attr#windowFullscreen} to true. -->
<style name="Theme.Holo.Light.NoActionBar.Fullscreen">
<item name="android:windowFullscreen">true</item>
<item name="android:windowContentOverlay">@null</item>
</style>
<!-- Variant of the holographic (light) theme that has no title bar and fills
- the entire screen and extends into the display overscan region. -->
+ the entire screen and extends into the display overscan region. This theme
+ sets {@link android.R.attr#windowFullscreen} and {@link android.R.attr#windowOverscan}
+ to true. -->
<style name="Theme.Holo.Light.NoActionBar.Overscan">
<item name="android:windowFullscreen">true</item>
<item name="android:windowOverscan">true</item>
diff --git a/core/res/res/values/themes_device_defaults.xml b/core/res/res/values/themes_device_defaults.xml
index 71aa5e6..87b1c9d 100644
--- a/core/res/res/values/themes_device_defaults.xml
+++ b/core/res/res/values/themes_device_defaults.xml
@@ -204,12 +204,15 @@
<style name="Theme.DeviceDefault.NoActionBar" parent="Theme.Holo.NoActionBar" >
</style>
- <!-- Variant of {@link #Theme_DeviceDefault} with no action bar and no status bar -->
+ <!-- Variant of {@link #Theme_DeviceDefault} with no action bar and no status bar. This theme
+ sets {@link android.R.attr#windowFullscreen} to true. -->
<style name="Theme.DeviceDefault.NoActionBar.Fullscreen" parent="Theme.Holo.NoActionBar.Fullscreen" >
</style>
<!-- Variant of {@link #Theme_DeviceDefault} with no action bar and no status bar and
- extending in to overscan region. -->
+ extending in to overscan region. This theme
+ sets {@link android.R.attr#windowFullscreen} and {@link android.R.attr#windowOverscan}
+ to true. -->
<style name="Theme.DeviceDefault.NoActionBar.Overscan" parent="Theme.Holo.NoActionBar.Overscan" >
</style>
@@ -362,11 +365,14 @@
<!-- Variant of {@link #Theme_DeviceDefault_Light} with no action bar -->
<style name="Theme.DeviceDefault.Light.NoActionBar" parent="Theme.Holo.Light.NoActionBar" >
</style>
- <!-- Variant of {@link #Theme_DeviceDefault_Light} with no action bar and no status bar -->
+ <!-- Variant of {@link #Theme_DeviceDefault_Light} with no action bar and no status bar.
+ This theme sets {@link android.R.attr#windowFullscreen} to true. -->
<style name="Theme.DeviceDefault.Light.NoActionBar.Fullscreen" parent="Theme.Holo.Light.NoActionBar.Fullscreen" >
</style>
<!-- Variant of {@link #Theme_DeviceDefault_Light} with no action bar and no status bar
- and extending in to overscan region-->
+ and extending in to overscan region. This theme
+ sets {@link android.R.attr#windowFullscreen} and {@link android.R.attr#windowOverscan}
+ to true. -->
<style name="Theme.DeviceDefault.Light.NoActionBar.Overscan"
parent="Theme.Holo.Light.NoActionBar.Overscan" >
</style>