diff options
| -rw-r--r-- | core/java/android/text/InputType.java | 80 | ||||
| -rw-r--r-- | core/java/android/view/inputmethod/EditorInfo.java | 106 | ||||
| -rw-r--r-- | core/java/android/view/inputmethod/InputConnection.java | 12 |
3 files changed, 134 insertions, 64 deletions
diff --git a/core/java/android/text/InputType.java b/core/java/android/text/InputType.java index 6d066d6..2e3ec52 100644 --- a/core/java/android/text/InputType.java +++ b/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 - * 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}: + * {@link 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 - * 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 @@ 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; diff --git a/core/java/android/view/inputmethod/EditorInfo.java b/core/java/android/view/inputmethod/EditorInfo.java index 5146567..e41df88 100644 --- a/core/java/android/view/inputmethod/EditorInfo.java +++ b/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 - * 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 @@ 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 - * 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 @@ 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 - * 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 @@ 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. */ 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 @@ 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 |