am a1ca3632: am 18ffec85: am 928bc43f: am ab642495: Merge "Doc update: Managing System UI class" into jb-mr2-docs

* commit 'a1ca3632bc53b288df437956c8228b4bb9099bee':
  Doc update: Managing System UI class

docs/html/training/system-ui/dim.jd

@@ -0,0 +1,89 @@
+page.title=Dimming the System Bars
+
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="#dim">Dim the Status and Navigation Bars</a></li>
+  <li><a href="#reveal">Reveal the Status and Navigation Bars</a></li>
+</ol>
+
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+
+<ul>
+    <li>
+        <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> API Guide
+    </li>
+    <li>
+        <a href="{@docRoot}design/index.html">
+        Android Design Guide
+        </a>
+    </li>
+</ul>
+
+
+</div>
+</div>
+
+<p>This lesson describes how to dim the system bars (that is, the status and the navigation
+bars) on Android 4.0 (API level 14) and higher. Android does not provide a built-in way to dim the
+system bars on earlier versions.</p>
+
+<p>When you use this approach, the content doesn't resize, but the icons in the system bars
+visually recede. As soon as the user touches either the status bar or the navigation bar area of
+the screen, both bars become fully visible. The advantage of this
+approach is that the bars are still present but their details are obscured, thus
+creating an immersive experience without sacrificing easy access to the bars.</p>
+
+<h2 id="dim">Dim the Status and Navigation Bars</h2>
+
+<p>You can dim the status and notification bars on Android 4.0 and higher using the
+{@link android.view.View#SYSTEM_UI_FLAG_LOW_PROFILE} flag, as follows:</p>
+
+<pre>
+// This example uses decor view, but you can use any visible view.
+View decorView = getActivity().getWindow().getDecorView();
+int uiOptions = View.SYSTEM_UI_FLAG_LOW_PROFILE;
+decorView.setSystemUiVisibility(uiOptions);
+</pre>
+
+<p>As soon as the user touches the status or navigation bar, the flag is cleared,
+causing the bars to be undimmed. Once the flag has been cleared, your app needs to reset
+it if you want to dim the bars again.</p>
+
+<p>Figure 1 shows a gallery image in which the navigation bar is dimmed (note that the Gallery app
+completely hides the status bar; it doesn't dim it). Notice that the navigation bar (right
+side of the image) has faint white dots on it to represent the navigation controls:</p>
+
+<p class="figure" style="width:340px">
+  <img src="{@docRoot}images/training/low_profile_hide2x.png"
+  alt="system bars" />
+    <p class="img-caption"><strong>Figure 1.</strong> Dimmed system bars.</p>
+
+<p>Figure 2 shows the same gallery image, but with the system bars displayed:</p>
+
+<p class="figure" style="width:340px">
+  <img src="{@docRoot}images/training/low_profile_show2x.png"
+  alt="system bars" />
+    <p class="img-caption"><strong>Figure 2.</strong> Visible system bars.</p>
+
+    <h2 id="reveal">Reveal the Status and Navigation Bars</h2>
+
+<p>If you want to programmatically clear flags set with
+{@link android.view.View#setSystemUiVisibility setSystemUiVisibility()}, you can do so
+as follows:</p>
+
+<pre>
+View decorView = getActivity().getWindow().getDecorView();
+// Calling setSystemUiVisibility() with a value of 0 clears
+// all flags.
+decorView.setSystemUiVisibility(0);
+</pre>

docs/html/training/system-ui/index.jd

@@ -0,0 +1,90 @@
+page.title=Managing the System UI
+page.tags=""
+
+trainingnavtop=true
+startpage=true
+
+
+@jd:body
+
+
+
+<div id="tb-wrapper">
+<div id="tb">
+
+
+<!-- Required platform, tools, add-ons, devices, knowledge, etc. -->
+<h2>Dependencies and prerequisites</h2>
+
+<ul>
+  <li>Android 1.6 (API Level 4) or higher</li>
+</ul>
+
+
+
+</div>
+</div>
+
+<a class="notice-designers wide" href="{@docRoot}design/get-started/ui-overview.html#system-bars">
+<div>
+    <h3>Design Guide</h3>
+    <p>System Bars</p>
+</div>
+</a>
+
+<div class="figure" style="width:278px">
+  <img src="{@docRoot}images/training/system-ui.png"
+  alt="system bars" />
+  <p class="img-caption"><strong>Figure 1.</strong> System bars, including the [1] status
+bar, and [2] navigation bar.</p>
+</div>
+
+<p>The <a href="https://developer.android.com/design/get-started/ui-overview.html#system-bars">
+system bars</a> are screen areas dedicated to the display of notifications, communication
+of device status, and device navigation. Typically the system bars (which consist of the status
+and navigation bars, as shown in figure 1) are displayed
+concurrently with your app. Apps that display immersive content, such as movies or images,
+can temporarily dim the system bar icons for a less distracting experience,
+or temporarily hide the bars for a fully immersive experience.</p>
+
+<p>If you're familiar with the <a href="{@docRoot}design/index.html">Android Design
+Guide</a>, you know the importance of designing your apps to conform to standard Android UI
+guidelines and usage patterns. You should carefully consider your users'
+needs and expectations before modifying the system bars, since they give users a
+standard way of navigating a device and viewing its status.</p>
+
+<p>This class describes how to dim or hide system bars across different versions of Android
+to create an immersive user experience, while still preserving easy access to the system
+bars.
+</p>
+<h2>Lessons</h2>
+
+<dl>
+ <dt>
+        <strong><a href="dim.html">Dimming the System Bars</a></strong>
+    </dt>
+    <dd>
+        Learn how to dim the status and navigation bars.
+    </dd>
+    <dt>
+        <strong><a href="status.html">Hiding the Status Bar</a></strong>
+    </dt>
+    <dd>
+        Learn how to hide the status bar on different versions of Android.
+    </dd>
+    <dt>
+        <strong><a href="navigation.html">Hiding the Navigation Bar</a></strong>
+    </dt>
+    <dd>
+        Learn how to hide the navigation bar, in addition to the status bar.
+    </dd>
+
+    <dt>
+        <strong><a href="visibility.html">Responding to UI Visibility Changes</a></strong>
+    </dt>
+    <dd>
+        Learn how to register a listener to get notified of system UI visibility changes
+        so that you can adjust your app's UI accordingly.
+    </dd>
+
+</dl>

docs/html/training/system-ui/navigation.jd

@@ -0,0 +1,101 @@
+page.title=Hiding the Navigation Bar
+
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="#40">Hiding the Navigation Bar on 4.0 and Higher</a></li>
+  <li><a href="#behind">Make Content Appear Behind the Navigation Bar</a></li>
+</ol>
+
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+
+<ul>
+    <li>
+        <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> API Guide
+    </li>
+    <li>
+        <a href="{@docRoot}design/index.html">
+        Android Design Guide
+        </a>
+    </li>
+</ul>
+
+
+</div>
+</div>
+
+<p>This lesson describes how to hide the navigation bar, which was introduced in
+Android 4.0 (API level 14).</p>
+
+<p>Even though this lesson focuses on hiding the
+navigation bar, you should design your app to hide the status bar
+at the same time, as described in <a href="status.html">Hiding the Status Bar</a>.
+Hiding the navigation and status bars (while still keeping them readily accessible)
+lets the content use the entire display space, thereby providing a more immersive
+user experience. </p>
+
+<img src="{@docRoot}images/training/navigation-bar.png"
+  alt="system bars">
+<p class="img-caption"><strong>Figure 1.</strong> Navigation bar.</p>
+
+
+
+<h2 id="40">Hide the Navigation Bar on 4.0 and Higher</h2>
+
+<p>You can hide the navigation bar on Android 4.0 and higher using the
+{@link android.view.View#SYSTEM_UI_FLAG_HIDE_NAVIGATION} flag. This snippet hides both
+the navigation bar and the status bar:</p>
+<pre>View decorView = getWindow().getDecorView();
+// Hide both the navigation bar and the status bar.
+int uiOptions = View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
+              | View.SYSTEM_UI_FLAG_FULLSCREEN;
+decorView.setSystemUiVisibility(uiOptions);</pre>
+
+<p>Note the following:</p>
+
+<ul>
+  <li>With this approach, touching anywhere on the screen causes the navigation bar (and
+  status bar) to reappear and remain visible. The user interaction causes the flags to be
+  be cleared.</li>
+<li>Once the flags have been cleared, your app needs to reset them if you
+want to hide the bars again. See <a href="visibility.html">Responding to UI Visibility Changes</a> for a
+discussion of how to listen for UI visibility changes so that your app can
+respond accordingly.</li>
+
+<li>Where you set the UI flags makes a difference. If you hide the system bars in your activity's
+ {@link android.app.Activity#onCreate onCreate()} method and the user presses Home, the system bars will
+ reappear. When the user reopens the activity, {@link android.app.Activity#onCreate onCreate()}
+won't get called, so the system bars will remain visible. If you want system UI changes to
+persist as the user navigates in and out of your activity, set UI flags in
+{@link android.app.Activity#onResume onResume()}
+or {@link android.view.Window.Callback#onWindowFocusChanged onWindowFocusChanged()}.</li>
+
+  <li>The method {@link android.view.View#setSystemUiVisibility setSystemUiVisibility()} only
+  has an effect if the view you call it from is visible.</li>
+  <li>Navigating away from the view causes flags
+  set with {@link android.view.View#setSystemUiVisibility setSystemUiVisibility()}
+  to be cleared.</li>
+</ul>
+
+<h2 id="behind">Make Content Appear Behind the Navigation Bar</h2>
+<p>On Android 4.1 and higher, you can set your application's content to appear behind
+the navigation bar, so that the content doesn't resize as the navigation bar hides and
+shows. To do this, use
+{@link android.view.View#setSystemUiVisibility setSystemuiVisibility(SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION)}.
+You may also need to use
+{@link android.view.View#SYSTEM_UI_FLAG_LAYOUT_STABLE} to help your app maintain a
+stable layout.</p>
+
+<p>When you use this approach, it becomes your responsibility to ensure that critical parts
+of your app's UI don't end up getting covered by system bars. For more
+discussion of this topic, see the <a href="status.html#behind">
+Hiding the Status Bar</a> lesson.</p>

docs/html/training/system-ui/status.jd

@@ -0,0 +1,220 @@
+page.title=Hiding the Status Bar
+
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="#40">Hide the Status Bar on Android 4.0 and Lower</a></li>
+  <li><a href="#41">Hide the Status Bar on Android 4.1 and Higher</a></li>
+
+  <li><a href="#behind">Make Content Appear Behind the Status Bar</a></li>
+  <li><a href="#action-bar">Synchronize the Status Bar with Action Bar Transition</a></li>
+</ol>
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+
+<ul>
+    <li>
+        <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> API Guide
+    </li>
+    <li>
+        <a href="{@docRoot}design/index.html">
+        Android Design Guide
+        </a>
+    </li>
+</ul>
+
+
+</div>
+</div>
+
+<p>
+    This lesson describes how to hide the status bar on different versions of
+    Android. Hiding the status bar (and optionally, the navigation bar) lets the
+    content use more of the display space, thereby providing a more immersive user experience.
+
+</p>
+
+<p>
+ Figure 1 shows an app with a visible status bar:
+</p>
+
+<img src="{@docRoot}images/training/status_bar_show.png"
+  alt="system bars">
+<p class="img-caption"><strong>Figure 1.</strong> Visible status bar.</p>
+
+<p>
+ Figure 2 shows an app with a hidden status bar. Note that the action bar is hidden too.
+ You should never show the action bar without the status bar.
+</p>
+
+<img src="{@docRoot}images/training/status_bar_hide.png"
+  alt="system bars">
+<p class="img-caption"><strong>Figure 2.</strong> Hidden status bar.</p>
+
+<h2 id="40">Hide the Status Bar on Android 4.0 and Lower</h2>
+
+<p>You can hide the status bar on Android 4.0 (API level 14) and lower by setting
+{@link android.view.WindowManager} flags. You can do this programmatically or by
+setting an activity theme in your app's manifest file. Setting an activity theme in your app's
+manifest file is the preferred approach if the status bar should always remain
+hidden in your app (though strictly speaking, you could programmatically override the
+theme if you wanted to). For example:</p>
+
+<pre>
+&lt;application
+    ...
+    android:theme=&quot;@android:style/Theme.Holo.NoActionBar.Fullscreen&quot; &gt;
+    ...
+&lt;/application&gt;
+</pre>
+
+<p>The advantages of using an activity theme are as follows:</p>
+
+<ul>
+<li>It's easier to maintain and less error-prone than setting a flag programmatically.</li>
+<li>It results in smoother UI transitions, because the system has the information it needs
+to render your UI before instantiating your app's main activity.</li>
+</ul>
+
+<p>
+Alternatively, you can programmatically set {@link android.view.WindowManager} flags.
+This approach makes it easier to hide and show the status bar as the user interacts with
+your app:</p>
+
+<pre>public class MainActivity extends Activity {
+
+    &#64;Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        // If the Android version is lower than Jellybean, use this call to hide
+        // the status bar.
+        if (Build.VERSION.SDK_INT < 16) {
+            getWindow().setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN,
+                    WindowManager.LayoutParams.FLAG_FULLSCREEN);
+        }
+        setContentView(R.layout.activity_main);
+    }
+    ...
+}
+</pre>
+
+<p>When you set {@link android.view.WindowManager} flags (whether through an activity theme or
+programmatically), the flags remain in effect unless your app clears them.</p>
+
+<p>You can use
+{@link android.view.WindowManager.LayoutParams#FLAG_LAYOUT_IN_SCREEN}
+to set  your activity layout to use the same screen area that's available when you've enabled
+{@link android.view.WindowManager.LayoutParams#FLAG_FULLSCREEN}. This prevents your
+content from resizing when the status bar hides and shows.</p>
+
+
+<h2 id="41">Hide the Status Bar on Android 4.1 and Higher</h2>
+
+<p>You can hide the status bar on Android 4.1 (API level 16) and higher by
+using {@link android.view.View#setSystemUiVisibility setSystemUiVisibility()}.
+{@link android.view.View#setSystemUiVisibility setSystemUiVisibility()} sets UI flags at
+the individual view level; these settings are aggregated to the window level. Using
+{@link android.view.View#setSystemUiVisibility setSystemUiVisibility()} to set UI flags
+gives you more granular control over the system bars than using
+{@link android.view.WindowManager} flags. This snippet hides the status bar:</p>
+
+<pre>View decorView = getWindow().getDecorView();
+// Hide the status bar.
+int uiOptions = View.SYSTEM_UI_FLAG_FULLSCREEN;
+decorView.setSystemUiVisibility(uiOptions);
+// Remember that you should never show the action bar if the
+// status bar is hidden, so hide that too if necessary.
+ActionBar actionBar = getActionBar();
+actionBar.hide();
+</pre>
+
+<p>Note the following:</p>
+
+<ul>
+<li>Once UI flags have been cleared (for example, by navigating away from the
+activity), your app needs to reset them if you want to hide the bars again.
+See <a href="visibility.html">Responding to UI Visibility Changes</a> for a
+discussion of how to listen for UI visibility changes so that your app can
+respond accordingly.</li>
+
+<li>Where you set the UI flags makes a difference. If you hide the system bars in your activity's
+ {@link android.app.Activity#onCreate onCreate()} method and the user presses Home, the system bars will
+ reappear. When the user reopens the activity, {@link android.app.Activity#onCreate onCreate()}
+won't get called, so the system bars will remain visible. If you want system UI changes to
+persist as the user navigates in and out of your activity, set UI flags in
+{@link android.app.Activity#onResume onResume()}
+or {@link android.view.Window.Callback#onWindowFocusChanged onWindowFocusChanged()}.</li>
+
+  <li>The method {@link android.view.View#setSystemUiVisibility setSystemUiVisibility()}
+  only has an effect if the view you call it from is visible.</li>
+
+  <li>Navigating away from the view causes flags
+  set with {@link android.view.View#setSystemUiVisibility setSystemUiVisibility()}
+  to be cleared.</li>
+</ul>
+
+
+ </p>
+
+ <h2 id="behind">Make Content Appear Behind the Status Bar</h2>
+<p>On Android 4.1 and higher, you can set your application's content to appear behind
+the status bar, so that the content doesn't resize as the status bar hides and shows.
+To do this, use
+{@link android.view.View#setSystemUiVisibility setSystemuiVisibility(SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN)}.
+You may also need to use
+{@link android.view.View#SYSTEM_UI_FLAG_LAYOUT_STABLE} to help your app maintain a
+stable layout.</p>
+
+<p>When you use this approach, it becomes your responsibility to ensure that critical parts
+of your app's UI (for example, the built-in controls in a Maps application) don't end up
+getting covered by system bars. This could make your app unusable. In most cases you can
+handle this by adding the {@code android:fitsSystemWindows} attribute to your XML layout file, set to
+{@code true}. This adjusts the padding of the parent {@link android.view.ViewGroup}
+to leave space for the system windows. This is sufficient for most applications.</p>
+
+<p>In some cases, however, you may need to modify the default padding to get the desired
+layout for your app. To directly manipulate how your
+content lays out relative to the system bars (which occupy a space known as the window's
+"content insets"), override {@link android.view.View#fitSystemWindows fitSystemWindows(Rect insets)}.
+The {@link android.view.View#fitSystemWindows fitSystemWindows()} method is called by the
+view hierarchy when the content insets for a window have changed, to allow the window to
+adjust its content accordingly. By overriding this method you can handle the
+insets (and hence your app's layout) however you want. </p>
+
+ <h2 id="action-bar">Synchronize the Status Bar with Action Bar Transition</h2>
+
+  <p>On Android 4.1 and higher, to avoid resizing your layout when the action bar hides and
+  shows, you can enable overlay mode for the <a href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>.
+  When in overlay mode, your activity layout uses all the
+  space available as if the action bar is not there and the system draws the action bar in
+  front of your layout. This obscures some of the layout at the top, but now when the
+  action bar hides or appears, the system does not need to resize your layout and the
+  transition is seamless.</p>
+
+  <p>To enable overlay mode for the action bar, you need to create a custom theme that
+  extends an existing theme with an action bar and set the
+  {@code android:windowActionBarOverlay} attribute
+  to {@code true}. For more discussion of this topic, see
+  <a href="{@docRoot}training/basics/actionbar/overlaying.html#EnableOverlay">
+  Overlaying the Action Bar</a> in the <a href="{@docRoot}training/basics/actionbar/index.html">
+  Adding the Action Bar</a> class.</p>
+
+
+<p>Then use
+{@link android.view.View#setSystemUiVisibility setSystemuiVisibility(SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN)},
+as described above,
+to set  your activity layout to use the same screen area that's available when you've enabled
+{@link android.view.View#SYSTEM_UI_FLAG_FULLSCREEN}.
+
+When you want to hide the system UI, call
+{@link android.view.View#setSystemUiVisibility setSystemUiVisibility(SYSTEM_UI_FLAG_FULLSCREEN)}.
+This also hides the action bar (because {@code windowActionBarOverlay=”true”)} and does
+so with a coordinated animation when both hiding and showing the two.</p>

docs/html/training/system-ui/visibility.jd

@@ -0,0 +1,69 @@
+page.title=Responding to UI Visibility Changes
+
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="#listener">Register a Listener</a></li>
+</ol>
+
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+
+<ul>
+    <li>
+        <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> API Guide
+    </li>
+    <li>
+        <a href="{@docRoot}design/index.html">
+        Android Design Guide
+        </a>
+    </li>
+</ul>
+
+
+</div>
+</div>
+
+<p>This lesson describes how to register a listener so that your app can get notified
+of system UI visibility changes. This is useful if you want to
+synchronize other parts of your UI with the hiding/showing of system bars.</p>
+
+<h2 id="listener">Register a Listener</h2>
+
+<p>To get notified of system UI visibility changes, register an
+{@link android.view.View.OnSystemUiVisibilityChangeListener} to your view.
+This is typically the view you are using to control the navigation visibility.</p>
+
+<p>For example, you could add this code to your activity's
+{@link android.app.Activity#onCreate onCreate()} method:</p>
+
+<pre>View decorView = getWindow().getDecorView();
+decorView.setOnSystemUiVisibilityChangeListener
+        (new View.OnSystemUiVisibilityChangeListener() {
+    &#64;Override
+    public void onSystemUiVisibilityChange(int visibility) {
+        // Note that system bars will only be "visible" if none of the
+        // LOW_PROFILE, HIDE_NAVIGATION, or FULLSCREEN flags are set.
+        if ((visibility & View.SYSTEM_UI_FLAG_FULLSCREEN) == 0) {
+            // TODO: The system bars are visible. Make any desired
+            // adjustments to your UI, such as showing the action bar or
+            // other navigational controls.
+        } else {
+            // TODO: The system bars are NOT visible. Make any desired
+            // adjustments to your UI, such as hiding the action bar or
+            // other navigational controls.
+        }
+    }
+});</pre>
+
+<p>It's generally good practice to keep your UI in sync with changes in system bar
+visibility. For example, you could use this listener to hide and show the action bar in
+concert with the status bar hiding and showing.</p>

docs/html/training/training_toc.cs

@@ -945,6 +945,34 @@ include the action bar on devices running Android 2.1 or higher."
         </ul>
       </li>
 
+      <li class="nav-section">
+        <div class="nav-section-header">
+          <a href="<?cs var:toroot ?>training/system-ui/index.html"
+             description=
+             "How to hide and show status and navigation bars across different versions of Android,
+              while managing the display of other screen components."
+            >Managing the System UI</a>
+        </div>
+        <ul>
+          <li><a href="<?cs var:toroot ?>training/system-ui/dim.html">
+            Dimming the System Bars
+          </a>
+          </li>
+          <li><a href="<?cs var:toroot ?>training/system-ui/status.html">
+            Hiding the Status Bar
+          </a>
+          </li>
+          <li><a href="<?cs var:toroot ?>training/system-ui/navigation.html">
+            Hiding the Navigation Bar
+          </a>
+          </li>
+          <li><a href="<?cs var:toroot ?>training/system-ui/visibility.html">
+            Responding to UI Visibility Changes
+          </a>
+          </li>
+        </ul>
+      </li>
+
     </ul>
   </li>
   <!-- End best UX and UI -->