Debian Codegraph @

closure-library/closure/goog/ui/ac/inputhandler.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 Class for managing the interactions between an
17 * auto-complete object and a text-input or textarea.
18 *
19 * IME note:
20 *
21 * We used to suspend autocomplete while there are IME preedit characters, but
22 * now for parity with Search we do not. We still detect the beginning and end
23 * of IME entry because we need to listen to more events while an IME commit is
24 * happening, but we update continuously as the user types.
25 *
26 * IMEs vary across operating systems, browsers, and even input languages. This
27 * class tries to handle IME for:
28 * - Windows x {FF3, IE7, Chrome} x MS IME 2002 (Japanese)
29 * - Mac x {FF3, Safari3} x Kotoeri (Japanese)
30 * - Linux x {FF3} x UIM + Anthy (Japanese)
31 *
32 * TODO(user): We cannot handle {Mac, Linux} x FF3 correctly.
33 * TODO(user): We need to support Windows x Google IME.
34 *
35 * This class was tested with hiragana input. The event sequence when inputting
36 * 'ai<enter>' with IME on (which commits two characters) is as follows:
37 *
38 * Notation: [key down code, key press, key up code]
39 * key code or +: event fired
40 * -: event not fired
41 *
42 * - Win/FF3: [WIN_IME, +, A], [-, -, ENTER]
43 * Note: No events are fired for 'i'.
44 *
45 * - Win/IE7: [WIN_IME, -, A], [WIN_IME, -, I], [WIN_IME, -, ENTER]
46 *
47 * - Win/Chrome: Same as Win/IE7
48 *
49 * - Mac/FF3: [A, -, A], [I, -, I], [ENTER, -, ENTER]
50 *
51 * - Mac/Safari3: Same as Win/IE7
52 *
53 * - Linux/FF3: No events are generated.
54 *
55 * With IME off,
56 *
57 * - ALL: [A, +, A], [I, +, I], [ENTER, +, ENTER]
58 * Note: Key code of key press event varies across configuration.
59 *
60 * With Microsoft Pinyin IME 3.0 (Simplified Chinese),
61 *
62 * - Win/IE7: Same as Win/IE7 with MS IME 2002 (Japanese)
63 *
64 * The issue with this IME is that the key sequence that ends preedit is not
65 * a single ENTER key up.
66 * - ENTER key up following either ENTER or SPACE ends preedit.
67 * - SPACE key up following even number of LEFT, RIGHT, or SPACE (any
68 * combination) ends preedit.
69 * TODO(user): We only support SPACE-then-ENTER sequence.
70 * TODO(mpd): With the change to autocomplete during IME, this might not be an
71 * issue. Remove this comment once tested.
72 *
73 * With Microsoft Korean IME 2002,
74 *
75 * - Win/IE7: Same as Win/IE7 with MS IME 2002 (Japanese), but there is no
76 * sequence that ends the preedit.
77 *
78 * The following is the algorithm we use to detect IME preedit:
79 *
80 * - WIN_IME key down starts predit.
81 * - (1) ENTER key up or (2) CTRL-M key up ends preedit.
82 * - Any key press not immediately following WIN_IME key down signifies that
83 * preedit has ended.
84 *
85 * If you need to change this algorithm, please note the OS, browser, language,
86 * and behavior above so that we can avoid regressions. Contact mpd or yuzo
87 * if you have questions or concerns.
88 *
89 */
90
91
92 goog.provide('goog.ui.ac.InputHandler');
93
94 goog.require('goog.Disposable');
95 goog.require('goog.Timer');
96 goog.require('goog.a11y.aria');
97 goog.require('goog.a11y.aria.Role');
98 goog.require('goog.a11y.aria.State');
99 goog.require('goog.dom');
100 goog.require('goog.dom.selection');
101 goog.require('goog.events.EventHandler');
102 goog.require('goog.events.EventType');
103 goog.require('goog.events.KeyCodes');
104 goog.require('goog.events.KeyHandler');
105 goog.require('goog.string');
106 goog.require('goog.userAgent');
107 goog.require('goog.userAgent.product');
108
109
110
111 /**
112 * Class for managing the interaction between an auto-complete object and a
113 * text-input or textarea.
114 *
115 * @param {?string=} opt_separators Separators to split multiple entries.
116 * If none passed, uses ',' and ';'.
117 * @param {?string=} opt_literals Characters used to delimit text literals.
118 * @param {?boolean=} opt_multi Whether to allow multiple entries
119 * (Default: true).
120 * @param {?number=} opt_throttleTime Number of milliseconds to throttle
121 * keyevents with (Default: 150). Use -1 to disable updates on typing. Note
122 * that typing the separator will update autocomplete suggestions.
123 * @constructor
124 * @extends {goog.Disposable}
125 */
126 goog.ui.ac.InputHandler = function(
127 opt_separators, opt_literals, opt_multi, opt_throttleTime) {
128 goog.Disposable.call(this);
129 var throttleTime = opt_throttleTime || 150;
130
131 /**
132 * Whether this input accepts multiple values
133 * @type {boolean}
134 * @private
135 */
136 this.multi_ = opt_multi != null ? opt_multi : true;
137
138 // Set separators depends on this.multi_ being set correctly
139 this.setSeparators(
140 opt_separators || goog.ui.ac.InputHandler.STANDARD_LIST_SEPARATORS);
141
142 /**
143 * Characters that are used to delimit literal text. Separarator characters
144 * found within literal text are not processed as separators
145 * @type {string}
146 * @private
147 */
148 this.literals_ = opt_literals || '';
149
150 /**
151 * Whether to prevent highlighted item selection when tab is pressed.
152 * @type {boolean}
153 * @private
154 */
155 this.preventSelectionOnTab_ = false;
156
157 /**
158 * Whether to prevent the default behavior (moving focus to another element)
159 * when tab is pressed. This occurs by default only for multi-value mode.
160 * @type {boolean}
161 * @private
162 */
163 this.preventDefaultOnTab_ = this.multi_;
164
165 /**
166 * A timer object used to monitor for changes when an element is active.
167 *
168 * TODO(user): Consider tuning the throttle time, so that it takes into
169 * account the length of the token. When the token is short it is likely to
170 * match lots of rows, therefore we want to check less frequently. Even
171 * something as simple as <3-chars = 150ms, then 100ms otherwise.
172 *
173 * @type {goog.Timer}
174 * @private
175 */
176 this.timer_ = throttleTime > 0 ? new goog.Timer(throttleTime) : null;
177
178 /**
179 * Event handler used by the input handler to manage events.
180 * @type {goog.events.EventHandler<!goog.ui.ac.InputHandler>}
181 * @private
182 */
183 this.eh_ = new goog.events.EventHandler(this);
184
185 /**
186 * Event handler to help us find an input element that already has the focus.
187 * @type {goog.events.EventHandler<!goog.ui.ac.InputHandler>}
188 * @private
189 */
190 this.activateHandler_ = new goog.events.EventHandler(this);
191
192 /**
193 * The keyhandler used for listening on most key events. This takes care of
194 * abstracting away some of the browser differences.
195 * @type {goog.events.KeyHandler}
196 * @private
197 */
198 this.keyHandler_ = new goog.events.KeyHandler();
199
200 /**
201 * The last key down key code.
202 * @type {number}
203 * @private
204 */
205 this.lastKeyCode_ = -1; // Initialize to a non-existent value.
206 };
207 goog.inherits(goog.ui.ac.InputHandler, goog.Disposable);
208 goog.tagUnsealableClass(goog.ui.ac.InputHandler);
209
210
211 /**
212 * Whether or not we need to pause the execution of the blur handler in order
213 * to allow the execution of the selection handler to run first. This is
214 * currently true when running on IOS version prior to 4.2, since we need
215 * some special logic for these devices to handle bug 4484488.
216 * @type {boolean}
217 * @private
218 */
219 goog.ui.ac.InputHandler.REQUIRES_ASYNC_BLUR_ =
220 (goog.userAgent.product.IPHONE || goog.userAgent.product.IPAD) &&
221 // Check the webkit version against the version for iOS 4.2.1.
222 !goog.userAgent.isVersionOrHigher('533.17.9');
223
224
225 /**
226 * Standard list separators.
227 * @type {string}
228 * @const
229 */
230 goog.ui.ac.InputHandler.STANDARD_LIST_SEPARATORS = ',;';
231
232
233 /**
234 * Literals for quotes.
235 * @type {string}
236 * @const
237 */
238 goog.ui.ac.InputHandler.QUOTE_LITERALS = '"';
239
240
241 /**
242 * The AutoComplete instance this inputhandler is associated with.
243 * @type {goog.ui.ac.AutoComplete}
244 */
245 goog.ui.ac.InputHandler.prototype.ac_;
246
247
248 /**
249 * Characters that can be used to split multiple entries in an input string
250 * @type {string}
251 * @private
252 */
253 goog.ui.ac.InputHandler.prototype.separators_;
254
255
256 /**
257 * The separator we use to reconstruct the string
258 * @type {string}
259 * @private
260 */
261 goog.ui.ac.InputHandler.prototype.defaultSeparator_;
262
263
264 /**
265 * Regular expression used from trimming tokens or null for no trimming.
266 * @type {RegExp}
267 * @private
268 */
269 goog.ui.ac.InputHandler.prototype.trimmer_;
270
271
272 /**
273 * Regular expression to test whether a separator exists
274 * @type {RegExp}
275 * @private
276 */
277 goog.ui.ac.InputHandler.prototype.separatorCheck_;
278
279
280 /**
281 * Should auto-completed tokens be wrapped in whitespace? Used in selectRow.
282 * @type {boolean}
283 * @private
284 */
285 goog.ui.ac.InputHandler.prototype.whitespaceWrapEntries_ = true;
286
287
288 /**
289 * Should the occurrence of a literal indicate a token boundary?
290 * @type {boolean}
291 * @private
292 */
293 goog.ui.ac.InputHandler.prototype.generateNewTokenOnLiteral_ = true;
294
295
296 /**
297 * Whether to flip the orientation of up & down for hiliting next
298 * and previous autocomplete entries.
299 * @type {boolean}
300 * @private
301 */
302 goog.ui.ac.InputHandler.prototype.upsideDown_ = false;
303
304
305 /**
306 * If we're in 'multi' mode, does typing a separator force the updating of
307 * suggestions?
308 * For example, if somebody finishes typing "obama, hillary,", should the last
309 * comma trigger updating suggestions in a guaranteed manner? Especially useful
310 * when the suggestions depend on complete keywords. Note that "obama, hill"
311 * (a leading sub-string of "obama, hillary" will lead to different and possibly
312 * irrelevant suggestions.
313 * @type {boolean}
314 * @private
315 */
316 goog.ui.ac.InputHandler.prototype.separatorUpdates_ = true;
317
318
319 /**
320 * If we're in 'multi' mode, does typing a separator force the current term to
321 * autocomplete?
322 * For example, if 'tomato' is a suggested completion and the user has typed
323 * 'to,', do we autocomplete to turn that into 'tomato,'?
324 * @type {boolean}
325 * @private
326 */
327 goog.ui.ac.InputHandler.prototype.separatorSelects_ = true;
328
329
330 /**
331 * The id of the currently active timeout, so it can be cleared if required.
332 * @type {?number}
333 * @private
334 */
335 goog.ui.ac.InputHandler.prototype.activeTimeoutId_ = null;
336
337
338 /**
339 * The element that is currently active.
340 * @type {Element}
341 * @private
342 */
343 goog.ui.ac.InputHandler.prototype.activeElement_ = null;
344
345
346 /**
347 * The previous value of the active element.
348 * @type {string}
349 * @private
350 */
351 goog.ui.ac.InputHandler.prototype.lastValue_ = '';
352
353
354 /**
355 * Flag used to indicate that the IME key has been seen and we need to wait for
356 * the up event.
357 * @type {boolean}
358 * @private
359 */
360 goog.ui.ac.InputHandler.prototype.waitingForIme_ = false;
361
362
363 /**
364 * Flag used to indicate that the user just selected a row and we should
365 * therefore ignore the change of the input value.
366 * @type {boolean}
367 * @private
368 */
369 goog.ui.ac.InputHandler.prototype.rowJustSelected_ = false;
370
371
372 /**
373 * Flag indicating whether the result list should be updated continuously
374 * during typing or only after a short pause.
375 * @type {boolean}
376 * @private
377 */
378 goog.ui.ac.InputHandler.prototype.updateDuringTyping_ = true;
379
380
381 /**
382 * Attach an instance of an AutoComplete
383 * @param {goog.ui.ac.AutoComplete} ac Autocomplete object.
384 */
385 goog.ui.ac.InputHandler.prototype.attachAutoComplete = function(ac) {
386 this.ac_ = ac;
387 };
388
389
390 /**
391 * Returns the associated autocomplete instance.
392 * @return {goog.ui.ac.AutoComplete} The associated autocomplete instance.
393 */
394 goog.ui.ac.InputHandler.prototype.getAutoComplete = function() {
395 return this.ac_;
396 };
397
398
399 /**
400 * Returns the current active element.
401 * @return {Element} The currently active element.
402 */
403 goog.ui.ac.InputHandler.prototype.getActiveElement = function() {
404 return this.activeElement_;
405 };
406
407
408 /**
409 * Returns the value of the current active element.
410 * @return {string} The value of the current active element.
411 */
412 goog.ui.ac.InputHandler.prototype.getValue = function() {
413 return this.activeElement_.value;
414 };
415
416
417 /**
418 * Sets the value of the current active element.
419 * @param {string} value The new value.
420 */
421 goog.ui.ac.InputHandler.prototype.setValue = function(value) {
422 this.activeElement_.value = value;
423 };
424
425
426 /**
427 * Returns the current cursor position.
428 * @return {number} The index of the cursor position.
429 */
430 goog.ui.ac.InputHandler.prototype.getCursorPosition = function() {
431 return goog.dom.selection.getStart(this.activeElement_);
432 };
433
434
435 /**
436 * Sets the cursor at the given position.
437 * @param {number} pos The index of the cursor position.
438 */
439 goog.ui.ac.InputHandler.prototype.setCursorPosition = function(pos) {
440 goog.dom.selection.setStart(this.activeElement_, pos);
441 goog.dom.selection.setEnd(this.activeElement_, pos);
442 };
443
444
445 /**
446 * Attaches the input handler to a target element. The target element
447 * should be a textarea, input box, or other focusable element with the
448 * same interface.
449 * @param {Element|goog.events.EventTarget} target An element to attach the
450 * input handler to.
451 */
452 goog.ui.ac.InputHandler.prototype.attachInput = function(target) {
453 if (goog.dom.isElement(target)) {
454 var el = /** @type {!Element} */ (target);
455 goog.a11y.aria.setRole(el, goog.a11y.aria.Role.COMBOBOX);
456 goog.a11y.aria.setState(el, goog.a11y.aria.State.AUTOCOMPLETE, 'list');
457 }
458
459 this.eh_.listen(target, goog.events.EventType.FOCUS, this.handleFocus);
460 this.eh_.listen(target, goog.events.EventType.BLUR, this.handleBlur);
461
462 if (!this.activeElement_) {
463 this.activateHandler_.listen(
464 target, goog.events.EventType.KEYDOWN,
465 this.onKeyDownOnInactiveElement_);
466
467 // Don't wait for a focus event if the element already has focus.
468 if (goog.dom.isElement(target)) {
469 var ownerDocument = goog.dom.getOwnerDocument(
470 /** @type {Element} */ (target));
471 if (goog.dom.getActiveElement(ownerDocument) == target) {
472 this.processFocus(/** @type {!Element} */ (target));
473 }
474 }
475 }
476 };
477
478
479 /**
480 * Detaches the input handler from the provided element.
481 * @param {Element|goog.events.EventTarget} target An element to detach the
482 * input handler from.
483 */
484 goog.ui.ac.InputHandler.prototype.detachInput = function(target) {
485 if (goog.dom.isElement(target)) {
486 var el = /** @type {!Element} */ (target);
487 goog.a11y.aria.removeRole(el);
488 goog.a11y.aria.removeState(el, goog.a11y.aria.State.AUTOCOMPLETE);
489 }
490
491 if (target == this.activeElement_) {
492 this.handleBlur();
493 }
494 this.eh_.unlisten(target, goog.events.EventType.FOCUS, this.handleFocus);
495 this.eh_.unlisten(target, goog.events.EventType.BLUR, this.handleBlur);
496
497 if (!this.activeElement_) {
498 this.activateHandler_.unlisten(
499 target, goog.events.EventType.KEYDOWN,
500 this.onKeyDownOnInactiveElement_);
501 }
502 };
503
504
505 /**
506 * Attaches the input handler to multiple elements.
507 * @param {...Element} var_args Elements to attach the input handler too.
508 */
509 goog.ui.ac.InputHandler.prototype.attachInputs = function(var_args) {
510 for (var i = 0; i < arguments.length; i++) {
511 this.attachInput(arguments[i]);
512 }
513 };
514
515
516 /**
517 * Detaches the input handler from multuple elements.
518 * @param {...Element} var_args Variable arguments for elements to unbind from.
519 */
520 goog.ui.ac.InputHandler.prototype.detachInputs = function(var_args) {
521 for (var i = 0; i < arguments.length; i++) {
522 this.detachInput(arguments[i]);
523 }
524 };
525
526
527 /**
528 * Selects the given row. Implements the SelectionHandler interface.
529 * @param {Object} row The row to select.
530 * @param {boolean=} opt_multi Should this be treated as a single or multi-token
531 * auto-complete? Overrides previous setting of opt_multi on constructor.
532 * @return {boolean} Whether to suppress the update event.
533 */
534 goog.ui.ac.InputHandler.prototype.selectRow = function(row, opt_multi) {
535 if (this.activeElement_) {
536 this.setTokenText(row.toString(), opt_multi);
537 }
538 return false;
539 };
540
541
542 /**
543 * Sets the text of the current token without updating the autocomplete
544 * choices.
545 * @param {string} tokenText The text for the current token.
546 * @param {boolean=} opt_multi Should this be treated as a single or multi-token
547 * auto-complete? Overrides previous setting of opt_multi on constructor.
548 * @protected
549 */
550 goog.ui.ac.InputHandler.prototype.setTokenText = function(
551 tokenText, opt_multi) {
552 if (goog.isDef(opt_multi) ? opt_multi : this.multi_) {
553 var index = this.getTokenIndex_(this.getValue(), this.getCursorPosition());
554
555 // Break up the current input string.
556 var entries = this.splitInput_(this.getValue());
557
558 // Get the new value, ignoring whitespace associated with the entry.
559 var replaceValue = tokenText;
560
561 // Only add punctuation if there isn't already a separator available.
562 if (!this.separatorCheck_.test(replaceValue)) {
563 replaceValue =
564 goog.string.trimRight(replaceValue) + this.defaultSeparator_;
565 }
566
567 // Ensure there's whitespace wrapping the entries, if whitespaceWrapEntries_
568 // has been set to true.
569 if (this.whitespaceWrapEntries_) {
570 if (index != 0 && !goog.string.isEmptyOrWhitespace(entries[index - 1])) {
571 replaceValue = ' ' + replaceValue;
572 }
573 // Add a space only if it's the last token; otherwise, we assume the
574 // next token already has the proper spacing.
575 if (index == entries.length - 1) {
576 replaceValue = replaceValue + ' ';
577 }
578 }
579
580 // If the token needs changing, then update the input box and move the
581 // cursor to the correct position.
582 if (replaceValue != entries[index]) {
583 // Replace the value in the array.
584 entries[index] = replaceValue;
585
586 var el = this.activeElement_;
587 // If there is an uncommitted IME in Firefox or IE 9, setting the value
588 // fails and results in actually clearing the value that's already in the
589 // input.
590 // The FF bug is http://bugzilla.mozilla.org/show_bug.cgi?id=549674
591 // Blurring before setting the value works around this problem. We'd like
592 // to do this only if there is an uncommitted IME, but this isn't possible
593 // to detect. Since text editing is finicky we restrict this
594 // workaround to Firefox and IE 9 where it's necessary.
595 // (Note: this has been fixed in Edge and since FF 41)
596 if (goog.userAgent.GECKO ||
597 (goog.userAgent.IE && goog.userAgent.isVersionOrHigher('9'))) {
598 el.blur();
599 }
600 // Join the array and replace the contents of the input.
601 el.value = entries.join('');
602
603 // Calculate which position to put the cursor at.
604 var pos = 0;
605 for (var i = 0; i <= index; i++) {
606 pos += entries[i].length;
607 }
608
609 // Set the cursor.
610 el.focus();
611 this.setCursorPosition(pos);
612 }
613 } else {
614 this.setValue(tokenText);
615 }
616
617 // Avoid triggering an autocomplete just because the value changed.
618 this.rowJustSelected_ = true;
619 };
620
621
622 /** @override */
623 goog.ui.ac.InputHandler.prototype.disposeInternal = function() {
624 goog.ui.ac.InputHandler.superClass_.disposeInternal.call(this);
625 if (this.activeTimeoutId_ != null) {
626 // Need to check against null explicitly because 0 is a valid value.
627 window.clearTimeout(this.activeTimeoutId_);
628 }
629 this.eh_.dispose();
630 delete this.eh_;
631 this.activateHandler_.dispose();
632 this.keyHandler_.dispose();
633 goog.dispose(this.timer_);
634 };
635
636
637 /**
638 * Sets the entry separator characters.
639 *
640 * @param {string} separators The separator characters to set.
641 * @param {string=} opt_defaultSeparators The defaultSeparator character to set.
642 */
643 goog.ui.ac.InputHandler.prototype.setSeparators = function(
644 separators, opt_defaultSeparators) {
645 this.separators_ = separators;
646 this.defaultSeparator_ = goog.isDefAndNotNull(opt_defaultSeparators) ?
647 opt_defaultSeparators :
648 this.separators_.substring(0, 1);
649
650 var wspaceExp = this.multi_ ? '[\\s' + this.separators_ + ']+' : '[\\s]+';
651
652 this.trimmer_ = new RegExp('^' + wspaceExp + '|' + wspaceExp + '$', 'g');
653 this.separatorCheck_ = new RegExp('\\s*[' + this.separators_ + ']$');
654 };
655
656
657 /**
658 * Sets whether to flip the orientation of up & down for hiliting next
659 * and previous autocomplete entries.
660 * @param {boolean} upsideDown Whether the orientation is upside down.
661 */
662 goog.ui.ac.InputHandler.prototype.setUpsideDown = function(upsideDown) {
663 this.upsideDown_ = upsideDown;
664 };
665
666
667 /**
668 * Sets whether auto-completed tokens should be wrapped with whitespace.
669 * @param {boolean} newValue boolean value indicating whether or not
670 * auto-completed tokens should be wrapped with whitespace.
671 */
672 goog.ui.ac.InputHandler.prototype.setWhitespaceWrapEntries = function(
673 newValue) {
674 this.whitespaceWrapEntries_ = newValue;
675 };
676
677
678 /**
679 * Sets whether new tokens should be generated from literals. That is, should
680 * hello'world be two tokens, assuming ' is a literal?
681 * @param {boolean} newValue boolean value indicating whether or not
682 * new tokens should be generated from literals.
683 */
684 goog.ui.ac.InputHandler.prototype.setGenerateNewTokenOnLiteral = function(
685 newValue) {
686 this.generateNewTokenOnLiteral_ = newValue;
687 };
688
689
690 /**
691 * Sets the regular expression used to trim the tokens before passing them to
692 * the matcher: every substring that matches the given regular expression will
693 * be removed. This can also be set to null to disable trimming.
694 * @param {RegExp} trimmer Regexp to use for trimming or null to disable it.
695 */
696 goog.ui.ac.InputHandler.prototype.setTrimmingRegExp = function(trimmer) {
697 this.trimmer_ = trimmer;
698 };
699
700
701 /**
702 * Sets whether we will prevent the default input behavior (moving focus to the
703 * next focusable element) on TAB.
704 * @param {boolean} newValue Whether to preventDefault on TAB.
705 */
706 goog.ui.ac.InputHandler.prototype.setPreventDefaultOnTab = function(newValue) {
707 this.preventDefaultOnTab_ = newValue;
708 };
709
710
711 /**
712 * Sets whether we will prevent highlighted item selection on TAB.
713 * @param {boolean} newValue Whether to prevent selection on TAB.
714 */
715 goog.ui.ac.InputHandler.prototype.setPreventSelectionOnTab = function(
716 newValue) {
717 this.preventSelectionOnTab_ = newValue;
718 };
719
720
721 /**
722 * Sets whether separators perform autocomplete.
723 * @param {boolean} newValue Whether to autocomplete on separators.
724 */
725 goog.ui.ac.InputHandler.prototype.setSeparatorCompletes = function(newValue) {
726 this.separatorUpdates_ = newValue;
727 this.separatorSelects_ = newValue;
728 };
729
730
731 /**
732 * Sets whether separators perform autocomplete.
733 * @param {boolean} newValue Whether to autocomplete on separators.
734 */
735 goog.ui.ac.InputHandler.prototype.setSeparatorSelects = function(newValue) {
736 this.separatorSelects_ = newValue;
737 };
738
739
740 /**
741 * Gets the time to wait before updating the results. If the update during
742 * typing flag is switched on, this delay counts from the last update,
743 * otherwise from the last keypress.
744 * @return {number} Throttle time in milliseconds.
745 */
746 goog.ui.ac.InputHandler.prototype.getThrottleTime = function() {
747 return this.timer_ ? this.timer_.getInterval() : -1;
748 };
749
750
751 /**
752 * Sets whether a row has just been selected.
753 * @param {boolean} justSelected Whether or not the row has just been selected.
754 */
755 goog.ui.ac.InputHandler.prototype.setRowJustSelected = function(justSelected) {
756 this.rowJustSelected_ = justSelected;
757 };
758
759
760 /**
761 * Sets the time to wait before updating the results.
762 * @param {number} time New throttle time in milliseconds.
763 */
764 goog.ui.ac.InputHandler.prototype.setThrottleTime = function(time) {
765 if (time < 0) {
766 this.timer_.dispose();
767 this.timer_ = null;
768 return;
769 }
770 if (this.timer_) {
771 this.timer_.setInterval(time);
772 } else {
773 this.timer_ = new goog.Timer(time);
774 }
775 };
776
777
778 /**
779 * Gets whether the result list is updated during typing.
780 * @return {boolean} Value of the flag.
781 */
782 goog.ui.ac.InputHandler.prototype.getUpdateDuringTyping = function() {
783 return this.updateDuringTyping_;
784 };
785
786
787 /**
788 * Sets whether the result list should be updated during typing.
789 * @param {boolean} value New value of the flag.
790 */
791 goog.ui.ac.InputHandler.prototype.setUpdateDuringTyping = function(value) {
792 this.updateDuringTyping_ = value;
793 };
794
795
796 /**
797 * Handles a key event.
798 * @param {goog.events.BrowserEvent} e Browser event object.
799 * @return {boolean} True if the key event was handled.
800 * @protected
801 */
802 goog.ui.ac.InputHandler.prototype.handleKeyEvent = function(e) {
803 switch (e.keyCode) {
804 // If the menu is open and 'down' caused a change then prevent the default
805 // action and prevent scrolling. If the box isn't a multi autocomplete
806 // and the menu isn't open, we force it open now.
807 case goog.events.KeyCodes.DOWN:
808 if (this.ac_.isOpen()) {
809 this.moveDown_();
810 e.preventDefault();
811 return true;
812
813 } else if (!this.multi_) {
814 this.update(true);
815 e.preventDefault();
816 return true;
817 }
818 break;
819
820 // If the menu is open and 'up' caused a change then prevent the default
821 // action and prevent scrolling.
822 case goog.events.KeyCodes.UP:
823 if (this.ac_.isOpen()) {
824 this.moveUp_();
825 e.preventDefault();
826 return true;
827 }
828 break;
829
830 // If tab key is pressed, select the current highlighted item. The default
831 // action is also prevented if the input is a multi input, to prevent the
832 // user tabbing out of the field.
833 case goog.events.KeyCodes.TAB:
834 if (this.ac_.isOpen() && !e.shiftKey && !this.preventSelectionOnTab_) {
835 // Ensure the menu is up to date before completing.
836 this.update();
837 if (this.ac_.selectHilited() && this.preventDefaultOnTab_) {
838 e.preventDefault();
839 return true;
840 }
841 } else {
842 this.ac_.dismiss();
843 }
844 break;
845
846 // On enter, just select the highlighted row.
847 case goog.events.KeyCodes.ENTER:
848 if (this.ac_.isOpen()) {
849 // Ensure the menu is up to date before completing.
850 this.update();
851 if (this.ac_.selectHilited()) {
852 e.preventDefault();
853 e.stopPropagation();
854 return true;
855 }
856 } else {
857 this.ac_.dismiss();
858 }
859 break;
860
861 // On escape tell the autocomplete to dismiss.
862 case goog.events.KeyCodes.ESC:
863 if (this.ac_.isOpen()) {
864 this.ac_.dismiss();
865 e.preventDefault();
866 e.stopPropagation();
867 return true;
868 }
869 break;
870
871 // The IME keycode indicates an IME sequence has started, we ignore all
872 // changes until we get an enter key-up.
873 case goog.events.KeyCodes.WIN_IME:
874 if (!this.waitingForIme_) {
875 this.startWaitingForIme_();
876 return true;
877 }
878 break;
879
880 default:
881 if (this.timer_ && !this.updateDuringTyping_) {
882 // Waits throttle time before sending the request again.
883 this.timer_.stop();
884 this.timer_.start();
885 }
886 }
887
888 return this.handleSeparator_(e);
889 };
890
891
892 /**
893 * Handles a key event for a separator key.
894 * @param {goog.events.BrowserEvent} e Browser event object.
895 * @return {boolean} True if the key event was handled.
896 * @private
897 */
898 goog.ui.ac.InputHandler.prototype.handleSeparator_ = function(e) {
899 var isSeparatorKey = this.multi_ && e.charCode &&
900 this.separators_.indexOf(String.fromCharCode(e.charCode)) != -1;
901 if (this.separatorUpdates_ && isSeparatorKey) {
902 this.update();
903 }
904 if (this.separatorSelects_ && isSeparatorKey) {
905 if (this.ac_.selectHilited()) {
906 e.preventDefault();
907 return true;
908 }
909 }
910 return false;
911 };
912
913
914 /**
915 * @return {boolean} Whether this inputhandler need to listen on key-up.
916 * @protected
917 */
918 goog.ui.ac.InputHandler.prototype.needKeyUpListener = function() {
919 return false;
920 };
921
922
923 /**
924 * Handles the key up event. Registered only if needKeyUpListener returns true.
925 * @param {goog.events.Event} e The keyup event.
926 * @return {boolean} Whether an action was taken or not.
927 * @protected
928 */
929 goog.ui.ac.InputHandler.prototype.handleKeyUp = function(e) {
930 return false;
931 };
932
933
934 /**
935 * Adds the necessary input event handlers.
936 * @private
937 */
938 goog.ui.ac.InputHandler.prototype.addEventHandlers_ = function() {
939 this.keyHandler_.attach(this.activeElement_);
940 this.eh_.listen(
941 this.keyHandler_, goog.events.KeyHandler.EventType.KEY, this.onKey_);
942 if (this.needKeyUpListener()) {
943 this.eh_.listen(
944 this.activeElement_, goog.events.EventType.KEYUP, this.handleKeyUp);
945 }
946 this.eh_.listen(
947 this.activeElement_, goog.events.EventType.MOUSEDOWN, this.onMouseDown_);
948
949 // IE6 also needs a keypress to check if the user typed a separator
950 if (goog.userAgent.IE) {
951 this.eh_.listen(
952 this.activeElement_, goog.events.EventType.KEYPRESS,
953 this.onIeKeyPress_);
954 }
955 };
956
957
958 /**
959 * Removes the necessary input event handlers.
960 * @private
961 */
962 goog.ui.ac.InputHandler.prototype.removeEventHandlers_ = function() {
963 this.eh_.unlisten(
964 this.keyHandler_, goog.events.KeyHandler.EventType.KEY, this.onKey_);
965 this.keyHandler_.detach();
966 this.eh_.unlisten(
967 this.activeElement_, goog.events.EventType.KEYUP, this.handleKeyUp);
968 this.eh_.unlisten(
969 this.activeElement_, goog.events.EventType.MOUSEDOWN, this.onMouseDown_);
970
971 if (goog.userAgent.IE) {
972 this.eh_.unlisten(
973 this.activeElement_, goog.events.EventType.KEYPRESS,
974 this.onIeKeyPress_);
975 }
976
977 if (this.waitingForIme_) {
978 this.stopWaitingForIme_();
979 }
980 };
981
982
983 /**
984 * Handles an element getting focus.
985 * @param {goog.events.Event} e Browser event object.
986 * @protected
987 */
988 goog.ui.ac.InputHandler.prototype.handleFocus = function(e) {
989 this.processFocus(/** @type {Element} */ (e.target || null));
990 };
991
992
993 /**
994 * Registers handlers for the active element when it receives focus.
995 * @param {Element} target The element to focus.
996 * @protected
997 */
998 goog.ui.ac.InputHandler.prototype.processFocus = function(target) {
999 this.activateHandler_.removeAll();
1000
1001 if (this.ac_) {
1002 this.ac_.cancelDelayedDismiss();
1003 }
1004
1005 // Double-check whether the active element has actually changed.
1006 // This is a fix for Safari 3, which fires spurious focus events.
1007 if (target != this.activeElement_) {
1008 this.activeElement_ = target;
1009 if (this.timer_) {
1010 this.timer_.start();
1011 this.eh_.listen(this.timer_, goog.Timer.TICK, this.onTick_);
1012 }
1013 this.lastValue_ = this.getValue();
1014 this.addEventHandlers_();
1015 }
1016 };
1017
1018
1019 /**
1020 * Handles an element blurring.
1021 * @param {goog.events.Event=} opt_e Browser event object.
1022 * @protected
1023 */
1024 goog.ui.ac.InputHandler.prototype.handleBlur = function(opt_e) {
1025 // Phones running iOS prior to version 4.2.
1026 if (goog.ui.ac.InputHandler.REQUIRES_ASYNC_BLUR_) {
1027 // @bug 4484488 This is required so that the menu works correctly on
1028 // iOS prior to version 4.2. Otherwise, the blur action closes the menu
1029 // before the menu button click can be processed.
1030 // In order to fix the bug, we set a timeout to process the blur event, so
1031 // that any pending selection event can be processed first.
1032 this.activeTimeoutId_ =
1033 window.setTimeout(goog.bind(this.processBlur, this), 0);
1034 return;
1035 } else {
1036 this.processBlur();
1037 }
1038 };
1039
1040
1041 /**
1042 * Helper function that does the logic to handle an element blurring.
1043 * @protected
1044 */
1045 goog.ui.ac.InputHandler.prototype.processBlur = function() {
1046 // it's possible that a blur event could fire when there's no active element,
1047 // in the case where attachInput was called on an input that already had
1048 // the focus
1049 if (this.activeElement_) {
1050 this.removeEventHandlers_();
1051 this.activeElement_ = null;
1052
1053 if (this.timer_) {
1054 this.timer_.stop();
1055 this.eh_.unlisten(this.timer_, goog.Timer.TICK, this.onTick_);
1056 }
1057
1058 if (this.ac_) {
1059 // Pause dismissal slightly to take into account any other events that
1060 // might fire on the renderer (e.g. a click will lose the focus).
1061 this.ac_.dismissOnDelay();
1062 }
1063 }
1064 };
1065
1066
1067 /**
1068 * Handles the timer's tick event. Calculates the current token, and reports
1069 * any update to the autocomplete.
1070 * @param {goog.events.Event} e Browser event object.
1071 * @private
1072 */
1073 goog.ui.ac.InputHandler.prototype.onTick_ = function(e) {
1074 this.update();
1075 };
1076
1077
1078 /**
1079 * Handles typing in an inactive input element. Activate it.
1080 * @param {goog.events.BrowserEvent} e Browser event object.
1081 * @private
1082 */
1083 goog.ui.ac.InputHandler.prototype.onKeyDownOnInactiveElement_ = function(e) {
1084 this.handleFocus(e);
1085 };
1086
1087
1088 /**
1089 * Handles typing in the active input element. Checks if the key is a special
1090 * key and does the relevant action as appropriate.
1091 * @param {goog.events.BrowserEvent} e Browser event object.
1092 * @private
1093 */
1094 goog.ui.ac.InputHandler.prototype.onKey_ = function(e) {
1095 this.lastKeyCode_ = e.keyCode;
1096 if (this.ac_) {
1097 this.handleKeyEvent(e);
1098 }
1099 };
1100
1101
1102 /**
1103 * Handles a KEYPRESS event generated by typing in the active input element.
1104 * Checks if IME input is ended.
1105 * @param {goog.events.BrowserEvent} e Browser event object.
1106 * @private
1107 */
1108 goog.ui.ac.InputHandler.prototype.onKeyPress_ = function(e) {
1109 if (this.waitingForIme_ &&
1110 this.lastKeyCode_ != goog.events.KeyCodes.WIN_IME) {
1111 this.stopWaitingForIme_();
1112 }
1113 };
1114
1115
1116 /**
1117 * Handles the key-up event. This is only ever used by Mac FF or when we are in
1118 * an IME entry scenario.
1119 * @param {goog.events.BrowserEvent} e Browser event object.
1120 * @private
1121 */
1122 goog.ui.ac.InputHandler.prototype.onKeyUp_ = function(e) {
1123 if (this.waitingForIme_ &&
1124 (e.keyCode == goog.events.KeyCodes.ENTER ||
1125 (e.keyCode == goog.events.KeyCodes.M && e.ctrlKey))) {
1126 this.stopWaitingForIme_();
1127 }
1128 };
1129
1130
1131 /**
1132 * Handles mouse-down event.
1133 * @param {goog.events.BrowserEvent} e Browser event object.
1134 * @private
1135 */
1136 goog.ui.ac.InputHandler.prototype.onMouseDown_ = function(e) {
1137 if (this.ac_) {
1138 this.handleMouseDown(e);
1139 }
1140 };
1141
1142
1143 /**
1144 * For subclasses to override to handle the mouse-down event.
1145 * @param {goog.events.BrowserEvent} e Browser event object.
1146 * @protected
1147 */
1148 goog.ui.ac.InputHandler.prototype.handleMouseDown = function(e) {};
1149
1150
1151 /**
1152 * Starts waiting for IME.
1153 * @private
1154 */
1155 goog.ui.ac.InputHandler.prototype.startWaitingForIme_ = function() {
1156 if (this.waitingForIme_) {
1157 return;
1158 }
1159 this.eh_.listen(
1160 this.activeElement_, goog.events.EventType.KEYUP, this.onKeyUp_);
1161 this.eh_.listen(
1162 this.activeElement_, goog.events.EventType.KEYPRESS, this.onKeyPress_);
1163 this.waitingForIme_ = true;
1164 };
1165
1166
1167 /**
1168 * Stops waiting for IME.
1169 * @private
1170 */
1171 goog.ui.ac.InputHandler.prototype.stopWaitingForIme_ = function() {
1172 if (!this.waitingForIme_) {
1173 return;
1174 }
1175 this.waitingForIme_ = false;
1176 this.eh_.unlisten(
1177 this.activeElement_, goog.events.EventType.KEYPRESS, this.onKeyPress_);
1178 this.eh_.unlisten(
1179 this.activeElement_, goog.events.EventType.KEYUP, this.onKeyUp_);
1180 };
1181
1182
1183 /**
1184 * Handles the key-press event for IE, checking to see if the user typed a
1185 * separator character.
1186 * @param {goog.events.BrowserEvent} e Browser event object.
1187 * @private
1188 */
1189 goog.ui.ac.InputHandler.prototype.onIeKeyPress_ = function(e) {
1190 this.handleSeparator_(e);
1191 };
1192
1193
1194 /**
1195 * Checks if an update has occurred and notified the autocomplete of the new
1196 * token.
1197 * @param {boolean=} opt_force If true the menu will be forced to update.
1198 */
1199 goog.ui.ac.InputHandler.prototype.update = function(opt_force) {
1200 if (this.activeElement_ &&
1201 (opt_force || this.getValue() != this.lastValue_)) {
1202 if (opt_force || !this.rowJustSelected_) {
1203 var token = this.parseToken();
1204
1205 if (this.ac_) {
1206 this.ac_.setTarget(this.activeElement_);
1207 this.ac_.setToken(token, this.getValue());
1208 }
1209 }
1210 this.lastValue_ = this.getValue();
1211 }
1212 this.rowJustSelected_ = false;
1213 };
1214
1215
1216 /**
1217 * Parses a text area or input box for the currently highlighted token.
1218 * @return {string} Token to complete.
1219 * @protected
1220 */
1221 goog.ui.ac.InputHandler.prototype.parseToken = function() {
1222 return this.parseToken_();
1223 };
1224
1225
1226 /**
1227 * Moves hilite up. May hilite next or previous depending on orientation.
1228 * @return {boolean} True if successful.
1229 * @private
1230 */
1231 goog.ui.ac.InputHandler.prototype.moveUp_ = function() {
1232 return this.upsideDown_ ? this.ac_.hiliteNext() : this.ac_.hilitePrev();
1233 };
1234
1235
1236 /**
1237 * Moves hilite down. May hilite next or previous depending on orientation.
1238 * @return {boolean} True if successful.
1239 * @private
1240 */
1241 goog.ui.ac.InputHandler.prototype.moveDown_ = function() {
1242 return this.upsideDown_ ? this.ac_.hilitePrev() : this.ac_.hiliteNext();
1243 };
1244
1245
1246 /**
1247 * Parses a text area or input box for the currently highlighted token.
1248 * @return {string} Token to complete.
1249 * @private
1250 */
1251 goog.ui.ac.InputHandler.prototype.parseToken_ = function() {
1252 var caret = this.getCursorPosition();
1253 var text = this.getValue();
1254 return this.trim_(this.splitInput_(text)[this.getTokenIndex_(text, caret)]);
1255 };
1256
1257
1258 /**
1259 * Trims a token of characters that we want to ignore
1260 * @param {string} text string to trim.
1261 * @return {string} Trimmed string.
1262 * @private
1263 */
1264 goog.ui.ac.InputHandler.prototype.trim_ = function(text) {
1265 return this.trimmer_ ? String(text).replace(this.trimmer_, '') : text;
1266 };
1267
1268
1269 /**
1270 * Gets the index of the currently highlighted token
1271 * @param {string} text string to parse.
1272 * @param {number} caret Position of cursor in string.
1273 * @return {number} Index of token.
1274 * @private
1275 */
1276 goog.ui.ac.InputHandler.prototype.getTokenIndex_ = function(text, caret) {
1277 // Split up the input string into multiple entries
1278 var entries = this.splitInput_(text);
1279
1280 // Short-circuit to select the last entry
1281 if (caret == text.length) return entries.length - 1;
1282
1283 // Calculate which of the entries the cursor is currently in
1284 var current = 0;
1285 for (var i = 0, pos = 0; i < entries.length && pos <= caret; i++) {
1286 pos += entries[i].length;
1287 current = i;
1288 }
1289
1290 // Get the token for the current item
1291 return current;
1292 };
1293
1294
1295 /**
1296 * Splits an input string of text at the occurrence of a character in
1297 * {@link goog.ui.ac.InputHandler.prototype.separators_} and creates
1298 * an array of tokens. Each token may contain additional whitespace and
1299 * formatting marks. If necessary use
1300 * {@link goog.ui.ac.InputHandler.prototype.trim_} to clean up the
1301 * entries.
1302 *
1303 * @param {string} text Input text.
1304 * @return {!Array<string>} Parsed array.
1305 * @private
1306 */
1307 goog.ui.ac.InputHandler.prototype.splitInput_ = function(text) {
1308 if (!this.multi_) {
1309 return [text];
1310 }
1311
1312 var arr = String(text).split('');
1313 var parts = [];
1314 var cache = [];
1315
1316 for (var i = 0, inLiteral = false; i < arr.length; i++) {
1317 if (this.literals_ && this.literals_.indexOf(arr[i]) != -1) {
1318 if (this.generateNewTokenOnLiteral_ && !inLiteral) {
1319 parts.push(cache.join(''));
1320 cache.length = 0;
1321 }
1322 cache.push(arr[i]);
1323 inLiteral = !inLiteral;
1324
1325 } else if (!inLiteral && this.separators_.indexOf(arr[i]) != -1) {
1326 cache.push(arr[i]);
1327 parts.push(cache.join(''));
1328 cache.length = 0;
1329
1330 } else {
1331 cache.push(arr[i]);
1332 }
1333 }
1334 parts.push(cache.join(''));
1335
1336 return parts;
1337 };