Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Doc update: Managing System UI class" into klp-docs

Browse Source
This commit is contained in:
Scott Main
2013-10-31 21:23:23 +00:00
committed by Android (Google) Code Review
parent f0c2bfd1c7 cfd3047f42
commit 7d1d7fa33e
14 changed files with 597 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/html/images/training/low_profile_hide2x.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 370 KiB

BIN
docs/html/images/training/low_profile_show2x.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 370 KiB

BIN
docs/html/images/training/navigation-bar.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

BIN
docs/html/images/training/status-bar.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

BIN
docs/html/images/training/status_bar_hide.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

BIN
docs/html/images/training/status_bar_show.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

BIN
docs/html/images/training/system-ui.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 163 KiB

BIN
docs/html/images/transparent--bars@2x.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 292 KiB

89
docs/html/training/system-ui/dim.jd Normal file
View File

@@ -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>

90
docs/html/training/system-ui/index.jd Normal file
View File

@@ -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>

101
docs/html/training/system-ui/navigation.jd Normal file
View File

@@ -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>

220
docs/html/training/system-ui/status.jd Normal file
View File

@@ -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>

69
docs/html/training/system-ui/visibility.jd Normal file
View File

@@ -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>

28
docs/html/training/training_toc.cs
View File

@@ -969,6 +969,34 @@ include the action bar on devices running Android 2.1 or higher."
</ul> </ul>
</li> </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> </ul>
</li> </li>
<!-- End best UX and UI --> <!-- End best UX and UI -->