Source.java revision f252dc7a25ba08b973ecc1cfbbce58eb78d42167 
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.Intent;
21import android.graphics.drawable.Drawable;
22import android.net.Uri;
23import android.os.Bundle;
24
25/**
26 * Interface for suggestion sources.
27 *
28 */
29public interface Source extends SuggestionCursorProvider<SourceResult> {
30
31    /**
32     * Gets the name of the activity that this source is for. When a suggestion is
33     * clicked, the resulting intent will be sent to this activity.
34     */
35    ComponentName getComponentName();
36
37    /**
38     * Gets the localized, human-readable label for this source.
39     */
40    CharSequence getLabel();
41
42    /**
43     * Gets the icon for this suggestion source.
44     */
45    Drawable getSourceIcon();
46
47    /**
48     * Gets the icon URI for this suggestion source.
49     */
50    Uri getSourceIconUri();
51
52    /**
53     * Gets an icon from this suggestion source.
54     *
55     * @param drawableId Resource ID or URI.
56     */
57    Drawable getIcon(String drawableId);
58
59    /**
60     * Gets the URI for an icon form this suggestion source.
61     *
62     * @param drawableId Resource ID or URI.
63     */
64    Uri getIconUri(String drawableId);
65
66    /**
67     * Gets the search hint text for this suggestion source.
68     */
69    CharSequence getHint();
70
71    /**
72     * Gets the description to use for this source in system search settings.
73     */
74    CharSequence getSettingsDescription();
75
76    /**
77     *
78     *  Note: this does not guarantee that this source will be queried for queries of
79     *  this length or longer, only that it will not be queried for anything shorter.
80     *
81     * @return The minimum number of characters needed to trigger this source.
82     */
83    int getQueryThreshold();
84
85    /**
86     * Indicates whether a source should be invoked for supersets of queries it has returned zero
87     * results for in the past.  For example, if a source returned zero results for "bo", it would
88     * be ignored for "bob".
89     *
90     * If set to <code>false</code>, this source will only be ignored for a single session; the next
91     * time the search dialog is brought up, all sources will be queried.
92     *
93     * @return <code>true</code> if this source should be queried after returning no results.
94     */
95    boolean queryAfterZeroResults();
96
97    boolean voiceSearchEnabled();
98
99    Intent createSearchIntent(String query, Bundle appData);
100
101    Intent createVoiceSearchIntent(Bundle appData);
102
103    /**
104     * Gets suggestions from this source.
105     *
106     * @param query The user query.
107     * @param queryLimit An advisory maximum number of results that the source should return.
108     * @return The suggestion results.
109     */
110    SourceResult getSuggestions(String query, int queryLimit);
111
112    /**
113     * Updates a shorcut.
114     *
115     * @param shortcutId The id of the shortcut to update.
116     * @param extraData associated with this shortcut.
117     * @return A SuggestionCursor positioned at the updated shortcut.  If the
118     *         cursor is empty or <code>null</code>, the shortcut will be removed.
119     */
120    SuggestionCursor refreshShortcut(String shortcutId, String extraData);
121
122    /**
123     * Checks whether this is a web suggestion source.
124     */
125    boolean isWebSuggestionSource();
126
127    /**
128     * Checks whether the text in the query field should come from the suggestion intent data.
129     */
130    boolean shouldRewriteQueryFromData();
131
132    /**
133     * Checks whether the text in the query field should come from the suggestion title.
134     */
135    boolean shouldRewriteQueryFromText();
136
137    /**
138     * Gets the default intent action for suggestions from this source.
139     *
140     * @return The default intent action, or {@code null}.
141     */
142    String getDefaultIntentAction();
143
144    /**
145     * Gets the default intent data for suggestions from this source.
146     *
147     * @return The default intent data, or {@code null}.
148     */
149    String getDefaultIntentData();
150
151    /**
152     * Gets the action message for a give action key code for suggestions from
153     * this source. This is only used if {@link #getSuggestActionMsgColumn}
154     * does not get an action message.
155     *
156     * @param keyCode Action key code, see {@link android.view.KeyEvent}.
157     * @return An action message, of {@code null} if this source does not support the given
158     *         action key.
159     */
160    String getSuggestActionMsg(int keyCode);
161
162    /**
163     * Gets the column name containing the action message for a give action key code.
164     *
165     * TODO: This is only meaningful for cursor-backed suggestion cursors.
166     *
167     * @param keyCode Action key code, see {@link android.view.KeyEvent}.
168     * @return A column name, of {@code null} if this source does not support the given
169     *         action key.
170     */
171    String getSuggestActionMsgColumn(int keyCode);
172}
173