SuggestionCursor.java revision 1e938ea2f5edefab446b9562b316bc5dc72adebb
1/* 2 * Copyright (C) 2009 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of 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, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package com.android.quicksearchbox; 18 19import android.content.ComponentName; 20import android.content.Context; 21import android.content.Intent; 22import android.database.DataSetObserver; 23import android.graphics.Rect; 24import android.graphics.drawable.Drawable; 25import android.net.Uri; 26import android.os.Bundle; 27 28public interface SuggestionCursor { 29 30 /** 31 * The user query that returned these suggestions. 32 */ 33 String getUserQuery(); 34 35 /** 36 * Gets the component name of the source that produced this result. 37 */ 38 ComponentName getSourceComponentName(); 39 40 /** 41 * Gets the localized, human-readable label for the source that produced this result. 42 */ 43 CharSequence getSourceLabel(); 44 45 /** 46 * Gets the icon for the source that produced this result. 47 */ 48 Drawable getSourceIcon(); 49 50 /** 51 * Gets the icon URI for the source that produced this result. 52 */ 53 Uri getSourceIconUri(); 54 55 /** 56 * Gets an icon by ID. Used for getting the icons returned by {@link #getSuggestionIcon1()} 57 * and {@link #getSuggestionIcon2()}. 58 */ 59 Drawable getIcon(String iconId); 60 61 /** 62 * Gets the URI for an icon. 63 */ 64 Uri getIconUri(String iconId); 65 66 /** 67 * Checks whether this result represents a failed suggestion query. 68 */ 69 boolean isFailed(); 70 71 /** 72 * Closes this suggestion result. 73 */ 74 void close(); 75 76 /** 77 * Register an observer that is called when changes happen to the contents 78 * of this cursor's data set. 79 * 80 * @param observer the object that gets notified when the data set changes. 81 */ 82 public void registerDataSetObserver(DataSetObserver observer); 83 84 /** 85 * Unregister an observer that has previously been registered with this cursor 86 * via {@link #registerDataSetObserver(DataSetObserver)} 87 * 88 * @param observer the object to unregister. 89 */ 90 public void unregisterDataSetObserver(DataSetObserver observer); 91 92 /** 93 * Gets the number of suggestions in this result. 94 * 95 * @return The number of suggestions, or {@code 0} if this result represents a failed query. 96 */ 97 int getCount(); 98 99 /** 100 * Moves to a given suggestion. 101 * 102 * @param pos The position to move to. 103 * @throws IndexOutOfBoundsException if {@code pos < 0} or {@code pos >= getCount()}. 104 */ 105 void moveTo(int pos); 106 107 /** 108 * Gets the current position within the cursor. 109 */ 110 int getPosition(); 111 112 /** 113 * Gets the text to put in the search box when the current suggestion is selected. 114 */ 115 String getSuggestionDisplayQuery(); 116 117 /** 118 * Gets the shortcut ID of the current suggestion. 119 */ 120 String getShortcutId(); 121 122 /** 123 * Whether to show a spinner while refreshing this shortcut. 124 */ 125 boolean isSpinnerWhileRefreshing(); 126 127 /** 128 * Gets the format of the text returned by {@link #getSuggestionText1()} 129 * and {@link #getSuggestionText2()}. 130 * 131 * @return {@code null} or "html" 132 */ 133 String getSuggestionFormat(); 134 135 /** 136 * Gets the first text line for the current suggestion. 137 */ 138 String getSuggestionText1(); 139 140 /** 141 * Gets the second text line for the current suggestion. 142 */ 143 String getSuggestionText2(); 144 145 /** 146 * Gets the left-hand-side icon for the current suggestion. 147 * 148 * @return A string that can be passed to {@link #getIcon()}. 149 */ 150 String getSuggestionIcon1(); 151 152 /** 153 * Gets the right-hand-side icon for the current suggestion. 154 * 155 * @return A string that can be passed to {@link #getIcon()}. 156 */ 157 String getSuggestionIcon2(); 158 159 /** 160 * Gets the intent that this suggestion launches. 161 * 162 * @param context Used for resolving the intent target. 163 * @param actionKey 164 * @param actionMsg 165 * @return 166 */ 167 Intent getSuggestionIntent(Context context, Bundle appSearchData, 168 int actionKey, String actionMsg); 169 170 /** 171 * Gets the extra data associated with this suggestion's intent. 172 */ 173 String getSuggestionIntentExtraData(); 174 175 /** 176 * Gets the data associated with this suggestion's intent. 177 */ 178 String getSuggestionIntentDataString(); 179 180 /** 181 * Gets a unique key that identifies this suggestion. This is used to avoid 182 * duplicate suggestions in the promoted list. This key should be based on 183 * the intent of the suggestion. 184 */ 185 String getSuggestionKey(); 186 187 /** 188 * Gets the first suggestion text line as styled text. 189 */ 190 CharSequence getSuggestionFormattedText1(); 191 192 /** 193 * Gets the second suggestion text line as styled text. 194 */ 195 CharSequence getSuggestionFormattedText2(); 196 197 /** 198 * Gets the first suggestion icon. 199 */ 200 Drawable getSuggestionDrawableIcon1(); 201 202 /** 203 * Gets the second suggestion icon. 204 */ 205 Drawable getSuggestionDrawableIcon2(); 206 207 /** 208 * Gets the action message for a key code for the current suggestion. 209 * 210 * @param keyCode Key code, see {@link android.view.KeyEvent}. 211 * @return The action message for the key, or {@code null} if there is none. 212 */ 213 String getActionKeyMsg(int keyCode); 214} 215