From d20c87c550524754956774004d1e7625d5e86c48 Mon Sep 17 00:00:00 2001 From: Katie McCormick Date: Fri, 27 Sep 2013 15:52:14 -0700 Subject: Doc update: Managing System UI class Change-Id: I8c8f8864411a4be64426e347351690078c922c1c --- docs/html/images/training/low_profile_hide2x.png | Bin 0 -> 379312 bytes docs/html/images/training/low_profile_show2x.png | Bin 0 -> 378674 bytes docs/html/images/training/navigation-bar.png | Bin 0 -> 40679 bytes docs/html/images/training/status-bar.png | Bin 0 -> 30653 bytes docs/html/images/training/status_bar_hide.png | Bin 0 -> 31000 bytes docs/html/images/training/status_bar_show.png | Bin 0 -> 36273 bytes docs/html/images/training/system-ui.png | Bin 0 -> 166545 bytes docs/html/images/transparent--bars@2x.png | Bin 0 -> 299455 bytes docs/html/training/system-ui/dim.jd | 89 +++++++++ docs/html/training/system-ui/index.jd | 90 ++++++++++ docs/html/training/system-ui/navigation.jd | 101 +++++++++++ docs/html/training/system-ui/status.jd | 220 +++++++++++++++++++++++ docs/html/training/system-ui/visibility.jd | 69 +++++++ docs/html/training/training_toc.cs | 28 +++ 14 files changed, 597 insertions(+) create mode 100644 docs/html/images/training/low_profile_hide2x.png create mode 100644 docs/html/images/training/low_profile_show2x.png create mode 100644 docs/html/images/training/navigation-bar.png create mode 100644 docs/html/images/training/status-bar.png create mode 100644 docs/html/images/training/status_bar_hide.png create mode 100644 docs/html/images/training/status_bar_show.png create mode 100644 docs/html/images/training/system-ui.png create mode 100644 docs/html/images/transparent--bars@2x.png create mode 100644 docs/html/training/system-ui/dim.jd create mode 100644 docs/html/training/system-ui/index.jd create mode 100644 docs/html/training/system-ui/navigation.jd create mode 100644 docs/html/training/system-ui/status.jd create mode 100644 docs/html/training/system-ui/visibility.jd diff --git a/docs/html/images/training/low_profile_hide2x.png b/docs/html/images/training/low_profile_hide2x.png new file mode 100644 index 000000000000..4248bcc1d2ec Binary files /dev/null and b/docs/html/images/training/low_profile_hide2x.png differ diff --git a/docs/html/images/training/low_profile_show2x.png b/docs/html/images/training/low_profile_show2x.png new file mode 100644 index 000000000000..748c0170ae4a Binary files /dev/null and b/docs/html/images/training/low_profile_show2x.png differ diff --git a/docs/html/images/training/navigation-bar.png b/docs/html/images/training/navigation-bar.png new file mode 100644 index 000000000000..e024d708f437 Binary files /dev/null and b/docs/html/images/training/navigation-bar.png differ diff --git a/docs/html/images/training/status-bar.png b/docs/html/images/training/status-bar.png new file mode 100644 index 000000000000..0a2bcae688af Binary files /dev/null and b/docs/html/images/training/status-bar.png differ diff --git a/docs/html/images/training/status_bar_hide.png b/docs/html/images/training/status_bar_hide.png new file mode 100644 index 000000000000..189db4abd366 Binary files /dev/null and b/docs/html/images/training/status_bar_hide.png differ diff --git a/docs/html/images/training/status_bar_show.png b/docs/html/images/training/status_bar_show.png new file mode 100644 index 000000000000..b4562581c3db Binary files /dev/null and b/docs/html/images/training/status_bar_show.png differ diff --git a/docs/html/images/training/system-ui.png b/docs/html/images/training/system-ui.png new file mode 100644 index 000000000000..a3aea6510f19 Binary files /dev/null and b/docs/html/images/training/system-ui.png differ diff --git a/docs/html/images/transparent--bars@2x.png b/docs/html/images/transparent--bars@2x.png new file mode 100644 index 000000000000..a3e2f70ccb5d Binary files /dev/null and b/docs/html/images/transparent--bars@2x.png differ diff --git a/docs/html/training/system-ui/dim.jd b/docs/html/training/system-ui/dim.jd new file mode 100644 index 000000000000..7c365d7d8efd --- /dev/null +++ b/docs/html/training/system-ui/dim.jd @@ -0,0 +1,89 @@ +page.title=Dimming the System Bars + +trainingnavtop=true + +@jd:body + +
+
+ + +

This lesson teaches you to

+
    +
  1. Dim the Status and Navigation Bars
    2. +
  2. Reveal the Status and Navigation Bars
    3. +
+ + + +

You should also read

+ + + + +
+
+ +

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.

+ +

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.

+ +

Dim the Status and Navigation Bars

+ +

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:

+ +
+// 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);
+
+ +

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.

+ +

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:

+ +

+ system bars +

Figure 1. Dimmed system bars.

+ +

Figure 2 shows the same gallery image, but with the system bars displayed:

+ +

+ system bars +

Figure 2. Visible system bars.

+ +

Reveal the Status and Navigation Bars

+ +

If you want to programmatically clear flags set with +{@link android.view.View#setSystemUiVisibility setSystemUiVisibility()}, you can do so +as follows:

+ +
+View decorView = getActivity().getWindow().getDecorView();
+// Calling setSystemUiVisibility() with a value of 0 clears
+// all flags.
+decorView.setSystemUiVisibility(0);
+
diff --git a/docs/html/training/system-ui/index.jd b/docs/html/training/system-ui/index.jd new file mode 100644 index 000000000000..7135a3d450eb --- /dev/null +++ b/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 + + + +
+
+ + + +

Dependencies and prerequisites

+ +
    +
  • Android 1.6 (API Level 4) or higher
    • +
+ + + +
+
+ + +
+

Design Guide

+

System Bars

+
+ + +
+ system bars +

Figure 1. System bars, including the [1] status +bar, and [2] navigation bar.

+
+ +

The +system bars 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.

+ +

If you're familiar with the Android Design +Guide, 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.

+ +

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. +

+

Lessons

+ +
+
+ Dimming the System Bars +
+
+ Learn how to dim the status and navigation bars. +
+
+ Hiding the Status Bar +
+
+ Learn how to hide the status bar on different versions of Android. +
+
+ Hiding the Navigation Bar +
+
+ Learn how to hide the navigation bar, in addition to the status bar. +
+ +
+ Responding to UI Visibility Changes +
+
+ Learn how to register a listener to get notified of system UI visibility changes + so that you can adjust your app's UI accordingly. +
+ +
\ No newline at end of file diff --git a/docs/html/training/system-ui/navigation.jd b/docs/html/training/system-ui/navigation.jd new file mode 100644 index 000000000000..3843da301fe4 --- /dev/null +++ b/docs/html/training/system-ui/navigation.jd @@ -0,0 +1,101 @@ +page.title=Hiding the Navigation Bar + +trainingnavtop=true + +@jd:body + +
+
+ + +

This lesson teaches you to

+
    +
  1. Hiding the Navigation Bar on 4.0 and Higher
    2. +
  2. Make Content Appear Behind the Navigation Bar
    3. +
+ + + +

You should also read

+ + + + +
+
+ +

This lesson describes how to hide the navigation bar, which was introduced in +Android 4.0 (API level 14).

+ +

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 Hiding the Status Bar. +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.

+ +system bars +

Figure 1. Navigation bar.

+ + + +

Hide the Navigation Bar on 4.0 and Higher

+ +

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:

+
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);
+ +

Note the following:

+ + + +

Make Content Appear Behind the Navigation Bar

+

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.

+ +

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 +Hiding the Status Bar lesson.

diff --git a/docs/html/training/system-ui/status.jd b/docs/html/training/system-ui/status.jd new file mode 100644 index 000000000000..25ee253e3bfb --- /dev/null +++ b/docs/html/training/system-ui/status.jd @@ -0,0 +1,220 @@ +page.title=Hiding the Status Bar + +trainingnavtop=true + +@jd:body + +
+ +
+ +

+ 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. + +

+ +

+ Figure 1 shows an app with a visible status bar: +

+ +system bars +

Figure 1. Visible status bar.

+ +

+ 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. +

+ +system bars +

Figure 2. Hidden status bar.

+ +

Hide the Status Bar on Android 4.0 and Lower

+ +

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:

+ +
+<application
+    ...
+    android:theme="@android:style/Theme.Holo.NoActionBar.Fullscreen" >
+    ...
+</application>
+
+ +

The advantages of using an activity theme are as follows:

+ + + +

+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:

+ +
public class MainActivity extends Activity {
+
+    @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);
+    }
+    ...
+}
+
+ +

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.

+ +

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.

+ + +

Hide the Status Bar on Android 4.1 and Higher

+ +

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:

+ +
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();
+
+ +

Note the following:

+ + + + +

+ +

Make Content Appear Behind the Status Bar

+

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.

+ +

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.

+ +

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.

+ +

Synchronize the Status Bar with Action Bar Transition

+ +

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 action bar. + 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.

+ +

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 + + Overlaying the Action Bar in the + Adding the Action Bar class.

+ + +

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.

diff --git a/docs/html/training/system-ui/visibility.jd b/docs/html/training/system-ui/visibility.jd new file mode 100644 index 000000000000..c26092c37199 --- /dev/null +++ b/docs/html/training/system-ui/visibility.jd @@ -0,0 +1,69 @@ +page.title=Responding to UI Visibility Changes + +trainingnavtop=true + +@jd:body + +
+
+ + +

This lesson teaches you to

+
    +
  1. Register a Listener
    2. +
+ + + +

You should also read

+ + + + +
+
+ +

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.

+ +

Register a Listener

+ +

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.

+ +

For example, you could add this code to your activity's +{@link android.app.Activity#onCreate onCreate()} method:

+ +
View decorView = getWindow().getDecorView();
+decorView.setOnSystemUiVisibilityChangeListener
+        (new View.OnSystemUiVisibilityChangeListener() {
+    @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.
+        }
+    }
+});
+ +

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.

diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 39386bc1cc66..347f2de5b60b 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -945,6 +945,34 @@ include the action bar on devices running Android 2.1 or higher." +
  • +
    + Managing the System UI +
    + +
    • + -- cgit v1.2.3-59-g8ed1b