Improve doc for EditorInfo#initialSel{Start,End}

Bug: 12772035
Change-Id: I2fe444685b9d02c15d002d36b1cb1fcfce42cb37

2 files changed, 86 insertions, 61 deletions

diff --git a/core/java/android/view/inputmethod/EditorInfo.java b/core/java/android/view/inputmethod/EditorInfo.java
index d4e005b..c0395cf 100644
--- a/core/java/android/view/inputmethod/EditorInfo.java
+++ b/core/java/android/view/inputmethod/EditorInfo.java
@@ -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;
diff --git a/core/java/android/view/inputmethod/InputMethodManager.java b/core/java/android/view/inputmethod/InputMethodManager.java
index 70c53d2..e812edd 100644
--- a/core/java/android/view/inputmethod/InputMethodManager.java
+++ b/core/java/android/view/inputmethod/InputMethodManager.java
@@ -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) {