summaryrefslogtreecommitdiffstats
path: root/toolkit/components/autocomplete/nsIAutoCompleteInput.idl
blob: 26a75ea776f2da8e4a19cc88549f2c7cf93b8947 (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
174
175
176
177
178
179
180
181
/* 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"
#include "nsIAutoCompleteController.idl"

interface nsIAutoCompletePopup;

[scriptable, uuid(B068E70F-F82C-4C12-AD87-82E271C5C180)]
interface nsIAutoCompleteInput : nsISupports
{
  /*
   * The result view that will be used to display results
   */
  readonly attribute nsIAutoCompletePopup popup;

  /*
   * The controller.
   */
  readonly attribute nsIAutoCompleteController controller;

  /*
   * Indicates if the popup is currently open
   */
  attribute boolean popupOpen;

  /*
   * Option to disable autocomplete functionality
   */
  attribute boolean disableAutoComplete;

  /*
   * If a search result has its defaultIndex set, this will optionally
   * try to complete the text in the textbox to the entire text of the
   * result at the default index as the user types
   */
  attribute boolean completeDefaultIndex;

  /*
   * complete text in the textbox as the user selects from the dropdown
   * options if set to true
   */
  attribute boolean completeSelectedIndex;

  /*
   * Option for completing to the default result whenever the user hits
   * enter or the textbox loses focus
   */
  attribute boolean forceComplete;

  /*
   * Option to open the popup only after a certain number of results are available
   */
  attribute unsigned long minResultsForPopup;

  /*
   * The maximum number of rows to show in the autocomplete popup.
   */
  attribute unsigned long maxRows;

  /*
   * Option to show a second column in the popup which contains
   * the comment for each autocomplete result
   */
  attribute boolean showCommentColumn;

  /*
   * Option to show a third column in the popup which contains
   * an additional image for each autocomplete result
   */
  attribute boolean showImageColumn;

  /*
   * Number of milliseconds after a keystroke before a search begins
   */
  attribute unsigned long timeout;

  /*
   * An extra parameter to configure searches with.
   */
  attribute AString searchParam;

  /*
   * The number of autocomplete session to search
   */
  readonly attribute unsigned long searchCount;

  /*
   * Get the name of one of the autocomplete search session objects
   */
  ACString getSearchAt(in unsigned long index);

  /*
   * The value of text in the autocomplete textbox.
   *
   * @note when setting a new value, the controller always first tries to use
   *       setTextboxValueWithReason, and only if that throws (unimplemented),
   *       fallbacks to the textValue's setter.  If a reason is not provided,
   *       the implementation should assume TEXTVALUE_REASON_UNKNOWN, but it
   *       should only happen in testing code.
   */
  attribute AString textValue;

  /*
   * Set the value of text in the autocomplete textbox, providing a reason to
   * the autocomplete view.
   */
  const unsigned short TEXTVALUE_REASON_UNKNOWN = 0;
  const unsigned short TEXTVALUE_REASON_COMPLETEDEFAULT = 1;
  const unsigned short TEXTVALUE_REASON_COMPLETESELECTED = 2;
  const unsigned short TEXTVALUE_REASON_REVERT = 3;
  const unsigned short TEXTVALUE_REASON_ENTERMATCH = 4;

  void setTextValueWithReason(in AString aValue,
                              in unsigned short aReason);

  /*
   * Report the starting index of the cursor in the textbox
   */
  readonly attribute long selectionStart;

  /*
   * Report the ending index of the cursor in the textbox
   */
  readonly attribute long selectionEnd;

  /*
   * Select a range of text in the autocomplete textbox
   */
  void selectTextRange(in long startIndex, in long endIndex);

  /*
   * Notification that the search has started
   */
  void onSearchBegin();

  /*
   * Notification that the search concluded successfully
   */
  void onSearchComplete();

  /*
   * Notification that the user selected and entered a result item
   *
   * @param aEvent
   *        The event that triggered the enter.
   * @return True if the user wishes to prevent the enter
   */
  boolean onTextEntered([optional] in nsIDOMEvent aEvent);

  /*
   * Notification that the user cancelled the autocomplete session
   *
   * @return True if the user wishes to prevent the revert
   */
  boolean onTextReverted();

  /*
   * This popup should consume or dispatch the rollup event.
   * TRUE: should consume; FALSE: should dispatch.
   */
  readonly attribute boolean consumeRollupEvent;

  /*
   * Indicates whether this input is in a "private browsing" context.
   * nsIAutoCompleteSearches for these inputs should not persist any data to disk
   * (such as a history database).
   */
  readonly attribute boolean inPrivateContext;

  /*
   * Don't rollup the popup when the caret is moved.
   */
  readonly attribute boolean noRollupOnCaretMove;

  /**
   * The userContextId of the current browser.
   */
  readonly attribute unsigned long userContextId;
};