SuggestionCursor.java revision 3e44ff1f2a204db3f479698cf0b3eab3d451dec2 
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.ComponentName;
20import android.content.Context;
21import android.content.Intent;
22import android.graphics.Rect;
23import android.graphics.drawable.Drawable;
24import android.net.Uri;
25import android.os.Bundle;
26
27public interface SuggestionCursor {
28
29    /**
30     * The user query that returned these suggestions.
31     */
32    String getUserQuery();
33
34    /**
35     * Gets the component name of the source that produced this result.
36     */
37    ComponentName getSourceComponentName();
38
39    /**
40     * Gets the localized, human-readable label for the source that produced this result.
41     */
42    CharSequence getSourceLabel();
43
44    /**
45     * Gets the icon for the source that produced this result.
46     */
47    Drawable getSourceIcon();
48
49    /**
50     * Gets the icon URI for the source that produced this result.
51     */
52    Uri getSourceIconUri();
53
54    /**
55     * Gets an icon by ID. Used for getting the icons returned by {@link #getSuggestionIcon1()}
56     * and {@link #getSuggestionIcon2()}.
57     */
58    Drawable getIcon(String iconId);
59
60    /**
61     * Gets the URI for an icon.
62     */
63    Uri getIconUri(String iconId);
64
65    /**
66     * Checks whether this result represents a failed suggestion query.
67     */
68    boolean isFailed();
69
70    /**
71     * Closes this suggestion result.
72     */
73    void close();
74
75    /**
76     * Gets the number of suggestions in this result.
77     *
78     * @return The number of suggestions, or {@code 0} if this result represents a failed query.
79     */
80    int getCount();
81
82    /**
83     * Moves to a given suggestion.
84     *
85     * @param pos The position to move to.
86     * @throws IndexOutOfBoundsException if {@code pos < 0} or {@code pos >= getCount()}.
87     */
88    void moveTo(int pos);
89
90    /**
91     * Gets the current position within the cursor.
92     */
93    int getPosition();
94
95    /**
96     * Gets the text to put in the search box when the current suggestion is selected.
97     */
98    String getSuggestionDisplayQuery();
99
100    /**
101     * Gets the shortcut ID of the current suggestion.
102     */
103    String getShortcutId();
104
105    /**
106     * Gets the format of the text returned by {@link #getSuggestionText1()}
107     * and {@link #getSuggestionText2()}.
108     *
109     * @return {@code null} or "html"
110     */
111    String getSuggestionFormat();
112
113    /**
114     * Gets the first text line for the current suggestion.
115     */
116    String getSuggestionText1();
117
118    /**
119     * Gets the second text line for the current suggestion.
120     */
121    String getSuggestionText2();
122
123    /**
124     * Gets the left-hand-side icon for the current suggestion.
125     *
126     * @return A string that can be passed to {@link #getIcon()}.
127     */
128    String getSuggestionIcon1();
129
130    /**
131     * Gets the right-hand-side icon for the current suggestion.
132     *
133     * @return A string that can be passed to {@link #getIcon()}.
134     */
135    String getSuggestionIcon2();
136
137    /**
138     * Gets the intent that this suggestion launches.
139     *
140     * @param context Used for resolving the intent target.
141     * @param actionKey
142     * @param actionMsg
143     * @return
144     */
145    Intent getSuggestionIntent(Context context, Bundle appSearchData,
146            int actionKey, String actionMsg);
147
148    /**
149     * Gets the secondary intent associated with this suggestion.
150     *
151     * @param context Used for resolving the intent target.
152     * @param appSearchData application specific data passed in the search request
153     * @param target Rect describing the position of this result on the screen
154     * @return the secondary intent, or {@code null} if there is none
155     */
156    Intent getSecondarySuggestionIntent(Context context, Bundle appSearchData,
157            Rect target);
158
159    /**
160     * Checks whether the current suggestion has a secondary intent.
161     */
162    boolean hasSecondaryIntent();
163
164    /**
165     * Gets a unique key that identifies this suggestion. This is used to avoid
166     * duplicate suggestions in the promoted list. This key should be based on
167     * the intent of the suggestion.
168     */
169    String getSuggestionKey();
170
171    /**
172     * Gets the first suggestion text line as styled text.
173     */
174    CharSequence getSuggestionFormattedText1();
175
176    /**
177     * Gets the second suggestion text line as styled text.
178     */
179    CharSequence getSuggestionFormattedText2();
180
181    /**
182     * Gets the first suggestion icon.
183     */
184    Drawable getSuggestionDrawableIcon1();
185
186    /**
187     * Gets the second suggestion icon.
188     */
189    Drawable getSuggestionDrawableIcon2();
190}
191