Source.java revision 77909685887bd6db7454b73cf274afc3aca2f58d 
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 com.android.quicksearchbox.util.NowOrLater;
20
21import android.content.ComponentName;
22import android.content.Intent;
23import android.graphics.drawable.Drawable;
24import android.net.Uri;
25import android.os.Bundle;
26
27/**
28 * Interface for suggestion sources.
29 *
30 */
31public interface Source extends SuggestionCursorProvider<SourceResult> {
32
33    /**
34     * Gets the name activity that intents from this source are sent to.
35     */
36    ComponentName getIntentComponent();
37
38    /**
39     * Gets the suggestion URI for getting suggestions from this Source.
40     */
41    String getSuggestUri();
42
43    /**
44     * Gets the version code of the source. This is expected to change when the app that
45     * this source is for is upgraded.
46     */
47    int getVersionCode();
48
49    /**
50     * Indicates if shortcuts from the given version of this source are compatible with the
51     * currently installed version. The version code given will only differ from the currently
52     * installed version after the source has been upgraded.
53     *
54     * @param version version of the source (as returned by {@link #getVersionCode} which originally
55     *      created the shortcut.
56     */
57    boolean isVersionCodeCompatible(int version);
58
59    /**
60     * Gets the localized, human-readable label for this source.
61     */
62    CharSequence getLabel();
63
64    /**
65     * Gets the icon for this suggestion source.
66     */
67    Drawable getSourceIcon();
68
69    /**
70     * Gets the icon URI for this suggestion source.
71     */
72    Uri getSourceIconUri();
73
74    /**
75     * Gets an icon from this suggestion source.
76     *
77     * @param drawableId Resource ID or URI.
78     */
79    NowOrLater<Drawable> getIcon(String drawableId);
80
81    /**
82     * Gets the URI for an icon form this suggestion source.
83     *
84     * @param drawableId Resource ID or URI.
85     */
86    Uri getIconUri(String drawableId);
87
88    /**
89     * Gets the search hint text for this suggestion source.
90     */
91    CharSequence getHint();
92
93    /**
94     * Gets the description to use for this source in system search settings.
95     */
96    CharSequence getSettingsDescription();
97
98    /**
99     *
100     *  Note: this does not guarantee that this source will be queried for queries of
101     *  this length or longer, only that it will not be queried for anything shorter.
102     *
103     * @return The minimum number of characters needed to trigger this source.
104     */
105    int getQueryThreshold();
106
107    /**
108     * Indicates whether a source should be invoked for supersets of queries it has returned zero
109     * results for in the past.  For example, if a source returned zero results for "bo", it would
110     * be ignored for "bob".
111     *
112     * If set to <code>false</code>, this source will only be ignored for a single session; the next
113     * time the search dialog is brought up, all sources will be queried.
114     *
115     * @return <code>true</code> if this source should be queried after returning no results.
116     */
117    boolean queryAfterZeroResults();
118
119    boolean voiceSearchEnabled();
120
121    /**
122     * Whether this source should be included in the blended All mode. The source must
123     * also be enabled to be included in All.
124     */
125    boolean includeInAll();
126
127    /**
128     * Gets the maximum number of shortcuts that will be shown from this source.
129     */
130    int getMaxShortcuts(Config config);
131
132    Intent createSearchIntent(String query, Bundle appData);
133
134    Intent createVoiceSearchIntent(Bundle appData);
135
136    /**
137     * Checks if the current process can read the suggestions from this source.
138     */
139    boolean canRead();
140
141    /**
142     * Gets suggestions from this source.
143     *
144     * @param query The user query.
145     * @param onlySource Indicates if this is the only source being queried.
146     * @return The suggestion results.
147     */
148    SourceResult getSuggestions(String query, int queryLimit, boolean onlySource);
149
150    /**
151     * Updates a shortcut.
152     *
153     * @param shortcutId The id of the shortcut to update.
154     * @param extraData associated with this shortcut.
155     * @return A SuggestionCursor positioned at the updated shortcut.  If the
156     *         cursor is empty or <code>null</code>, the shortcut will be removed.
157     */
158    SuggestionCursor refreshShortcut(String shortcutId, String extraData);
159
160    /**
161     * Gets the default intent action for suggestions from this source.
162     *
163     * @return The default intent action, or {@code null}.
164     */
165    String getDefaultIntentAction();
166
167    /**
168     * Gets the default intent data for suggestions from this source.
169     *
170     * @return The default intent data, or {@code null}.
171     */
172    String getDefaultIntentData();
173
174    /**
175     * Gets the root source, if this source is a wrapper around another. Otherwise, returns this
176     * source.
177     */
178    Source getRoot();
179
180}
181