packages/apps/QuickSearchBox/src/com/android/quicksearchbox/SuggestionCursor.java

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