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 
17 package com.android.quicksearchbox;
18 
19 import com.android.quicksearchbox.util.NowOrLater;
20 
21 import android.content.ComponentName;
22 import android.content.Intent;
23 import android.graphics.drawable.Drawable;
24 import android.net.Uri;
25 import android.os.Bundle;
26 
27 /**
28  * Interface for suggestion sources.
29  *
30  */
31 public interface Source extends SuggestionCursorProvider<SourceResult> {
32 
33     /**
34      * Gets the name activity that intents from this source are sent to.
35      */
getIntentComponent()36     ComponentName getIntentComponent();
37 
38     /**
39      * Gets the suggestion URI for getting suggestions from this Source.
40      */
getSuggestUri()41     String getSuggestUri();
42 
43     /**
44      * Gets the localized, human-readable label for this source.
45      */
getLabel()46     CharSequence getLabel();
47 
48     /**
49      * Gets the icon for this suggestion source.
50      */
getSourceIcon()51     Drawable getSourceIcon();
52 
53     /**
54      * Gets the icon URI for this suggestion source.
55      */
getSourceIconUri()56     Uri getSourceIconUri();
57 
58     /**
59      * Gets an icon from this suggestion source.
60      *
61      * @param drawableId Resource ID or URI.
62      */
getIcon(String drawableId)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      */
getIconUri(String drawableId)70     Uri getIconUri(String drawableId);
71 
72     /**
73      * Gets the search hint text for this suggestion source.
74      */
getHint()75     CharSequence getHint();
76 
77     /**
78      * Gets the description to use for this source in system search settings.
79      */
getSettingsDescription()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      */
getQueryThreshold()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      */
queryAfterZeroResults()101     boolean queryAfterZeroResults();
102 
voiceSearchEnabled()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      */
includeInAll()109     boolean includeInAll();
110 
createSearchIntent(String query, Bundle appData)111     Intent createSearchIntent(String query, Bundle appData);
112 
createVoiceSearchIntent(Bundle appData)113     Intent createVoiceSearchIntent(Bundle appData);
114 
115     /**
116      * Checks if the current process can read the suggestions from this source.
117      */
canRead()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
getSuggestions(String query, int queryLimit)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      */
getDefaultIntentAction()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      */
getDefaultIntentData()141     String getDefaultIntentData();
142 
143     /**
144      * Gets the root source, if this source is a wrapper around another. Otherwise, returns this
145      * source.
146      */
getRoot()147     Source getRoot();
148 
149 }
150