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 localized, human-readable label for this source.
45     */
46    CharSequence getLabel();
47
48    /**
49     * Gets the icon for this suggestion source.
50     */
51    Drawable getSourceIcon();
52
53    /**
54     * Gets the icon URI for this suggestion source.
55     */
56    Uri getSourceIconUri();
57
58    /**
59     * Gets an icon from this suggestion source.
60     *
61     * @param drawableId Resource ID or URI.
62     */
63    NowOrLater<Drawable> getIcon(String drawableId);
64
65    /**
66     * Gets the URI for an icon form this suggestion source.
67     *
68     * @param drawableId Resource ID or URI.
69     */
70    Uri getIconUri(String drawableId);
71
72    /**
73     * Gets the search hint text for this suggestion source.
74     */
75    CharSequence getHint();
76
77    /**
78     * Gets the description to use for this source in system search settings.
79     */
80    CharSequence getSettingsDescription();
81
82    /**
83     *
84     *  Note: this does not guarantee that this source will be queried for queries of
85     *  this length or longer, only that it will not be queried for anything shorter.
86     *
87     * @return The minimum number of characters needed to trigger this source.
88     */
89    int getQueryThreshold();
90
91    /**
92     * Indicates whether a source should be invoked for supersets of queries it has returned zero
93     * results for in the past.  For example, if a source returned zero results for "bo", it would
94     * be ignored for "bob".
95     *
96     * If set to <code>false</code>, this source will only be ignored for a single session; the next
97     * time the search dialog is brought up, all sources will be queried.
98     *
99     * @return <code>true</code> if this source should be queried after returning no results.
100     */
101    boolean queryAfterZeroResults();
102
103    boolean voiceSearchEnabled();
104
105    /**
106     * Whether this source should be included in the blended All mode. The source must
107     * also be enabled to be included in All.
108     */
109    boolean includeInAll();
110
111    Intent createSearchIntent(String query, Bundle appData);
112
113    Intent createVoiceSearchIntent(Bundle appData);
114
115    /**
116     * Checks if the current process can read the suggestions from this source.
117     */
118    boolean canRead();
119
120    /**
121     * Gets suggestions from this source.
122     *
123     * @param query The user query.
124     * @return The suggestion results.
125     */
126    @Override
127    SourceResult getSuggestions(String query, int queryLimit);
128
129    /**
130     * Gets the default intent action for suggestions from this source.
131     *
132     * @return The default intent action, or {@code null}.
133     */
134    String getDefaultIntentAction();
135
136    /**
137     * Gets the default intent data for suggestions from this source.
138     *
139     * @return The default intent data, or {@code null}.
140     */
141    String getDefaultIntentData();
142
143    /**
144     * Gets the root source, if this source is a wrapper around another. Otherwise, returns this
145     * source.
146     */
147    Source getRoot();
148
149}
150