gecko-dev/toolkit/components/autocomplete/nsIAutoCompleteController.idl

148 lines
4.4 KiB
Plaintext

/* 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 nsIAutoCompleteInput;
[scriptable, uuid(ff9f8465-204a-47a6-b3c9-0628b3856684)]
interface nsIAutoCompleteController : nsISupports
{
/*
* Possible values for the searchStatus attribute
*/
const unsigned short STATUS_NONE = 1;
const unsigned short STATUS_SEARCHING = 2;
const unsigned short STATUS_COMPLETE_NO_MATCH = 3;
const unsigned short STATUS_COMPLETE_MATCH = 4;
/*
* The input widget that is currently being controlled.
*/
attribute nsIAutoCompleteInput input;
/*
* State which indicates the status of possible ongoing searches
*/
readonly attribute unsigned short searchStatus;
/*
* The number of matches
*/
readonly attribute unsigned long matchCount;
/*
* Start a search on a string, assuming the input property is already set.
*/
void startSearch(in AString searchString);
/*
* Stop all asynchronous searches
*/
void stopSearch();
/*
* Notify the controller that the user has changed text in the textbox.
* This includes all means of changing the text value, including typing a
* character, backspacing, deleting, pasting, committing composition or
* canceling composition.
*
* NOTE: handleText() must be called after composition actually ends, even if
* the composition is canceled and the textbox value isn't changed.
* Then, implementation of handleText() can access the editor when
* it's not in composing mode. DOM compositionend event is not good
* timing for calling handleText(). DOM input event immediately after
* DOM compositionend event is the best timing to call this.
*/
void handleText();
/*
* Notify the controller that the user wishes to enter the current text. If
* aIsPopupSelection is true, then a selection was made from the popup, so
* fill this value into the input field before continuing. If false, just
* use the current value of the input field.
*
* @return True if the controller wishes to prevent event propagation and default event
*/
boolean handleEnter(in boolean aIsPopupSelection);
/*
* Notify the controller that the user wishes to revert autocomplete
*
* @return True if the controller wishes to prevent event propagation and default event
*/
boolean handleEscape();
/*
* Notify the controller that the user wishes to start composition
*
* NOTE: nsIAutoCompleteController implementation expects that this is called
* by DOM compositionstart handler.
*/
void handleStartComposition();
/*
* Notify the controller that the user wishes to end composition
*
* NOTE: nsIAutoCompleteController implementation expects that this is called
* by DOM compositionend handler.
*/
void handleEndComposition();
/*
* Handle tab. Just closes up.
*/
void handleTab();
/*
* Notify the controller of the following key navigation events:
* up, down, left, right, page up, page down
*
* @return True if the controller wishes to prevent event propagation and default event
*/
boolean handleKeyNavigation(in unsigned long key);
/*
* Notify the controller that the user chose to delete the current
* auto-complete result.
*/
boolean handleDelete();
/*
* Get the value of the result at a given index in the last completed search
*/
AString getValueAt(in long index);
/*
* Get the label of the result at a given index in the last completed search
*/
AString getLabelAt(in long index);
/*
* Get the comment of the result at a given index in the last completed search
*/
AString getCommentAt(in long index);
/*
* Get the style hint for the result at a given index in the last completed search
*/
AString getStyleAt(in long index);
/*
* Get the url of the image of the result at a given index in the last completed search
*/
AString getImageAt(in long index);
/*
* For the last completed search, get the final value that should be completed
* when the user confirms the match at the given index
*/
AString getFinalCompleteValueAt(in long index);
/*
* Get / set the current search string. Note, setting will not start searching
*/
attribute AString searchString;
};