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