Debian Codegraph @

closure-library/closure/goog/ui/abstractspellchecker.js

raw
1 // Copyright 2007 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 Abstract base class for spell checker implementations.
17 *
18 * The spell checker supports two modes - synchronous and asynchronous.
19 *
20 * In synchronous mode subclass calls processText_ which processes all the text
21 * given to it before it returns. If the text string is very long, it could
22 * cause warnings from the browser that considers the script to be
23 * busy-looping.
24 *
25 * Asynchronous mode allows breaking processing large text segments without
26 * encountering stop script warnings by rescheduling remaining parts of the
27 * text processing to another stack.
28 *
29 * In asynchronous mode abstract spell checker keeps track of a number of text
30 * chunks that have been processed after the very beginning, and returns every
31 * so often so that the calling function could reschedule its execution on a
32 * different stack (for example by calling setInterval(0)).
33 *
34 * @author [email protected] (Emil A Eklund)
35 */
36
37 goog.provide('goog.ui.AbstractSpellChecker');
38 goog.provide('goog.ui.AbstractSpellChecker.AsyncResult');
39
40 goog.require('goog.a11y.aria');
41 goog.require('goog.array');
42 goog.require('goog.asserts');
43 goog.require('goog.dom');
44 goog.require('goog.dom.InputType');
45 goog.require('goog.dom.NodeType');
46 goog.require('goog.dom.TagName');
47 goog.require('goog.dom.classlist');
48 goog.require('goog.dom.selection');
49 goog.require('goog.events');
50 goog.require('goog.events.Event');
51 goog.require('goog.events.EventType');
52 goog.require('goog.math.Coordinate');
53 goog.require('goog.spell.SpellCheck');
54 goog.require('goog.structs.Set');
55 goog.require('goog.style');
56 goog.require('goog.ui.Component');
57 goog.require('goog.ui.MenuItem');
58 goog.require('goog.ui.MenuSeparator');
59 goog.require('goog.ui.PopupMenu');
60
61
62
63 /**
64 * Abstract base class for spell checker editor implementations. Provides basic
65 * functionality such as word lookup and caching.
66 *
67 * @param {goog.spell.SpellCheck} spellCheck Instance of the SpellCheck
68 * support object to use. A single instance can be shared by multiple editor
69 * components.
70 * @param {goog.dom.DomHelper=} opt_domHelper Optional DOM helper.
71 * @constructor
72 * @extends {goog.ui.Component}
73 */
74 goog.ui.AbstractSpellChecker = function(spellCheck, opt_domHelper) {
75 goog.ui.Component.call(this, opt_domHelper);
76
77 /**
78 * Handler to use for caching and lookups.
79 * @type {goog.spell.SpellCheck}
80 * @protected
81 */
82 this.spellCheck = spellCheck;
83
84 /**
85 * Word to element references. Used by replace/ignore.
86 * @type {Object}
87 * @private
88 */
89 this.wordElements_ = {};
90
91 /**
92 * List of all 'edit word' input elements.
93 * @type {Array<Element>}
94 * @private
95 */
96 this.inputElements_ = [];
97
98 /**
99 * Global regular expression for splitting a string into individual words and
100 * blocks of separators. Matches zero or one word followed by zero or more
101 * separators.
102 * @type {RegExp}
103 * @private
104 */
105 this.splitRegex_ = new RegExp(
106 '([^' + goog.spell.SpellCheck.WORD_BOUNDARY_CHARS + ']*)' +
107 '([' + goog.spell.SpellCheck.WORD_BOUNDARY_CHARS + ']*)',
108 'g');
109
110 goog.events.listen(
111 this.spellCheck, goog.spell.SpellCheck.EventType.WORD_CHANGED,
112 this.onWordChanged_, false, this);
113 };
114 goog.inherits(goog.ui.AbstractSpellChecker, goog.ui.Component);
115 goog.tagUnsealableClass(goog.ui.AbstractSpellChecker);
116
117
118 /**
119 * The prefix to mark keys with.
120 * @type {string}
121 * @private
122 */
123 goog.ui.AbstractSpellChecker.KEY_PREFIX_ = ':';
124
125
126 /**
127 * The attribute name for original element contents (to offer subsequent
128 * correction menu).
129 * @type {string}
130 * @private
131 */
132 goog.ui.AbstractSpellChecker.ORIGINAL_ = 'g-spell-original';
133
134
135 /**
136 * Suggestions menu.
137 *
138 * @type {goog.ui.PopupMenu|undefined}
139 * @private
140 */
141 goog.ui.AbstractSpellChecker.prototype.menu_;
142
143
144 /**
145 * Separator between suggestions and ignore in suggestions menu.
146 *
147 * @type {goog.ui.MenuSeparator|undefined}
148 * @private
149 */
150 goog.ui.AbstractSpellChecker.prototype.menuSeparator_;
151
152
153 /**
154 * Menu item for ignore option.
155 *
156 * @type {goog.ui.MenuItem|undefined}
157 * @private
158 */
159 goog.ui.AbstractSpellChecker.prototype.menuIgnore_;
160
161
162 /**
163 * Menu item for edit word option.
164 *
165 * @type {goog.ui.MenuItem|undefined}
166 * @private
167 */
168 goog.ui.AbstractSpellChecker.prototype.menuEdit_;
169
170
171 /**
172 * Whether the correction UI is visible.
173 *
174 * @type {boolean}
175 * @private
176 */
177 goog.ui.AbstractSpellChecker.prototype.isVisible_ = false;
178
179
180 /**
181 * Cache for corrected words. All corrected words are reverted to their original
182 * status on resume. Therefore that status is never written to the cache and is
183 * instead indicated by this set.
184 *
185 * @type {goog.structs.Set|undefined}
186 * @private
187 */
188 goog.ui.AbstractSpellChecker.prototype.correctedWords_;
189
190
191 /**
192 * Class name for suggestions menu.
193 *
194 * @type {string}
195 */
196 goog.ui.AbstractSpellChecker.prototype.suggestionsMenuClassName =
197 goog.getCssName('goog-menu');
198
199
200 /**
201 * Whether corrected words should be highlighted.
202 *
203 * @type {boolean}
204 */
205 goog.ui.AbstractSpellChecker.prototype.markCorrected = false;
206
207
208 /**
209 * Word the correction menu is displayed for.
210 *
211 * @type {string|undefined}
212 * @private
213 */
214 goog.ui.AbstractSpellChecker.prototype.activeWord_;
215
216
217 /**
218 * Element the correction menu is displayed for.
219 *
220 * @type {Element|undefined}
221 * @private
222 */
223 goog.ui.AbstractSpellChecker.prototype.activeElement_;
224
225
226 /**
227 * Indicator that the spell checker is running in the asynchronous mode.
228 *
229 * @type {boolean}
230 * @private
231 */
232 goog.ui.AbstractSpellChecker.prototype.asyncMode_ = false;
233
234
235 /**
236 * Maximum number of words to process on a single stack in asynchronous mode.
237 *
238 * @type {number}
239 * @private
240 */
241 goog.ui.AbstractSpellChecker.prototype.asyncWordsPerBatch_ = 1000;
242
243
244 /**
245 * Current text to process when running in the asynchronous mode.
246 *
247 * @type {string|undefined}
248 * @private
249 */
250 goog.ui.AbstractSpellChecker.prototype.asyncText_;
251
252
253 /**
254 * Current start index of the range that spell-checked correctly.
255 *
256 * @type {number|undefined}
257 * @private
258 */
259 goog.ui.AbstractSpellChecker.prototype.asyncRangeStart_;
260
261
262 /**
263 * Current node with which the asynchronous text is associated.
264 *
265 * @type {Node|undefined}
266 * @private
267 */
268 goog.ui.AbstractSpellChecker.prototype.asyncNode_;
269
270
271 /**
272 * Number of elements processed in the asyncronous mode since last yield.
273 *
274 * @type {number}
275 * @private
276 */
277 goog.ui.AbstractSpellChecker.prototype.processedElementsCount_ = 0;
278
279
280 /**
281 * Markers for the text that does not need to be included in the processing.
282 *
283 * For rich text editor this is a list of strings formatted as
284 * tagName.className or className. If both are specified, the element will be
285 * excluded if BOTH are matched. If only a className is specified, then we will
286 * exclude regions with the className. If only one marker is needed, it may be
287 * passed as a string.
288 * For plain text editor this is a RegExp that matches the excluded text.
289 *
290 * Used exclusively by the derived classes
291 *
292 * @type {Array<string>|string|RegExp|undefined}
293 * @protected
294 */
295 goog.ui.AbstractSpellChecker.prototype.excludeMarker;
296
297
298 /**
299 * Numeric Id of the element that has focus. 0 when not set.
300 *
301 * @private {number}
302 */
303 goog.ui.AbstractSpellChecker.prototype.focusedElementIndex_ = 0;
304
305
306 /**
307 * Index for the most recently added misspelled word.
308 *
309 * @private {number}
310 */
311 goog.ui.AbstractSpellChecker.prototype.lastIndex_ = 0;
312
313
314 /**
315 * @return {goog.spell.SpellCheck} The handler used for caching and lookups.
316 */
317 goog.ui.AbstractSpellChecker.prototype.getSpellCheck = function() {
318 return this.spellCheck;
319 };
320
321 /**
322 * Sets the spell checker used for caching and lookups.
323 * @param {goog.spell.SpellCheck} spellCheck The handler used for caching and
324 * lookups.
325 */
326 goog.ui.AbstractSpellChecker.prototype.setSpellCheck = function(spellCheck) {
327 this.spellCheck = spellCheck;
328 };
329
330
331 /**
332 * Sets the handler used for caching and lookups.
333 * @param {goog.spell.SpellCheck} handler The handler used for caching and
334 * lookups.
335 * @deprecated Use #setSpellCheck instead.
336 */
337 goog.ui.AbstractSpellChecker.prototype.setHandler = function(handler) {
338 this.setSpellCheck(handler);
339 };
340
341
342 /**
343 * @return {goog.ui.PopupMenu|undefined} The suggestions menu.
344 * @protected
345 */
346 goog.ui.AbstractSpellChecker.prototype.getMenu = function() {
347 return this.menu_;
348 };
349
350
351 /**
352 * @return {goog.ui.MenuItem|undefined} The menu item for edit word option.
353 * @protected
354 */
355 goog.ui.AbstractSpellChecker.prototype.getMenuEdit = function() {
356 return this.menuEdit_;
357 };
358
359
360 /**
361 * @return {number} The index of the latest misspelled word to be added.
362 * @protected
363 */
364 goog.ui.AbstractSpellChecker.prototype.getLastIndex = function() {
365 return this.lastIndex_;
366 };
367
368
369 /**
370 * @return {number} Increments and returns the index for the next misspelled
371 * word to be added.
372 * @protected
373 */
374 goog.ui.AbstractSpellChecker.prototype.getNextIndex = function() {
375 return ++this.lastIndex_;
376 };
377
378
379 /**
380 * Sets the marker for the excluded text.
381 *
382 * {@see goog.ui.AbstractSpellChecker.prototype.excludeMarker}
383 *
384 * @param {Array<string>|string|RegExp|null} marker A RegExp for plain text
385 * or class names for the rich text spell checker for the elements to
386 * exclude from checking.
387 */
388 goog.ui.AbstractSpellChecker.prototype.setExcludeMarker = function(marker) {
389 this.excludeMarker = marker || undefined;
390 };
391
392
393 /**
394 * Checks spelling for all text.
395 * Should be overridden by implementation.
396 */
397 goog.ui.AbstractSpellChecker.prototype.check = function() {
398 this.isVisible_ = true;
399 if (this.markCorrected) {
400 this.correctedWords_ = new goog.structs.Set();
401 }
402 };
403
404
405 /**
406 * Hides correction UI.
407 * Should be overridden by implementation.
408 */
409 goog.ui.AbstractSpellChecker.prototype.resume = function() {
410 this.isVisible_ = false;
411 this.clearWordElements();
412 this.lastIndex_ = 0;
413 this.setFocusedElementIndex(0);
414
415 var input;
416 while (input = this.inputElements_.pop()) {
417 input.parentNode.replaceChild(
418 this.getDomHelper().createTextNode(input.value), input);
419 }
420
421 if (this.correctedWords_) {
422 this.correctedWords_.clear();
423 }
424 };
425
426
427 /**
428 * @return {boolean} Whether the correction ui is visible.
429 */
430 goog.ui.AbstractSpellChecker.prototype.isVisible = function() {
431 return this.isVisible_;
432 };
433
434
435 /**
436 * Clears the word to element references map used by replace/ignore.
437 * @protected
438 */
439 goog.ui.AbstractSpellChecker.prototype.clearWordElements = function() {
440 this.wordElements_ = {};
441 };
442
443
444 /**
445 * Ignores spelling of word.
446 *
447 * @param {string} word Word to add.
448 */
449 goog.ui.AbstractSpellChecker.prototype.ignoreWord = function(word) {
450 this.spellCheck.setWordStatus(word, goog.spell.SpellCheck.WordStatus.IGNORED);
451 };
452
453
454 /**
455 * Edits a word.
456 *
457 * @param {Element} el An element wrapping the word that should be edited.
458 * @param {string} old Word to edit.
459 * @private
460 */
461 goog.ui.AbstractSpellChecker.prototype.editWord_ = function(el, old) {
462 var input = this.getDomHelper().createDom(
463 goog.dom.TagName.INPUT, {'type': goog.dom.InputType.TEXT, 'value': old});
464 var w = goog.style.getSize(el).width;
465
466 // Minimum width to ensure there's always enough room to type.
467 if (w < 50) {
468 w = 50;
469 }
470 input.style.width = w + 'px';
471 el.parentNode.replaceChild(input, el);
472 try {
473 input.focus();
474 goog.dom.selection.setCursorPosition(input, old.length);
475 } catch (o) {
476 }
477
478 this.inputElements_.push(input);
479 };
480
481
482 /**
483 * Replaces word.
484 *
485 * @param {Element} el An element wrapping the word that should be replaced.
486 * @param {string} old Word that was replaced.
487 * @param {string} word Word to replace with.
488 */
489 goog.ui.AbstractSpellChecker.prototype.replaceWord = function(el, old, word) {
490 if (old != word) {
491 if (!el.getAttribute(goog.ui.AbstractSpellChecker.ORIGINAL_)) {
492 el.setAttribute(goog.ui.AbstractSpellChecker.ORIGINAL_, old);
493 }
494 goog.dom.setTextContent(el, word);
495
496 var status = this.spellCheck.checkWord(word);
497
498 // Indicate that the word is corrected unless the status is 'INVALID'.
499 // (if markCorrected is enabled).
500 if (this.markCorrected && this.correctedWords_ &&
501 status != goog.spell.SpellCheck.WordStatus.INVALID) {
502 this.correctedWords_.add(word);
503 status = goog.spell.SpellCheck.WordStatus.CORRECTED;
504 }
505
506 // Avoid potential collision with the built-in object namespace. For
507 // example, 'watch' is a reserved name in FireFox.
508 var oldIndex = goog.ui.AbstractSpellChecker.toInternalKey_(old);
509 var newIndex = goog.ui.AbstractSpellChecker.toInternalKey_(word);
510
511 // Remove reference between old word and element
512 var elements = this.wordElements_[oldIndex];
513 goog.array.remove(elements, el);
514
515 if (status != goog.spell.SpellCheck.WordStatus.VALID) {
516 // Create reference between new word and element
517 if (this.wordElements_[newIndex]) {
518 this.wordElements_[newIndex].push(el);
519 } else {
520 this.wordElements_[newIndex] = [el];
521 }
522 }
523
524 // Update element based on status.
525 this.updateElement(el, word, status);
526
527 this.dispatchEvent(goog.events.EventType.CHANGE);
528 }
529 };
530
531
532 /**
533 * Retrieves the array of suggested spelling choices.
534 *
535 * @return {Array<string>} Suggested spelling choices.
536 * @private
537 */
538 goog.ui.AbstractSpellChecker.prototype.getSuggestions_ = function() {
539 // Add new suggestion entries.
540 var suggestions = this.spellCheck.getSuggestions(
541 /** @type {string} */ (this.activeWord_));
542 if (!suggestions[0]) {
543 var originalWord = this.activeElement_.getAttribute(
544 goog.ui.AbstractSpellChecker.ORIGINAL_);
545 if (originalWord && originalWord != this.activeWord_) {
546 suggestions = this.spellCheck.getSuggestions(originalWord);
547 }
548 }
549 return suggestions;
550 };
551
552
553 /**
554 * Displays suggestions menu.
555 *
556 * @param {Element} el Element to display menu for.
557 * @param {goog.events.BrowserEvent|goog.math.Coordinate=} opt_pos Position to
558 * display menu at relative to the viewport (in client coordinates), or a
559 * mouse event.
560 */
561 goog.ui.AbstractSpellChecker.prototype.showSuggestionsMenu = function(
562 el, opt_pos) {
563 this.activeWord_ = goog.dom.getTextContent(el);
564 this.activeElement_ = el;
565
566 // Remove suggestion entries from menu, if any.
567 while (this.menu_.getChildAt(0) != this.menuSeparator_) {
568 this.menu_.removeChildAt(0, true).dispose();
569 }
570
571 // Add new suggestion entries.
572 var suggestions = this.getSuggestions_();
573 for (var suggestion, i = 0; suggestion = suggestions[i]; i++) {
574 this.menu_.addChildAt(
575 new goog.ui.MenuItem(suggestion, suggestion, this.getDomHelper()), i,
576 true);
577 }
578
579 if (!suggestions[0]) {
580 /** @desc Item shown in menu when no suggestions are available. */
581 var MSG_SPELL_NO_SUGGESTIONS = goog.getMsg('No Suggestions');
582 var item =
583 new goog.ui.MenuItem(MSG_SPELL_NO_SUGGESTIONS, '', this.getDomHelper());
584 item.setEnabled(false);
585 this.menu_.addChildAt(item, 0, true);
586 }
587
588 // Show 'Edit word' option if {@link markCorrected} is enabled and don't show
589 // 'Ignore' option for corrected words.
590 if (this.markCorrected) {
591 var corrected =
592 this.correctedWords_ && this.correctedWords_.contains(this.activeWord_);
593 this.menuIgnore_.setVisible(!corrected);
594 this.menuEdit_.setVisible(true);
595 } else {
596 this.menuIgnore_.setVisible(true);
597 this.menuEdit_.setVisible(false);
598 }
599
600 if (opt_pos) {
601 if (!(opt_pos instanceof goog.math.Coordinate)) { // it's an event
602 var posX = opt_pos.clientX;
603 var posY = opt_pos.clientY;
604 // Certain implementations which derive from AbstractSpellChecker
605 // use an iframe in which case the coordinates are relative to
606 // that iframe's view port.
607 if (this.getElement().contentDocument ||
608 this.getElement().contentWindow) {
609 var offset = goog.style.getClientPosition(this.getElement());
610 posX += offset.x;
611 posY += offset.y;
612 }
613 opt_pos = new goog.math.Coordinate(posX, posY);
614 }
615 this.menu_.showAt(opt_pos.x, opt_pos.y);
616 } else {
617 this.menu_.setVisible(true);
618 }
619 };
620
621
622 /**
623 * Initializes suggestions menu. Populates menu with separator and ignore option
624 * that are always valid. Suggestions are later added above the separator.
625 *
626 * @protected
627 */
628 goog.ui.AbstractSpellChecker.prototype.initSuggestionsMenu = function() {
629 this.menu_ = new goog.ui.PopupMenu(this.getDomHelper());
630 this.menuSeparator_ = new goog.ui.MenuSeparator(this.getDomHelper());
631
632 // Leave alone setAllowAutoFocus at default (true). This allows menu to get
633 // keyboard focus and thus allowing non-mouse users to get to the menu.
634
635 /** @desc Ignore entry in suggestions menu. */
636 var MSG_SPELL_IGNORE = goog.getMsg('Ignore');
637
638 /** @desc Edit word entry in suggestions menu. */
639 var MSG_SPELL_EDIT_WORD = goog.getMsg('Edit Word');
640
641 this.menu_.addChild(this.menuSeparator_, true);
642 this.menuIgnore_ =
643 new goog.ui.MenuItem(MSG_SPELL_IGNORE, '', this.getDomHelper());
644 this.menu_.addChild(this.menuIgnore_, true);
645 this.menuEdit_ =
646 new goog.ui.MenuItem(MSG_SPELL_EDIT_WORD, '', this.getDomHelper());
647 this.menuEdit_.setVisible(false);
648 this.menu_.addChild(this.menuEdit_, true);
649 this.menu_.setParent(this);
650 this.menu_.render();
651
652 var menuElement = this.menu_.getElement();
653 goog.asserts.assert(menuElement);
654 goog.dom.classlist.add(menuElement, this.suggestionsMenuClassName);
655
656 goog.events.listen(
657 this.menu_, goog.ui.Component.EventType.ACTION, this.onCorrectionAction,
658 false, this);
659 };
660
661
662 /**
663 * Handles correction menu actions.
664 *
665 * @param {goog.events.Event} event Action event.
666 * @protected
667 */
668 goog.ui.AbstractSpellChecker.prototype.onCorrectionAction = function(event) {
669 var word = /** @type {string} */ (this.activeWord_);
670 var el = /** @type {Element} */ (this.activeElement_);
671 if (event.target == this.menuIgnore_) {
672 this.ignoreWord(word);
673 } else if (event.target == this.menuEdit_) {
674 this.editWord_(el, word);
675 } else {
676 this.replaceWord(el, word, event.target.getModel());
677 this.dispatchEvent(goog.ui.Component.EventType.CHANGE);
678 }
679
680 delete this.activeWord_;
681 delete this.activeElement_;
682 };
683
684
685 /**
686 * Removes spell-checker markup and restore the node to text.
687 *
688 * @param {Element} el Word element. MUST have a text node child.
689 * @protected
690 */
691 goog.ui.AbstractSpellChecker.prototype.removeMarkup = function(el) {
692 var firstChild = el.firstChild;
693 var text = firstChild.nodeValue;
694
695 if (el.nextSibling && el.nextSibling.nodeType == goog.dom.NodeType.TEXT) {
696 if (el.previousSibling &&
697 el.previousSibling.nodeType == goog.dom.NodeType.TEXT) {
698 el.previousSibling.nodeValue =
699 el.previousSibling.nodeValue + text + el.nextSibling.nodeValue;
700 this.getDomHelper().removeNode(el.nextSibling);
701 } else {
702 el.nextSibling.nodeValue = text + el.nextSibling.nodeValue;
703 }
704 } else if (
705 el.previousSibling &&
706 el.previousSibling.nodeType == goog.dom.NodeType.TEXT) {
707 el.previousSibling.nodeValue += text;
708 } else {
709 el.parentNode.insertBefore(firstChild, el);
710 }
711
712 this.getDomHelper().removeNode(el);
713 };
714
715
716 /**
717 * Updates element based on word status. Either converts it to a text node, or
718 * merges it with the previous or next text node if the status of the world is
719 * VALID, in which case the element itself is eliminated.
720 *
721 * @param {Element} el Word element.
722 * @param {string} word Word to update status for.
723 * @param {goog.spell.SpellCheck.WordStatus} status Status of word.
724 * @protected
725 */
726 goog.ui.AbstractSpellChecker.prototype.updateElement = function(
727 el, word, status) {
728 if (this.markCorrected && this.correctedWords_ &&
729 this.correctedWords_.contains(word)) {
730 status = goog.spell.SpellCheck.WordStatus.CORRECTED;
731 }
732 if (status == goog.spell.SpellCheck.WordStatus.VALID) {
733 this.removeMarkup(el);
734 } else {
735 goog.dom.setProperties(el, this.getElementProperties(status));
736 }
737 };
738
739
740 /**
741 * Generates unique Ids for spell checker elements.
742 * @param {number=} opt_id Id to suffix with.
743 * @return {string} Unique element id.
744 * @protected
745 */
746 goog.ui.AbstractSpellChecker.prototype.makeElementId = function(opt_id) {
747 return this.getId() + '.' + (opt_id ? opt_id : this.getNextIndex());
748 };
749
750
751 /**
752 * Returns the span element that matches the given number index.
753 * @param {number} index Number index that is used in the element id.
754 * @return {Element} The matching span element or null if no span matches.
755 * @protected
756 */
757 goog.ui.AbstractSpellChecker.prototype.getElementByIndex = function(index) {
758 return this.getDomHelper().getElement(this.makeElementId(index));
759 };
760
761
762 /**
763 * Creates an element for a specified word and stores a reference to it.
764 *
765 * @param {string} word Word to create element for.
766 * @param {goog.spell.SpellCheck.WordStatus} status Status of word.
767 * @return {!HTMLSpanElement} The created element.
768 * @protected
769 */
770 goog.ui.AbstractSpellChecker.prototype.createWordElement = function(
771 word, status) {
772 var parameters = this.getElementProperties(status);
773
774 // Add id & tabindex as necessary.
775 if (!parameters['id']) {
776 parameters['id'] = this.makeElementId();
777 }
778 if (!parameters['tabIndex']) {
779 parameters['tabIndex'] = -1;
780 }
781
782 var el =
783 this.getDomHelper().createDom(goog.dom.TagName.SPAN, parameters, word);
784 goog.a11y.aria.setRole(el, 'menuitem');
785 goog.a11y.aria.setState(el, 'haspopup', true);
786 this.registerWordElement(word, el);
787
788 return el;
789 };
790
791
792 /**
793 * Stores a reference to word element.
794 *
795 * @param {string} word The word to store.
796 * @param {HTMLSpanElement} el The element associated with it.
797 * @protected
798 */
799 goog.ui.AbstractSpellChecker.prototype.registerWordElement = function(
800 word, el) {
801 // Avoid potential collision with the built-in object namespace. For
802 // example, 'watch' is a reserved name in FireFox.
803 var index = goog.ui.AbstractSpellChecker.toInternalKey_(word);
804 if (this.wordElements_[index]) {
805 this.wordElements_[index].push(el);
806 } else {
807 this.wordElements_[index] = [el];
808 }
809 };
810
811
812 /**
813 * Returns desired element properties for the specified status.
814 * Should be overridden by implementation.
815 *
816 * @param {goog.spell.SpellCheck.WordStatus} status Status of word.
817 * @return {Object} Properties to apply to the element.
818 * @protected
819 */
820 goog.ui.AbstractSpellChecker.prototype.getElementProperties =
821 goog.abstractMethod;
822
823
824 /**
825 * Handles word change events and updates the word elements accordingly.
826 *
827 * @param {goog.spell.SpellCheck.WordChangedEvent} event The event object.
828 * @private
829 */
830 goog.ui.AbstractSpellChecker.prototype.onWordChanged_ = function(event) {
831 // Avoid potential collision with the built-in object namespace. For
832 // example, 'watch' is a reserved name in FireFox.
833 var index = goog.ui.AbstractSpellChecker.toInternalKey_(event.word);
834 var elements = this.wordElements_[index];
835 if (elements) {
836 for (var el, i = 0; el = elements[i]; i++) {
837 this.updateElement(el, event.word, event.status);
838 }
839 }
840 };
841
842
843 /** @override */
844 goog.ui.AbstractSpellChecker.prototype.disposeInternal = function() {
845 if (this.isVisible_) {
846 // Clears wordElements_
847 this.resume();
848 }
849
850 goog.events.unlisten(
851 this.spellCheck, goog.spell.SpellCheck.EventType.WORD_CHANGED,
852 this.onWordChanged_, false, this);
853
854 if (this.menu_) {
855 this.menu_.dispose();
856 delete this.menu_;
857 delete this.menuIgnore_;
858 delete this.menuSeparator_;
859 }
860 delete this.spellCheck;
861 delete this.wordElements_;
862
863 goog.ui.AbstractSpellChecker.superClass_.disposeInternal.call(this);
864 };
865
866
867 /**
868 * Precharges local dictionary cache. This is optional, but greatly reduces
869 * amount of subsequent churn in the DOM tree because most of the words become
870 * known from the very beginning.
871 *
872 * @param {string} text Text to process.
873 * @param {number} words Max number of words to scan.
874 * @return {number} number of words actually scanned.
875 * @protected
876 */
877 goog.ui.AbstractSpellChecker.prototype.populateDictionary = function(
878 text, words) {
879 this.splitRegex_.lastIndex = 0;
880 var result;
881 var numScanned = 0;
882 while (result = this.splitRegex_.exec(text)) {
883 if (result[0].length == 0) {
884 break;
885 }
886 var word = result[1];
887 if (word) {
888 this.spellCheck.checkWord(word);
889 ++numScanned;
890 if (numScanned >= words) {
891 break;
892 }
893 }
894 }
895 this.spellCheck.processPending();
896 return numScanned;
897 };
898
899
900 /**
901 * Processes word.
902 * Should be overridden by implementation.
903 *
904 * @param {Node} node Node containing word.
905 * @param {string} text Word to process.
906 * @param {goog.spell.SpellCheck.WordStatus} status Status of the word.
907 * @protected
908 */
909 goog.ui.AbstractSpellChecker.prototype.processWord = function(
910 node, text, status) {
911 throw new Error('Need to override processWord_ in derivative class');
912 };
913
914
915 /**
916 * Processes range of text that checks out (contains no unrecognized words).
917 * Should be overridden by implementation. May contain words and separators.
918 *
919 * @param {Node} node Node containing text range.
920 * @param {string} text text to process.
921 * @protected
922 */
923 goog.ui.AbstractSpellChecker.prototype.processRange = function(node, text) {
924 throw new Error('Need to override processRange_ in derivative class');
925 };
926
927
928 /**
929 * Starts asynchronous processing mode.
930 *
931 * @protected
932 */
933 goog.ui.AbstractSpellChecker.prototype.initializeAsyncMode = function() {
934 if (this.asyncMode_ || this.processedElementsCount_ ||
935 this.asyncText_ != null || this.asyncNode_) {
936 throw new Error('Async mode already in progress.');
937 }
938 this.asyncMode_ = true;
939 this.processedElementsCount_ = 0;
940 delete this.asyncText_;
941 this.asyncRangeStart_ = 0;
942 delete this.asyncNode_;
943
944 this.blockReadyEvents();
945 };
946
947
948 /**
949 * Finalizes asynchronous processing mode. Should be called after there is no
950 * more text to process and processTextAsync and/or continueAsyncProcessing
951 * returned FINISHED.
952 *
953 * @protected
954 */
955 goog.ui.AbstractSpellChecker.prototype.finishAsyncProcessing = function() {
956 if (!this.asyncMode_ || this.asyncText_ != null || this.asyncNode_) {
957 throw new Error(
958 'Async mode not started or there is still text to process.');
959 }
960 this.asyncMode_ = false;
961 this.processedElementsCount_ = 0;
962
963 this.unblockReadyEvents();
964 this.spellCheck.processPending();
965 };
966
967
968 /**
969 * Blocks processing of spell checker READY events. This is used in dictionary
970 * recharge and async mode so that completion is not signaled prematurely.
971 *
972 * @protected
973 */
974 goog.ui.AbstractSpellChecker.prototype.blockReadyEvents = function() {
975 goog.events.listen(
976 this.spellCheck, goog.spell.SpellCheck.EventType.READY,
977 goog.events.Event.stopPropagation, true);
978 };
979
980
981 /**
982 * Unblocks processing of spell checker READY events. This is used in
983 * dictionary recharge and async mode so that completion is not signaled
984 * prematurely.
985 *
986 * @protected
987 */
988 goog.ui.AbstractSpellChecker.prototype.unblockReadyEvents = function() {
989 goog.events.unlisten(
990 this.spellCheck, goog.spell.SpellCheck.EventType.READY,
991 goog.events.Event.stopPropagation, true);
992 };
993
994
995 /**
996 * Splits text into individual words and blocks of separators. Calls virtual
997 * processWord_ and processRange_ methods.
998 *
999 * @param {Node} node Node containing text.
1000 * @param {string} text Text to process.
1001 * @return {goog.ui.AbstractSpellChecker.AsyncResult} operation result.
1002 * @protected
1003 */
1004 goog.ui.AbstractSpellChecker.prototype.processTextAsync = function(node, text) {
1005 if (!this.asyncMode_ || this.asyncText_ != null || this.asyncNode_) {
1006 throw new Error(
1007 'Not in async mode or previous text has not been processed.');
1008 }
1009
1010 this.splitRegex_.lastIndex = 0;
1011 var stringSegmentStart = 0;
1012
1013 var result;
1014 while (result = this.splitRegex_.exec(text)) {
1015 if (result[0].length == 0) {
1016 break;
1017 }
1018 var word = result[1];
1019 if (word) {
1020 var status = this.spellCheck.checkWord(word);
1021 if (status != goog.spell.SpellCheck.WordStatus.VALID) {
1022 var precedingText =
1023 text.substr(stringSegmentStart, result.index - stringSegmentStart);
1024 if (precedingText) {
1025 this.processRange(node, precedingText);
1026 }
1027 stringSegmentStart = result.index + word.length;
1028 this.processWord(node, word, status);
1029 }
1030 }
1031 this.processedElementsCount_++;
1032 if (this.processedElementsCount_ > this.asyncWordsPerBatch_) {
1033 this.asyncText_ = text;
1034 this.asyncRangeStart_ = stringSegmentStart;
1035 this.asyncNode_ = node;
1036 this.processedElementsCount_ = 0;
1037 return goog.ui.AbstractSpellChecker.AsyncResult.PENDING;
1038 }
1039 }
1040
1041 var leftoverText = text.substr(stringSegmentStart);
1042 if (leftoverText) {
1043 this.processRange(node, leftoverText);
1044 }
1045
1046 return goog.ui.AbstractSpellChecker.AsyncResult.DONE;
1047 };
1048
1049
1050 /**
1051 * Continues processing started by processTextAsync. Calls virtual
1052 * processWord_ and processRange_ methods.
1053 *
1054 * @return {goog.ui.AbstractSpellChecker.AsyncResult} operation result.
1055 * @protected
1056 */
1057 goog.ui.AbstractSpellChecker.prototype.continueAsyncProcessing = function() {
1058 if (!this.asyncMode_ || this.asyncText_ == null || !this.asyncNode_) {
1059 throw new Error('Not in async mode or processing not started.');
1060 }
1061 var node = /** @type {Node} */ (this.asyncNode_);
1062 var stringSegmentStart = this.asyncRangeStart_;
1063 goog.asserts.assertNumber(stringSegmentStart);
1064 var text = this.asyncText_;
1065
1066 var result;
1067 while (result = this.splitRegex_.exec(text)) {
1068 if (result[0].length == 0) {
1069 break;
1070 }
1071 var word = result[1];
1072 if (word) {
1073 var status = this.spellCheck.checkWord(word);
1074 if (status != goog.spell.SpellCheck.WordStatus.VALID) {
1075 var precedingText =
1076 text.substr(stringSegmentStart, result.index - stringSegmentStart);
1077 if (precedingText) {
1078 this.processRange(node, precedingText);
1079 }
1080 stringSegmentStart = result.index + word.length;
1081 this.processWord(node, word, status);
1082 }
1083 }
1084 this.processedElementsCount_++;
1085 if (this.processedElementsCount_ > this.asyncWordsPerBatch_) {
1086 this.processedElementsCount_ = 0;
1087 this.asyncRangeStart_ = stringSegmentStart;
1088 return goog.ui.AbstractSpellChecker.AsyncResult.PENDING;
1089 }
1090 }
1091 delete this.asyncText_;
1092 this.asyncRangeStart_ = 0;
1093 delete this.asyncNode_;
1094
1095 var leftoverText = text.substr(stringSegmentStart);
1096 if (leftoverText) {
1097 this.processRange(node, leftoverText);
1098 }
1099
1100 return goog.ui.AbstractSpellChecker.AsyncResult.DONE;
1101 };
1102
1103
1104 /**
1105 * Converts a word to an internal key representation. This is necessary to
1106 * avoid collisions with object's internal namespace. Only words that are
1107 * reserved need to be escaped.
1108 *
1109 * @param {string} word The word to map.
1110 * @return {string} The index.
1111 * @private
1112 */
1113 goog.ui.AbstractSpellChecker.toInternalKey_ = function(word) {
1114 if (word in Object.prototype) {
1115 return goog.ui.AbstractSpellChecker.KEY_PREFIX_ + word;
1116 }
1117 return word;
1118 };
1119
1120
1121 /**
1122 * Navigate keyboard focus in the given direction.
1123 *
1124 * @param {goog.ui.AbstractSpellChecker.Direction} direction The direction to
1125 * navigate in.
1126 * @return {boolean} Whether the action is handled here. If not handled
1127 * here, the initiating event may be propagated.
1128 * @protected
1129 */
1130 goog.ui.AbstractSpellChecker.prototype.navigate = function(direction) {
1131 var handled = false;
1132 var isMovingToNextWord =
1133 direction == goog.ui.AbstractSpellChecker.Direction.NEXT;
1134 var focusedIndex = this.getFocusedElementIndex();
1135
1136 var el;
1137 do {
1138 // Determine new index based on given direction.
1139 focusedIndex += isMovingToNextWord ? 1 : -1;
1140
1141 if (focusedIndex < 1 || focusedIndex > this.getLastIndex()) {
1142 // Exit the loop, because this focusedIndex cannot have an element.
1143 handled = true;
1144 break;
1145 }
1146
1147 // Word elements are removed during the correction action. If no element is
1148 // found for the new focusedIndex, then try again with the next value.
1149 } while (!(el = this.getElementByIndex(focusedIndex)));
1150
1151 if (el) {
1152 this.setFocusedElementIndex(focusedIndex);
1153 this.focusOnElement(el);
1154 handled = true;
1155 }
1156
1157 return handled;
1158 };
1159
1160
1161 /**
1162 * Returns the index of the currently focussed invalid word element. This index
1163 * starts at one instead of zero.
1164 *
1165 * @return {number} the index of the currently focussed element
1166 * @protected
1167 */
1168 goog.ui.AbstractSpellChecker.prototype.getFocusedElementIndex = function() {
1169 return this.focusedElementIndex_;
1170 };
1171
1172
1173 /**
1174 * Sets the index of the currently focussed invalid word element. This index
1175 * should start at one instead of zero.
1176 *
1177 * @param {number} focusElementIndex the index of the currently focussed element
1178 * @protected
1179 */
1180 goog.ui.AbstractSpellChecker.prototype.setFocusedElementIndex = function(
1181 focusElementIndex) {
1182 this.focusedElementIndex_ = focusElementIndex;
1183 };
1184
1185
1186 /**
1187 * Sets the focus on the provided word element.
1188 *
1189 * @param {Element} element The word element that should receive focus.
1190 * @protected
1191 */
1192 goog.ui.AbstractSpellChecker.prototype.focusOnElement = function(element) {
1193 element.focus();
1194 };
1195
1196
1197 /**
1198 * Constants for representing the direction while navigating.
1199 *
1200 * @enum {number}
1201 */
1202 goog.ui.AbstractSpellChecker.Direction = {
1203 PREVIOUS: 0,
1204 NEXT: 1
1205 };
1206
1207
1208 /**
1209 * Constants for the result of asynchronous processing.
1210 * @enum {number}
1211 */
1212 goog.ui.AbstractSpellChecker.AsyncResult = {
1213 /**
1214 * Caller must reschedule operation and call continueAsyncProcessing on the
1215 * new stack frame.
1216 */
1217 PENDING: 1,
1218 /**
1219 * Current element has been fully processed. Caller can call
1220 * processTextAsync or finishAsyncProcessing.
1221 */
1222 DONE: 2
1223 };