com.jivesoftware.spark.component.spelling
Class BackgroundChecker

java.lang.Object
  com.jivesoftware.spark.component.spelling.BackgroundChecker

All Implemented Interfaces:

javax.swing.event.CaretListener, javax.swing.event.DocumentListener, java.util.EventListener

public class BackgroundChecker

extends java.lang.Object

implements javax.swing.event.DocumentListener, javax.swing.event.CaretListener

Monitor JTextComponents in the background for misspelled words. This class is part of the Sentry Java SDK examples.

By default, misspelled words are indicated to the user by a red zigzag underline. The color of the underline is customizable; the type of highlighting can be changed by providing an alternate HighlightPainter. Misspelled words are un-highlighted as they are corrected. BackgroundChecker also supports a popup menu that contains suggested replacements for misspelled words plus, optionally, "Ignore All" and "Add" items.

To monitor a JTextComponent for spelling errors, call the BackgroundChecker constructor and pass the component to be monitored. Note that the BackgroundChecker object must remain in scope as long as the monitored JTextComponent remains in scope. Background checking can be temporarily turned off by calling the stop method, and restarted via the resume method.

To display a popup menu over a misspelled word, catch awt.event.MouseEvents. When MouseEvent.isPopupTrigger returns true, call BackgroundChecker.isInMisspelledWord to determine if the popup menu was requested over a misspelled word. If so, call createPopupMenu to generate a popup menu appropriate for the misspelled word.

Nested Class Summary

protected class

BackgroundChecker.ZigZagHighlightPainter HighlightPainter that underlines highlighted text with a zig-zag line.

Field Summary

protected boolean	busy True if we're processing an event.
protected int	caretPos The current caret position.
protected javax.swing.text.JTextComponent	component The text component being monitored.
boolean	debug Set to true to enable diagnostics.
protected javax.swing.text.Highlighter.HighlightPainter	highlightPainter Painter used to highlight misspelled words.
protected java.util.Vector	misspelledWords Collection of misspelled words detected in the text component.
protected com.wintertree.ssce.PropSpellingSession	sentry Sentry spelling session used to check spelling.
protected com.wintertree.ssce.EditableLexicon	userDictionary The user dictionary words will be added to when the Add Word action is performed.

Constructor Summary

BackgroundChecker(javax.swing.text.JTextComponent component, com.wintertree.ssce.PropSpellingSession sentry)
Construct a BackgroundChecker to begin monitoring a text component.

BackgroundChecker(javax.swing.text.JTextComponent component, com.wintertree.ssce.PropSpellingSession sentry, javax.swing.text.Highlighter.HighlightPainter highlightPainter)
Construct a BackgroundChecker to begin monitoring a text component.

Method Summary

void	addMisspelledWord(java.lang.String word, int offset) Indicate that a word in the text component's text is misspelled.
void	caretUpdate(javax.swing.event.CaretEvent ev) Catch events relating to change in caret position in the monitored text component.
void	changedUpdate(javax.swing.event.DocumentEvent junk) Required by the DocumentListener interface.
boolean	checkWord(java.lang.String word, int offset) Check the spelling of a word at a given offset in the text componet's text.
javax.swing.JPopupMenu	createPopupMenu(int x, int y, int maxSuggestions, java.lang.String ignoreAllLabel, java.lang.String addLabel, java.lang.String noSuggestionsLabel) Create a popup menu containing items related to the word under a specified point.
boolean	fillPopupMenu(javax.swing.JPopupMenu menu, int x, int y, int maxSuggestions, java.lang.String ignoreAllLabel, java.lang.String addLabel, java.lang.String noSuggestionsLabel) Populate a popup menu with items related to the word under a specified point.
protected com.jivesoftware.spark.component.spelling.BackgroundChecker.MisspelledWord	findMisspelledWord(int offset) Locate a misspelled word with which a specified offset intersects.
protected com.jivesoftware.spark.component.spelling.BackgroundChecker.MisspelledWord	findMisspelledWord(int start, int end) Locate a misspelled word which intersects with specified start and end offsets.
protected int	getWordAt(int offset, java.lang.StringBuffer word) Obtain the word in the text component's text at a given offset.
java.awt.Color	getZigZagColor() Obtain the color used to mark misspelled words if the default zig-zag highlight painter is used.
void	insertUpdate(javax.swing.event.DocumentEvent ev) Catch events reporting text insertion in the text component.
protected boolean	isInMisspelledWord(int offset) Determine if an offset is within a known misspelled word.
protected boolean	isInMisspelledWord(int start, int end) Determine if a range is within a known misspelled word.
boolean	isInMisspelledWord(java.awt.Point pt) Determine if a specified point is within a misspelled word.
protected boolean	isInWord(int x, int y) Determine if a specified point is within a word in the text component.
protected boolean	isWordChar(char c) Determine if a character can be part of a word.
protected void	onInsertText(int offset, int nChars) Respond to insertion of multiple characters in the text component.
void	recheckAll() Check or recheck the contents of the text component.
protected void	recheckAll(java.lang.String word) Recheck all occurrences of a given word.
void	removeMisspelledWord(int offset) Indicate that a word considered to be misspelled is not misspelled.
void	removeUpdate(javax.swing.event.DocumentEvent ev) Catch events reporting text deletion in the text component.
void	resume() Resume monitoring the text component after monitoring was stopped via the stop() method.
void	setUserDictionary(com.wintertree.ssce.EditableLexicon lex) Specify which lexicon words should be added to when the Add Word action is performed.
void	setZigZagColor(java.awt.Color c) Change the color used to underline misspelled words.
void	stop() Stop monitoring the text component.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

busy

protected boolean busy

True if we're processing an event. Sometimes the steps needed to respond to an event cause other events which causes infinite recursion. This switch prevents that.

component

protected javax.swing.text.JTextComponent component

The text component being monitored.

caretPos

protected int caretPos

The current caret position. At the time a CaretEvent occurs, this will contain the previous caret position.

misspelledWords

protected java.util.Vector misspelledWords

Collection of misspelled words detected in the text component.

debug

public boolean debug

Set to true to enable diagnostics.

highlightPainter

protected javax.swing.text.Highlighter.HighlightPainter highlightPainter

Painter used to highlight misspelled words.

sentry

protected com.wintertree.ssce.PropSpellingSession sentry

Sentry spelling session used to check spelling.

userDictionary

protected com.wintertree.ssce.EditableLexicon userDictionary

The user dictionary words will be added to when the Add Word action is performed.

Constructor Detail

BackgroundChecker

public BackgroundChecker(javax.swing.text.JTextComponent component,
                         com.wintertree.ssce.PropSpellingSession sentry,
                         javax.swing.text.Highlighter.HighlightPainter highlightPainter)

Construct a BackgroundChecker to begin monitoring a text component.

Parameters:

component - The JTextComponent to monitor

sentry - The spelling session to use when checking spelling

highlightPainter - The painter used to highlight misspelled words. If null, an internal highlight painter which draws red zig-zag lines below misspelled words is used. Method setZigZagColor can be used to change the color of the zig-zag line.

BackgroundChecker

public BackgroundChecker(javax.swing.text.JTextComponent component,
                         com.wintertree.ssce.PropSpellingSession sentry)

Construct a BackgroundChecker to begin monitoring a text component. Misspelled words will be underlined with a red zig-zag line; the zig-zag line color can be changed via the setZigZagColor method.

Parameters:

component - The JTextComponent to monitor

sentry - The spelling session to use when checking spelling

Method Detail

addMisspelledWord

public void addMisspelledWord(java.lang.String word,
                              int offset)
                       throws javax.swing.text.BadLocationException

Indicate that a word in the text component's text is misspelled. The word is highlighted. If the word is already known to be misspelled, it is updated if necessary (e.g., it may have been edited). If the user subsequently edits the word, or even if the caret passes through it, the word's spelling status will be re-evaluated.

Parameters:

word - The misspelled word

offset - Offset of the misspelled word in the text.

Throws:

javax.swing.text.BadLocationException - The supplied offset is outside the range of text contained by the text component.

caretUpdate

public void caretUpdate(javax.swing.event.CaretEvent ev)

Catch events relating to change in caret position in the monitored text component.

Specified by:

caretUpdate in interface javax.swing.event.CaretListener

Parameters:

ev - Information about the event.

changedUpdate

public void changedUpdate(javax.swing.event.DocumentEvent junk)

Required by the DocumentListener interface.

Specified by:

changedUpdate in interface javax.swing.event.DocumentListener

Parameters:

junk - Not used.

checkWord

public boolean checkWord(java.lang.String word,
                         int offset)

Check the spelling of a word at a given offset in the text componet's text. If the word is misspelled, highlight it in the text component. If the word is not misspelled but the word at the specified offset had previously been highlighted (i.e., was misspelled but has now been corrected, or should no longer be considered misspelled), then the highlighting is removed.

Parameters:

word - The word to check

offset - Offset of the word in the text component's text.

Returns:

true if the word is misspelled; false otherwise.

createPopupMenu

public javax.swing.JPopupMenu createPopupMenu(int x,
                                              int y,
                                              int maxSuggestions,
                                              java.lang.String ignoreAllLabel,
                                              java.lang.String addLabel,
                                              java.lang.String noSuggestionsLabel)

Create a popup menu containing items related to the word under a specified point. The menu will contain suggested replacements for the word and an "Ignore all" item. If the userDictionary property is non-null, the menu will also contain an "Add" item.

Selecting a suggested replacement invokes a ReplaceWordAction. Selecting the "Ignore All" item invokes an IgnoreAllAction. Selecting the "Add" item invokes an AddWordAction.

If the specified point is not over a word, null is returned.

Note that this method creates a popup menu whether the indicated word is misspelled or not. Use the isInMisspelledWord method to determine if the point is contained within a misspelled word.

Parameters:

x - The x coordinate of a point within the word.

y - The y coordinate of a point within the word.

maxSuggestions - The maximum number of suggested replacement words to display in the menu.

ignoreAllLabel - The text to associate with the Ignore All action (typically "Ignore All"). If null, the Ignore All item will not appear in the menu.

addLabel - The text to associate with the Add Word action (typically "Add"). If null, the Add item will not appear in the menu. The Add item will also not appear in the menu if the userDictionary property is null.

noSuggestionsLabel - The text to place in a disabled menu item if no suggestions could be found for the word (typically "(No suggestions"). If null, no suggestion items will be added to the popup menu if no suggestions could be found.

Returns:

A popup menu populated as described above, or null if the specified point is not over a word.

fillPopupMenu

public boolean fillPopupMenu(javax.swing.JPopupMenu menu,
                             int x,
                             int y,
                             int maxSuggestions,
                             java.lang.String ignoreAllLabel,
                             java.lang.String addLabel,
                             java.lang.String noSuggestionsLabel)

Populate a popup menu with items related to the word under a specified point. Items will be added contain suggested replacements for the word and an "Ignore all" item. If the userDictionary property is non-null, the menu will also contain an "Add" item.

Selecting a suggested replacement invokes a ReplaceWordAction. Selecting the "Ignore All" item invokes an IgnoreAllAction. Selecting the "Add" item invokes an AddWordAction.

If the specified point is not over a word, no items are added to the menu. In this situation, false is returned.

Note that this method adds items to the popup menu whether the indicated word is misspelled or not. Use the isInMisspelledWord method to determine if the point is contained within a misspelled word.

Parameters:

menu - The popup menu to populate.

x - The x coordinate of a point within the word.

y - The y coordinate of a point within the word.

maxSuggestions - The maximum number of suggested replacement words to display in the menu.

ignoreAllLabel - The text to associate with the Ignore All action (typically "Ignore All"). If null, the Ignore All item will not appear in the menu.

addLabel - The text to associated with the Add Word action (typically "Add"). If null, the Add item will not appear in the menu. The Add item will also not appear in the menu if the userDictionary property is null.

noSuggestionsLabel - The text to place in a disabled menu item if no suggestions could be found for the word (typically "(No suggestions"). If null, no suggestion items will be added to the popup menu if no suggestions could be found.

Returns:

True if the indicated point is over a word; false if not.

getZigZagColor

public java.awt.Color getZigZagColor()

Obtain the color used to mark misspelled words if the default zig-zag highlight painter is used. Note that this method does nothing useful if other highlight painters are used.

Returns:

The color used to draw zig-zag lines under misspelled words.

insertUpdate

public void insertUpdate(javax.swing.event.DocumentEvent ev)

Catch events reporting text insertion in the text component.

Specified by:

insertUpdate in interface javax.swing.event.DocumentListener

Parameters:

ev - Information about the event.

isInMisspelledWord

public boolean isInMisspelledWord(java.awt.Point pt)

Determine if a specified point is within a misspelled word.

Parameters:

pt - The point to test.

Returns:

True if the given point is within a misspelled word; false otherwise.

recheckAll

public void recheckAll()

Check or recheck the contents of the text component. Any misspelled words found are highlighted, and any highlighted words which are no longer considered misspelled (e.g., because they have been added to a lexicon) are un-highlighted. This method might be called after the contents of the component are loaded from a file, for example.

removeMisspelledWord

public void removeMisspelledWord(int offset)

Indicate that a word considered to be misspelled is not misspelled. If the word was not considered misspelled, nothing happens.

Parameters:

offset - Offset of the word in the text.

removeUpdate

public void removeUpdate(javax.swing.event.DocumentEvent ev)

Catch events reporting text deletion in the text component.

Specified by:

removeUpdate in interface javax.swing.event.DocumentListener

Parameters:

ev - Information about the event.

resume

public void resume()

Resume monitoring the text component after monitoring was stopped via the stop() method.

setUserDictionary

public void setUserDictionary(com.wintertree.ssce.EditableLexicon lex)

Specify which lexicon words should be added to when the Add Word action is performed. Adding of words can be disabled by setting the user dictionary to null.

Parameters:

lex - The user dictionary words will be added to. If null, adding of words will be disabled.

setZigZagColor

public void setZigZagColor(java.awt.Color c)

Change the color used to underline misspelled words. Note that this method has effect only if the internal (default) highlight painter is used.

Parameters:

c - The color to use when drawing zig-zag lines below misspelled words.

stop

public void stop()

Stop monitoring the text component. To resume monitoring, call the resume() method.

findMisspelledWord

protected com.jivesoftware.spark.component.spelling.BackgroundChecker.MisspelledWord findMisspelledWord(int start,
                                                                                                        int end)

Locate a misspelled word which intersects with specified start and end offsets.

Parameters:

start - The offset of the beginning of the range from the start of the text component's text.

end - The offset of the end of the range from the start of the text component's text.

Returns:

The misspelled word which intersects with the range, or null if no word was found.

findMisspelledWord

protected com.jivesoftware.spark.component.spelling.BackgroundChecker.MisspelledWord findMisspelledWord(int offset)

Locate a misspelled word with which a specified offset intersects.

Parameters:

offset - The offset from the beginning of the text component's text where the misspelled word is located.

Returns:

The misspelled word which covers the offset, or null if no word was found.

getWordAt

protected int getWordAt(int offset,
                        java.lang.StringBuffer word)

Obtain the word in the text component's text at a given offset. The offset may point to the first character of the word or any character within the word.

Parameters:

offset - The offset in the text component's text where the word should be located.

word - The word obtained from the text.

Returns:

>= 0: The offset of the first character of the word, if a word word was found; < 0: No word was found at the specified offset.

isInMisspelledWord

protected boolean isInMisspelledWord(int start,
                                     int end)

Determine if a range is within a known misspelled word.

Parameters:

start - The offset of the beginning of the range from the start of the text component's text.

end - The offset of the end of the range from the start of the text component's text.

Returns:

True if the range intersects with a known misspelled word; false otherwise.

isInMisspelledWord

protected boolean isInMisspelledWord(int offset)

Determine if an offset is within a known misspelled word.

Parameters:

offset - The offset to test from the start of the text component's text.

Returns:

True if the offset is within a known misspelled word; false otherwise.

isInWord

protected boolean isInWord(int x,
                           int y)

Determine if a specified point is within a word in the text component.

Parameters:

x - The x coordinate to test.

y - The y coordinate to test.

Returns:

True if the point is within a word; false if the point is over whitespace, punctuation, or is outside the bounds of the component's text.

isWordChar

protected boolean isWordChar(char c)

Determine if a character can be part of a word.

Parameters:

c - The character to test.

Returns:

True if the character can be part of a word.

onInsertText

protected void onInsertText(int offset,
                            int nChars)

Respond to insertion of multiple characters in the text component. Any misspelled words in the inserted text are highlighted.

Parameters:

offset - The offset of the first character inserted from the start of text in the component.

nChars - The number of characters inserted.

recheckAll

protected void recheckAll(java.lang.String word)

Recheck all occurrences of a given word. If the word was highlighted but is no longer considered misspelled (e.g., it has since been added to a lexicon) it will be un-highlighted. Similarly, if the word had been considered corrected but has since been removed from a lexicon, it will be highlighted.

Parameters:

word - The word to recheck.