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