Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit e811de2d authored by Jean Chalard's avatar Jean Chalard
Browse files

Improve the documentation for InputConnection. 

- Add many details to most methods.
- Add comments specific to IME authors and to editor authors.
- Add missing return value docs.
- Straighten out single-spacing vs double spacing.

Bug: 8843866
Change-Id: If1f6dcf0457d5332a7ebb1ebfb1967c6ff0df722
parent b318f7b9

core/java/android/view/inputmethod/BaseInputConnection.java

+2 −1
Original line number Diff line number Diff line
@@ -42,7 +42,8 @@ class ComposingText implements NoCopySpan { 
 * Base class for implementors of the InputConnection interface, taking care

 * of most of the common behavior for providing a connection to an Editable.

 * Implementors of this class will want to be sure to implement

 * {@link #getEditable} to provide access to their own editable object.

 * {@link #getEditable} to provide access to their own editable object, and

 * to refer to the documentation in {@link InputConnection}.

 */

public class BaseInputConnection implements InputConnection {

    private static final boolean DEBUG = false;

core/java/android/view/inputmethod/CompletionInfo.java

+50 −9
Original line number Diff line number Diff line
@@ -23,6 +23,30 @@ import android.text.TextUtils; 
/**

 * Information about a single text completion that an editor has reported to

 * an input method.

 *

 * <p>This class encapsulates a completion offered by an application

 * that wants it to be presented to the user by the IME. Usually, apps

 * present their completions directly in a scrolling list for example

 * (UI developers will usually use or extend

 * {@see android.widget.AutoCompleteTextView} to implement this).

 * However, in some cases, the editor may not be visible, as in the

 * case in extract mode where the IME has taken over the full

 * screen. In this case, the editor can choose to send their

 * completions to the IME for display.

 *

 * <p>Most applications who want to send completions to an IME should use

 * {@link android.widget.AutoCompleteTextView} as this class makes this

 * process easy. In this case, the application would not have to deal directly

 * with this class.

 *

 * <p>An application who implements its own editor and wants direct control

 * over this would create an array of CompletionInfo objects, and send it to the IME using

 * {@link InputMethodManager#displayCompletions(View, CompletionInfo[])}.

 * The IME would present the completions however they see fit, and

 * call back to the editor through

 * {@link InputConnection#commitCompletion(CompletionInfo)}.

 * The application can then pick up the commit event by overriding

 * {@link android.widget.TextView#onCommitCompletion(CompletionInfo)}.

 */

public final class CompletionInfo implements Parcelable {

    private final long mId;
@@ -32,6 +56,12 @@ public final class CompletionInfo implements Parcelable { 


    /**

     * Create a simple completion with just text, no label.

     *

     * @param id An id that get passed as is (to the editor's discretion)

     * @param index An index that get passed as is. Typically this is the

     * index in the list of completions inside the editor.

     * @param text The text that should be inserted into the editor when

     * this completion is chosen.

     */

    public CompletionInfo(long id, int index, CharSequence text) {

        mId = id;
@@ -41,7 +71,18 @@ public final class CompletionInfo implements Parcelable { 
    }



    /**

     * Create a full completion with both text and label.

     * Create a full completion with both text and label. The text is

     * what will get inserted into the editor, while the label is what

     * the IME should display. If they are the same, use the version

     * of the constructor without a `label' argument.

     *

     * @param id An id that get passed as is (to the editor's discretion)

     * @param index An index that get passed as is. Typically this is the

     * index in the list of completions inside the editor.

     * @param text The text that should be inserted into the editor when

     * this completion is chosen.

     * @param label The text that the IME should be showing among the

     * completions list.

     */

    public CompletionInfo(long id, int index, CharSequence text, CharSequence label) {

        mId = id;

core/java/android/view/inputmethod/ExtractedText.java

+17 −10
Original line number Diff line number Diff line
@@ -22,6 +22,9 @@ import android.text.TextUtils; 


/**

 * Information about text that has been extracted for use by an input method.

 *

 * This contains information about a portion of the currently edited text,

 * that the IME should display into its own interface while in extracted mode.

 */

public class ExtractedText implements Parcelable {

    /**
@@ -72,6 +75,9 @@ public class ExtractedText implements Parcelable { 


    /**

     * Bit for {@link #flags}: set if the editor is currently in selection mode.

     *

     * This happens when a hardware keyboard with latched keys is attached and

     * the shift key is currently latched.

     */

    public static final int FLAG_SELECTING = 0x0002;
@@ -99,7 +105,8 @@ public class ExtractedText implements Parcelable { 
    /**

     * Used to make this class parcelable.

     */

    public static final Parcelable.Creator<ExtractedText> CREATOR = new Parcelable.Creator<ExtractedText>() {

    public static final Parcelable.Creator<ExtractedText> CREATOR

            = new Parcelable.Creator<ExtractedText>() {

        public ExtractedText createFromParcel(Parcel source) {

            ExtractedText res = new ExtractedText();

            res.text = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);

core/java/android/view/inputmethod/InputConnection.java

+531 −182

File changed.

Preview size limit exceeded, changes collapsed.