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

Merge "Improve doc for EditorInfo#initialSel{Start,End}"

Browse Source
This commit is contained in:
Jean Chalard
2014-03-10 04:03:32 +00:00
committed by Android (Google) Code Review
parent 6f91cedfeb 6fd68e0930
commit 30c86ad475
3 changed files with 94 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
core/java/android/view/View.java
View File

@@ -8705,7 +8705,14 @@ public class View implements Drawable.Callback, KeyEvent.Callback,
*
* <p>When implementing this, you probably also want to implement
* {@link #onCheckIsTextEditor()} to indicate you will return a
* non-null InputConnection.
* non-null InputConnection.</p>
*
* <p>Also, take good care to fill in the {@link android.view.inputmethod.EditorInfo}
* object correctly and in its entirety, so that the connected IME can rely
* on its values. For example, {@link android.view.inputmethod.EditorInfo#initialSelStart}
* and {@link android.view.inputmethod.EditorInfo#initialSelEnd} members
* must be filled in with the correct cursor position for IMEs to work correctly
* with your application.</p>
*
* @param outAttrs Fill in with attribute information about the connection.
*/

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

@@ -26,13 +26,13 @@ import android.util.Printer;
/**
* An EditorInfo describes several attributes of a text editing object
* that an input method is communicating with (typically an EditText), most
* importantly the type of text content it contains.
* importantly the type of text content it contains and the current cursor position.
*/
public class EditorInfo implements InputType, Parcelable {
/**
* The content type of the text box, whose bits are defined by
* {@link InputType}.
*
*
* @see InputType
* @see #TYPE_MASK_CLASS
* @see #TYPE_MASK_VARIATION
@@ -47,55 +47,55 @@ public class EditorInfo implements InputType, Parcelable {
* to provide alternative mechanisms for providing that command.
*/
public static final int IME_MASK_ACTION = 0x000000ff;
/**
* Bits of {@link #IME_MASK_ACTION}: no specific action has been
* associated with this editor, let the editor come up with its own if
* it can.
*/
public static final int IME_ACTION_UNSPECIFIED = 0x00000000;
/**
* Bits of {@link #IME_MASK_ACTION}: there is no available action.
*/
public static final int IME_ACTION_NONE = 0x00000001;
/**
* Bits of {@link #IME_MASK_ACTION}: the action key performs a "go"
* operation to take the user to the target of the text they typed.
* Typically used, for example, when entering a URL.
*/
public static final int IME_ACTION_GO = 0x00000002;
/**
* Bits of {@link #IME_MASK_ACTION}: the action key performs a "search"
* operation, taking the user to the results of searching for the text
* 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 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 "next"
* operation, taking the user to the next field that will accept text.
*/
public static final int IME_ACTION_NEXT = 0x00000005;
/**
* Bits of {@link #IME_MASK_ACTION}: the action key performs a "done"
* 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
* 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
* can be returned to the app if it sets {@link #IME_FLAG_NAVIGATE_PREVIOUS}.
@@ -154,7 +154,7 @@ public class EditorInfo implements InputType, Parcelable {
* on older versions of the platform.
*/
public static final int IME_FLAG_NO_EXTRACT_UI = 0x10000000;
/**
* Flag of {@link #imeOptions}: used in conjunction with one of the actions
* masked by {@link #IME_MASK_ACTION}, this indicates that the action
@@ -167,7 +167,7 @@ public class EditorInfo implements InputType, Parcelable {
* to show more text.
*/
public static final int IME_FLAG_NO_ACCESSORY_ACTION = 0x20000000;
/**
* 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
@@ -202,13 +202,13 @@ public class EditorInfo implements InputType, Parcelable {
* Generic unspecified type for {@link #imeOptions}.
*/
public static final int IME_NULL = 0x00000000;
/**
* Extended type information for the editor, to help the IME better
* integrate with it.
*/
public int imeOptions = IME_NULL;
/**
* A string supplying additional information options that are
* private to a particular IME implementation. The string must be
@@ -221,7 +221,7 @@ public class EditorInfo implements InputType, Parcelable {
* attribute of a TextView.
*/
public String privateImeOptions = null;
/**
* 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. This is
@@ -233,7 +233,7 @@ public class EditorInfo implements InputType, Parcelable {
* ignore this.
*/
public CharSequence actionLabel = null;
/**
* If {@link #actionLabel} has been given, this is the id for that command
* when the user presses its button that is delivered back with
@@ -241,50 +241,66 @@ public class EditorInfo implements InputType, Parcelable {
* InputConnection.performEditorAction()}.
*/
public int actionId = 0;
/**
* The text offset of the start of the selection at the time editing
* 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.
* begins; -1 if not known. Keep in mind that, without knowing the cursor
* position, many IMEs will not be able to offer their full feature set and
* may even behave in unpredictable ways: pass the actual cursor position
* here if possible at all.
*
* <p>Also, this needs to be the cursor position <strong>right now</strong>,
* not at some point in the past, even if input is starting in the same text field
* as before. When the app is filling this object, input is about to start by
* definition, and this value will override any value the app may have passed to
* {@link InputMethodManager#updateSelection(android.view.View, int, int, int, int)}
* before.</p>
*/
public int initialSelStart = -1;
/**
* The text offset of the end of the selection at the time editing
* 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.
* <p>The text offset of the end of the selection at the time editing
* begins; -1 if not known. Keep in mind that, without knowing the cursor
* position, many IMEs will not be able to offer their full feature set and
* may behave in unpredictable ways: pass the actual cursor position
* here if possible at all.</p>
*
* <p>Also, this needs to be the cursor position <strong>right now</strong>,
* not at some point in the past, even if input is starting in the same text field
* as before. When the app is filling this object, input is about to start by
* definition, and this value will override any value the app may have passed to
* {@link InputMethodManager#updateSelection(android.view.View, int, int, int, int)}
* before.</p>
*/
public int initialSelEnd = -1;
/**
* The capitalization mode of the first character being edited in the
* text. Values may be any combination of
* {@link TextUtils#CAP_MODE_CHARACTERS TextUtils.CAP_MODE_CHARACTERS},
* {@link TextUtils#CAP_MODE_WORDS TextUtils.CAP_MODE_WORDS}, and
* {@link TextUtils#CAP_MODE_SENTENCES TextUtils.CAP_MODE_SENTENCES}, though
* you should generally just take a non-zero value to mean start out in
* caps mode.
* you should generally just take a non-zero value to mean "start out in
* caps mode".
*/
public int initialCapsMode = 0;
/**
* The "hint" text of the text view, typically shown in-line when the
* text is empty to tell the user what to enter.
*/
public CharSequence hintText;
/**
* A label to show to the user describing the text they are writing.
*/
public CharSequence label;
/**
* Name of the package that owns this editor.
*/
public String packageName;
/**
* Identifier for the editor's field. This is optional, and may be
* 0. By default it is filled in with the result of
@@ -292,14 +308,14 @@ public class EditorInfo implements InputType, Parcelable {
* is being edited.
*/
public int fieldId;
/**
* Additional name for the editor's field. This can supply additional
* name information for the field. By default it is null. The actual
* contents have no meaning.
*/
public String fieldName;
/**
* Any extra data to supply to the input method. This is for extended
* communication with specific input methods; the name fields in the
@@ -309,7 +325,7 @@ public class EditorInfo implements InputType, Parcelable {
* attribute of a TextView.
*/
public Bundle extras;
/**
* Ensure that the data in this EditorInfo is compatible with an application
* that was developed against the given target API version. This can
@@ -365,10 +381,10 @@ public class EditorInfo implements InputType, Parcelable {
+ " fieldName=" + fieldName);
pw.println(prefix + "extras=" + extras);
}
/**
* Used to package this object into a {@link Parcel}.
*
*
* @param dest The {@link Parcel} to be written.
* @param flags The flags used for parceling.
*/
@@ -392,30 +408,31 @@ public class EditorInfo implements InputType, Parcelable {
/**
* Used to make this class parcelable.
*/
public static final Parcelable.Creator<EditorInfo> CREATOR = new Parcelable.Creator<EditorInfo>() {
public EditorInfo createFromParcel(Parcel source) {
EditorInfo res = new EditorInfo();
res.inputType = source.readInt();
res.imeOptions = source.readInt();
res.privateImeOptions = source.readString();
res.actionLabel = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
res.actionId = source.readInt();
res.initialSelStart = source.readInt();
res.initialSelEnd = source.readInt();
res.initialCapsMode = source.readInt();
res.hintText = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
res.label = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
res.packageName = source.readString();
res.fieldId = source.readInt();
res.fieldName = source.readString();
res.extras = source.readBundle();
return res;
}
public static final Parcelable.Creator<EditorInfo> CREATOR =
new Parcelable.Creator<EditorInfo>() {
public EditorInfo createFromParcel(Parcel source) {
EditorInfo res = new EditorInfo();
res.inputType = source.readInt();
res.imeOptions = source.readInt();
res.privateImeOptions = source.readString();
res.actionLabel = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
res.actionId = source.readInt();
res.initialSelStart = source.readInt();
res.initialSelEnd = source.readInt();
res.initialCapsMode = source.readInt();
res.hintText = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
res.label = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
res.packageName = source.readString();
res.fieldId = source.readInt();
res.fieldName = source.readString();
res.extras = source.readBundle();
return res;
}
public EditorInfo[] newArray(int size) {
return new EditorInfo[size];
}
};
public EditorInfo[] newArray(int size) {
return new EditorInfo[size];
}
};
public int describeContents() {
return 0;

8
core/java/android/view/inputmethod/InputMethodManager.java
View File

@@ -1394,6 +1394,14 @@ public final class InputMethodManager {
/**
* Report the current selection range.
*
* <p><strong>Editor authors</strong>, you need to call this method whenever
* the cursor moves in your editor. Remember that in addition to doing this, your
* editor needs to always supply current cursor values in
* {@link EditorInfo#initialSelStart} and {@link EditorInfo#initialSelEnd} every
* time {@link android.view.View#onCreateInputConnection(EditorInfo)} is
* called, which happens whenever the keyboard shows up or the focus changes
* to a text field, among other cases.</p>
*/
public void updateSelection(View view, int selStart, int selEnd,
int candidatesStart, int candidatesEnd) {