1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/components/autocomplete/nsIAutoCompleteController.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,147 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsIAutoCompleteInput;
1.11 +
1.12 +[scriptable, uuid(ff9f8465-204a-47a6-b3c9-0628b3856684)]
1.13 +interface nsIAutoCompleteController : nsISupports
1.14 +{
1.15 + /*
1.16 + * Possible values for the searchStatus attribute
1.17 + */
1.18 + const unsigned short STATUS_NONE = 1;
1.19 + const unsigned short STATUS_SEARCHING = 2;
1.20 + const unsigned short STATUS_COMPLETE_NO_MATCH = 3;
1.21 + const unsigned short STATUS_COMPLETE_MATCH = 4;
1.22 +
1.23 + /*
1.24 + * The input widget that is currently being controlled.
1.25 + */
1.26 + attribute nsIAutoCompleteInput input;
1.27 +
1.28 + /*
1.29 + * State which indicates the status of possible ongoing searches
1.30 + */
1.31 + readonly attribute unsigned short searchStatus;
1.32 +
1.33 + /*
1.34 + * The number of matches
1.35 + */
1.36 + readonly attribute unsigned long matchCount;
1.37 +
1.38 + /*
1.39 + * Start a search on a string, assuming the input property is already set.
1.40 + */
1.41 + void startSearch(in AString searchString);
1.42 +
1.43 + /*
1.44 + * Stop all asynchronous searches
1.45 + */
1.46 + void stopSearch();
1.47 +
1.48 + /*
1.49 + * Notify the controller that the user has changed text in the textbox.
1.50 + * This includes all means of changing the text value, including typing a
1.51 + * character, backspacing, deleting, pasting, committing composition or
1.52 + * canceling composition.
1.53 + *
1.54 + * NOTE: handleText() must be called after composition actually ends, even if
1.55 + * the composition is canceled and the textbox value isn't changed.
1.56 + * Then, implementation of handleText() can access the editor when
1.57 + * it's not in composing mode. DOM compositionend event is not good
1.58 + * timing for calling handleText(). DOM input event immediately after
1.59 + * DOM compositionend event is the best timing to call this.
1.60 + */
1.61 + void handleText();
1.62 +
1.63 + /*
1.64 + * Notify the controller that the user wishes to enter the current text. If
1.65 + * aIsPopupSelection is true, then a selection was made from the popup, so
1.66 + * fill this value into the input field before continuing. If false, just
1.67 + * use the current value of the input field.
1.68 + *
1.69 + * @return True if the controller wishes to prevent event propagation and default event
1.70 + */
1.71 + boolean handleEnter(in boolean aIsPopupSelection);
1.72 +
1.73 + /*
1.74 + * Notify the controller that the user wishes to revert autocomplete
1.75 + *
1.76 + * @return True if the controller wishes to prevent event propagation and default event
1.77 + */
1.78 + boolean handleEscape();
1.79 +
1.80 + /*
1.81 + * Notify the controller that the user wishes to start composition
1.82 + *
1.83 + * NOTE: nsIAutoCompleteController implementation expects that this is called
1.84 + * by DOM compositionstart handler.
1.85 + */
1.86 + void handleStartComposition();
1.87 +
1.88 + /*
1.89 + * Notify the controller that the user wishes to end composition
1.90 + *
1.91 + * NOTE: nsIAutoCompleteController implementation expects that this is called
1.92 + * by DOM compositionend handler.
1.93 + */
1.94 + void handleEndComposition();
1.95 +
1.96 + /*
1.97 + * Handle tab. Just closes up.
1.98 + */
1.99 + void handleTab();
1.100 +
1.101 + /*
1.102 + * Notify the controller of the following key navigation events:
1.103 + * up, down, left, right, page up, page down
1.104 + *
1.105 + * @return True if the controller wishes to prevent event propagation and default event
1.106 + */
1.107 + boolean handleKeyNavigation(in unsigned long key);
1.108 +
1.109 + /*
1.110 + * Notify the controller that the user chose to delete the current
1.111 + * auto-complete result.
1.112 + */
1.113 + boolean handleDelete();
1.114 +
1.115 + /*
1.116 + * Get the value of the result at a given index in the last completed search
1.117 + */
1.118 + AString getValueAt(in long index);
1.119 +
1.120 + /*
1.121 + * Get the label of the result at a given index in the last completed search
1.122 + */
1.123 + AString getLabelAt(in long index);
1.124 +
1.125 + /*
1.126 + * Get the comment of the result at a given index in the last completed search
1.127 + */
1.128 + AString getCommentAt(in long index);
1.129 +
1.130 + /*
1.131 + * Get the style hint for the result at a given index in the last completed search
1.132 + */
1.133 + AString getStyleAt(in long index);
1.134 +
1.135 + /*
1.136 + * Get the url of the image of the result at a given index in the last completed search
1.137 + */
1.138 + AString getImageAt(in long index);
1.139 +
1.140 + /*
1.141 + * For the last completed search, get the final value that should be completed
1.142 + * when the user confirms the match at the given index
1.143 + */
1.144 + AString getFinalCompleteValueAt(in long index);
1.145 +
1.146 + /*
1.147 + * Get / set the current search string. Note, setting will not start searching
1.148 + */
1.149 + attribute AString searchString;
1.150 +};
