net.rim.blackberry.api.spellcheck
Interface SpellCheckEngine

public interface SpellCheckEngine

Provides spell checking and suggesting services for words. Words are spell checked against two sets of lists. One set is a set of builtin lists that are common to the language associated with the locale associated with this object. These lists cannot be modified by this API. The second set of lists are those that are learned. Words are learned through the use of the spell checking UI and can be explicitly learned using the method SpellCheckEngine.learnWord(java.lang.StringBuffer).

Correction suggestions are determined by looking through the lists of correct words for words that are close to the word in question. A word is considered close to another word if the words are close lexographically or phonetically. The closer a word is to a misspelled word, the higher the word will appear in a list of spelling suggestions for the misspelled word. The builtin lists also track the frequency of the words as they appear in the language. Higher frequency words will be suggested ahead of lower frequency words, sometimes even if the lower frequency word is closer lexographically. If a word has a learned correction then the correction will always appear as the first suggestion.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

Field Summary
	static int	OPTION_IGNORE_ACRONYMS Option to ignore words in all uppercase during spell checking.
	static int	OPTION_IGNORE_ALPHANUMERIC Option to ignore words containing numbers during spell checking.
	static int	OPTION_IGNORE_CASE Option to perform case-insensitive spell checking.
	static int	SOURCE_ADDRESS_BOOK Word Source "Address Book".
	static int	SOURCE_ALL Word Sources "All".
	static int	SOURCE_LEARNED_WORDS Word Source "Learned Words".
	static int	SOURCE_NONE Word Sources "None".

Method Summary
	boolean	getBooleanOption(int option) Gets the value of a boolean option.
	Locale	getLocale() Gets the locale whose language is being used by this object for spell checking.
	int	getSpellingCandidates(StringBuffer word, StringBuffer suggestions) Gets suggested spelling candidates for a word.
	int	getSpellingCandidates(StringBuffer word, Vector suggestions) Gets suggested spelling candidates for a word.
	int	getWordSources() Gets the sources that will be used to look up words for spell checking.
	boolean	isCorrect(StringBuffer word) Checks a word for spelling correctness.
	void	learnCorrection(StringBuffer word, StringBuffer correction) Learn a correction to a word.
	void	learnWord(StringBuffer word) Treat a word as correctly spelled.
	void	setBooleanOption(int option, boolean value) Sets the value of a boolean option.
	void	setWordSources(int sources) Sets the sources that will be used to look up words for spell checking.
	void	unlearnAll() Unlearns all previously learned words and learned corrections.
	void	unlearnWord(StringBuffer word) Unlearns a previously-learned word.

Field Detail

OPTION_IGNORE_CASE

static final int OPTION_IGNORE_CASE

Option to perform case-insensitive spell checking.

See Also:

SpellCheckEngine.setBooleanOption(int, boolean), SpellCheckEngine.getBooleanOption(int), Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

OPTION_IGNORE_ACRONYMS

static final int OPTION_IGNORE_ACRONYMS

Option to ignore words in all uppercase during spell checking. Any words consisting entirely of uppercase characters will never be considered misspelled when this option is set to true.

See Also:

SpellCheckEngine.setBooleanOption(int, boolean), SpellCheckEngine.getBooleanOption(int), Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

OPTION_IGNORE_ALPHANUMERIC

static final int OPTION_IGNORE_ALPHANUMERIC

Option to ignore words containing numbers during spell checking. Any words containing numbers will never be considered misspelled when this option is set to true.

See Also:

SpellCheckEngine.setBooleanOption(int, boolean), SpellCheckEngine.getBooleanOption(int), Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

SOURCE_NONE

static final int SOURCE_NONE

Word Sources "None". This value can be used as a convenience to specify that no word sources except the built-in source should be used.

The value of this constant is zero.

See Also:

SpellCheckEngine.setWordSources(int), SpellCheckEngine.getWordSources(), Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

SOURCE_ADDRESS_BOOK

static final int SOURCE_ADDRESS_BOOK

Word Source "Address Book". This word source is the fields of entries in the BlackBerry Address Book. When this word source is used, words in various fields of address book entries, such as names and addresses, are considered correctly spelled.

See Also:

SpellCheckEngine.setWordSources(int), SpellCheckEngine.getWordSources(), Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

SOURCE_LEARNED_WORDS

static final int SOURCE_LEARNED_WORDS

Word Source "Learned Words". This word source is the set of words that have been learned by the spell checking engine for the applicable locale. If this word source is not used then the learned words are not considered correctly-spelled (unless they are present in another word source that is being used) and will not be candidates for spelling corrections.

See Also:

SpellCheckEngine.setWordSources(int), SpellCheckEngine.getWordSources(), Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

SOURCE_ALL

static final int SOURCE_ALL

Word Sources "All". This value can be used as a convenience to specify that all available word sources should be used.

The value of this constant is ~0.

See Also:

SpellCheckEngine.setWordSources(int), SpellCheckEngine.getWordSources(), Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

Method Detail

getLocale

Locale getLocale()

Gets the locale whose language is being used by this object for spell checking.

Returns:

the locale whose language is being used by this object for spell checking; never returns null.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.6.0

setWordSources

void setWordSources(int sources)

Sets the sources that will be used to look up words for spell checking. The specified sources will be used both for determining if a word is spelled correctly via SpellCheckEngine.isCorrect(java.lang.StringBuffer) and for suggesting corrections via SpellCheckEngine.getSpellingCandidates(java.lang.StringBuffer, java.util.Vector).

The default setting is to use all available word sources.

The SOURCE_ constants defined in this interface are the sources recognized by this method. For convenience, one of SpellCheckEngine.SOURCE_ALL or SpellCheckEngine.SOURCE_NONE can be specified to use all sources or only the built-in source, respectively.

Parameters:

sources - the set of sources to use when spell checking; this value is created by bitwise or-ing the SOURCE_ constants defined in this interface that represent the sources to use when spell checking.

See Also:

SpellCheckEngine.getWordSources()

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

getWordSources

int getWordSources()

Gets the sources that will be used to look up words for spell checking. The specified sources will be used both for determining if a word is spelled correctly and for suggesting corrections.

The default setting is to use all available word sources.

Returns:

the set of sources that will be used when spell checking; this value is created by bitwise or-ing the SOURCE_ constants defined in this interface that represent the sources that will be used when spell checking.

See Also:

SpellCheckEngine.setWordSources(int)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

setBooleanOption

void setBooleanOption(int option,
                      boolean value)

Sets the value of a boolean option.

Parameters:

option - the option to set; valid values are any of the OPTION_ constants defined in this interface. Setting options constants affects both SpellCheckEngine.isCorrect(java.lang.StringBuffer) and SpellCheckEngine.getSpellingCandidates(java.lang.StringBuffer, java.util.Vector) methods. If the current system locale is not supported by the engine then nothing is set.

value - the value to set for the specified option.

Throws:

IllegalArgumentException - if the specified option is not valid, as defined above.

See Also:

SpellCheckEngine.getBooleanOption(int)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

getBooleanOption

boolean getBooleanOption(int option)

Gets the value of a boolean option.

Parameters:

option - the option whose value to get; valid values are any of the OPTION_ constants defined in this interface.

Returns:

the value of the specified option or false if the current system locale is not supported by the engine.

Throws:

IllegalArgumentException - if the specified option is not valid, as defined above.

See Also:

SpellCheckEngine.setBooleanOption(int, boolean)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

isCorrect

boolean isCorrect(StringBuffer word)

Checks a word for spelling correctness. Only words considered correct for the language associated with this object's locale are considered correct. Tailoring of wordlist sources used to determine spelling correctness can be achieved by setting SOURCE_ * constants on an engine. Likewise, applicable word filters can be applied by setting OPTIONS_ * constants on an engine.

Parameters:

word - a StringBuffer containing the word being spell checked; the entire contents of the buffer will be checked; any leading or trailing non-word characters, such as whitespace or symbols, will be considered part of the word and will not be trimmed off when performing the check.

Returns:

true if the specified word is spelled correctly or null; false otherwise. In addition, if the current system locale is not supported by the engine it returns false.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

getSpellingCandidates

int getSpellingCandidates(StringBuffer word,
                          Vector suggestions)

Gets suggested spelling candidates for a word. If the word is correctly spelled the suggestions will contain words that are close to the given word. Only words for the language associated with this object's locale are considered.

Parameters:

word - a StringBuffer containing the word for which suggestions are requested; the entire contents of the buffer will be checked; any leading or trailing non-word characters, such as whitespace or symbols, will be considered part of the word and will not be trimmed off when performing the check.

suggestions - a container for holding the suggestions; each spelling suggestion will be added to this object using Vector.addElement(Object) and will be an instance of String.

Returns:

the number of suggestions added to suggestions or -1 if the current system locale is not supported by the engine.

Throws:

NullPointerException - if any argument is null.

See Also:

SpellCheckEngine.getSpellingCandidates(StringBuffer, StringBuffer)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

getSpellingCandidates

int getSpellingCandidates(StringBuffer word,
                          StringBuffer suggestions)

Gets suggested spelling candidates for a word. If the word is correctly spelled the suggestions will contain words that are close to the given word. Only words for the language associated with this object's locale are considered.

Parameters:

word - a StringBuffer containing the word for which suggestions are requested; the entire contents of the buffer will be checked; any leading or trailing non-word characters, such as whitespace or symbols, will be considered part of the word and will not be trimmed off when performing the check.

suggestions - a StringBuffer for holding the suggestions; each spelling suggestion will be added to this buffer and suggestions will be separated by the null character, '\000'.

Returns:

the number of suggestions added to suggestions or -1 if the current system locale is not supported by the engine.

Throws:

NullPointerException - if any argument is null.

See Also:

SpellCheckEngine.getSpellingCandidates(StringBuffer, Vector)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

learnWord

void learnWord(StringBuffer word)

Treat a word as correctly spelled. The word is only considered learned with respect to the language associated with this object's locale. The learning of this word is persisted so the word is considered correctly spelled by this and any other instances of the spell checker.

If the specified word is already learned then this method does nothing.

Words learned by this method may be unlearned using SpellCheckEngine.unlearnWord(java.lang.StringBuffer) or SpellCheckEngine.unlearnAll(). Note: Words are learned regardless of what SOURCE_ * constants may have been set on the engine.

Parameters:

word - a StringBuffer containing the word to be learned; the entire contents of the buffer will be used; any leading or trailing non-word characters, such as whitespace or symbols, will be considered part of the word and will added to the list of learned words.

Throws:

NullPointerException - if any argument is null.

See Also:

SpellCheckEngine.isCorrect(java.lang.StringBuffer), SpellCheckEngine.unlearnWord(java.lang.StringBuffer)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

unlearnWord

void unlearnWord(StringBuffer word)

Unlearns a previously-learned word. The word will be considered misspelled during subsequent spell checking. Only previously-learned words for the language associated with this object's locale can be unlearned.

If the specified word has never been learned or has already been unlearned then this method does nothing.

This method only unlearns words that were learned by SpellCheckEngine.learnWord(java.lang.StringBuffer). Notably, it does not unlearn corrections that were learned via SpellCheckEngine.learnCorrection(StringBuffer, StringBuffer). To unlearn corrections one must use SpellCheckEngine.unlearnAll(). Note: Words are unlearned regardless of what SOURCE_ * constants may have been set on the engine.

Parameters:

word - a StringBuffer containing the word to be unlearned; the entire contents of the buffer will be used; any leading or trailing non-word characters, such as whitespace or symbols, will be considered part of the word to unlearn.

Throws:

NullPointerException - if any argument is null.

See Also:

SpellCheckEngine.isCorrect(java.lang.StringBuffer), SpellCheckEngine.learnWord(java.lang.StringBuffer), SpellCheckEngine.unlearnAll()

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

learnCorrection

void learnCorrection(StringBuffer word,
                     StringBuffer correction)

Learn a correction to a word. Whenever suggestions are determined for this word, the given correction will always be the first suggestion. The learned correction is persisted and learned only with respect to the language associated with this object's locale. Note: The correction learned via this method will only appear as a spelling candidate iff SpellCheckEngine.getSpellingCandidates(java.lang.StringBuffer, java.util.Vector) is invoked with the exact same word for which the correction was learned. If it is desired for the correction to appear as a spelling candidate for words that are close to the correction, learn the word via SpellCheckEngine.learnWord(java.lang.StringBuffer). Note: corrections are learned regardless of what SOURCE_ * constants may have been set on the engine.

Words learned by this method may be unlearned using SpellCheckEngine.unlearnAll().

Parameters:

word - a StringBuffer containing the misspelled word whose correction to learn; the entire contents of the buffer will be used; any leading or trailing non-word characters, such as whitespace or symbols, will be considered part of the word.

correction - a StringBuffer containing the spelling correction to learn for word; the entire contents of the buffer will be used; any leading or trailing non-word characters, such as whitespace or symbols, will be considered part of the spelling correction.

Throws:

NullPointerException - if any argument is null

See Also:

SpellCheckEngine.isCorrect(java.lang.StringBuffer), SpellCheckEngine.learnWord(java.lang.StringBuffer), SpellCheckEngine.unlearnAll()

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0

unlearnAll

void unlearnAll()

Unlearns all previously learned words and learned corrections. This only affects the language associated with this object's locale. All unlearned words will be considered misspelled during subsequent spell checking. Note: Words are unlearned regardless of what SOURCE_ * constants may have been set on the engine.

See Also:

SpellCheckEngine.isCorrect(java.lang.StringBuffer), SpellCheckEngine.learnCorrection(java.lang.StringBuffer, java.lang.StringBuffer), SpellCheckEngine.learnWord(java.lang.StringBuffer), SpellCheckEngine.unlearnWord(java.lang.StringBuffer)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 4.5.0