FileDocCategorySizeDatePackage
SearchRecentSuggestions.javaAPI DocAndroid 1.5 API9876Wed May 06 22:41:56 BST 2009android.provider

SearchRecentSuggestions

public class SearchRecentSuggestions extends Object
This is a utility class providing access to {@link android.content.SearchRecentSuggestionsProvider}.

Unlike some utility classes, this one must be instantiated and properly initialized, so that it can be configured to operate with the search suggestions provider that you have created.

Typically, you will do this in your searchable activity, each time you receive an incoming {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent. The code to record each incoming query is as follows: 

SearchSuggestions suggestions = new SearchSuggestions(this,
MySuggestionsProvider.AUTHORITY, MySuggestionsProvider.MODE);
suggestions.saveRecentQuery(queryString, null);

For a working example, see SearchSuggestionSampleProvider and SearchQueryResults in samples/ApiDemos/app.

Fields Summary
private static final String
LOG_TAG
private static final int
DBG_SUGGESTION_TIMESTAMPS
public static final String[]
QUERIES_PROJECTION_1LINE
This is the database projection that can be used to view saved queries, when configured for one-line operation.
public static final String[]
QUERIES_PROJECTION_2LINE
This is the database projection that can be used to view saved queries, when configured for two-line operation.
public static final int
QUERIES_PROJECTION_DATE_INDEX
Index into the provided query projections. For use with Cursor.update methods.
public static final int
QUERIES_PROJECTION_QUERY_INDEX
Index into the provided query projections. For use with Cursor.update methods.
public static final int
QUERIES_PROJECTION_DISPLAY1_INDEX
Index into the provided query projections. For use with Cursor.update methods.
public static final int
QUERIES_PROJECTION_DISPLAY2_INDEX
Index into the provided query projections. For use with Cursor.update methods.
private static final String[]
TRUNCATE_HISTORY_PROJECTION
private static final int
MAX_HISTORY_COUNT
private android.content.Context
mContext
private String
mAuthority
private boolean
mTwoLineDisplay
private android.net.Uri
mSuggestionsUri
private String[]
mQueriesProjection
Constructors Summary
public SearchRecentSuggestions(android.content.Context context, String authority, int mode)
Although provider utility classes are typically static, this one must be constructed because it needs to be initialized using the same values that you provided in your {@link android.content.SearchRecentSuggestionsProvider}.

param
authority This must match the authority that you've declared in your manifest.
param
mode You can use mode flags here to determine certain functional aspects of your database. Note, this value should not change from run to run, because when it does change, your suggestions database may be wiped.
see
android.content.SearchRecentSuggestionsProvider
see
android.content.SearchRecentSuggestionsProvider#setupSuggestions


                                                                                                  
           
        if (TextUtils.isEmpty(authority) || 
                ((mode & SearchRecentSuggestionsProvider.DATABASE_MODE_QUERIES) == 0)) {
            throw new IllegalArgumentException();
        }
        // unpack mode flags
        mTwoLineDisplay = (0 != (mode & SearchRecentSuggestionsProvider.DATABASE_MODE_2LINES));
            
        // saved values
        mContext = context;
        mAuthority = new String(authority);
        
        // derived values
        mSuggestionsUri = Uri.parse("content://" + mAuthority + "/suggestions");
        
        if (mTwoLineDisplay) {
            mQueriesProjection = QUERIES_PROJECTION_2LINE;
        } else {
            mQueriesProjection = QUERIES_PROJECTION_1LINE;
        }
Methods Summary
public voidclearHistory()
Completely delete the history. Use this call to implement a "clear history" UI. Any application that implements search suggestions based on previous actions (such as recent queries, page/items viewed, etc.) should provide a way for the user to clear the history. This gives the user a measure of privacy, if they do not wish for their recent searches to be replayed by other users of the device (via suggestions).

        ContentResolver cr = mContext.getContentResolver();
        truncateHistory(cr, 0);
public voidsaveRecentQuery(java.lang.String queryString, java.lang.String line2)
Add a query to the recent queries list.

param
queryString The string as typed by the user. This string will be displayed as the suggestion, and if the user clicks on the suggestion, this string will be sent to your searchable activity (as a new search query).
param
line2 If you have configured your recent suggestions provider with {@link android.content.SearchRecentSuggestionsProvider#DATABASE_MODE_2LINES}, you can pass a second line of text here. It will be shown in a smaller font, below the primary suggestion. When typing, matches in either line of text will be displayed in the list. If you did not configure two-line mode, or if a given suggestion does not have any additional text to display, you can pass null here.

        if (TextUtils.isEmpty(queryString)) {
            return;
        }
        if (!mTwoLineDisplay && !TextUtils.isEmpty(line2)) {
            throw new IllegalArgumentException();
        }
        
        ContentResolver cr = mContext.getContentResolver();
        long now = System.currentTimeMillis();
        
        // Use content resolver (not cursor) to insert/update this query
        try {
            ContentValues values = new ContentValues();
            values.put(SuggestionColumns.DISPLAY1, queryString);
            if (mTwoLineDisplay) {
                values.put(SuggestionColumns.DISPLAY2, line2);
            }
            values.put(SuggestionColumns.QUERY, queryString);
            values.put(SuggestionColumns.DATE, now);
            cr.insert(mSuggestionsUri, values);
        } catch (RuntimeException e) {
            Log.e(LOG_TAG, "saveRecentQuery", e);
        }
        
        // Shorten the list (if it has become too long)
        truncateHistory(cr, MAX_HISTORY_COUNT);
protected voidtruncateHistory(android.content.ContentResolver cr, int maxEntries)
Reduces the length of the history table, to prevent it from growing too large.

param
cr Convenience copy of the content resolver.
param
maxEntries Max entries to leave in the table. 0 means remove all entries.

        if (maxEntries < 0) {
            throw new IllegalArgumentException();
        }
        
        try {
            // null means "delete all".  otherwise "delete but leave n newest"
            String selection = null;
            if (maxEntries > 0) {
                selection = "_id IN " +
                        "(SELECT _id FROM suggestions" +
                        " ORDER BY " + SuggestionColumns.DATE + " DESC" +
                        " LIMIT -1 OFFSET " + String.valueOf(maxEntries) + ")";
            }
            cr.delete(mSuggestionsUri, selection, null);
        } catch (RuntimeException e) {
            Log.e(LOG_TAG, "truncateHistory", e);
        }