SuggestionCursor.java revision 145693e12b77c193a65b7eaa038a272dd1f48f33
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.database.DataSetObserver; 20 21 22/** 23 * A sequence of suggestions, with a current position. 24 */ 25public interface SuggestionCursor { 26 27 /** 28 * Gets the number of suggestions in this result. 29 * 30 * @return The number of suggestions, or {@code 0} if this result represents a failed query. 31 */ 32 int getCount(); 33 34 /** 35 * Moves to a given suggestion. 36 * 37 * @param pos The position to move to. 38 * @throws IndexOutOfBoundsException if {@code pos < 0} or {@code pos >= getCount()}. 39 */ 40 void moveTo(int pos); 41 42 /** 43 * Moves to the next suggestion, if there is one. 44 * 45 * @return {@code false} if there is no next suggestion. 46 */ 47 boolean moveToNext(); 48 49 /** 50 * Gets the current position within the cursor. 51 */ 52 int getPosition(); 53 54 /** 55 * Frees any resources used by this cursor. 56 */ 57 void close(); 58 59 /** 60 * Register an observer that is called when changes happen to this data set. 61 * 62 * @param observer gets notified when the data set changes. 63 */ 64 void registerDataSetObserver(DataSetObserver observer); 65 66 /** 67 * Unregister an observer that has previously been registered with 68 * {@link #registerDataSetObserver(DataSetObserver)} 69 * 70 * @param observer the observer to unregister. 71 */ 72 void unregisterDataSetObserver(DataSetObserver observer); 73 74 /** 75 * Gets the source that produced the current suggestion. 76 */ 77 Source getSuggestionSource(); 78 79 /** 80 * Gets the query that the user typed to get this suggestion. 81 */ 82 String getUserQuery(); 83 84 /** 85 * Gets the shortcut ID of the current suggestion. 86 */ 87 String getShortcutId(); 88 89 /** 90 * Whether to show a spinner while refreshing this shortcut. 91 */ 92 boolean isSpinnerWhileRefreshing(); 93 94 /** 95 * Gets the format of the text returned by {@link #getSuggestionText1()} 96 * and {@link #getSuggestionText2()}. 97 * 98 * @return {@code null} or "html" 99 */ 100 String getSuggestionFormat(); 101 102 /** 103 * Gets the first text line for the current suggestion. 104 */ 105 String getSuggestionText1(); 106 107 /** 108 * Gets the second text line for the current suggestion. 109 */ 110 String getSuggestionText2(); 111 112 /** 113 * Gets the second text line URL for the current suggestion. 114 */ 115 String getSuggestionText2Url(); 116 117 /** 118 * Gets the left-hand-side icon for the current suggestion. 119 * 120 * @return A string that can be passed to {@link Source#getIcon(String)}. 121 */ 122 String getSuggestionIcon1(); 123 124 /** 125 * Gets the right-hand-side icon for the current suggestion. 126 * 127 * @return A string that can be passed to {@link Source#getIcon(String)}. 128 */ 129 String getSuggestionIcon2(); 130 131 /** 132 * Gets the intent action for the current suggestion. 133 */ 134 String getSuggestionIntentAction(); 135 136 /** 137 * Gets the extra data associated with this suggestion's intent. 138 */ 139 String getSuggestionIntentExtraData(); 140 141 /** 142 * Gets the data associated with this suggestion's intent. 143 */ 144 String getSuggestionIntentDataString(); 145 146 /** 147 * Gets the query associated with this suggestion's intent. 148 */ 149 String getSuggestionQuery(); 150 151 String getSuggestionDisplayQuery(); 152 153 /** 154 * Gets a unique key that identifies this suggestion. This is used to avoid 155 * duplicate suggestions in the promoted list. This key should be based on 156 * the intent of the suggestion. 157 */ 158 String getSuggestionKey(); 159 160 /** 161 * Gets the suggestion log type for the current suggestion. This is logged together 162 * with the value returned from {@link Source#getName()}. 163 * The value is source-specific. Most sources return {@code null}. 164 */ 165 String getSuggestionLogType(); 166 167 /** 168 * Checks if this suggestion is a shortcut. 169 */ 170 boolean isSuggestionShortcut(); 171} 172