+ 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.
+ +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:
+ +
+
+
Figure 1. Dimmed system bars.
+ +Figure 2 shows the same gallery image, but with the system bars displayed:
+ +
+ 
+
Figure 2. Visible system 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 0000000000000..7135a3d450eb0 --- /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 + + + +
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. +
+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.
+ +
+Figure 1. Navigation bar.
+ + + +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:
+ +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 0000000000000..25ee253e3bfbb --- /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: +
+ +
+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. +
+ +
+Figure 2. Hidden status bar.
+ +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.
+ + +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:
+ +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.
+ +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 0000000000000..c26092c371993 --- /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 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.
+ +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 39386bc1cc667..347f2de5b60b3 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." +