* 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;
* 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;
* 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;
* 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;
/**
* 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;
// ----------------------------------------------------------------------
/**
- * 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;
* 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;
/**
* 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;
/**
* 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;
* 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;
/**
* 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;
/**
* 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;
* 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.
*/
OSDN Git Service
