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 version code of the source. This is expected to change when the app that 45 * this source is for is upgraded. 46 */ getVersionCode()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 */ isVersionCodeCompatible(int version)57 boolean isVersionCodeCompatible(int version); 58 59 /** 60 * Gets the localized, human-readable label for this source. 61 */ getLabel()62 CharSequence getLabel(); 63 64 /** 65 * Gets the icon for this suggestion source. 66 */ getSourceIcon()67 Drawable getSourceIcon(); 68 69 /** 70 * Gets the icon URI for this suggestion source. 71 */ getSourceIconUri()72 Uri getSourceIconUri(); 73 74 /** 75 * Gets an icon from this suggestion source. 76 * 77 * @param drawableId Resource ID or URI. 78 */ getIcon(String drawableId)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 */ getIconUri(String drawableId)86 Uri getIconUri(String drawableId); 87 88 /** 89 * Gets the search hint text for this suggestion source. 90 */ getHint()91 CharSequence getHint(); 92 93 /** 94 * Gets the description to use for this source in system search settings. 95 */ getSettingsDescription()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 */ getQueryThreshold()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 */ queryAfterZeroResults()117 boolean queryAfterZeroResults(); 118 voiceSearchEnabled()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 */ includeInAll()125 boolean includeInAll(); 126 127 /** 128 * Gets the maximum number of shortcuts that will be shown from this source. 129 */ getMaxShortcuts(Config config)130 int getMaxShortcuts(Config config); 131 createSearchIntent(String query, Bundle appData)132 Intent createSearchIntent(String query, Bundle appData); 133 createVoiceSearchIntent(Bundle appData)134 Intent createVoiceSearchIntent(Bundle appData); 135 136 /** 137 * Checks if the current process can read the suggestions from this source. 138 */ canRead()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 */ getSuggestions(String query, int queryLimit, boolean onlySource)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 */ refreshShortcut(String shortcutId, String extraData)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 */ getDefaultIntentAction()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 */ getDefaultIntentData()172 String getDefaultIntentData(); 173 174 /** 175 * Gets the root source, if this source is a wrapper around another. Otherwise, returns this 176 * source. 177 */ getRoot()178 Source getRoot(); 179 180 } 181