Debian Codegraph @

closure-library/closure/goog/ui/ac/autocomplete.js

raw
1 // Copyright 2006 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Gmail-like AutoComplete logic.
17 *
18 * @see ../../demos/autocomplete-basic.html
19 */
20
21 goog.provide('goog.ui.ac.AutoComplete');
22 goog.provide('goog.ui.ac.AutoComplete.EventType');
23
24 goog.require('goog.array');
25 goog.require('goog.asserts');
26 goog.require('goog.events');
27 goog.require('goog.events.EventTarget');
28 goog.require('goog.object');
29 goog.require('goog.ui.ac.RenderOptions');
30
31
32 /**
33 * This is the central manager class for an AutoComplete instance. The matcher
34 * can specify disabled rows that should not be hilited or selected by
35 * implementing <code>isRowDisabled(row):boolean</code> for each autocomplete
36 * row. No row will be considered disabled if this method is not implemented.
37 *
38 * @param {Object} matcher A data source and row matcher, implements
39 * <code>requestMatchingRows(token, maxMatches, matchCallback)</code>.
40 * @param {goog.events.EventTarget} renderer An object that implements
41 * <code>
42 * isVisible():boolean<br>
43 * renderRows(rows:Array, token:string, target:Element);<br>
44 * hiliteId(row-id:number);<br>
45 * dismiss();<br>
46 * dispose():
47 * </code>.
48 * @param {Object} selectionHandler An object that implements
49 * <code>
50 * selectRow(row);<br>
51 * update(opt_force);
52 * </code>.
53 *
54 * @constructor
55 * @extends {goog.events.EventTarget}
56 * @suppress {underscore}
57 */
58 goog.ui.ac.AutoComplete = function(matcher, renderer, selectionHandler) {
59 goog.events.EventTarget.call(this);
60
61 /**
62 * A data-source which provides autocomplete suggestions.
63 *
64 * TODO(chrishenry): Tighten the type to !goog.ui.ac.AutoComplete.Matcher.
65 *
66 * @type {Object}
67 * @protected
68 * @suppress {underscore|visibility}
69 */
70 this.matcher_ = matcher;
71
72 /**
73 * A handler which interacts with the input DOM element (textfield, textarea,
74 * or richedit).
75 *
76 * TODO(chrishenry): Tighten the type to !Object.
77 *
78 * @type {Object}
79 * @protected
80 * @suppress {underscore|visibility}
81 */
82 this.selectionHandler_ = selectionHandler;
83
84 /**
85 * A renderer to render/show/highlight/hide the autocomplete menu.
86 * @type {goog.events.EventTarget}
87 * @protected
88 * @suppress {underscore|visibility}
89 */
90 this.renderer_ = renderer;
91 goog.events.listen(
92 renderer,
93 [
94 goog.ui.ac.AutoComplete.EventType.HILITE,
95 goog.ui.ac.AutoComplete.EventType.SELECT,
96 goog.ui.ac.AutoComplete.EventType.CANCEL_DISMISS,
97 goog.ui.ac.AutoComplete.EventType.DISMISS
98 ],
99 this.handleEvent, false, this);
100
101 /**
102 * Currently typed token which will be used for completion.
103 * @type {?string}
104 * @protected
105 * @suppress {underscore|visibility}
106 */
107 this.token_ = null;
108
109 /**
110 * Autocomplete suggestion items.
111 * @type {Array<?>}
112 * @protected
113 * @suppress {underscore|visibility}
114 */
115 this.rows_ = [];
116
117 /**
118 * Id of the currently highlighted row.
119 * @type {number}
120 * @protected
121 * @suppress {underscore|visibility}
122 */
123 this.hiliteId_ = -1;
124
125 /**
126 * Id of the first row in autocomplete menu. Note that new ids are assigned
127 * every time new suggestions are fetched.
128 *
129 * TODO(chrishenry): Figure out what subclass does with this value
130 * and whether we should expose a more proper API.
131 *
132 * @type {number}
133 * @protected
134 * @suppress {underscore|visibility}
135 */
136 this.firstRowId_ = 0;
137
138 /**
139 * The target HTML node for displaying.
140 * @type {Element}
141 * @protected
142 * @suppress {underscore|visibility}
143 */
144 this.target_ = null;
145
146 /**
147 * The timer id for dismissing autocomplete menu with a delay.
148 * @type {?number}
149 * @private
150 */
151 this.dismissTimer_ = null;
152
153 /**
154 * Mapping from text input element to the anchor element. If the
155 * mapping does not exist, the input element will act as the anchor
156 * element.
157 * @type {Object<Element>}
158 * @private
159 */
160 this.inputToAnchorMap_ = {};
161 };
162 goog.inherits(goog.ui.ac.AutoComplete, goog.events.EventTarget);
163
164
165 /**
166 * The maximum number of matches that should be returned
167 * @type {number}
168 * @private
169 */
170 goog.ui.ac.AutoComplete.prototype.maxMatches_ = 10;
171
172
173 /**
174 * True iff the first row should automatically be highlighted
175 * @type {boolean}
176 * @private
177 */
178 goog.ui.ac.AutoComplete.prototype.autoHilite_ = true;
179
180
181 /**
182 * True iff the user can unhilight all rows by pressing the up arrow.
183 * @type {boolean}
184 * @private
185 */
186 goog.ui.ac.AutoComplete.prototype.allowFreeSelect_ = false;
187
188
189 /**
190 * True iff item selection should wrap around from last to first. If
191 * allowFreeSelect_ is on in conjunction, there is a step of free selection
192 * before wrapping.
193 * @type {boolean}
194 * @private
195 */
196 goog.ui.ac.AutoComplete.prototype.wrap_ = false;
197
198
199 /**
200 * Whether completion from suggestion triggers fetching new suggestion.
201 * @type {boolean}
202 * @private
203 */
204 goog.ui.ac.AutoComplete.prototype.triggerSuggestionsOnUpdate_ = false;
205
206
207 /**
208 * Events associated with the autocomplete
209 * @enum {string}
210 */
211 goog.ui.ac.AutoComplete.EventType = {
212
213 /** A row has been highlighted by the renderer */
214 ROW_HILITE: 'rowhilite',
215
216 // Note: The events below are used for internal autocomplete events only and
217 // should not be used in non-autocomplete code.
218
219 /** A row has been mouseovered and should be highlighted by the renderer. */
220 HILITE: 'hilite',
221
222 /** A row has been selected by the renderer */
223 SELECT: 'select',
224
225 /** A dismiss event has occurred */
226 DISMISS: 'dismiss',
227
228 /** Event that cancels a dismiss event */
229 CANCEL_DISMISS: 'canceldismiss',
230
231 /**
232 * Field value was updated. A row field is included and is non-null when a
233 * row has been selected. The value of the row typically includes fields:
234 * contactData and formattedValue as well as a toString function (though none
235 * of these fields are guaranteed to exist). The row field may be used to
236 * return custom-type row data.
237 */
238 UPDATE: 'update',
239
240 /**
241 * The list of suggestions has been updated, usually because either the list
242 * has opened, or because the user has typed another character and the
243 * suggestions have been updated, or the user has dismissed the autocomplete.
244 */
245 SUGGESTIONS_UPDATE: 'suggestionsupdate'
246 };
247
248
249 /**
250 * @typedef {{
251 * requestMatchingRows:(!Function|undefined),
252 * isRowDisabled:(!Function|undefined)
253 * }}
254 */
255 goog.ui.ac.AutoComplete.Matcher;
256
257
258 /**
259 * @return {!Object} The data source providing the `autocomplete
260 * suggestions.
261 */
262 goog.ui.ac.AutoComplete.prototype.getMatcher = function() {
263 return goog.asserts.assert(this.matcher_);
264 };
265
266
267 /**
268 * Sets the data source providing the autocomplete suggestions.
269 *
270 * See constructor documentation for the interface.
271 *
272 * @param {!Object} matcher The matcher.
273 * @protected
274 */
275 goog.ui.ac.AutoComplete.prototype.setMatcher = function(matcher) {
276 this.matcher_ = matcher;
277 };
278
279
280 /**
281 * @return {!Object} The handler used to interact with the input DOM
282 * element (textfield, textarea, or richedit), e.g. to update the
283 * input DOM element with selected value.
284 * @protected
285 */
286 goog.ui.ac.AutoComplete.prototype.getSelectionHandler = function() {
287 return goog.asserts.assert(this.selectionHandler_);
288 };
289
290
291 /**
292 * @return {goog.events.EventTarget} The renderer that
293 * renders/shows/highlights/hides the autocomplete menu.
294 * See constructor documentation for the expected renderer API.
295 */
296 goog.ui.ac.AutoComplete.prototype.getRenderer = function() {
297 return this.renderer_;
298 };
299
300
301 /**
302 * Sets the renderer that renders/shows/highlights/hides the autocomplete
303 * menu.
304 *
305 * See constructor documentation for the expected renderer API.
306 *
307 * @param {goog.events.EventTarget} renderer The renderer.
308 * @protected
309 */
310 goog.ui.ac.AutoComplete.prototype.setRenderer = function(renderer) {
311 this.renderer_ = renderer;
312 };
313
314
315 /**
316 * @return {?string} The currently typed token used for completion.
317 * @protected
318 */
319 goog.ui.ac.AutoComplete.prototype.getToken = function() {
320 return this.token_;
321 };
322
323
324 /**
325 * Sets the current token (without changing the rendered autocompletion).
326 *
327 * NOTE(chrishenry): This method will likely go away when we figure
328 * out a better API.
329 *
330 * @param {?string} token The new token.
331 * @protected
332 */
333 goog.ui.ac.AutoComplete.prototype.setTokenInternal = function(token) {
334 this.token_ = token;
335 };
336
337
338 /**
339 * @param {number} index The suggestion index, must be within the
340 * interval [0, this.getSuggestionCount()).
341 * @return {Object} The currently suggested item at the given index
342 * (or null if there is none).
343 */
344 goog.ui.ac.AutoComplete.prototype.getSuggestion = function(index) {
345 return this.rows_[index];
346 };
347
348
349 /**
350 * @return {!Array<?>} The current autocomplete suggestion items.
351 */
352 goog.ui.ac.AutoComplete.prototype.getAllSuggestions = function() {
353 return goog.asserts.assert(this.rows_);
354 };
355
356
357 /**
358 * @return {number} The number of currently suggested items.
359 */
360 goog.ui.ac.AutoComplete.prototype.getSuggestionCount = function() {
361 return this.rows_.length;
362 };
363
364
365 /**
366 * @return {number} The id (not index!) of the currently highlighted row.
367 */
368 goog.ui.ac.AutoComplete.prototype.getHighlightedId = function() {
369 return this.hiliteId_;
370 };
371
372
373 /**
374 * Generic event handler that handles any events this object is listening to.
375 * @param {goog.events.Event} e Event Object.
376 */
377 goog.ui.ac.AutoComplete.prototype.handleEvent = function(e) {
378 var matcher = /** @type {?goog.ui.ac.AutoComplete.Matcher} */ (this.matcher_);
379
380 if (e.target == this.renderer_) {
381 switch (e.type) {
382 case goog.ui.ac.AutoComplete.EventType.HILITE:
383 this.hiliteId(/** @type {number} */ (e.row));
384 break;
385
386 case goog.ui.ac.AutoComplete.EventType.SELECT:
387 var rowDisabled = false;
388
389 // e.row can be either a valid row id or empty.
390 if (goog.isNumber(e.row)) {
391 var rowId = e.row;
392 var index = this.getIndexOfId(rowId);
393 var row = this.rows_[index];
394
395 // Make sure the row selected is not a disabled row.
396 rowDisabled =
397 !!row && matcher.isRowDisabled && matcher.isRowDisabled(row);
398 if (row && !rowDisabled && this.hiliteId_ != rowId) {
399 // Event target row not currently highlighted - fix the mismatch.
400 this.hiliteId(rowId);
401 }
402 }
403 if (!rowDisabled) {
404 // Note that rowDisabled can be false even if e.row does not
405 // contain a valid row ID; at least one client depends on us
406 // proceeding anyway.
407 this.selectHilited();
408 }
409 break;
410
411 case goog.ui.ac.AutoComplete.EventType.CANCEL_DISMISS:
412 this.cancelDelayedDismiss();
413 break;
414
415 case goog.ui.ac.AutoComplete.EventType.DISMISS:
416 this.dismissOnDelay();
417 break;
418 }
419 }
420 };
421
422
423 /**
424 * Sets the max number of matches to fetch from the Matcher.
425 *
426 * @param {number} max Max number of matches.
427 */
428 goog.ui.ac.AutoComplete.prototype.setMaxMatches = function(max) {
429 this.maxMatches_ = max;
430 };
431
432
433 /**
434 * Sets whether or not the first row should be highlighted by default.
435 *
436 * @param {boolean} autoHilite true iff the first row should be
437 * highlighted by default.
438 */
439 goog.ui.ac.AutoComplete.prototype.setAutoHilite = function(autoHilite) {
440 this.autoHilite_ = autoHilite;
441 };
442
443
444 /**
445 * Sets whether or not the up/down arrow can unhilite all rows.
446 *
447 * @param {boolean} allowFreeSelect true iff the up arrow can unhilite all rows.
448 */
449 goog.ui.ac.AutoComplete.prototype.setAllowFreeSelect = function(
450 allowFreeSelect) {
451 this.allowFreeSelect_ = allowFreeSelect;
452 };
453
454
455 /**
456 * Sets whether or not selections can wrap around the edges.
457 *
458 * @param {boolean} wrap true iff sections should wrap around the edges.
459 */
460 goog.ui.ac.AutoComplete.prototype.setWrap = function(wrap) {
461 this.wrap_ = wrap;
462 };
463
464
465 /**
466 * Sets whether or not to request new suggestions immediately after completion
467 * of a suggestion.
468 *
469 * @param {boolean} triggerSuggestionsOnUpdate true iff completion should fetch
470 * new suggestions.
471 */
472 goog.ui.ac.AutoComplete.prototype.setTriggerSuggestionsOnUpdate = function(
473 triggerSuggestionsOnUpdate) {
474 this.triggerSuggestionsOnUpdate_ = triggerSuggestionsOnUpdate;
475 };
476
477
478 /**
479 * Sets the token to match against. This triggers calls to the Matcher to
480 * fetch the matches (up to maxMatches), and then it triggers a call to
481 * <code>renderer.renderRows()</code>.
482 *
483 * @param {string} token The string for which to search in the Matcher.
484 * @param {string=} opt_fullString Optionally, the full string in the input
485 * field.
486 */
487 goog.ui.ac.AutoComplete.prototype.setToken = function(token, opt_fullString) {
488 if (this.token_ == token) {
489 return;
490 }
491 this.token_ = token;
492 this.matcher_.requestMatchingRows(
493 this.token_, this.maxMatches_, goog.bind(this.matchListener_, this),
494 opt_fullString);
495 this.cancelDelayedDismiss();
496 };
497
498
499 /**
500 * Gets the current target HTML node for displaying autocomplete UI.
501 * @return {Element} The current target HTML node for displaying autocomplete
502 * UI.
503 */
504 goog.ui.ac.AutoComplete.prototype.getTarget = function() {
505 return this.target_;
506 };
507
508
509 /**
510 * Sets the current target HTML node for displaying autocomplete UI.
511 * Can be an implementation specific definition of how to display UI in relation
512 * to the target node.
513 * This target will be passed into <code>renderer.renderRows()</code>
514 *
515 * @param {Element} target The current target HTML node for displaying
516 * autocomplete UI.
517 */
518 goog.ui.ac.AutoComplete.prototype.setTarget = function(target) {
519 this.target_ = target;
520 };
521
522
523 /**
524 * @return {boolean} Whether the autocomplete's renderer is open.
525 */
526 goog.ui.ac.AutoComplete.prototype.isOpen = function() {
527 return this.renderer_.isVisible();
528 };
529
530
531 /**
532 * @return {number} Number of rows in the autocomplete.
533 * @deprecated Use this.getSuggestionCount().
534 */
535 goog.ui.ac.AutoComplete.prototype.getRowCount = function() {
536 return this.getSuggestionCount();
537 };
538
539
540 /**
541 * Moves the hilite to the next non-disabled row.
542 * Calls renderer.hiliteId() when there's something to do.
543 * @return {boolean} Returns true on a successful hilite.
544 */
545 goog.ui.ac.AutoComplete.prototype.hiliteNext = function() {
546 var lastId = this.firstRowId_ + this.rows_.length - 1;
547 var toHilite = this.hiliteId_;
548 // Hilite the next row, skipping any disabled rows.
549 for (var i = 0; i < this.rows_.length; i++) {
550 // Increment to the next row.
551 if (toHilite >= this.firstRowId_ && toHilite < lastId) {
552 toHilite++;
553 } else if (toHilite == -1) {
554 toHilite = this.firstRowId_;
555 } else if (this.allowFreeSelect_ && toHilite == lastId) {
556 this.hiliteId(-1);
557 return false;
558 } else if (this.wrap_ && toHilite == lastId) {
559 toHilite = this.firstRowId_;
560 } else {
561 return false;
562 }
563
564 if (this.hiliteId(toHilite)) {
565 return true;
566 }
567 }
568 return false;
569 };
570
571
572 /**
573 * Moves the hilite to the previous non-disabled row. Calls
574 * renderer.hiliteId() when there's something to do.
575 * @return {boolean} Returns true on a successful hilite.
576 */
577 goog.ui.ac.AutoComplete.prototype.hilitePrev = function() {
578 var lastId = this.firstRowId_ + this.rows_.length - 1;
579 var toHilite = this.hiliteId_;
580 // Hilite the previous row, skipping any disabled rows.
581 for (var i = 0; i < this.rows_.length; i++) {
582 // Decrement to the previous row.
583 if (toHilite > this.firstRowId_) {
584 toHilite--;
585 } else if (this.allowFreeSelect_ && toHilite == this.firstRowId_) {
586 this.hiliteId(-1);
587 return false;
588 } else if (this.wrap_ && (toHilite == -1 || toHilite == this.firstRowId_)) {
589 toHilite = lastId;
590 } else {
591 return false;
592 }
593
594 if (this.hiliteId(toHilite)) {
595 return true;
596 }
597 }
598 return false;
599 };
600
601
602 /**
603 * Hilites the id if it's valid and the row is not disabled, otherwise does
604 * nothing.
605 * @param {number} id A row id (not index).
606 * @return {boolean} Whether the id was hilited. Returns false if the row is
607 * disabled.
608 */
609 goog.ui.ac.AutoComplete.prototype.hiliteId = function(id) {
610 var index = this.getIndexOfId(id);
611 var row = this.rows_[index];
612 var rowDisabled =
613 !!row && this.matcher_.isRowDisabled && this.matcher_.isRowDisabled(row);
614 if (!rowDisabled) {
615 this.hiliteId_ = id;
616 this.renderer_.hiliteId(id);
617 return index != -1;
618 }
619 return false;
620 };
621
622
623 /**
624 * Hilites the index, if it's valid and the row is not disabled, otherwise does
625 * nothing.
626 * @param {number} index The row's index.
627 * @return {boolean} Whether the index was hilited.
628 */
629 goog.ui.ac.AutoComplete.prototype.hiliteIndex = function(index) {
630 return this.hiliteId(this.getIdOfIndex_(index));
631 };
632
633
634 /**
635 * If there are any current matches, this passes the hilited row data to
636 * <code>selectionHandler.selectRow()</code>
637 * @return {boolean} Whether there are any current matches.
638 */
639 goog.ui.ac.AutoComplete.prototype.selectHilited = function() {
640 var index = this.getIndexOfId(this.hiliteId_);
641 if (index != -1) {
642 var selectedRow = this.rows_[index];
643 var suppressUpdate = this.selectionHandler_.selectRow(selectedRow);
644 if (this.triggerSuggestionsOnUpdate_) {
645 this.token_ = null;
646 this.dismissOnDelay();
647 } else {
648 this.dismiss();
649 }
650 if (!suppressUpdate) {
651 this.dispatchEvent({
652 type: goog.ui.ac.AutoComplete.EventType.UPDATE,
653 row: selectedRow,
654 index: index
655 });
656 if (this.triggerSuggestionsOnUpdate_) {
657 this.selectionHandler_.update(true);
658 }
659 }
660 return true;
661 } else {
662 this.dismiss();
663 this.dispatchEvent({
664 type: goog.ui.ac.AutoComplete.EventType.UPDATE,
665 row: null,
666 index: null
667 });
668 return false;
669 }
670 };
671
672
673 /**
674 * Returns whether or not the autocomplete is open and has a highlighted row.
675 * @return {boolean} Whether an autocomplete row is highlighted.
676 */
677 goog.ui.ac.AutoComplete.prototype.hasHighlight = function() {
678 return this.isOpen() && this.getIndexOfId(this.hiliteId_) != -1;
679 };
680
681
682 /**
683 * Clears out the token, rows, and hilite, and calls
684 * <code>renderer.dismiss()</code>
685 */
686 goog.ui.ac.AutoComplete.prototype.dismiss = function() {
687 this.hiliteId_ = -1;
688 this.token_ = null;
689 this.firstRowId_ += this.rows_.length;
690 this.rows_ = [];
691 window.clearTimeout(this.dismissTimer_);
692 this.dismissTimer_ = null;
693 this.renderer_.dismiss();
694 this.dispatchEvent(goog.ui.ac.AutoComplete.EventType.SUGGESTIONS_UPDATE);
695 this.dispatchEvent(goog.ui.ac.AutoComplete.EventType.DISMISS);
696 };
697
698
699 /**
700 * Call a dismiss after a delay, if there's already a dismiss active, ignore.
701 */
702 goog.ui.ac.AutoComplete.prototype.dismissOnDelay = function() {
703 if (!this.dismissTimer_) {
704 this.dismissTimer_ = window.setTimeout(goog.bind(this.dismiss, this), 100);
705 }
706 };
707
708
709 /**
710 * Cancels any delayed dismiss events immediately.
711 * @return {boolean} Whether a delayed dismiss was cancelled.
712 * @private
713 */
714 goog.ui.ac.AutoComplete.prototype.immediatelyCancelDelayedDismiss_ =
715 function() {
716 if (this.dismissTimer_) {
717 window.clearTimeout(this.dismissTimer_);
718 this.dismissTimer_ = null;
719 return true;
720 }
721 return false;
722 };
723
724
725 /**
726 * Cancel the active delayed dismiss if there is one.
727 */
728 goog.ui.ac.AutoComplete.prototype.cancelDelayedDismiss = function() {
729 // Under certain circumstances a cancel event occurs immediately prior to a
730 // delayedDismiss event that it should be cancelling. To handle this situation
731 // properly, a timer is used to stop that event.
732 // Using only the timer creates undesirable behavior when the cancel occurs
733 // less than 10ms before the delayed dismiss timout ends. If that happens the
734 // clearTimeout() will occur too late and have no effect.
735 if (!this.immediatelyCancelDelayedDismiss_()) {
736 window.setTimeout(
737 goog.bind(this.immediatelyCancelDelayedDismiss_, this), 10);
738 }
739 };
740
741
742 /** @override */
743 goog.ui.ac.AutoComplete.prototype.disposeInternal = function() {
744 goog.ui.ac.AutoComplete.superClass_.disposeInternal.call(this);
745 delete this.inputToAnchorMap_;
746 this.renderer_.dispose();
747 this.selectionHandler_.dispose();
748 this.matcher_ = null;
749 };
750
751
752 /**
753 * Callback passed to Matcher when requesting matches for a token.
754 * This might be called synchronously, or asynchronously, or both, for
755 * any implementation of a Matcher.
756 * If the Matcher calls this back, with the same token this AutoComplete
757 * has set currently, then this will package the matching rows in object
758 * of the form
759 * <pre>
760 * {
761 * id: an integer ID unique to this result set and AutoComplete instance,
762 * data: the raw row data from Matcher
763 * }
764 * </pre>
765 *
766 * @param {string} matchedToken Token that corresponds with the rows.
767 * @param {!Array<?>} rows Set of data that match the given token.
768 * @param {(boolean|goog.ui.ac.RenderOptions)=} opt_options If true,
769 * keeps the currently hilited (by index) element hilited. If false not.
770 * Otherwise a RenderOptions object.
771 * @private
772 */
773 goog.ui.ac.AutoComplete.prototype.matchListener_ = function(
774 matchedToken, rows, opt_options) {
775 if (this.token_ != matchedToken) {
776 // Matcher's response token doesn't match current token.
777 // This is probably an async response that came in after
778 // the token was changed, so don't do anything.
779 return;
780 }
781
782 this.renderRows(rows, opt_options);
783 };
784
785
786 /**
787 * Renders the rows and adds highlighting.
788 * @param {!Array<?>} rows Set of data that match the given token.
789 * @param {(boolean|goog.ui.ac.RenderOptions)=} opt_options If true,
790 * keeps the currently hilited (by index) element hilited. If false not.
791 * Otherwise a RenderOptions object.
792 */
793 goog.ui.ac.AutoComplete.prototype.renderRows = function(rows, opt_options) {
794 // The optional argument should be a RenderOptions object. It can be a
795 // boolean for backwards compatibility, defaulting to false.
796 var optionsObj = goog.typeOf(opt_options) == 'object' && opt_options;
797
798 var preserveHilited =
799 optionsObj ? optionsObj.getPreserveHilited() : opt_options;
800 var indexToHilite = preserveHilited ? this.getIndexOfId(this.hiliteId_) : -1;
801
802 // Current token matches the matcher's response token.
803 this.firstRowId_ += this.rows_.length;
804 this.rows_ = rows;
805 var rendRows = [];
806 for (var i = 0; i < rows.length; ++i) {
807 rendRows.push({id: this.getIdOfIndex_(i), data: rows[i]});
808 }
809
810 var anchor = null;
811 if (this.target_) {
812 anchor = this.inputToAnchorMap_[goog.getUid(this.target_)] || this.target_;
813 }
814 this.renderer_.setAnchorElement(anchor);
815 this.renderer_.renderRows(rendRows, this.token_, this.target_);
816
817 var autoHilite = this.autoHilite_;
818 if (optionsObj && optionsObj.getAutoHilite() !== undefined) {
819 autoHilite = optionsObj.getAutoHilite();
820 }
821 this.hiliteId_ = -1;
822 if ((autoHilite || indexToHilite >= 0) && rendRows.length != 0 &&
823 this.token_) {
824 if (indexToHilite >= 0) {
825 this.hiliteId(this.getIdOfIndex_(indexToHilite));
826 } else {
827 // Hilite the first non-disabled row.
828 this.hiliteNext();
829 }
830 }
831 this.dispatchEvent(goog.ui.ac.AutoComplete.EventType.SUGGESTIONS_UPDATE);
832 };
833
834
835 /**
836 * Gets the index corresponding to a particular id.
837 * @param {number} id A unique id for the row.
838 * @return {number} A valid index into rows_, or -1 if the id is invalid.
839 * @protected
840 */
841 goog.ui.ac.AutoComplete.prototype.getIndexOfId = function(id) {
842 var index = id - this.firstRowId_;
843 if (index < 0 || index >= this.rows_.length) {
844 return -1;
845 }
846 return index;
847 };
848
849
850 /**
851 * Gets the id corresponding to a particular index. (Does no checking.)
852 * @param {number} index The index of a row in the result set.
853 * @return {number} The id that currently corresponds to that index.
854 * @private
855 */
856 goog.ui.ac.AutoComplete.prototype.getIdOfIndex_ = function(index) {
857 return this.firstRowId_ + index;
858 };
859
860
861 /**
862 * Attach text areas or input boxes to the autocomplete by DOM reference. After
863 * elements are attached to the autocomplete, when a user types they will see
864 * the autocomplete drop down.
865 * @param {...Element} var_args Variable args: Input or text area elements to
866 * attach the autocomplete too.
867 */
868 goog.ui.ac.AutoComplete.prototype.attachInputs = function(var_args) {
869 // Delegate to the input handler
870 var inputHandler = /** @type {goog.ui.ac.InputHandler} */
871 (this.selectionHandler_);
872 inputHandler.attachInputs.apply(inputHandler, arguments);
873 };
874
875
876 /**
877 * Detach text areas or input boxes to the autocomplete by DOM reference.
878 * @param {...Element} var_args Variable args: Input or text area elements to
879 * detach from the autocomplete.
880 */
881 goog.ui.ac.AutoComplete.prototype.detachInputs = function(var_args) {
882 // Delegate to the input handler
883 var inputHandler = /** @type {goog.ui.ac.InputHandler} */
884 (this.selectionHandler_);
885 inputHandler.detachInputs.apply(inputHandler, arguments);
886
887 // Remove mapping from input to anchor if one exists.
888 goog.array.forEach(arguments, function(input) {
889 goog.object.remove(this.inputToAnchorMap_, goog.getUid(input));
890 }, this);
891 };
892
893
894 /**
895 * Attaches the autocompleter to a text area or text input element
896 * with an anchor element. The anchor element is the element the
897 * autocomplete box will be positioned against.
898 * @param {Element} inputElement The input element. May be 'textarea',
899 * text 'input' element, or any other element that exposes similar
900 * interface.
901 * @param {Element} anchorElement The anchor element.
902 */
903 goog.ui.ac.AutoComplete.prototype.attachInputWithAnchor = function(
904 inputElement, anchorElement) {
905 this.inputToAnchorMap_[goog.getUid(inputElement)] = anchorElement;
906 this.attachInputs(inputElement);
907 };
908
909
910 /**
911 * Forces an update of the display.
912 * @param {boolean=} opt_force Whether to force an update.
913 */
914 goog.ui.ac.AutoComplete.prototype.update = function(opt_force) {
915 var inputHandler = /** @type {goog.ui.ac.InputHandler} */
916 (this.selectionHandler_);
917 inputHandler.update(opt_force);
918 };