1/*
2 * Copyright (C) 2007-2008 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5 * use this file except in compliance with the License. You may obtain a copy of
6 * the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations under
14 * the License.
15 */
16
17package android.view.inputmethod;
18
19import android.os.Parcel;
20import android.os.Parcelable;
21import android.text.TextUtils;
22
23/**
24 * Information about a single text completion that an editor has reported to
25 * an input method.
26 *
27 * <p>This class encapsulates a completion offered by an application
28 * that wants it to be presented to the user by the IME. Usually, apps
29 * present their completions directly in a scrolling list for example
30 * (UI developers will usually use or extend
31 * {@see android.widget.AutoCompleteTextView} to implement this).
32 * However, in some cases, the editor may not be visible, as in the
33 * case in extract mode where the IME has taken over the full
34 * screen. In this case, the editor can choose to send their
35 * completions to the IME for display.
36 *
37 * <p>Most applications who want to send completions to an IME should use
38 * {@link android.widget.AutoCompleteTextView} as this class makes this
39 * process easy. In this case, the application would not have to deal directly
40 * with this class.
41 *
42 * <p>An application who implements its own editor and wants direct control
43 * over this would create an array of CompletionInfo objects, and send it to the IME using
44 * {@link InputMethodManager#displayCompletions(View, CompletionInfo[])}.
45 * The IME would present the completions however they see fit, and
46 * call back to the editor through
47 * {@link InputConnection#commitCompletion(CompletionInfo)}.
48 * The application can then pick up the commit event by overriding
49 * {@link android.widget.TextView#onCommitCompletion(CompletionInfo)}.
50 */
51public final class CompletionInfo implements Parcelable {
52    private final long mId;
53    private final int mPosition;
54    private final CharSequence mText;
55    private final CharSequence mLabel;
56
57    /**
58     * Create a simple completion with just text, no label.
59     *
60     * @param id An id that get passed as is (to the editor's discretion)
61     * @param index An index that get passed as is. Typically this is the
62     * index in the list of completions inside the editor.
63     * @param text The text that should be inserted into the editor when
64     * this completion is chosen.
65     */
66    public CompletionInfo(long id, int index, CharSequence text) {
67        mId = id;
68        mPosition = index;
69        mText = text;
70        mLabel = null;
71    }
72
73    /**
74     * Create a full completion with both text and label. The text is
75     * what will get inserted into the editor, while the label is what
76     * the IME should display. If they are the same, use the version
77     * of the constructor without a `label' argument.
78     *
79     * @param id An id that get passed as is (to the editor's discretion)
80     * @param index An index that get passed as is. Typically this is the
81     * index in the list of completions inside the editor.
82     * @param text The text that should be inserted into the editor when
83     * this completion is chosen.
84     * @param label The text that the IME should be showing among the
85     * completions list.
86     */
87    public CompletionInfo(long id, int index, CharSequence text, CharSequence label) {
88        mId = id;
89        mPosition = index;
90        mText = text;
91        mLabel = label;
92    }
93
94    private CompletionInfo(Parcel source) {
95        mId = source.readLong();
96        mPosition = source.readInt();
97        mText = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
98        mLabel = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(source);
99    }
100
101    /**
102     * Return the abstract identifier for this completion, typically
103     * corresponding to the id associated with it in the original adapter.
104     */
105    public long getId() {
106        return mId;
107    }
108
109    /**
110     * Return the original position of this completion, typically
111     * corresponding to its position in the original adapter.
112     */
113    public int getPosition() {
114        return mPosition;
115    }
116
117    /**
118     * Return the actual text associated with this completion.  This is the
119     * real text that will be inserted into the editor if the user selects it.
120     */
121    public CharSequence getText() {
122        return mText;
123    }
124
125    /**
126     * Return the user-visible label for the completion, or null if the plain
127     * text should be shown.  If non-null, this will be what the user sees as
128     * the completion option instead of the actual text.
129     */
130    public CharSequence getLabel() {
131        return mLabel;
132    }
133
134    @Override
135    public String toString() {
136        return "CompletionInfo{#" + mPosition + " \"" + mText
137                + "\" id=" + mId + " label=" + mLabel + "}";
138    }
139
140    /**
141     * Used to package this object into a {@link Parcel}.
142     *
143     * @param dest The {@link Parcel} to be written.
144     * @param flags The flags used for parceling.
145     */
146    public void writeToParcel(Parcel dest, int flags) {
147        dest.writeLong(mId);
148        dest.writeInt(mPosition);
149        TextUtils.writeToParcel(mText, dest, flags);
150        TextUtils.writeToParcel(mLabel, dest, flags);
151    }
152
153    /**
154     * Used to make this class parcelable.
155     */
156    public static final Parcelable.Creator<CompletionInfo> CREATOR
157            = new Parcelable.Creator<CompletionInfo>() {
158        public CompletionInfo createFromParcel(Parcel source) {
159            return new CompletionInfo(source);
160        }
161
162        public CompletionInfo[] newArray(int size) {
163            return new CompletionInfo[size];
164        }
165    };
166
167    public int describeContents() {
168        return 0;
169    }
170}
171