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