Source.java revision 49fd8e0994577badc6194c2c3b5f771f2b793fe4 
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 activity that intents from this source are sent to.
33     */
34    ComponentName getIntentComponent();
35
36    /**
37     * Gets the version code of the source. This is expected to change when the app that
38     * this source is for is upgraded.
39     */
40    int getVersionCode();
41
42    /**
43     * Gets the localized, human-readable label for this source.
44     */
45    CharSequence getLabel();
46
47    /**
48     * Gets the icon for this suggestion source.
49     */
50    Drawable getSourceIcon();
51
52    /**
53     * Gets the icon URI for this suggestion source.
54     */
55    Uri getSourceIconUri();
56
57    /**
58     * Gets an icon from this suggestion source.
59     *
60     * @param drawableId Resource ID or URI.
61     */
62    Drawable getIcon(String drawableId);
63
64    /**
65     * Gets the URI for an icon form this suggestion source.
66     *
67     * @param drawableId Resource ID or URI.
68     */
69    Uri getIconUri(String drawableId);
70
71    /**
72     * Gets the search hint text for this suggestion source.
73     */
74    CharSequence getHint();
75
76    /**
77     * Gets the description to use for this source in system search settings.
78     */
79    CharSequence getSettingsDescription();
80
81    /**
82     *
83     *  Note: this does not guarantee that this source will be queried for queries of
84     *  this length or longer, only that it will not be queried for anything shorter.
85     *
86     * @return The minimum number of characters needed to trigger this source.
87     */
88    int getQueryThreshold();
89
90    /**
91     * Indicates whether a source should be invoked for supersets of queries it has returned zero
92     * results for in the past.  For example, if a source returned zero results for "bo", it would
93     * be ignored for "bob".
94     *
95     * If set to <code>false</code>, this source will only be ignored for a single session; the next
96     * time the search dialog is brought up, all sources will be queried.
97     *
98     * @return <code>true</code> if this source should be queried after returning no results.
99     */
100    boolean queryAfterZeroResults();
101
102    boolean voiceSearchEnabled();
103
104    boolean isLocationAware();
105
106    Intent createSearchIntent(String query, Bundle appData);
107
108    Intent createVoiceSearchIntent(Bundle appData);
109
110    /**
111     * Checks if the current process can read the suggestions from this source.
112     */
113    boolean canRead();
114
115    /**
116     * Gets suggestions from this source.
117     *
118     * @param query The user query.
119     * @param queryLimit An advisory maximum number of results that the source should return.
120     * @param onlySource Indicates if this is the only source being queried.
121     * @return The suggestion results.
122     */
123    SourceResult getSuggestions(String query, int queryLimit, boolean onlySource);
124
125    /**
126     * Updates a shorcut.
127     *
128     * @param shortcutId The id of the shortcut to update.
129     * @param extraData associated with this shortcut.
130     * @return A SuggestionCursor positioned at the updated shortcut.  If the
131     *         cursor is empty or <code>null</code>, the shortcut will be removed.
132     */
133    SuggestionCursor refreshShortcut(String shortcutId, String extraData);
134
135    /**
136     * Gets the default intent action for suggestions from this source.
137     *
138     * @return The default intent action, or {@code null}.
139     */
140    String getDefaultIntentAction();
141
142    /**
143     * Gets the default intent data for suggestions from this source.
144     *
145     * @return The default intent data, or {@code null}.
146     */
147    String getDefaultIntentData();
148
149}
150