SuggestionCursor.java revision abd33f7f8d8e56348a8a87bb9e7af491d83ee833
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.graphics.Rect; 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 localized, human-readable label for the source that produced this result. 41 */ 42 CharSequence getSourceLabel(); 43 44 /** 45 * Gets the icon for the source that produced this result. 46 */ 47 Drawable getSourceIcon(); 48 49 /** 50 * Gets the icon URI for the source that produced this result. 51 */ 52 Uri getSourceIconUri(); 53 54 /** 55 * Gets an icon by ID. Used for getting the icons returned by {@link #getSuggestionIcon1()} 56 * and {@link #getSuggestionIcon2()}. 57 */ 58 Drawable getIcon(String iconId); 59 60 /** 61 * Gets the URI for an icon. 62 */ 63 Uri getIconUri(String iconId); 64 65 /** 66 * Checks whether this result represents a failed suggestion query. 67 */ 68 boolean isFailed(); 69 70 /** 71 * Closes this suggestion result. 72 */ 73 void close(); 74 75 /** 76 * Gets the number of suggestions in this result. 77 * 78 * @return The number of suggestions, or {@code 0} if this result represents a failed query. 79 */ 80 int getCount(); 81 82 /** 83 * Moves to a given suggestion. 84 * 85 * @param pos The position to move to. 86 * @throws IndexOutOfBoundsException if {@code pos < 0} or {@code pos >= getCount()}. 87 */ 88 void moveTo(int pos); 89 90 /** 91 * Gets the current position within the cursor. 92 */ 93 int getPosition(); 94 95 /** 96 * Gets the text to put in the search box when the current suggestion is selected. 97 */ 98 String getSuggestionDisplayQuery(); 99 100 /** 101 * Gets the shortcut ID of the current suggestion. 102 */ 103 String getShortcutId(); 104 105 /** 106 * Gets the format of the text returned by {@link #getSuggestionText1()} 107 * and {@link #getSuggestionText2()}. 108 * 109 * @return {@code null} or "html" 110 */ 111 String getSuggestionFormat(); 112 113 /** 114 * Gets the first text line for the current suggestion. 115 */ 116 String getSuggestionText1(); 117 118 /** 119 * Gets the second text line for the current suggestion. 120 */ 121 String getSuggestionText2(); 122 123 /** 124 * Gets the left-hand-side icon for the current suggestion. 125 * 126 * @return A string that can be passed to {@link #getIcon()}. 127 */ 128 String getSuggestionIcon1(); 129 130 /** 131 * Gets the right-hand-side icon for the current suggestion. 132 * 133 * @return A string that can be passed to {@link #getIcon()}. 134 */ 135 String getSuggestionIcon2(); 136 137 /** 138 * Gets the intent that this suggestion launches. 139 * 140 * @param context Used for resolving the intent target. 141 * @param actionKey 142 * @param actionMsg 143 * @return 144 */ 145 Intent getSuggestionIntent(Context context, Bundle appSearchData, 146 int actionKey, String actionMsg); 147 148 /** 149 * Gets the secondary intent associated with this suggestion. 150 * 151 * @param context Used for resolving the intent target. 152 * @param appSearchData application specific data passed in the search request 153 * @param target Rect describing the position of this result on the screen 154 * @return the secondary intent, or {@code null} if there is none 155 */ 156 Intent getSecondarySuggestionIntent(Context context, Bundle appSearchData, 157 Rect target); 158 159 /** 160 * Checks whether the current suggestion has a secondary intent. 161 */ 162 boolean hasSecondaryIntent(); 163 164 /** 165 * Gets a unique key that identifies this suggestion. This is used to avoid 166 * duplicate suggestions in the promoted list. This key should be based on 167 * the intent of the suggestion. 168 */ 169 String getSuggestionKey(); 170 171 /** 172 * Gets the first suggestion text line as styled text. 173 */ 174 CharSequence getSuggestionFormattedText1(); 175 176 /** 177 * Gets the second suggestion text line as styled text. 178 */ 179 CharSequence getSuggestionFormattedText2(); 180 181 /** 182 * Gets the first suggestion icon. 183 */ 184 Drawable getSuggestionDrawableIcon1(); 185 186 /** 187 * Gets the second suggestion icon. 188 */ 189 Drawable getSuggestionDrawableIcon2(); 190 191 /** 192 * Gets the action message for a key code for the current suggestion. 193 * 194 * @param keyCode Key code, see {@link android.view.KeyEvent}. 195 * @return The action message for the key, or {@code null} if there is none. 196 */ 197 String getActionKeyMsg(int keyCode); 198} 199