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