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