SuggestionCursor.java revision 87e947cbd9f279a83337900ff8bbd5ab0a8dc455
13e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert/* 23e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * Copyright (C) 2009 The Android Open Source Project 33e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * 43e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * Licensed under the Apache License, Version 2.0 (the "License"); 53e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * you may not use this file except in compliance with the License. 63e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * You may obtain a copy of the License at 73e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * 83e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * http://www.apache.org/licenses/LICENSE-2.0 93e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * 103e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * Unless required by applicable law or agreed to in writing, software 113e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * distributed under the License is distributed on an "AS IS" BASIS, 123e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 133e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * See the License for the specific language governing permissions and 143e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * limitations under the License. 153e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 163e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 173e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringertpackage com.android.quicksearchbox; 183e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 1994e8a2be78530170f50e7895a558bf8011bbf8e8Bryan Mawhinneyimport android.database.DataSetObserver; 203e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 213e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 22fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert/** 23fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * A sequence of suggestions, with a current position. 24fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert */ 25fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringertpublic interface SuggestionCursor { 263e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 273e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 28fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * Gets the number of suggestions in this result. 29fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * 30fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * @return The number of suggestions, or {@code 0} if this result represents a failed query. 313e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 32fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert int getCount(); 333e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 343e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 35fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * Moves to a given suggestion. 36fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * 37fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * @param pos The position to move to. 38fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * @throws IndexOutOfBoundsException if {@code pos < 0} or {@code pos >= getCount()}. 393e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 40fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert void moveTo(int pos); 413e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 423e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 4387e947cbd9f279a83337900ff8bbd5ab0a8dc455Bjorn Bringert * Moves to the next suggestion, if there is one. 4487e947cbd9f279a83337900ff8bbd5ab0a8dc455Bjorn Bringert * 4587e947cbd9f279a83337900ff8bbd5ab0a8dc455Bjorn Bringert * @return {@code false} if there is no next suggestion. 4687e947cbd9f279a83337900ff8bbd5ab0a8dc455Bjorn Bringert */ 4787e947cbd9f279a83337900ff8bbd5ab0a8dc455Bjorn Bringert boolean moveToNext(); 4887e947cbd9f279a83337900ff8bbd5ab0a8dc455Bjorn Bringert 4987e947cbd9f279a83337900ff8bbd5ab0a8dc455Bjorn Bringert /** 50fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * Gets the current position within the cursor. 513e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 52fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert int getPosition(); 533e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 543e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 55fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * Frees any resources used by this cursor. 563e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 573e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert void close(); 583e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 593e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 60fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * Register an observer that is called when changes happen to this data set. 6194e8a2be78530170f50e7895a558bf8011bbf8e8Bryan Mawhinney * 62fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * @param observer gets notified when the data set changes. 6394e8a2be78530170f50e7895a558bf8011bbf8e8Bryan Mawhinney */ 64fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert void registerDataSetObserver(DataSetObserver observer); 6594e8a2be78530170f50e7895a558bf8011bbf8e8Bryan Mawhinney 6694e8a2be78530170f50e7895a558bf8011bbf8e8Bryan Mawhinney /** 67fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * Unregister an observer that has previously been registered with 68fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * {@link #registerDataSetObserver(DataSetObserver)} 6994e8a2be78530170f50e7895a558bf8011bbf8e8Bryan Mawhinney * 70fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * @param observer the observer to unregister. 7194e8a2be78530170f50e7895a558bf8011bbf8e8Bryan Mawhinney */ 72fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert void unregisterDataSetObserver(DataSetObserver observer); 7394e8a2be78530170f50e7895a558bf8011bbf8e8Bryan Mawhinney 7494e8a2be78530170f50e7895a558bf8011bbf8e8Bryan Mawhinney /** 75fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * Gets the source that produced the current suggestion. 763e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 77fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert Source getSuggestionSource(); 783e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 793e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 80fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * Gets the query that the user typed to get this suggestion. 813e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 82fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert String getUserQuery(); 833e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 843e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 853e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * Gets the shortcut ID of the current suggestion. 863e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 873e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert String getShortcutId(); 883e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 893e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 9094e8a2be78530170f50e7895a558bf8011bbf8e8Bryan Mawhinney * Whether to show a spinner while refreshing this shortcut. 9194e8a2be78530170f50e7895a558bf8011bbf8e8Bryan Mawhinney */ 9294e8a2be78530170f50e7895a558bf8011bbf8e8Bryan Mawhinney boolean isSpinnerWhileRefreshing(); 9394e8a2be78530170f50e7895a558bf8011bbf8e8Bryan Mawhinney 9494e8a2be78530170f50e7895a558bf8011bbf8e8Bryan Mawhinney /** 953e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * Gets the format of the text returned by {@link #getSuggestionText1()} 963e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * and {@link #getSuggestionText2()}. 973e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * 983e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * @return {@code null} or "html" 993e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 1003e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert String getSuggestionFormat(); 1013e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 1023e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 1033e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * Gets the first text line for the current suggestion. 1043e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 1053e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert String getSuggestionText1(); 1063e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 1073e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 1083e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * Gets the second text line for the current suggestion. 1093e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 1103e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert String getSuggestionText2(); 1113e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 1123e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 113965d98377ddfdc52b772c2444d840000b665e000Bjorn Bringert * Gets the second text line URL for the current suggestion. 114965d98377ddfdc52b772c2444d840000b665e000Bjorn Bringert */ 115965d98377ddfdc52b772c2444d840000b665e000Bjorn Bringert String getSuggestionText2Url(); 116965d98377ddfdc52b772c2444d840000b665e000Bjorn Bringert 117965d98377ddfdc52b772c2444d840000b665e000Bjorn Bringert /** 1183e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * Gets the left-hand-side icon for the current suggestion. 1193e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * 120fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * @return A string that can be passed to {@link Source#getIcon(String)}. 1213e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 1223e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert String getSuggestionIcon1(); 1233e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 1243e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 1253e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * Gets the right-hand-side icon for the current suggestion. 1263e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert * 127fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * @return A string that can be passed to {@link Source#getIcon(String)}. 1283e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 1293e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert String getSuggestionIcon2(); 1303e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 1313e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 132fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * Gets the intent action for the current suggestion. 1333e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 134fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert String getSuggestionIntentAction(); 1353e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 1363e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 1371e938ea2f5edefab446b9562b316bc5dc72adebbBryan Mawhinney * Gets the extra data associated with this suggestion's intent. 1383e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 1391e938ea2f5edefab446b9562b316bc5dc72adebbBryan Mawhinney String getSuggestionIntentExtraData(); 1403e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 1413e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 1421e938ea2f5edefab446b9562b316bc5dc72adebbBryan Mawhinney * Gets the data associated with this suggestion's intent. 1433e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 1441e938ea2f5edefab446b9562b316bc5dc72adebbBryan Mawhinney String getSuggestionIntentDataString(); 1453e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 1463e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 147fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * Gets the data associated with this suggestion's intent. 1483e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 149fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert String getSuggestionQuery(); 1503e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 151fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert String getSuggestionDisplayQuery(); 1523e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert 1533e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert /** 154fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * Gets a unique key that identifies this suggestion. This is used to avoid 155fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * duplicate suggestions in the promoted list. This key should be based on 156fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert * the intent of the suggestion. 1573e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert */ 158fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert String getSuggestionKey(); 159782dd228e78e9294692d639597f96c26283968bbBjorn Bringert 160782dd228e78e9294692d639597f96c26283968bbBjorn Bringert /** 161dbce1abe91200e83a41bcd95aaf5ea89496e5e48Bjorn Bringert * Gets the suggestion log type for the current suggestion. This is logged together 162dbce1abe91200e83a41bcd95aaf5ea89496e5e48Bjorn Bringert * with the value returned from {@link Source#getLogName()}. 163dbce1abe91200e83a41bcd95aaf5ea89496e5e48Bjorn Bringert * The value is source-specific. Most sources return {@code null}. 164782dd228e78e9294692d639597f96c26283968bbBjorn Bringert */ 165fde948e69f59589cf0d217ea414af7947de600bbBjorn Bringert String getSuggestionLogType(); 166883c1bf364e38c5b133afb55f8493a14b65f4dd4Bjorn Bringert 167883c1bf364e38c5b133afb55f8493a14b65f4dd4Bjorn Bringert /** 168883c1bf364e38c5b133afb55f8493a14b65f4dd4Bjorn Bringert * Checks if this suggestion is a shortcut. 169883c1bf364e38c5b133afb55f8493a14b65f4dd4Bjorn Bringert */ 170883c1bf364e38c5b133afb55f8493a14b65f4dd4Bjorn Bringert boolean isSuggestionShortcut(); 1713e44ff1f2a204db3f479698cf0b3eab3d451dec2Bjorn Bringert} 172