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 17 package android.view.inputmethod; 18 19 import android.os.Parcel; 20 import android.os.Parcelable; 21 import 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 */ 51 public 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
