Merge "[DO NOT MERGE] Improve documentation for InputType and EditorInfo." into klp-docs

core/java/android/text/InputType.java

@@ -46,9 +46,9 @@ public interface InputType {
      * 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 @@ public interface InputType {
      * 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 @@ public interface InputType {
      * 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
+     * Flag for {@link #TYPE_CLASS_TEXT}: capitalize the first character of
-     * all words.  Overrides {@link #TYPE_TEXT_FLAG_CAP_SENTENCES}.  This
+     * 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
+     * Flag for {@link #TYPE_CLASS_TEXT}: the text editor (which means
-     * auto-completion of the text being entered based on its own semantics,
+     * the application) is performing auto-completion of the text being entered
-     * which it will present to the user as they type.  This generally means
+     * based on its own semantics, which it will present to the user as they type.
-     * that the input method should not be showing candidates itself, but can
+     * This generally means that the input method should not be showing
-     * expect for the editor to supply its own completions/candidates from
+     * 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 @@ public interface InputType {
      * 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 @@ public interface InputType {
     
     /**
      * 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 @@ public interface InputType {
     // ----------------------------------------------------------------------
     
     /**
-     * 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
+     * {@link #TYPE_NUMBER_VARIATION_PASSWORD}.
-     * the variation, normal should be assumed.
+     * <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 @@ public interface InputType {
      * 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;
     

core/java/android/view/inputmethod/EditorInfo.java

@@ -70,14 +70,14 @@ public class EditorInfo implements InputType, Parcelable {
     /**
      * 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 @@ public class EditorInfo implements InputType, Parcelable {
     
     /**
      * 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
+     * into fullscreen mode.
-     * a guarantee, and not all IMEs will respect it.
+     * 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 @@ public class EditorInfo implements InputType, Parcelable {
      * 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
+     * of the application be shown behind, through transparent UI parts in the
-     * access to the application available from the user, it can make the
+     * fullscreen IME. The part of the UI visible to the user may not be responsive
-     * experience of a (mostly) fullscreen IME less jarring.  Note that when
+     * to touch because the IME will receive touch events, which may confuse the
-     * this flag is specified the IME may <em>not</em> be set up to be able
+     * user; use {@link #IME_FLAG_NO_FULLSCREEN} instead for a better experience.
-     * to display text, so it should only be used in situations where this is
+     * Using this flag is discouraged and it may become deprecated in the future.
-     * not needed.
+     * 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
+     * Flag of {@link #imeOptions}: used in conjunction with one of the actions
-     * {@link #IME_MASK_ACTION}, this indicates that the action should not
+     * masked by {@link #IME_MASK_ACTION}, this indicates that the action
-     * be available as an accessory button when the input method is full-screen.
+     * should not be available as an accessory button on the right of the extracted
-     * Note that by setting this flag, there can be cases where the action
+     * text when the input method is full-screen. Note that by setting this flag,
-     * is simply never available to the user.  Setting this generally means
+     * there can be cases where the action is simply never available to the
-     * that you think showing text being edited is more important than the
+     * user. Setting this generally means that you think that in fullscreen mode,
-     * action you have supplied. 
+     * 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
+     * Flag of {@link #imeOptions}: used in conjunction with one of the actions
-     * {@link #IME_MASK_ACTION}, this indicates that the action should not
+     * masked by {@link #IME_MASK_ACTION}. If this flag is not set, IMEs will
-     * be available in-line as a replacement for "enter" key.  Typically this is
+     * normally replace the "enter" key with the action supplied. This flag
-     * because the action has such a significant impact or is not recoverable
+     * indicates that the action should not be available in-line as a replacement
-     * enough that accidentally hitting it should be avoided, such as sending
+     * for the "enter" key. Typically this is because the action has such a
-     * a message.  Note that {@link android.widget.TextView} will automatically set this
+     * significant impact or is not recoverable enough that accidentally hitting
-     * flag for you on multi-line text views.
+     * 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}
+     * 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
+     * It is typically used for an account ID or password input. A lot of the time,
-     * normally are able to input ASCII even without being told so (such IMEs
+     * IMEs are already 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
+     * already respect this flag in a sense), but there are cases when this is not
-     * aren't when, for instance, only non-ASCII input languagaes like Arabic,
+     * the default. For instance, users of languages using a different script like
-     * Greek, Hebrew, Russian are enabled in the IME.  Applications need to be
+     * Arabic, Greek, Hebrew or Russian typically have a keyboard that can't
-     * aware that the flag is not a guarantee, and not all IMEs will respect it.
+     * 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
+     * especially when their IME could end up with a state where only languages
-     * input languages enabled.
+     * using non-ASCII are enabled.
      */
     public static final int IME_FLAG_FORCE_ASCII = 0x80000000;
 
@@ -209,8 +224,13 @@ public class EditorInfo implements InputType, Parcelable {
     
     /**
      * 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
+     * a command the user can perform, which you can specify here. This is
-     * not count on this being used.
+     * 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 @@ public class EditorInfo implements InputType, Parcelable {
     
     /**
      * 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 @@ public class EditorInfo implements InputType, Parcelable {
      * 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.
      */

core/java/android/view/inputmethod/InputConnection.java

@@ -142,7 +142,11 @@ public interface InputConnection {
      * 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 @@ public interface InputConnection {
      * 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