SuggestionCursor.java revision b42184f1e6a1b7bb22797ff92cae696753aca770
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 */ 16package com.android.quicksearchbox; 17 18import com.android.quicksearchbox.util.QuietlyCloseable; 19 20import android.database.DataSetObserver; 21 22/** 23 * A sequence of suggestions, with a current position. 24 */ 25public interface SuggestionCursor extends Suggestion, QuietlyCloseable { 26 27 /** 28 * Gets the query that the user typed to get this suggestion. 29 */ 30 String getUserQuery(); 31 32 /** 33 * Gets the number of suggestions in this result. 34 * 35 * @return The number of suggestions, or {@code 0} if this result represents a failed query. 36 */ 37 int getCount(); 38 39 /** 40 * Moves to a given suggestion. 41 * 42 * @param pos The position to move to. 43 * @throws IndexOutOfBoundsException if {@code pos < 0} or {@code pos >= getCount()}. 44 */ 45 void moveTo(int pos); 46 47 /** 48 * Moves to the next suggestion, if there is one. 49 * 50 * @return {@code false} if there is no next suggestion. 51 */ 52 boolean moveToNext(); 53 54 /** 55 * Gets the current position within the cursor. 56 */ 57 int getPosition(); 58 59 /** 60 * Frees any resources used by this cursor. 61 */ 62 void close(); 63 64 /** 65 * Register an observer that is called when changes happen to this data set. 66 * 67 * @param observer gets notified when the data set changes. 68 */ 69 void registerDataSetObserver(DataSetObserver observer); 70 71 /** 72 * Unregister an observer that has previously been registered with 73 * {@link #registerDataSetObserver(DataSetObserver)} 74 * 75 * @param observer the observer to unregister. 76 */ 77 void unregisterDataSetObserver(DataSetObserver observer); 78} 79