diff options
author | Katie McCormick <kmccormick@google.com> | 2013-09-27 15:52:14 -0700 |
---|---|---|
committer | Katie McCormick <kmccormick@google.com> | 2013-10-30 16:23:48 -0700 |
commit | d20c87c550524754956774004d1e7625d5e86c48 (patch) | |
tree | 113587788e91446b707ea00e093d4d777c7a9408 /docs/html/training | |
parent | 2d96a0d3424314b53b46b0fd6fd5b0dad71e7790 (diff) | |
download | frameworks_base-d20c87c550524754956774004d1e7625d5e86c48.zip frameworks_base-d20c87c550524754956774004d1e7625d5e86c48.tar.gz frameworks_base-d20c87c550524754956774004d1e7625d5e86c48.tar.bz2 |
Doc update: Managing System UI class
Change-Id: I8c8f8864411a4be64426e347351690078c922c1c
Diffstat (limited to 'docs/html/training')
-rw-r--r-- | docs/html/training/system-ui/dim.jd | 89 | ||||
-rw-r--r-- | docs/html/training/system-ui/index.jd | 90 | ||||
-rw-r--r-- | docs/html/training/system-ui/navigation.jd | 101 | ||||
-rw-r--r-- | docs/html/training/system-ui/status.jd | 220 | ||||
-rw-r--r-- | docs/html/training/system-ui/visibility.jd | 69 | ||||
-rw-r--r-- | docs/html/training/training_toc.cs | 28 |
6 files changed, 597 insertions, 0 deletions
diff --git a/docs/html/training/system-ui/dim.jd b/docs/html/training/system-ui/dim.jd new file mode 100644 index 0000000..7c365d7 --- /dev/null +++ b/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> diff --git a/docs/html/training/system-ui/index.jd b/docs/html/training/system-ui/index.jd new file mode 100644 index 0000000..7135a3d --- /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 + + + +<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>
\ 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 0000000..3843da3 --- /dev/null +++ b/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> diff --git a/docs/html/training/system-ui/status.jd b/docs/html/training/system-ui/status.jd new file mode 100644 index 0000000..25ee253 --- /dev/null +++ b/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> +<application + ... + android:theme="@android:style/Theme.Holo.NoActionBar.Fullscreen" > + ... +</application> +</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 { + + @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> diff --git a/docs/html/training/system-ui/visibility.jd b/docs/html/training/system-ui/visibility.jd new file mode 100644 index 0000000..c26092c --- /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 + +<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() { + @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> diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 39386bc..347f2de 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." </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 --> |