Merge "Add link to HCE dev guide." into klp-docs
diff --git a/core/java/android/text/InputType.java b/core/java/android/text/InputType.java
index 6d066d6..c596388 100644
--- a/core/java/android/text/InputType.java
+++ b/core/java/android/text/InputType.java
@@ -46,9 +46,9 @@
* of text being given. Currently supported classes are:
* {@link #TYPE_CLASS_TEXT}, {@link #TYPE_CLASS_NUMBER},
* {@link #TYPE_CLASS_PHONE}, {@link #TYPE_CLASS_DATETIME}.
- * If the class is not one you
+ * <p>IME authors: If the class is not one you
* understand, assume {@link #TYPE_CLASS_TEXT} with NO variation
- * or flags.
+ * or flags.<p>
*/
public static final int TYPE_MASK_CLASS = 0x0000000f;
@@ -69,7 +69,10 @@
* This should be interpreted to mean that the target input connection
* is not rich, it can not process and show things like candidate text nor
* retrieve the current text, so the input method will need to run in a
- * limited "generate key events" mode.
+ * limited "generate key events" mode, if it supports it. Note that some
+ * input methods may not support it, for example a voice-based input
+ * method will likely not be able to generate key events even if this
+ * flag is set.
*/
public static final int TYPE_NULL = 0x00000000;
@@ -94,48 +97,70 @@
* Flag for {@link #TYPE_CLASS_TEXT}: capitalize all characters. Overrides
* {@link #TYPE_TEXT_FLAG_CAP_WORDS} and
* {@link #TYPE_TEXT_FLAG_CAP_SENTENCES}. This value is explicitly defined
- * to be the same as {@link TextUtils#CAP_MODE_CHARACTERS}.
+ * to be the same as {@link TextUtils#CAP_MODE_CHARACTERS}. Of course,
+ * this only affects languages where there are upper-case and lower-case letters.
*/
public static final int TYPE_TEXT_FLAG_CAP_CHARACTERS = 0x00001000;
/**
- * Flag for {@link #TYPE_CLASS_TEXT}: capitalize first character of
- * all words. Overrides {@link #TYPE_TEXT_FLAG_CAP_SENTENCES}. This
+ * Flag for {@link #TYPE_CLASS_TEXT}: capitalize the first character of
+ * every word. Overrides {@link #TYPE_TEXT_FLAG_CAP_SENTENCES}. This
* value is explicitly defined
- * to be the same as {@link TextUtils#CAP_MODE_WORDS}.
+ * to be the same as {@link TextUtils#CAP_MODE_WORDS}. Of course,
+ * this only affects languages where there are upper-case and lower-case letters.
*/
public static final int TYPE_TEXT_FLAG_CAP_WORDS = 0x00002000;
/**
- * Flag for {@link #TYPE_CLASS_TEXT}: capitalize first character of
+ * Flag for {@link #TYPE_CLASS_TEXT}: capitalize the first character of
* each sentence. This value is explicitly defined
- * to be the same as {@link TextUtils#CAP_MODE_SENTENCES}.
+ * to be the same as {@link TextUtils#CAP_MODE_SENTENCES}. For example
+ * in English it means to capitalize after a period and a space (note that other
+ * languages may have different characters for period, or not use spaces,
+ * or use different grammatical rules). Of course,
+ * this only affects languages where there are upper-case and lower-case letters.
*/
public static final int TYPE_TEXT_FLAG_CAP_SENTENCES = 0x00004000;
/**
* Flag for {@link #TYPE_CLASS_TEXT}: the user is entering free-form
- * text that should have auto-correction applied to it.
+ * text that should have auto-correction applied to it. Without this flag,
+ * the IME will not try to correct typos. You should always set this flag
+ * unless you really expect users to type non-words in this field, for
+ * example to choose a name for a character in a game.
+ * Contrast this with {@link #TYPE_TEXT_FLAG_AUTO_COMPLETE} and
+ * {@link #TYPE_TEXT_FLAG_NO_SUGGESTIONS}:
+ * {@code TYPE_TEXT_FLAG_AUTO_CORRECT} means that the IME will try to
+ * auto-correct typos as the user is typing, but does not define whether
+ * the IME offers an interface to show suggestions.
*/
public static final int TYPE_TEXT_FLAG_AUTO_CORRECT = 0x00008000;
/**
- * Flag for {@link #TYPE_CLASS_TEXT}: the text editor is performing
- * auto-completion of the text being entered based on its own semantics,
- * which it will present to the user as they type. This generally means
- * that the input method should not be showing candidates itself, but can
- * expect for the editor to supply its own completions/candidates from
+ * Flag for {@link #TYPE_CLASS_TEXT}: the text editor (which means
+ * the application) is performing auto-completion of the text being entered
+ * based on its own semantics, which it will present to the user as they type.
+ * This generally means that the input method should not be showing
+ * candidates itself, but can expect the editor to supply its own
+ * completions/candidates from
* {@link android.view.inputmethod.InputMethodSession#displayCompletions
* InputMethodSession.displayCompletions()} as a result of the editor calling
* {@link android.view.inputmethod.InputMethodManager#displayCompletions
* InputMethodManager.displayCompletions()}.
+ * Note the contrast with {@link #TYPE_TEXT_FLAG_AUTO_CORRECT} and
+ * {@link #TYPE_TEXT_FLAG_NO_SUGGESTIONS}:
+ * {@code TYPE_TEXT_FLAG_AUTO_COMPLETE} means the editor should show an
+ * interface for displaying suggestions, but instead of supplying its own
+ * it will rely on the Editor to pass completions/corrections.
*/
public static final int TYPE_TEXT_FLAG_AUTO_COMPLETE = 0x00010000;
/**
* Flag for {@link #TYPE_CLASS_TEXT}: multiple lines of text can be
* entered into the field. If this flag is not set, the text field
- * will be constrained to a single line.
+ * will be constrained to a single line. The IME may also choose not to
+ * display an enter key when this flag is not set, as there should be no
+ * need to create new lines.
*/
public static final int TYPE_TEXT_FLAG_MULTI_LINE = 0x00020000;
@@ -152,6 +177,16 @@
* do not contain words from the language and do not benefit from any
* dictionary-based completions or corrections. It overrides the
* {@link #TYPE_TEXT_FLAG_AUTO_CORRECT} value when set.
+ * Please avoid using this unless you are certain this is what you want.
+ * Many input methods need suggestions to work well, for example the ones
+ * based on gesture typing. Consider clearing
+ * {@link #TYPE_TEXT_FLAG_AUTO_CORRECT} instead if you just do not
+ * want the IME to correct typos.
+ * Note the contrast with {@link #TYPE_TEXT_FLAG_AUTO_CORRECT} and
+ * {@link #TYPE_TEXT_FLAG_AUTO_COMPLETE}:
+ * {@code TYPE_TEXT_FLAG_NO_SUGGESTIONS} means the IME should never
+ * show an interface to display suggestions. Most IMEs will also take this to
+ * mean they should not try to auto-correct what the user is typing.
*/
public static final int TYPE_TEXT_FLAG_NO_SUGGESTIONS = 0x00080000;
@@ -224,7 +259,9 @@
/**
* Variation of {@link #TYPE_CLASS_TEXT}: entering text for phonetic
- * pronunciation, such as a phonetic name field in contacts.
+ * pronunciation, such as a phonetic name field in contacts. This is mostly
+ * useful for languages where one spelling may have several phonetic
+ * readings, like Japanese.
*/
public static final int TYPE_TEXT_VARIATION_PHONETIC = 0x000000c0;
@@ -255,12 +292,13 @@
// ----------------------------------------------------------------------
/**
- * Class for numeric text. This class supports the following flag:
+ * Class for numeric text. This class supports the following flags:
* {@link #TYPE_NUMBER_FLAG_SIGNED} and
* {@link #TYPE_NUMBER_FLAG_DECIMAL}. It also supports the following
* variations: {@link #TYPE_NUMBER_VARIATION_NORMAL} and
- * {@link #TYPE_NUMBER_VARIATION_PASSWORD}. If you do not recognize
- * the variation, normal should be assumed.
+ * {@link #TYPE_NUMBER_VARIATION_PASSWORD}.
+ * <p>IME authors: If you do not recognize
+ * the variation, normal should be assumed.</p>
*/
public static final int TYPE_CLASS_NUMBER = 0x00000002;
@@ -318,7 +356,7 @@
* following variations:
* {@link #TYPE_DATETIME_VARIATION_NORMAL}
* {@link #TYPE_DATETIME_VARIATION_DATE}, and
- * {@link #TYPE_DATETIME_VARIATION_TIME},.
+ * {@link #TYPE_DATETIME_VARIATION_TIME}.
*/
public static final int TYPE_CLASS_DATETIME = 0x00000004;
diff --git a/core/java/android/view/inputmethod/EditorInfo.java b/core/java/android/view/inputmethod/EditorInfo.java
index 5146567..d4e005b 100644
--- a/core/java/android/view/inputmethod/EditorInfo.java
+++ b/core/java/android/view/inputmethod/EditorInfo.java
@@ -70,14 +70,14 @@
/**
* Bits of {@link #IME_MASK_ACTION}: the action key performs a "search"
* operation, taking the user to the results of searching for the text
- * the have typed (in whatever context is appropriate).
+ * they have typed (in whatever context is appropriate).
*/
public static final int IME_ACTION_SEARCH = 0x00000003;
/**
* Bits of {@link #IME_MASK_ACTION}: the action key performs a "send"
* operation, delivering the text to its target. This is typically used
- * when composing a message.
+ * when composing a message in IM or SMS where sending is immediate.
*/
public static final int IME_ACTION_SEND = 0x00000004;
@@ -89,22 +89,31 @@
/**
* Bits of {@link #IME_MASK_ACTION}: the action key performs a "done"
- * operation, typically meaning the IME will be closed.
+ * operation, typically meaning there is nothing more to input and the
+ * IME will be closed.
*/
public static final int IME_ACTION_DONE = 0x00000006;
/**
* Bits of {@link #IME_MASK_ACTION}: Like {@link #IME_ACTION_NEXT}, but
* for moving to the previous field. This will normally not be used to
- * specify an action (since it precludes {@link #IME_ACTION_NEXT}, but
+ * specify an action (since it precludes {@link #IME_ACTION_NEXT}), but
* can be returned to the app if it sets {@link #IME_FLAG_NAVIGATE_PREVIOUS}.
*/
public static final int IME_ACTION_PREVIOUS = 0x00000007;
/**
* Flag of {@link #imeOptions}: used to request that the IME never go
- * into fullscreen mode. Applications need to be aware that the flag is not
- * a guarantee, and not all IMEs will respect it.
+ * into fullscreen mode.
+ * By default, IMEs may go into full screen mode when they think
+ * it's appropriate, for example on small screens in landscape
+ * orientation where displaying a software keyboard may occlude
+ * such a large portion of the screen that the remaining part is
+ * too small to meaningfully display the application UI.
+ * If this flag is set, compliant IMEs will never go into full screen mode,
+ * and always leave some space to display the application UI.
+ * Applications need to be aware that the flag is not a guarantee, and
+ * some IMEs may ignore it.
*/
public static final int IME_FLAG_NO_FULLSCREEN = 0x2000000;
@@ -136,50 +145,56 @@
* Flag of {@link #imeOptions}: used to specify that the IME does not need
* to show its extracted text UI. For input methods that may be fullscreen,
* often when in landscape mode, this allows them to be smaller and let part
- * of the application be shown behind. Though there will likely be limited
- * access to the application available from the user, it can make the
- * experience of a (mostly) fullscreen IME less jarring. Note that when
- * this flag is specified the IME may <em>not</em> be set up to be able
- * to display text, so it should only be used in situations where this is
- * not needed.
+ * of the application be shown behind, through transparent UI parts in the
+ * fullscreen IME. The part of the UI visible to the user may not be responsive
+ * to touch because the IME will receive touch events, which may confuse the
+ * user; use {@link #IME_FLAG_NO_FULLSCREEN} instead for a better experience.
+ * Using this flag is discouraged and it may become deprecated in the future.
+ * Its meaning is unclear in some situations and it may not work appropriately
+ * on older versions of the platform.
*/
public static final int IME_FLAG_NO_EXTRACT_UI = 0x10000000;
/**
- * Flag of {@link #imeOptions}: used in conjunction with
- * {@link #IME_MASK_ACTION}, this indicates that the action should not
- * be available as an accessory button when the input method is full-screen.
- * Note that by setting this flag, there can be cases where the action
- * is simply never available to the user. Setting this generally means
- * that you think showing text being edited is more important than the
- * action you have supplied.
+ * Flag of {@link #imeOptions}: used in conjunction with one of the actions
+ * masked by {@link #IME_MASK_ACTION}, this indicates that the action
+ * should not be available as an accessory button on the right of the extracted
+ * text when the input method is full-screen. Note that by setting this flag,
+ * there can be cases where the action is simply never available to the
+ * user. Setting this generally means that you think that in fullscreen mode,
+ * where there is little space to show the text, it's not worth taking some
+ * screen real estate to display the action and it should be used instead
+ * to show more text.
*/
public static final int IME_FLAG_NO_ACCESSORY_ACTION = 0x20000000;
/**
- * Flag of {@link #imeOptions}: used in conjunction with
- * {@link #IME_MASK_ACTION}, this indicates that the action should not
- * be available in-line as a replacement for "enter" key. Typically this is
- * because the action has such a significant impact or is not recoverable
- * enough that accidentally hitting it should be avoided, such as sending
- * a message. Note that {@link android.widget.TextView} will automatically set this
- * flag for you on multi-line text views.
+ * Flag of {@link #imeOptions}: used in conjunction with one of the actions
+ * masked by {@link #IME_MASK_ACTION}. If this flag is not set, IMEs will
+ * normally replace the "enter" key with the action supplied. This flag
+ * indicates that the action should not be available in-line as a replacement
+ * for the "enter" key. Typically this is because the action has such a
+ * significant impact or is not recoverable enough that accidentally hitting
+ * it should be avoided, such as sending a message. Note that
+ * {@link android.widget.TextView} will automatically set this flag for you
+ * on multi-line text views.
*/
public static final int IME_FLAG_NO_ENTER_ACTION = 0x40000000;
/**
- * Flag of {@link #imeOptions}: used to request that the IME is capable of
+ * Flag of {@link #imeOptions}: used to request an IME that is capable of
* inputting ASCII characters. The intention of this flag is to ensure that
- * the user can type Roman alphabet characters in a {@link android.widget.TextView}
- * used for, typically, account ID or password input. It is expected that IMEs
- * normally are able to input ASCII even without being told so (such IMEs
- * already respect this flag in a sense), but there could be some cases they
- * aren't when, for instance, only non-ASCII input languagaes like Arabic,
- * Greek, Hebrew, Russian are enabled in the IME. Applications need to be
- * aware that the flag is not a guarantee, and not all IMEs will respect it.
+ * the user can type Roman alphabet characters in a {@link android.widget.TextView}.
+ * It is typically used for an account ID or password input. A lot of the time,
+ * IMEs are already able to input ASCII even without being told so (such IMEs
+ * already respect this flag in a sense), but there are cases when this is not
+ * the default. For instance, users of languages using a different script like
+ * Arabic, Greek, Hebrew or Russian typically have a keyboard that can't
+ * input ASCII characters by default. Applications need to be
+ * aware that the flag is not a guarantee, and some IMEs may not respect it.
* However, it is strongly recommended for IME authors to respect this flag
- * especially when their IME could end up with a state that has only non-ASCII
- * input languages enabled.
+ * especially when their IME could end up with a state where only languages
+ * using non-ASCII are enabled.
*/
public static final int IME_FLAG_FORCE_ASCII = 0x80000000;
@@ -209,8 +224,13 @@
/**
* In some cases an IME may be able to display an arbitrary label for
- * a command the user can perform, which you can specify here. You can
- * not count on this being used.
+ * a command the user can perform, which you can specify here. This is
+ * typically used as the label for the action to use in-line as a replacement
+ * for the "enter" key (see {@link #actionId}). Remember the key where
+ * this will be displayed is typically very small, and there are significant
+ * localization challenges to make this fit in all supported languages. Also
+ * you can not count absolutely on this being used, as some IMEs may
+ * ignore this.
*/
public CharSequence actionLabel = null;
@@ -224,13 +244,17 @@
/**
* The text offset of the start of the selection at the time editing
- * began; -1 if not known.
+ * began; -1 if not known. Keep in mind some IMEs may not be able
+ * to give their full feature set without knowing the cursor position;
+ * avoid passing -1 here if you can.
*/
public int initialSelStart = -1;
/**
* The text offset of the end of the selection at the time editing
- * began; -1 if not known.
+ * began; -1 if not known. Keep in mind some IMEs may not be able
+ * to give their full feature set without knowing the cursor position;
+ * avoid passing -1 here if you can.
*/
public int initialSelEnd = -1;
@@ -280,7 +304,7 @@
* Any extra data to supply to the input method. This is for extended
* communication with specific input methods; the name fields in the
* bundle should be scoped (such as "com.mydomain.im.SOME_FIELD") so
- * that they don't conflict with others. This field is can be
+ * that they don't conflict with others. This field can be
* filled in from the {@link android.R.attr#editorExtras}
* attribute of a TextView.
*/
diff --git a/core/java/android/view/inputmethod/InputConnection.java b/core/java/android/view/inputmethod/InputConnection.java
index 59330ca..3537aec 100644
--- a/core/java/android/view/inputmethod/InputConnection.java
+++ b/core/java/android/view/inputmethod/InputConnection.java
@@ -142,7 +142,11 @@
* conditions in implementing this call. An IME can make a change
* to the text and use this method right away; you need to make
* sure the returned value is consistent with the result of the
- * latest edits.
+ * latest edits. Also, you may return less than n characters if performance
+ * dictates so, but keep in mind IMEs are relying on this for many
+ * functions: you should not, for example, limit the returned value to
+ * the current line, and specifically do not return 0 characters unless
+ * the cursor is really at the start of the text.</p>
*
* @param n The expected length of the text.
* @param flags Supplies additional options controlling how the text is
@@ -176,7 +180,11 @@
* conditions in implementing this call. An IME can make a change
* to the text and use this method right away; you need to make
* sure the returned value is consistent with the result of the
- * latest edits.</p>
+ * latest edits. Also, you may return less than n characters if performance
+ * dictates so, but keep in mind IMEs are relying on this for many
+ * functions: you should not, for example, limit the returned value to
+ * the current line, and specifically do not return 0 characters unless
+ * the cursor is really at the end of the text.</p>
*
* @param n The expected length of the text.
* @param flags Supplies additional options controlling how the text is
diff --git a/docs/downloads/training/OpenGLES.zip b/docs/downloads/training/OpenGLES.zip
index 862ae1f..5bdfee3 100644
--- a/docs/downloads/training/OpenGLES.zip
+++ b/docs/downloads/training/OpenGLES.zip
Binary files differ
diff --git a/docs/html/distribute/googleplay/edu/index.jd b/docs/html/distribute/googleplay/edu/index.jd
index 8a60cb9..487028f 100644
--- a/docs/html/distribute/googleplay/edu/index.jd
+++ b/docs/html/distribute/googleplay/edu/index.jd
@@ -19,7 +19,7 @@
teacher-approved, educational apps and videos on Play Store. Teachers can filter
content by subject matter, grade and other criteria. Bulk purchase and instant
distribution let educators bring your apps directly to classrooms and schools.</p>
- <p>If have an educational app, be part of Google Play for Education.</p>
+ <p>If you have an educational app, join Google Play for Education.</p>
<p><a class="button" href="{@docRoot}distribute/googleplay/edu/about.html">Learn More</a></p>
</div>
</div>
diff --git a/docs/html/google/play-services/setup.jd b/docs/html/google/play-services/setup.jd
index fb656b7..5c8c63b 100644
--- a/docs/html/google/play-services/setup.jd
+++ b/docs/html/google/play-services/setup.jd
@@ -110,6 +110,14 @@
<img src="{@docRoot}images/tools/sync-project.png" style="vertical-align:bottom;margin:0;height:19px" />
in the toolbar.
</li>
+ <li>Open your app's manifest file and add the following tag as a child of the <a
+href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a>
+element:
+<pre>
+<meta-data android:name="com.google.android.gms.version"
+ android:value="@integer/google_play_services_version" />
+</pre>
+ </li>
</ol>
<p>You can now begin developing features with the
@@ -129,6 +137,16 @@
You should be referencing a copy of the library that you copied to your development
workspace—you should not reference the library directly from the Android SDK directory.</p>
+<p>After you've added the Google Play services library as a dependency for your app project,
+open your app's manifest file and add the following tag as a child of the <a
+href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a>
+element:
+<pre>
+<meta-data android:name="com.google.android.gms.version"
+ android:value="@integer/google_play_services_version" />
+</pre>
+
+
<p>Once you've set up your project to reference the library project,
you can begin developing features with the
<a href="{@docRoot}reference/gms-packages.html">Google Play services APIs</a>.</p>
diff --git a/docs/html/google/play/billing/gp-purchase-status-api.jd b/docs/html/google/play/billing/gp-purchase-status-api.jd
index 25ef28b..4d80680 100644
--- a/docs/html/google/play/billing/gp-purchase-status-api.jd
+++ b/docs/html/google/play/billing/gp-purchase-status-api.jd
@@ -58,7 +58,7 @@
<p>The Purchase Status API is part of the <a
href="https://developers.google.com/android-publisher/v1_1/">Google Play Android
-Developer API v1.1</a>, available through the Google APIs console. The new version
+Developer API v1.1</a>, available through the Google Cloud Console. The new version
of the API supersedes the v1 API, which is deprecated. If you are using the v1
API, please migrate your operations to the v1.1 API as soon as possible.</p>
@@ -66,7 +66,7 @@
<h2 id="using">Using the API</h2>
<p>To use the API, you must first register a project at the <a
-href="https://code.google.com/apis/console">Google APIs Console</a> and receive
+href="https://cloud.google.com/console">Google Cloud Console</a> and receive
a Client ID and shared secret that your app will present when calling the
API. All calls are authenticated with OAuth 2.0.</p>
@@ -93,9 +93,9 @@
subscription-validation needs, assuming that you follow the recommendation in
this section.</p>
-<p>If you need to request a higher limit for your application, please use the
-“Request more” link in the <a
-href="https://code.google.com/apis/console/#:quotas">Google APIs Console</a>.
+<p>If you need to request a higher limit for your application, see the
+instructions in the <a
+href="https://developers.google.com/console/help/new/#trafficcontrols">Google Cloud Console Help</a>.
Also, please read the section below on design best practices for minimizing your
use of the API.</p>
diff --git a/docs/html/guide/topics/manifest/uses-configuration-element.jd b/docs/html/guide/topics/manifest/uses-configuration-element.jd
index 810975e..e9a0ba4 100644
--- a/docs/html/guide/topics/manifest/uses-configuration-element.jd
+++ b/docs/html/guide/topics/manifest/uses-configuration-element.jd
@@ -6,18 +6,18 @@
<!-- ##api level 3## see comment below -->
<!-- the "no___" values are nonsensical if they mean "doesn't work on devices with a
-keyboard / navigation control / touch screen." Dianne says that that's what they mean and
-that they therefore should be eliminated. Suchi says that they mean "doesn't require a
+keyboard / navigation control / touch screen." Dianne says that that's what they mean and
+that they therefore should be eliminated. Suchi says that they mean "doesn't require a
keyboard / navigation control / touch screen to work." But then what does "undefined" mean?
Seems like some API change is in the works, either eliminating the "no___" values or
-"undefined". Since it's unclear what the change will be, I've chosen to document the "no___"
+"undefined". Since it's unclear what the change will be, I've chosen to document the "no___"
and "undefined" attributes using the same language, which is surely wrong but may make it
-easier to update the doc when the change is made. -->
+easier to update the doc when the change is made... Nov 2013, this still seems unresolved. -->
<dl class="xml">
<dt>syntax:</dt>
<dd><pre class="stx"><uses-configuration
- android:<a href="#five">reqFiveWayNav</a>=["true" | "false"]
+ android:<a href="#five">reqFiveWayNav</a>=["true" | "false"]
android:<a href="#hard">reqHardKeyboard</a>=["true" | "false"]
android:<a href="#kbd">reqKeyboardType</a>=["undefined" | "nokeys" | "qwerty" | "twelvekey"]
android:<a href="#nav">reqNavigation</a>=["undefined" | "nonav" | "dpad" | "trackball" | "wheel"]
@@ -27,38 +27,35 @@
<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd>
<dt>description:</dt>
-<dd>Indicates what hardware and software features the application requires.
-For example, an application might specify that it requires a physical keyboard
+<dd>Indicates what hardware and software features the application requires.
+For example, an application might specify that it requires a physical keyboard
or a particular navigation device, like a trackball. The specification is
used to avoid installing the application on devices where it will not work.
-<p>
-If an application can work with different device configurations, it
-should include separate {@code <uses-configuration>} declarations for
-each one. Each declaration must be complete. For example, if an application
-requires a five-way navigation control, a touch screen that can be operated
-with a finger, and either a standard QWERTY keyboard or a numeric 12-key
-keypad like those found on most phones, it would specify these requirements
-with two {@code <uses-configuration>} elements as follows:
-</p>
+<p class="note"><strong>Note: Most apps should not use this manifest tag.</strong> You should
+<em>always</em> support input with a directional pad (d-pad) in order to assist sight-impaired
+users and support devices that provide d-pad input in addition to or instead of touch. For
+information about how to support d-pad input in your app, read <a href=
+"{@docRoot}guide/topics/ui/accessibility/apps.html#focus-nav">Enabling Focus Navigation</a>. If
+your app absolutely cannot function without a touchscreen, then instead use the <a href=
+"{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> tag to
+declare the required touchscreen type, ranging from {@code "android.hardware.faketouch"} for basic
+touch-style events to more advanced touch types such as {@code
+"android.hardware.touchscreen.multitouch.jazzhand"} for distinct input from multiple fingers.</p>
-<pre><uses-configuration android:reqFiveWayNav="true" android:reqTouchScreen="finger"
- android:reqKeyboardType="qwerty" />
-<uses-configuration android:reqFiveWayNav="true" android:reqTouchScreen="finger"
- android:reqKeyboardType="twelvekey" /></pre></dd>
<dt>attributes:</dt>
<dd><dl class="attr">
<dt><a name="five"></a>{@code android:reqFiveWayNav}</dt>
-<dd>Whether or not the application requires a five-way navigation control
+<dd>Whether or not the application requires a five-way navigation control
— "{@code true}" if it does, and "{@code false}" if not. A five-way
-control is one that can move the selection up, down, right, or left, and
-also provides a way of invoking the current selection. It could be a
-D-pad (directional pad), trackball, or other device.
+control is one that can move the selection up, down, right, or left, and
+also provides a way of invoking the current selection. It could be a
+D-pad (directional pad), trackball, or other device.
<p>
If an application requires a directional control, but not a control of a
-particular type, it can set this attribute to "{@code true}" and ignore
+particular type, it can set this attribute to "{@code true}" and ignore
the <code><a href="#nav">reqNavigation</a></code> attribute. However,
if it requires a particular type of directional control, it can ignore
this attribute and set {@code reqNavigation} instead.
@@ -69,10 +66,10 @@
"{@code true}" if it does, and "{@code false}" if not.</dd>
<dt><a name="kbd"></a>{@code android:reqKeyboardType}</dt>
-<dd>The type of keyboard the application requires, if any at all.
-This attribute does not distinguish between hardware and software
+<dd>The type of keyboard the application requires, if any at all.
+This attribute does not distinguish between hardware and software
keyboards. If a hardware keyboard of a certain type is required,
-specify the type here and also set the {@code reqHardKeyboard} attribute
+specify the type here and also set the {@code reqHardKeyboard} attribute
to "{@code true}".
<p>
@@ -85,8 +82,8 @@
<th>Description</th>
</tr><tr>
<td>"{@code undefined}"</td>
- <td>The application does not require a keyboard.
- (A keyboard requirement is not defined.)
+ <td>The application does not require a keyboard.
+ (A keyboard requirement is not defined.)
This is the default value.</td>
</tr><tr>
<td>"{@code nokeys}"</td>
@@ -96,14 +93,14 @@
<td>The application requires a standard QWERTY keyboard.</td>
</tr><tr>
<td>"{@code twelvekey}"</td>
- <td>The application requires a twelve-key keypad, like those on most
- phones — with keys for the digits from {@code 0} through
+ <td>The application requires a twelve-key keypad, like those on most
+ phones — with keys for the digits from {@code 0} through
{@code 9} plus star ({@code *}) and pound ({@code #}) keys.</td>
</tr>
</table></dd>
<dt><a name="nav"></a>{@code android:reqNavigation}</dt>
-<dd>The navigation device required by the application, if any. The value
+<dd>The navigation device required by the application, if any. The value
must be one of the following strings:
<table>
@@ -112,8 +109,8 @@
<th>Description</th>
</tr><tr>
<td>"{@code undefined}"</td>
- <td>The application does not require any type of navigation control.
- (The navigation requirement is not defined.)
+ <td>The application does not require any type of navigation control.
+ (The navigation requirement is not defined.)
This is the default value.</td>
</tr><tr>
<td>"{@code nonav}"</td>
@@ -132,14 +129,14 @@
<p>
If an application requires a navigational control, but the exact type of
-control doesn't matter, it can set the
+control doesn't matter, it can set the
<code><a href="#five">reqFiveWayNav</a></code> attribute to "{@code true}"
rather than set this one.
</p></dd>
<dt><a name="touch"></a>{@code android:reqTouchScreen}</dt>
<dd>The type of touch screen the application requires, if any at all.
-The value must be one of the following strings:
+The value must be one of the following strings:
<table>
<tr>
@@ -147,7 +144,7 @@
<th>Description</th>
</tr><tr>
<td>"{@code undefined}"</td>
- <td>The application doesn't require a touch screen.
+ <td>The application doesn't require a touch screen.
(The touch screen requirement is undefined.)
This is the default value.</td>
</tr><tr>
@@ -158,7 +155,14 @@
<td>The application requires a touch screen that's operated with a stylus.</td>
</tr><tr>
<td>"{@code finger}"</td>
- <td>The application requires a touch screen that can be operated with a finger.</td>
+ <td>The application requires a touch screen that can be operated with a finger.
+
+ <p class="note"><strong>Note:</strong> If some type of touch input is required for your app,
+ you should instead use the
+ <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code
+ <uses-feature>}</a> tag to declare the required touchscreen
+ type, beginning with {@code "android.hardware.faketouch"} for basic touch-style events.</p>
+ </td>
</tr>
</table></dd>
</dl></dd>
@@ -172,7 +176,7 @@
<ul>
<li><code><a href="{@docRoot}guide/topics/manifest/activity-element.html#config">configChanges</a></code>
attribute of the
-<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>
+<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>
element</dd></li>
<li>{@link android.content.pm.ConfigurationInfo}</li>
</ul>
diff --git a/docs/html/images/opengl/ogl-triangle-projected.png b/docs/html/images/opengl/ogl-triangle-projected.png
index d10bbdc..4b18b98 100644
--- a/docs/html/images/opengl/ogl-triangle-projected.png
+++ b/docs/html/images/opengl/ogl-triangle-projected.png
Binary files differ
diff --git a/docs/html/images/opengl/ogl-triangle-touch.png b/docs/html/images/opengl/ogl-triangle-touch.png
index 35177a4..8323dd9 100644
--- a/docs/html/images/opengl/ogl-triangle-touch.png
+++ b/docs/html/images/opengl/ogl-triangle-touch.png
Binary files differ
diff --git a/docs/html/images/opengl/ogl-triangle.png b/docs/html/images/opengl/ogl-triangle.png
index 3d4a385..66047ab 100644
--- a/docs/html/images/opengl/ogl-triangle.png
+++ b/docs/html/images/opengl/ogl-triangle.png
Binary files differ
diff --git a/docs/html/images/training/imm-states.png b/docs/html/images/training/imm-states.png
new file mode 100644
index 0000000..59c4092
--- /dev/null
+++ b/docs/html/images/training/imm-states.png
Binary files differ
diff --git a/docs/html/images/training/imm-sticky.png b/docs/html/images/training/imm-sticky.png
new file mode 100644
index 0000000..31b118a
--- /dev/null
+++ b/docs/html/images/training/imm-sticky.png
Binary files differ
diff --git a/docs/html/images/training/system-ui.png b/docs/html/images/training/system-ui.png
index a3aea65..2c13c75 100644
--- a/docs/html/images/training/system-ui.png
+++ b/docs/html/images/training/system-ui.png
Binary files differ
diff --git a/docs/html/sdk/win-usb.jd b/docs/html/sdk/win-usb.jd
index 5ca38c6..c287a0c 100644
--- a/docs/html/sdk/win-usb.jd
+++ b/docs/html/sdk/win-usb.jd
@@ -191,27 +191,19 @@
</div>
</div>
-<p>The Google USB Driver is for <strong>Windows only</strong> and provides the
-necessary drivers for the following devices:</p>
- <ul>
- <li>ADP1 / T-Mobile G1*</li>
- <li>ADP2 / Google Ion / T-Mobile myTouch 3G*</li>
- <li>Verizon Droid*</li>
- <li>Nexus One</li>
- <li>Nexus S</li>
- <li>Nexus 4</li>
- <li>Nexus 7</li>
- <li>Nexus 10</li>
- </ul>
- <p>* <em>Or similar hardware on other carriers</em></p>
-
- <p>All other devices require Windows drivers provided by the respective hardware manufacturer,
- as listed in the <a href="{@docRoot}tools/extras/oem-usb.html">OEM USB Drivers</a> document.</p>
-
- <p>The Galaxy Nexus driver is distributed by <a
+<p>The Google USB Driver is <strong>required for Windows only</strong> in order to perform
+<a href="{@docRoot}tools/help/adb.html">adb</a> debugging with any of
+the <strong>Google Nexus devices</strong>. The one exception is the
+Galaxy Nexus: the driver for Galaxy Nexus is distributed by <a
href="http://www.samsung.com/us/support/downloads/verizon-wireless/SCH-I515MSAVZW">Samsung</a>
(listed as model SCH-I515).</p>
+<p>Windows drivers for all other devices are provided by the respective hardware
+manufacturer, as listed in the <a href="{@docRoot}tools/extras/oem-usb.html">OEM USB Drivers</a>
+document.</p>
+
+
+
<p class="note"><strong>Note:</strong>
If you're developing on Mac OS X or Linux, then you <strong>do not</strong> need to install a USB
driver. To start developing with your device, read
diff --git a/docs/html/tools/support-library/setup.jd b/docs/html/tools/support-library/setup.jd
index 73d9468..2d2065a 100644
--- a/docs/html/tools/support-library/setup.jd
+++ b/docs/html/tools/support-library/setup.jd
@@ -180,8 +180,8 @@
file and select <strong>Build Path > Add to Build Path</strong>. For example, when
creating the the v7 appcompat project, add both the {@code android-support-v4.jar} and
{@code android-support-v7-appcompat.jar} files to the build path.</li>
- <li>Right-click the project and select <strong>Build Path > Configure Build Path</strong>.
- </li>
+ <li>Right-click the library project folder and select <strong>Build Path > Configure
+ Build Path</strong>.</li>
<li>In the <strong>Order and Export</strong> tab, check the <code>.jar</code> files you just
added to the build path, so they are available to projects that depend on this library
project. For example, the {@code appcompat} project requires you to export both the
@@ -197,12 +197,13 @@
<p>Add the library to your application project:</p>
<ol>
- <li>In the Project Explorer, right-click your project and select <strong>Properties</strong>.
- <li>In the Library pane, click <strong>Add</strong>.
+ <li>In the Project Explorer, right-click your project and select <strong>Properties</strong>.</li>
+ <li>In the category panel on the left side of the dialog, select <strong>Android</strong>.</li>
+ <li>In the Library pane, click the <strong>Add</strong> button.</li>
<li>Select the library project and click <strong>OK</strong>. For example, the
{@code appcompat} project should be listed as <strong>android-support-v7-appcompat</strong>.
</li>
- <li>In the properties window, click <strong>OK</strong>.
+ <li>In the properties window, click <strong>OK</strong>.</li>
</ol>
</div>
diff --git a/docs/html/training/graphics/opengl/draw.jd b/docs/html/training/graphics/opengl/draw.jd
index 156ff70..ba00627 100644
--- a/docs/html/training/graphics/opengl/draw.jd
+++ b/docs/html/training/graphics/opengl/draw.jd
@@ -122,7 +122,7 @@
get created once and then cached for later use.</p>
<pre>
-public Triangle() {
+public class Triangle() {
...
int vertexShader = loadShader(GLES20.GL_VERTEX_SHADER, vertexShaderCode);
diff --git a/docs/html/training/graphics/opengl/environment.jd b/docs/html/training/graphics/opengl/environment.jd
index e1e2c8a..77faabf 100644
--- a/docs/html/training/graphics/opengl/environment.jd
+++ b/docs/html/training/graphics/opengl/environment.jd
@@ -92,7 +92,7 @@
{@link android.opengl.GLSurfaceView} as its primary view:</p>
<pre>
-public class OpenGLES20 extends Activity {
+public class OpenGLES20Activity extends Activity {
private GLSurfaceView mGLView;
@@ -190,11 +190,11 @@
gray background in the {@link android.opengl.GLSurfaceView}:</p>
<pre>
-public class MyGL20Renderer implements GLSurfaceView.Renderer {
+public class MyGLRenderer implements GLSurfaceView.Renderer {
public void onSurfaceCreated(GL10 unused, EGLConfig config) {
// Set the background frame color
- GLES20.glClearColor(0.5f, 0.5f, 0.5f, 1.0f);
+ GLES20.glClearColor(0.0f, 0.0f, 0.0f, 1.0f);
}
public void onDrawFrame(GL10 unused) {
diff --git a/docs/html/training/graphics/opengl/motion.jd b/docs/html/training/graphics/opengl/motion.jd
index af70de0..fbcdd7f 100644
--- a/docs/html/training/graphics/opengl/motion.jd
+++ b/docs/html/training/graphics/opengl/motion.jd
@@ -53,16 +53,20 @@
private float[] mRotationMatrix = new float[16];
public void onDrawFrame(GL10 gl) {
...
+ float[] scratch = new float[16];
+
// Create a rotation transformation for the triangle
long time = SystemClock.uptimeMillis() % 4000L;
float angle = 0.090f * ((int) time);
Matrix.setRotateM(mRotationMatrix, 0, angle, 0, 0, -1.0f);
// Combine the rotation matrix with the projection and camera view
- Matrix.multiplyMM(mMVPMatrix, 0, mRotationMatrix, 0, mMVPMatrix, 0);
+ // Note that the mMVPMatrix factor *must be first* in order
+ // for the matrix multiplication product to be correct.
+ Matrix.multiplyMM(scratch, 0, mMVPMatrix, 0, mRotationMatrix, 0);
// Draw triangle
- mTriangle.draw(mMVPMatrix);
+ mTriangle.draw(scratch);
}
</pre>
@@ -82,8 +86,9 @@
<pre>
public MyGLSurfaceView(Context context) {
...
- // Render the view only when there is a change in the drawing data
- //setRenderMode(GLSurfaceView.RENDERMODE_WHEN_DIRTY); // comment out for auto-rotation
+ // Render the view only when there is a change in the drawing data.
+ // To allow the triangle to rotate automatically, this line is commented out:
+ <strong>//setRenderMode(GLSurfaceView.RENDERMODE_WHEN_DIRTY);</strong>
}
</pre>
diff --git a/docs/html/training/graphics/opengl/projection.jd b/docs/html/training/graphics/opengl/projection.jd
index 2a91093..b09e74c 100644
--- a/docs/html/training/graphics/opengl/projection.jd
+++ b/docs/html/training/graphics/opengl/projection.jd
@@ -79,12 +79,12 @@
// this projection matrix is applied to object coordinates
// in the onDrawFrame() method
- Matrix.frustumM(mProjMatrix, 0, -ratio, ratio, -1, 1, 3, 7);
+ Matrix.frustumM(mProjectionMatrix, 0, -ratio, ratio, -1, 1, 3, 7);
}
</pre>
-<p>This code populates a projection matrix, {@code mProjMatrix} which you can then combine with a
-camera view transformation in the {@link android.opengl.GLSurfaceView.Renderer#onDrawFrame
+<p>This code populates a projection matrix, {@code mProjectionMatrix} which you can then combine
+with a camera view transformation in the {@link android.opengl.GLSurfaceView.Renderer#onDrawFrame
onDrawFrame()} method, which is shown in the next section.</p>
<p class="note"><strong>Note:</strong> Just applying a projection transformation to your
@@ -104,12 +104,11 @@
@Override
public void onDrawFrame(GL10 unused) {
...
-
// Set the camera position (View matrix)
- Matrix.setLookAtM(mVMatrix, 0, 0, 0, -3, 0f, 0f, 0f, 0f, 1.0f, 0.0f);
+ Matrix.setLookAtM(mViewMatrix, 0, 0, 0, -3, 0f, 0f, 0f, 0f, 1.0f, 0.0f);
// Calculate the projection and view transformation
- Matrix.multiplyMM(mMVPMatrix, 0, mProjMatrix, 0, mVMatrix, 0);
+ Matrix.multiplyMM(mMVPMatrix, 0, mProjectionMatrix, 0, mViewMatrix, 0);
// Draw shape
mTriangle.draw(mMVPMatrix);
@@ -130,7 +129,7 @@
// get handle to shape's transformation matrix
mMVPMatrixHandle = GLES20.glGetUniformLocation(mProgram, "uMVPMatrix");
- // Apply the projection and view transformation
+ // Pass the projection and view transformation to the shader
GLES20.glUniformMatrix4fv(mMVPMatrixHandle, 1, false, mvpMatrix, 0);
// Draw the triangle
@@ -139,7 +138,7 @@
}
</pre>
-<p>Once you have correctly calulated and applied the projection and camera view transformations,
+<p>Once you have correctly calculated and applied the projection and camera view transformations,
your graphic objects are drawn in correct proportions and should look like this:</p>
diff --git a/docs/html/training/graphics/opengl/shapes.jd b/docs/html/training/graphics/opengl/shapes.jd
index 98381cc..b960bb7 100644
--- a/docs/html/training/graphics/opengl/shapes.jd
+++ b/docs/html/training/graphics/opengl/shapes.jd
@@ -50,16 +50,16 @@
OpenGL ES graphics pipeline for processing.</p>
<pre>
-class Triangle {
+public class Triangle {
private FloatBuffer vertexBuffer;
// number of coordinates per vertex in this array
static final int COORDS_PER_VERTEX = 3;
- static float triangleCoords[] = { // in counterclockwise order:
- 0.0f, 0.622008459f, 0.0f, // top
- -0.5f, -0.311004243f, 0.0f, // bottom left
- 0.5f, -0.311004243f, 0.0f // bottom right
+ static float triangleCoords[] = { // in counterclockwise order:
+ 0.0f, 0.622008459f, 0.0f, // top
+ -0.5f, -0.311004243f, 0.0f, // bottom left
+ 0.5f, -0.311004243f, 0.0f // bottom right
};
// Set color with red, green, blue and alpha (opacity) values
@@ -112,17 +112,18 @@
OpenGL ES graphics pipeline how to draw these vertices. Here’s the code for this shape:</p>
<pre>
-class Square {
+public class Square {
private FloatBuffer vertexBuffer;
private ShortBuffer drawListBuffer;
// number of coordinates per vertex in this array
static final int COORDS_PER_VERTEX = 3;
- static float squareCoords[] = { -0.5f, 0.5f, 0.0f, // top left
- -0.5f, -0.5f, 0.0f, // bottom left
- 0.5f, -0.5f, 0.0f, // bottom right
- 0.5f, 0.5f, 0.0f }; // top right
+ static float squareCoords[] = {
+ -0.5f, 0.5f, 0.0f, // top left
+ -0.5f, -0.5f, 0.0f, // bottom left
+ 0.5f, -0.5f, 0.0f, // bottom right
+ 0.5f, 0.5f, 0.0f }; // top right
private short drawOrder[] = { 0, 1, 2, 0, 2, 3 }; // order to draw vertices
diff --git a/docs/html/training/graphics/opengl/touch.jd b/docs/html/training/graphics/opengl/touch.jd
index c058a59..4c9f0c7 100644
--- a/docs/html/training/graphics/opengl/touch.jd
+++ b/docs/html/training/graphics/opengl/touch.jd
@@ -75,7 +75,9 @@
dy = dy * -1 ;
}
- mRenderer.mAngle += (dx + dy) * TOUCH_SCALE_FACTOR; // = 180.0f / 320
+ mRenderer.setAngle(
+ mRenderer.getAngle() +
+ ((dx + dy) * TOUCH_SCALE_FACTOR); // = 180.0f / 320
requestRender();
}
@@ -123,16 +125,20 @@
<pre>
public void onDrawFrame(GL10 gl) {
...
+ float[] scratch = new float[16];
+
// Create a rotation for the triangle
// long time = SystemClock.uptimeMillis() % 4000L;
// float angle = 0.090f * ((int) time);
<strong>Matrix.setRotateM(mRotationMatrix, 0, mAngle, 0, 0, -1.0f);</strong>
// Combine the rotation matrix with the projection and camera view
- Matrix.multiplyMM(mMVPMatrix, 0, mRotationMatrix, 0, mMVPMatrix, 0);
+ // Note that the mMVPMatrix factor *must be first* in order
+ // for the matrix multiplication product to be correct.
+ Matrix.multiplyMM(scratch, 0, mMVPMatrix, 0, mRotationMatrix, 0);
// Draw triangle
- mTriangle.draw(mMVPMatrix);
+ mTriangle.draw(scratch);
}
</pre>
diff --git a/docs/html/training/system-ui/dim.jd b/docs/html/training/system-ui/dim.jd
index 7c365d7..f28c948 100644
--- a/docs/html/training/system-ui/dim.jd
+++ b/docs/html/training/system-ui/dim.jd
@@ -29,6 +29,14 @@
</li>
</ul>
+<h2>Try it out</h2>
+
+<div class="download-box">
+ <a href="{@docRoot}samples/ImmersiveMode/index.html"
+class="button">Get the sample</a>
+ <p class="filename">ImmersiveMode sample</p>
+</div>
+
</div>
</div>
diff --git a/docs/html/training/system-ui/immersive.jd b/docs/html/training/system-ui/immersive.jd
new file mode 100644
index 0000000..21672c8
--- /dev/null
+++ b/docs/html/training/system-ui/immersive.jd
@@ -0,0 +1,285 @@
+page.title=Using Immersive Full-Screen Mode
+
+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="#compare">Choose an Approach</a></li>
+ <li><a href="#nonsticky">Use IMMERSIVE</a></li>
+ <li><a href="#sticky">Use IMMERSIVE_STICKY</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/patterns/fullscreen.html">
+ Android Design Guide
+ </a>
+ </li>
+</ul>
+
+
+
+<h2>Try it out</h2>
+
+<div class="download-box">
+ <a href="{@docRoot}samples/ImmersiveMode/index.html"
+class="button">Get the sample</a>
+ <p class="filename">ImmersiveMode sample</p>
+</div>
+
+</div>
+</div>
+
+<a class="notice-developers-video wide" href="http://www.youtube.com/watch?v=cBi8fjv90E4">
+<div>
+ <h3>Video</h3>
+ <p>DevBytes: Android 4.4 Immersive Mode</p>
+</div>
+</a>
+
+<p>Android 4.4 (API Level 19) introduces a new
+{@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE} flag for
+{@link android.view.View#setSystemUiVisibility setSystemUiVisibility()} that lets your app
+go truly "full screen." This flag, when combined with the
+{@link android.view.View#SYSTEM_UI_FLAG_HIDE_NAVIGATION} and
+{@link android.view.View#SYSTEM_UI_FLAG_FULLSCREEN} flags, hides the navigation and status
+bars and lets your app capture all touch events on the screen.</p>
+
+<p>When immersive full-screen mode is
+enabled, your activity continues to receive all touch events. The user can reveal the
+system bars with an inward swipe along the region where the system bars normally appear.
+This clears the {@link android.view.View#SYSTEM_UI_FLAG_HIDE_NAVIGATION} flag
+(and the {@link android.view.View#SYSTEM_UI_FLAG_FULLSCREEN} flag, if applied) so the
+system bars become visible. This also triggers your
+{@link android.view.View.OnSystemUiVisibilityChangeListener},
+if set. However, if you'd like the system bars to automatically hide
+again after a few moments, you can instead use the
+{@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE_STICKY} flag. Note that the
+"sticky" version of the flag doesn't trigger any listeners, as system bars temporarily
+shown in this mode are in a transient state.
+</p>
+
+ <p>When you use {@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE IMMERSIVE} or
+ {@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE_STICKY IMMERSIVE_STICKY},
+ the system UI stays hidden, even while users are interacting with your
+app or game. You can capture touch events from anywhere across the screen, even areas that
+would otherwise be occupied by the system bars. This gives you a great way to create a
+larger, richer, more <a href="{@docRoot}design/patterns/fullscreen.html">
+immersive</a> UI in your app or game and reduce visual distraction at the same time.</p>
+
+<p>Figure 1 illustrates the different "immersive mode" states:</p>
+
+ <img src="{@docRoot}images/training/imm-states.png"
+ alt="system bars">
+<p class="img-caption"><strong>Figure 1.</strong> Immersive mode states.</p>
+
+<p>In figure 1:</p>
+<ol>
+<li><strong>Non-immersive mode</strong>—This is how the app
+appears before it enters immersive mode. It is also how the app appears if you use the
+{@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE IMMERSIVE} flag, and the user swipes to
+display the system bars, thereby clearing the {@link android.view.View#SYSTEM_UI_FLAG_HIDE_NAVIGATION} and
+{@link android.view.View#SYSTEM_UI_FLAG_FULLSCREEN} flags. Once these flags are cleared, the system
+bars reappear and remain visible.</li>
+
+<p>Note that it's best practice to
+ keep all UI controls in sync with the system bars, to minimize the
+ number of states your screen can be in. This provides a more seamless user experience. So
+ here all UI controls are displayed along with the status bars. Once the app enters
+ immersive mode, the UI controls are hidden along with the system bars.
+ To ensure that your UI visibility stays in sync with system bar visibility, make sure to
+ provide an appropriate {@link android.view.View.OnSystemUiVisibilityChangeListener}
+ to watch for changes, as described in
+ <a href="visibility.html">Responding to UI Visibility Changes</a>.</p></li>
+
+<li><strong>Reminder bubble</strong>—The system displays a reminder bubble
+the first time users enter
+immersive mode in your app. The reminder bubble reminds users how to display
+the system bars.
+<p class="note"><strong>Note:</strong> If you want to force the reminder bubble to appear
+for testing purposes, you can do so by putting the app in immersive mode, turning off the
+screen with the power button, and then turning the screen back on again within 5 seconds.
+</p></li>
+
+<li><strong>Immersive mode</strong>—This is the app in immersive mode, with the
+system bars and other UI controls hidden. You can achieve this state with either
+{@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE IMMERSIVE} or
+ {@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE_STICKY IMMERSIVE_STICKY}. </li>
+
+<li><strong>Sticky flag</strong>—This is the UI you see if you use the
+{@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE_STICKY IMMERSIVE_STICKY} flag,
+and the user swipes to display the system bars. Semi-transparent bars temporarily appear and then
+hide again. The act of swiping doesn't clear any flags, nor does it trigger your
+system UI visibility change listeners, because the transient appearance of the system bars isn't
+considered a UI visibility change.</li>
+</ol>
+
+<p class="note"><strong>Note:</strong> Remember that the "immersive" flags only take effect
+if you use them in conjunction with {@link android.view.View#SYSTEM_UI_FLAG_HIDE_NAVIGATION},
+{@link android.view.View#SYSTEM_UI_FLAG_FULLSCREEN}, or
+ both. You can just use one or the other, but it's common to hide both the status and the
+ navigation bar when you're implementing "full immersion" mode.</p>
+
+ <h2 id="compare">Choose an Approach</h2>
+
+ <p>The flags {@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE} and
+ {@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE_STICKY} both provide an immersive
+ experience. But whereas the
+ {@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE_STICKY IMMERSIVE_STICKY}
+ flag causes semi-transparent system bars to briefly show and then hide again in response to
+ a swipe gesture, the same swipe gesture causes the system bars to reappear and remain
+ visible if you instead use the {@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE IMMERSIVE}
+ flag. Here are examples of when you would use one vs. the other:</p>
+
+<ul>
+<li>If you're building a book reader, news reader, or a magazine, use
+the {@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE IMMERSIVE} flag in conjunction
+with {@link android.view.View#SYSTEM_UI_FLAG_FULLSCREEN} and
+{@link android.view.View#SYSTEM_UI_FLAG_HIDE_NAVIGATION}. Because users may want to access
+the action bar and other UI controls somewhat frequently, but not be bothered with any UI
+elements while flipping through content,
+{@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE IMMERSIVE} is a good option for this
+use case.</li>
+
+<li>If you're building a truly immersive app, where you expect users to interact near
+the edges of the screen and you don't expect them to need frequent access to the system
+UI, use the
+{@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE_STICKY IMMERSIVE_STICKY} flag
+in conjunction with {@link android.view.View#SYSTEM_UI_FLAG_FULLSCREEN} and
+{@link android.view.View#SYSTEM_UI_FLAG_HIDE_NAVIGATION}. For example, this approach
+might be suitable for a game or a drawing app.</li>
+
+<li>If you're building a video player or some other app that requires minimal user
+interaction, you can probably get by with the <a href="{@docRoot}design/patterns/fullscreen.html">
+lean back</a> approach, available since
+Android 4.0 (API Level 14). For this type of app, simply using
+{@link android.view.View#SYSTEM_UI_FLAG_FULLSCREEN}
+ and {@link android.view.View#SYSTEM_UI_FLAG_HIDE_NAVIGATION} should be
+sufficient. Don't use the "immersive" flags in this case.</li>
+</ul>
+
+<h2 id="nonsticky">Use IMMERSIVE</h2>
+
+ <p>When you use the {@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE} flag, it hides
+ the system bars based on what other UI flags you have set
+ ({@link android.view.View#SYSTEM_UI_FLAG_HIDE_NAVIGATION},
+ {@link android.view.View#SYSTEM_UI_FLAG_FULLSCREEN}, or
+ both). When the user swipes inward in a system bars region, the
+system bars reappear and remain visible.</p>
+
+<p>It's good practice to include other system UI flags (such as
+{@link android.view.View#SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION} and
+{@link android.view.View#SYSTEM_UI_FLAG_LAYOUT_STABLE}) to keep the content from resizing
+when the system bars hide and show. You should also make sure that the action bar and other
+UI controls are hidden at the same time. This snippet demonstrates how to hide and show the
+status and navigation bars, without resizing the content:</p>
+
+<pre>
+// This snippet hides the system bars.
+private void hideSystemUI() {
+ // Set the IMMERSIVE flag.
+ // Set the content to appear under the system bars so that the content
+ // doesn't resize when the system bars hide and show.
+ mDecorView.setSystemUiVisibility(
+ View.SYSTEM_UI_FLAG_LAYOUT_STABLE
+ | View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
+ | View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
+ | View.SYSTEM_UI_FLAG_HIDE_NAVIGATION // hide nav bar
+ | View.SYSTEM_UI_FLAG_FULLSCREEN // hide status bar
+ | View.SYSTEM_UI_FLAG_IMMERSIVE);
+}
+
+// This snippet shows the system bars. It does this by removing all the flags
+// except for the ones that make the content appear under the system bars.
+private void showSystemUI() {
+ mDecorView.setSystemUiVisibility(
+ View.SYSTEM_UI_FLAG_LAYOUT_STABLE
+ | View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
+ | View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN);
+}
+</pre>
+
+
+<p>You may also want to implement the following in conjunction with the
+{@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE IMMERSIVE} flag to provide a better user
+experience:</p>
+
+<ul>
+<li>Register a listener so that your app can get notified of system UI visibility changes,
+as described in <a href="visibility.html">Responding to UI Visibility Changes</a>.</li>
+
+<li>Implement {@link android.app.Activity#onWindowFocusChanged onWindowFocusChanged()}.
+If you gain window focus, you may want to re-hide the system bars.
+If you lose window focus, for example due to a dialog or pop up menu showing above your app,
+you'll probably want to cancel any pending "hide" operations you previously scheduled
+with {@link android.os.Handler#postDelayed Handler.postDelayed()} or something similar.</li>
+
+<li>Implement a {@link android.view.GestureDetector} that detects
+{@link android.view.GestureDetector.OnGestureListener#onSingleTapUp}, to allow users to
+manually toggle the visibility of the system bars by touching your content.
+Simple click listeners aren't the best solution for this because they get triggered even
+if the user drags a finger across the screen (assuming the click target takes up the whole
+screen).
+</li>
+
+</ul>
+
+<p>
+For more discussion of these topics, watch the video
+<a class ="external-link" href="http://www.youtube.com/embed/cBi8fjv90E4">DevBytes:
+ Android 4.4 Immersive Mode</a>.</p>
+
+<h2 id="sticky">Use IMMERSIVE_STICKY</h2>
+
+<p>When you use the {@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE_STICKY} flag,
+an inward swipe in the system bars areas causes the bars to temporarily appear in a
+semi-transparent state, but no flags are cleared, and your
+system UI visibility change listeners are not triggered. The bars
+automatically hide again after a short delay, or if the user interacts with the middle of the
+screen.</p>
+
+<p>Figure 2 shows the semi-transparent system bars that briefly appear and then hide again
+when you use the {@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE_STICKY IMMERSIVE_STICKY} flag.</p>
+
+ <img src="{@docRoot}images/training/imm-sticky.png"
+ alt="system bars">
+<p class="img-caption"><strong>Figure 2.</strong> Auto-hiding system bars.</p>
+
+<p>Below is a simple approach to using this flag. Any time the window receives focus, simply
+set the {@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE_STICKY IMMERSIVE_STICKY} flag, along
+with the other flags discussed in <a href="#nonsticky">Use IMMERSIVE</a>. For example:</p>
+
+<pre>
+@Override
+public void onWindowFocusChanged(boolean hasFocus) {
+ super.onWindowFocusChanged(hasFocus);
+ if (hasFocus) {
+ decorView.setSystemUiVisibility(
+ View.SYSTEM_UI_FLAG_LAYOUT_STABLE
+ | View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
+ | View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
+ | View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
+ | View.SYSTEM_UI_FLAG_FULLSCREEN
+ | View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY);}
+}
+</pre>
+
+<p class="note"><strong>Note:</strong> If you like the auto-hiding behavior of
+{@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE_STICKY IMMERSIVE_STICKY}
+but need to show your own UI controls as well, just use
+{@link android.view.View#SYSTEM_UI_FLAG_IMMERSIVE IMMERSIVE} combined with
+{@link android.os.Handler#postDelayed Handler.postDelayed()} or something similar to
+re-enter immersive mode after a few seconds.</p>
diff --git a/docs/html/training/system-ui/index.jd b/docs/html/training/system-ui/index.jd
index 7135a3d..c45327f 100644
--- a/docs/html/training/system-ui/index.jd
+++ b/docs/html/training/system-ui/index.jd
@@ -20,7 +20,27 @@
<li>Android 1.6 (API Level 4) or higher</li>
</ul>
+<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/patterns/fullscreen.html">
+ Android Design Guide
+ </a>
+ </li>
+
+</ul>
+
+<h2>Try it out</h2>
+
+<div class="download-box">
+ <a href="{@docRoot}samples/ImmersiveMode/index.html"
+class="button">Get the sample</a>
+ <p class="filename">ImmersiveMode sample</p>
+</div>
</div>
</div>
@@ -32,6 +52,13 @@
</div>
</a>
+<a class="notice-developers-video wide" href="http://www.youtube.com/watch?v=cBi8fjv90E4">
+<div>
+ <h3>Video</h3>
+ <p>DevBytes: Android 4.4 Immersive Mode</p>
+</div>
+</a>
+
<div class="figure" style="width:278px">
<img src="{@docRoot}images/training/system-ui.png"
alt="system bars" />
@@ -78,6 +105,12 @@
<dd>
Learn how to hide the navigation bar, in addition to the status bar.
</dd>
+ <dt>
+ <strong><a href="immersive.html">Using Immersive Full-Screen Mode</a></strong>
+ </dt>
+ <dd>
+ Learn how to create a fully immersive experience in your app.
+ </dd>
<dt>
<strong><a href="visibility.html">Responding to UI Visibility Changes</a></strong>
diff --git a/docs/html/training/system-ui/navigation.jd b/docs/html/training/system-ui/navigation.jd
index 3843da3..3907bb2 100644
--- a/docs/html/training/system-ui/navigation.jd
+++ b/docs/html/training/system-ui/navigation.jd
@@ -10,7 +10,7 @@
<!-- 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="#40">Hide the Navigation Bar on 4.0 and Higher</a></li>
<li><a href="#behind">Make Content Appear Behind the Navigation Bar</a></li>
</ol>
@@ -29,6 +29,13 @@
</li>
</ul>
+<h2>Try it out</h2>
+
+<div class="download-box">
+ <a href="{@docRoot}samples/ImmersiveMode/index.html"
+class="button">Get the sample</a>
+ <p class="filename">ImmersiveMode sample</p>
+</div>
</div>
</div>
@@ -90,7 +97,7 @@
<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)}.
+{@link android.view.View#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>
diff --git a/docs/html/training/system-ui/status.jd b/docs/html/training/system-ui/status.jd
index 25ee253..06b6143 100644
--- a/docs/html/training/system-ui/status.jd
+++ b/docs/html/training/system-ui/status.jd
@@ -12,6 +12,7 @@
<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="#44">Hide the Status Bar on Android 4.4 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>
@@ -31,6 +32,13 @@
</li>
</ul>
+<h2>Try it out</h2>
+
+<div class="download-box">
+ <a href="{@docRoot}samples/ImmersiveMode/index.html"
+class="button">Get the sample</a>
+ <p class="filename">ImmersiveMode sample</p>
+</div>
</div>
</div>
@@ -160,15 +168,13 @@
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)}.
+{@link android.view.View#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>
@@ -209,12 +215,12 @@
<p>Then use
-{@link android.view.View#setSystemUiVisibility setSystemuiVisibility(SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN)},
+{@link android.view.View#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)}.
+When you want to hide the system UI, use
+{@link android.view.View#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
index c26092c..b562add 100644
--- a/docs/html/training/system-ui/visibility.jd
+++ b/docs/html/training/system-ui/visibility.jd
@@ -28,6 +28,13 @@
</li>
</ul>
+<h2>Try it out</h2>
+
+<div class="download-box">
+ <a href="{@docRoot}samples/ImmersiveMode/index.html"
+class="button">Get the sample</a>
+ <p class="filename">ImmersiveMode sample</p>
+</div>
</div>
</div>
diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs
index 547faae..1314c7a 100644
--- a/docs/html/training/training_toc.cs
+++ b/docs/html/training/training_toc.cs
@@ -990,6 +990,10 @@
Hiding the Navigation Bar
</a>
</li>
+ <li><a href="/training/system-ui/immersive.html">
+ Using Immersive Full-Screen Mode
+ </a>
+ </li>
<li><a href="<?cs var:toroot ?>training/system-ui/visibility.html">
Responding to UI Visibility Changes
</a>
