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

/*
 * Copyright (C) 2007-2008 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */

package android.view.inputmethod;

import android.os.Parcel;
import android.os.Parcelable;
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;
    private final int mPosition;
    private final CharSequence mText;
    private final CharSequence mLabel;

    /**
     * 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;
        mPosition = index;
        mText = text;
        mLabel = null;
    }

    /**
     * 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;
        mPosition = index;
        mText = text;
        mLabel = label;
    }

    private CompletionInfo(Parcel source) {
        mId = source.readLong();
        mPosition = source.readInt();
        mText = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
        mLabel = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
    }

    /**
     * Return the abstract identifier for this completion, typically
     * corresponding to the id associated with it in the original adapter.
     */
    public long getId() {
        return mId;
    }

    /**
     * Return the original position of this completion, typically
     * corresponding to its position in the original adapter.
     */
    public int getPosition() {
        return mPosition;
    }

    /**
     * Return the actual text associated with this completion.  This is the
     * real text that will be inserted into the editor if the user selects it.
     */
    public CharSequence getText() {
        return mText;
    }

    /**
     * Return the user-visible label for the completion, or null if the plain
     * text should be shown.  If non-null, this will be what the user sees as
     * the completion option instead of the actual text.
     */
    public CharSequence getLabel() {
        return mLabel;
    }

    @Override
    public String toString() {
        return "CompletionInfo{#" + mPosition + " \"" + mText
                + "\" id=" + mId + " label=" + mLabel + "}";
    }

    /**
     * Used to package this object into a {@link Parcel}.
     *
     * @param dest The {@link Parcel} to be written.
     * @param flags The flags used for parceling.
     */
    public void writeToParcel(Parcel dest, int flags) {
        dest.writeLong(mId);
        dest.writeInt(mPosition);
        TextUtils.writeToParcel(mText, dest, flags);
        TextUtils.writeToParcel(mLabel, dest, flags);
    }

    /**
     * Used to make this class parcelable.
     */
    public static final @android.annotation.NonNull Parcelable.Creator<CompletionInfo> CREATOR
            = new Parcelable.Creator<CompletionInfo>() {
        public CompletionInfo createFromParcel(Parcel source) {
            return new CompletionInfo(source);
        }

        public CompletionInfo[] newArray(int size) {
            return new CompletionInfo[size];
        }
    };

    public int describeContents() {
        return 0;
    }
}