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

Improve documentation for InputType and EditorInfo.

Browse Source 
Bug: 11245912
Change-Id: Ie92ba20079461f7f0e30d969ba3692fec3a3b97f
This commit is contained in:
Jean Chalard
2013-11-11 17:47:51 +09:00
parent e8d0fbf240
commit c1a11f17a2
3 changed files with 134 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
core/java/android/text/InputType.java
View File

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

106
core/java/android/view/inputmethod/EditorInfo.java
View File

@@ -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.
*/

12
core/java/android/view/inputmethod/InputConnection.java
View File

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