/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */


#include "nsISupports.idl"

interface nsIAutoCompleteResult;
interface nsIFormAutoCompleteObserver;
interface nsIDOMHTMLInputElement;

[scriptable, uuid(c079f18f-40ab-409d-800e-878889b83b58)]

interface nsIFormAutoComplete: nsISupports {

    /**
     * Generate results for a form input autocomplete menu synchronously.
     * This method is deprecated in favour of autoCompleteSearchAsync.
     */
    nsIAutoCompleteResult autoCompleteSearch(in AString aInputName,
                                             in AString aSearchString,
                                             in nsIDOMHTMLInputElement aField,
                                             in nsIAutoCompleteResult aPreviousResult);

    /**
     * Generate results for a form input autocomplete menu asynchronously.
     */
    void autoCompleteSearchAsync(in AString aInputName,
                                 in AString aSearchString,
                                 in nsIDOMHTMLInputElement aField,
                                 in nsIAutoCompleteResult aPreviousResult,
                                 in nsIFormAutoCompleteObserver aListener);

    /**
     * If a search is in progress, stop it. Otherwise, do nothing. This is used
     * to cancel an existing search, for example, in preparation for a new search.
     */
    void stopAutoCompleteSearch();
};

[scriptable, function, uuid(604419ab-55a0-4831-9eca-1b9e67cc4751)]
interface nsIFormAutoCompleteObserver : nsISupports
{
  /*
   * Called when a search is complete and the results are ready even if the
   * result set is empty. If the search is cancelled or a new search is
   * started, this is not called.
   *
   * @param result - The search result object
   */
  void onSearchCompletion(in nsIAutoCompleteResult result);
};