SuggestionCursor.java revision 965d98377ddfdc52b772c2444d840000b665e000
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 * Gets the current position within the cursor. 44 */ 45 int getPosition(); 46 47 /** 48 * Frees any resources used by this cursor. 49 */ 50 void close(); 51 52 /** 53 * Register an observer that is called when changes happen to this data set. 54 * 55 * @param observer gets notified when the data set changes. 56 */ 57 void registerDataSetObserver(DataSetObserver observer); 58 59 /** 60 * Unregister an observer that has previously been registered with 61 * {@link #registerDataSetObserver(DataSetObserver)} 62 * 63 * @param observer the observer to unregister. 64 */ 65 void unregisterDataSetObserver(DataSetObserver observer); 66 67 /** 68 * Gets the source that produced the current suggestion. 69 */ 70 Source getSuggestionSource(); 71 72 /** 73 * Gets the query that the user typed to get this suggestion. 74 */ 75 String getUserQuery(); 76 77 /** 78 * Gets the shortcut ID of the current suggestion. 79 */ 80 String getShortcutId(); 81 82 /** 83 * Whether to show a spinner while refreshing this shortcut. 84 */ 85 boolean isSpinnerWhileRefreshing(); 86 87 /** 88 * Gets the format of the text returned by {@link #getSuggestionText1()} 89 * and {@link #getSuggestionText2()}. 90 * 91 * @return {@code null} or "html" 92 */ 93 String getSuggestionFormat(); 94 95 /** 96 * Gets the first text line for the current suggestion. 97 */ 98 String getSuggestionText1(); 99 100 /** 101 * Gets the second text line for the current suggestion. 102 */ 103 String getSuggestionText2(); 104 105 /** 106 * Gets the second text line URL for the current suggestion. 107 */ 108 String getSuggestionText2Url(); 109 110 /** 111 * Gets the left-hand-side icon for the current suggestion. 112 * 113 * @return A string that can be passed to {@link Source#getIcon(String)}. 114 */ 115 String getSuggestionIcon1(); 116 117 /** 118 * Gets the right-hand-side icon for the current suggestion. 119 * 120 * @return A string that can be passed to {@link Source#getIcon(String)}. 121 */ 122 String getSuggestionIcon2(); 123 124 /** 125 * Gets the intent action for the current suggestion. 126 */ 127 String getSuggestionIntentAction(); 128 129 /** 130 * Gets the extra data associated with this suggestion's intent. 131 */ 132 String getSuggestionIntentExtraData(); 133 134 /** 135 * Gets the data associated with this suggestion's intent. 136 */ 137 String getSuggestionIntentDataString(); 138 139 /** 140 * Gets the data associated with this suggestion's intent. 141 */ 142 String getSuggestionQuery(); 143 144 String getSuggestionDisplayQuery(); 145 146 /** 147 * Gets a unique key that identifies this suggestion. This is used to avoid 148 * duplicate suggestions in the promoted list. This key should be based on 149 * the intent of the suggestion. 150 */ 151 String getSuggestionKey(); 152 153 /** 154 * Gets the suggestion log type for the current suggestion. 155 */ 156 String getSuggestionLogType(); 157 158 /** 159 * Checks if this suggestion is a shortcut. 160 */ 161 boolean isSuggestionShortcut(); 162} 163