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