Home | History | Annotate | Download | only in quicksearchbox 
      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 of the activity that this source is for. When a suggestion is
     33      * clicked, the resulting intent will be sent to this activity.
     34      */
     35     ComponentName getComponentName();
     36 
     37     /**
     38      * Gets the version code of the source. This is expected to change when the app that
     39      * this source is for is upgraded.
     40      */
     41     int getVersionCode();
     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     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     Intent createSearchIntent(String query, Bundle appData);
    106 
    107     Intent createVoiceSearchIntent(Bundle appData);
    108 
    109     /**
    110      * Gets suggestions from this source.
    111      *
    112      * @param query The user query.
    113      * @param queryLimit An advisory maximum number of results that the source should return.
    114      * @return The suggestion results.
    115      */
    116     SourceResult getSuggestions(String query, int queryLimit);
    117 
    118     /**
    119      * Updates a shorcut.
    120      *
    121      * @param shortcutId The id of the shortcut to update.
    122      * @param extraData associated with this shortcut.
    123      * @return A SuggestionCursor positioned at the updated shortcut.  If the
    124      *         cursor is empty or <code>null</code>, the shortcut will be removed.
    125      */
    126     SuggestionCursor refreshShortcut(String shortcutId, String extraData);
    127 
    128     /**
    129      * Checks whether this is a web suggestion source.
    130      */
    131     boolean isWebSuggestionSource();
    132 
    133     /**
    134      * Checks whether the text in the query field should come from the suggestion intent data.
    135      */
    136     boolean shouldRewriteQueryFromData();
    137 
    138     /**
    139      * Checks whether the text in the query field should come from the suggestion title.
    140      */
    141     boolean shouldRewriteQueryFromText();
    142 
    143     /**
    144      * Gets the default intent action for suggestions from this source.
    145      *
    146      * @return The default intent action, or {@code null}.
    147      */
    148     String getDefaultIntentAction();
    149 
    150     /**
    151      * Gets the default intent data for suggestions from this source.
    152      *
    153      * @return The default intent data, or {@code null}.
    154      */
    155     String getDefaultIntentData();
    156 
    157 }
    158