Add documentation for overscan flag.

Change-Id: Ibed06f23b2011a66021344384150e9d4ba6e61ed

4 files changed, 104 insertions, 21 deletions

diff --git a/core/java/android/view/WindowManager.java b/core/java/android/view/WindowManager.java
index bf330f3b8c6c..792188bb501a 100644
--- a/core/java/android/view/WindowManager.java
+++ b/core/java/android/view/WindowManager.java
@@ -612,10 +612,23 @@ public interface WindowManager extends ViewManager {
         /** 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 @@ public interface WindowManager extends ViewManager {
          * 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 interface WindowManager extends ViewManager {
          */
         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 @@ public interface WindowManager extends ViewManager {
          * {@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 c73ff817ed56..4a1d12d4d748 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 411419bdd51d..e1750af3335a 100644
--- a/core/res/res/values/themes.xml
+++ b/core/res/res/values/themes.xml
@@ -398,14 +398,17 @@ please see themes_device_defaults.xml.
         <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 @@ please see themes_device_defaults.xml.
     </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 @@ please see themes_device_defaults.xml.
     </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 @@ please see themes_device_defaults.xml.
     </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 @@ please see themes_device_defaults.xml.
     </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 71aa5e692f5a..87b1c9d3c824 100644
--- a/core/res/res/values/themes_device_defaults.xml
+++ b/core/res/res/values/themes_device_defaults.xml
@@ -204,12 +204,15 @@ easier.
     <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 @@ easier.
     <!-- 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>