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