summaryrefslogtreecommitdiffstats
path: root/toolkit/components/autocomplete/nsIAutoCompleteController.idl
blob: 0b68032dc45b6c26a48e46fe41c4b7211261ce47 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
/* 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;
interface nsIDOMEvent;

[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.
   *
   * @return whether this handler started a new search.
   */
  boolean 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.
   *
   * @param aIsPopupSelection
   *        Pass true if the selection was made from the popup.
   * @param aEvent
   *        The event that triggered the enter, like a key event if the user
   *        pressed the Return key or a click event if the user clicked a popup
   *        item.
   * @return Whether the controller wishes to prevent event propagation and
   *         default event.
   */
  boolean handleEnter(in boolean aIsPopupSelection,
                      [optional] in nsIDOMEvent aEvent);

  /*
   * Notify the controller that the user wishes to revert autocomplete
   *
   * @return Whether 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 Whether 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.
   *
   * @return Whether the controller removed a result item.
   */
  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;

  /*
   * Set the index of the result item that should be initially selected.
   * This should be used when a search wants to pre-select an element before
   * the user starts using results.
   *
   * @note Setting this is not the same as just setting selectedIndex in
   * nsIAutocompletePopup, since this will take care of updating any internal
   * tracking variables of features like completeSelectedIndex.
   */
  void setInitiallySelectedIndex(in long index);
};