net.rim.blackberry.api.spellcheck
Interface SpellCheckUIListener

All Known Implementing Classes:

AbstractSpellCheckUIListener

public interface SpellCheckUIListener

A listener for events on a SpellCheckUI. The listener can be used for as little as determining when each field is spell checked and as much as determining corrections to misspelled words.

Note that all method invocations will be made on the event thread of the calling application.

Getting Text From a Field

Several methods in this interface will be specified a Field, offset, and length indicating the substring of the field's text to which the method is referring. The way that the offset and length are used varies depending on the type of field.

The table below shows the various types of fields and the method to use to get the substring referred to by the offset and length. Fields not present in the list below will not be spell checked by this API.

Field Type	Method to Get Text
TextField	getText(int, int)

Performing UI Operations in Listener Methods

It is currently not supported to perform UI operations in any listener method callbacks. Doing so will yield undefined behaviour as it interferes with the spell checking user interface. Examples of forbidden operations include pushing a screen onto the display stack, modifying the fields displayed on the screen, or adding a new field to the screen.

Since:

BlackBerry API 4.5.0

Field Summary
static int	ACTION_ADD_TO_DICTIONARY An action code to indicate that the current misspelled word should be treated as correctly spelled and added to the list of correctly spelled words.
static int	ACTION_CANCEL An action code to indicate that the spell checking session should be cancelled.
static int	ACTION_CHANGED An action code to indicate that the current misspelled word has been fixed.
static int	ACTION_IGNORE_ALL An action code to indicate that the current misspelled word should be be skipped.
static int	ACTION_IGNORE_ONCE An action code to indicate that the current misspelled word should be be skipped.
static int	ACTION_OPEN_UI An action code to indicate that a screen should be presented to the user with a list of suggested corrections to the given misspelled word.
static int	LEARNING_ACCEPT A code to indicate that the given word learning should be accepted
static int	LEARNING_REJECT A code to indicate that the given word learning should be rejected
static int	REASON_HOLSTERED The user holstered the device during spell checking, cancelling the spell checking of a field.
static int	REASON_LOCKED The device entered Security Lock during spell checking, cancelling the spell checking of a field.
static int	REASON_UNKNOWN Used to indicate that the reason for the cancellation of the spell checking is unknown.
static int	REASON_USER_CANCELLED The user cancelled the spell checking.

Method Summary
boolean	generatedSpellingCandidates(SpellCheckUI ui, Field field, int offset, int len, StringBuffer suggestions) Invoked after candidates for a misspelling have been generated.
boolean	generatingSpellingCandidates(SpellCheckUI ui, Field field, int offset, int len, StringBuffer suggestions) Invoked when candidates for a misspelling are about to be generated.
int	misspelledWordFound(SpellCheckUI ui, Field field, int offset, int len) Invoked when a misspelled word has been found.
int	repeatedWordsFound(SpellCheckUI ui, Field field, int offset, int len) Invoked when a pair of consecutive identical words has been found.
void	spellCheckCompleted(SpellCheckUI ui, Field field, int status, int reason) Invoked when the spell checking for a Field has completed.
boolean	spellCheckStarted(SpellCheckUI ui, Field field) Invoked just before spell checking a Field.
int	wordCorrectionLearned(SpellCheckUI ui, StringBuffer word, StringBuffer correction) Invoked when a correction to a word has been learned via the UI.
int	wordIgnored(SpellCheckUI ui, StringBuffer word, boolean ignoreAll) Invoked when a word has been ignored via the UI.
int	wordLearned(SpellCheckUI ui, StringBuffer word) Invoked when a word has been learned via the UI.

Field Detail

REASON_UNKNOWN

static final int REASON_UNKNOWN

Used to indicate that the reason for the cancellation of the spell checking is unknown.

See Also:

SpellCheckUIListener.spellCheckCompleted(net.rim.blackberry.api.spellcheck.SpellCheckUI, net.rim.device.api.ui.Field, int, int), Constant Field Values

Since:

BlackBerry API 4.5.0

REASON_USER_CANCELLED

static final int REASON_USER_CANCELLED

The user cancelled the spell checking.

See Also:

SpellCheckUIListener.spellCheckCompleted(net.rim.blackberry.api.spellcheck.SpellCheckUI, net.rim.device.api.ui.Field, int, int), Constant Field Values

Since:

BlackBerry API 4.5.0

REASON_HOLSTERED

static final int REASON_HOLSTERED

The user holstered the device during spell checking, cancelling the spell checking of a field.

See Also:

SpellCheckUIListener.spellCheckCompleted(net.rim.blackberry.api.spellcheck.SpellCheckUI, net.rim.device.api.ui.Field, int, int), Constant Field Values

Since:

BlackBerry API 4.5.0

REASON_LOCKED

static final int REASON_LOCKED

The device entered Security Lock during spell checking, cancelling the spell checking of a field.

See Also:

SpellCheckUIListener.spellCheckCompleted(net.rim.blackberry.api.spellcheck.SpellCheckUI, net.rim.device.api.ui.Field, int, int), Constant Field Values

Since:

BlackBerry API 4.5.0

ACTION_OPEN_UI

static final int ACTION_OPEN_UI

An action code to indicate that a screen should be presented to the user with a list of suggested corrections to the given misspelled word.

See Also:

SpellCheckUIListener.misspelledWordFound(net.rim.blackberry.api.spellcheck.SpellCheckUI, net.rim.device.api.ui.Field, int, int), Constant Field Values

Since:

BlackBerry API 4.5.0

ACTION_ADD_TO_DICTIONARY

static final int ACTION_ADD_TO_DICTIONARY

An action code to indicate that the current misspelled word should be treated as correctly spelled and added to the list of correctly spelled words.

See Also:

SpellCheckUIListener.misspelledWordFound(net.rim.blackberry.api.spellcheck.SpellCheckUI, net.rim.device.api.ui.Field, int, int), Constant Field Values

Since:

BlackBerry API 4.5.0

ACTION_IGNORE_ONCE

static final int ACTION_IGNORE_ONCE

An action code to indicate that the current misspelled word should be be skipped.

See Also:

SpellCheckUIListener.misspelledWordFound(net.rim.blackberry.api.spellcheck.SpellCheckUI, net.rim.device.api.ui.Field, int, int), Constant Field Values

Since:

BlackBerry API 4.5.0

ACTION_IGNORE_ALL

static final int ACTION_IGNORE_ALL

An action code to indicate that the current misspelled word should be be skipped. Any future encounters with the word in the current spell checking session should also be skipped.

See Also:

SpellCheckUIListener.misspelledWordFound(net.rim.blackberry.api.spellcheck.SpellCheckUI, net.rim.device.api.ui.Field, int, int), Constant Field Values

Since:

BlackBerry API 4.5.0

ACTION_CHANGED

static final int ACTION_CHANGED

An action code to indicate that the current misspelled word has been fixed.

See Also:

SpellCheckUIListener.misspelledWordFound(net.rim.blackberry.api.spellcheck.SpellCheckUI, net.rim.device.api.ui.Field, int, int), Constant Field Values

Since:

BlackBerry API 4.5.0

ACTION_CANCEL

static final int ACTION_CANCEL

An action code to indicate that the spell checking session should be cancelled.

See Also:

SpellCheckUIListener.misspelledWordFound(net.rim.blackberry.api.spellcheck.SpellCheckUI, net.rim.device.api.ui.Field, int, int), Constant Field Values

Since:

BlackBerry API 4.5.0

LEARNING_ACCEPT

static final int LEARNING_ACCEPT

A code to indicate that the given word learning should be accepted

See Also:

SpellCheckUIListener.wordLearned(net.rim.blackberry.api.spellcheck.SpellCheckUI, java.lang.StringBuffer), SpellCheckUIListener.wordCorrectionLearned(net.rim.blackberry.api.spellcheck.SpellCheckUI, java.lang.StringBuffer, java.lang.StringBuffer), Constant Field Values

Since:

BlackBerry API 4.5.0

LEARNING_REJECT

static final int LEARNING_REJECT

A code to indicate that the given word learning should be rejected

See Also:

SpellCheckUIListener.wordLearned(net.rim.blackberry.api.spellcheck.SpellCheckUI, java.lang.StringBuffer), SpellCheckUIListener.wordCorrectionLearned(net.rim.blackberry.api.spellcheck.SpellCheckUI, java.lang.StringBuffer, java.lang.StringBuffer), Constant Field Values

Since:

BlackBerry API 4.5.0

Method Detail

spellCheckStarted

boolean spellCheckStarted(SpellCheckUI ui,
                          Field field)

Invoked just before spell checking a Field. This can be used to skip spell checking of a particular field by returning false.

Parameters:

ui - the SpellCheckUI that caused this method invocation.

field - the field about to be spell checked.

Returns:

true to proceed with spell checking of the field; otherwise false to skip spell checking of the field.

Since:

BlackBerry API 4.5.0

spellCheckCompleted

void spellCheckCompleted(SpellCheckUI ui,
                         Field field,
                         int status,
                         int reason)

Invoked when the spell checking for a Field has completed.

The status parameter will contain information about how the completion occurred. A value of SpellCheckUI.SPELL_CHECK_COMPLETE indicates that spell checking of the field completed normally. A value of SpellCheckUI.SPELL_CHECK_CANCELLED indicates that spell checking did not complete normally; the reason for the abnormal termination will be specified in the reason parameter.

The reason parameter contains additional information about an abnormal spellcheck termination. Therefore, if status==SPELL_CHECK_COMPLETE then the value of this parameter is undefined. However, if status==SPELL_CHECK_CANCELLED then the value of this parameter will be one of the REASON_ constants defined in this interface that identifies the reason that the spell checking of the specified field terminated abnormally.

Parameters:

ui - the SpellCheckUI that caused this method invocation.

field - the field that was spell checked.

status - the result of the spell checking of the field.

reason - the reason for abnormal completion when spell checking the field.

See Also:

SpellCheckUIListener.REASON_UNKNOWN, SpellCheckUIListener.REASON_USER_CANCELLED, SpellCheckUIListener.REASON_HOLSTERED, SpellCheckUIListener.REASON_LOCKED

Since:

BlackBerry API 4.5.0

misspelledWordFound

int misspelledWordFound(SpellCheckUI ui,
                        Field field,
                        int offset,
                        int len)

Invoked when a misspelled word has been found.

The returned action can be one of

1. SpellCheckUIListener.ACTION_OPEN_UI
2. SpellCheckUIListener.ACTION_ADD_TO_DICTIONARY
3. SpellCheckUIListener.ACTION_IGNORE_ONCE
4. SpellCheckUIListener.ACTION_IGNORE_ALL
5. SpellCheckUIListener.ACTION_CHANGED
6. SpellCheckUIListener.ACTION_CANCEL

To get the misspelled word from the field see Getting Text From a Field.

Parameters:

ui - the SpellCheckUI that caused this method invocation.

field - the field whose text contains the the misspelled word.

offset - the offset of the misspelled word in the field.

len - the length of the misspelled word.

Returns:

the action to take; returning any value other than the above-listed valid return values will cause undefined behaviour in the spellcheck engine.

Since:

BlackBerry API 4.5.0

repeatedWordsFound

int repeatedWordsFound(SpellCheckUI ui,
                       Field field,
                       int offset,
                       int len)

Invoked when a pair of consecutive identical words has been found. This is normally considered to be a spelling error.

The returned action can be one of

1. SpellCheckUIListener.ACTION_OPEN_UI
2. SpellCheckUIListener.ACTION_IGNORE_ONCE
3. SpellCheckUIListener.ACTION_CHANGED
4. SpellCheckUIListener.ACTION_CANCEL

To get the text containing the repeated words from the field see Getting Text From a Field.

Parameters:

ui - the SpellCheckUI that caused this method invocation.

field - the field whose text contains the the repeated word.

offset - the offset of the first character of the first of the two repeated words in the field.

len - the length of the text containing the two repeated words.

Returns:

the action to take; returning any value other than the above-listed valid return values will cause undefined behaviour in the spellcheck engine.

Since:

BlackBerry API 4.5.0

generatingSpellingCandidates

boolean generatingSpellingCandidates(SpellCheckUI ui,
                                     Field field,
                                     int offset,
                                     int len,
                                     StringBuffer suggestions)

Invoked when candidates for a misspelling are about to be generated. This callback can be used to override the candidate generation process.

If true is returned the spelling candidates added to the suggestions parameter will be the spelling candidates. Candidates must be separated by the null character '\000'.

To get the text from the field that is being spell checked see Getting Text From a Field. Note: The StringBuffer instance passed as an argument to this method may be re-used for other purposes after this method returns.

Parameters:

ui - the SpellCheckUI that caused this method invocation.

field - the field whose text contains the the misspelled word.

offset - the offset of the misspelled word in the field.

len - the length of the misspelled word.

suggestions - container for storing spelling suggestions provided by this method; the first suggestion must be appended without prepending the null character but subsequent spelling suggestions must be separated from the previous suggestions with the null character.

Returns:

true if suggestions generated by this method are to be used as the list of suggestions; false otherwise.

Since:

BlackBerry API 4.5.0

generatedSpellingCandidates

boolean generatedSpellingCandidates(SpellCheckUI ui,
                                    Field field,
                                    int offset,
                                    int len,
                                    StringBuffer suggestions)

Invoked after candidates for a misspelling have been generated. This callback can be used to add, remove, modify, or reorder the list of spelling suggestions to be presented to the user.

If true is returned the modified list of spelling suggestions will be presented to the user. Candidates must be separated by the null character '\000'.

To get the text from the field that is being spell checked see Getting Text From a Field. Note: The StringBuffer instance passed as an argument to this method may be re-used for other purposes after this method returns.

Parameters:

ui - the SpellCheckUI that caused this method invocation.

field - the field whose text contains the the misspelled word.

offset - the offset of the misspelled word in the field.

len - the length of the misspelled word.

suggestions - the list of suggestions about to be presented to the user, separated by the null character.

Returns:

true if the modified list of suggestions is to be used as the list of suggestions; false to discard any changes made by this method to the list of suggestions.

Since:

BlackBerry API 4.5.0

wordIgnored

int wordIgnored(SpellCheckUI ui,
                StringBuffer word,
                boolean ignoreAll)

Invoked when a word has been ignored via the UI. For example, upon being presented a list of suggestions for the misspelled word the user has chosen to simply skip to the next misspelled word. The return value is currently ignored but may be used in the future to allow some action to be taken. Note: The StringBuffer instance passed as an argument to this method may be re-used for other purposes after this method returns.

Parameters:

ui - the SpellCheckUI that caused this method invocation.

word - the misspelled word

Returns:

the action to take, currently ignored.

Since:

BlackBerry API 4.5.0

wordLearned

int wordLearned(SpellCheckUI ui,
                StringBuffer word)

Invoked when a word has been learned via the UI. The return value can be used to either accept or reject the learning. Rejecting the correction will not stop the UI from going on to the next word but it will stop the word from being added to the custom word list. Note: The StringBuffer instance passed as an argument to this method may be re-used for other purposes after this method returns.

Parameters:

ui - the SpellCheckUI that caused this method invocation.

word - the learned word

Returns:

SpellCheckUIListener.LEARNING_ACCEPT to accept the learning and add the word to the custom word list or SpellCheckUIListener.LEARNING_REJECT to reject the learning and not add the word to the custom word list; returning any other value will cause undefined behaviour in the spellcheck engine.

Since:

BlackBerry API 4.5.0

wordCorrectionLearned

int wordCorrectionLearned(SpellCheckUI ui,
                          StringBuffer word,
                          StringBuffer correction)

Invoked when a correction to a word has been learned via the UI. The return value can be used to either accept or reject the learned correction. Rejecting the correction will not stop the substitution of the correction. Note: The StringBuffer instances passed as arguments to this method may be re-used for other purposes after this method returns.

Parameters:

ui - the SpellCheckUI that caused this method invocation.

word - the misspelled word

correction - the learned correction to the misspelled word

Returns:

SpellCheckUIListener.LEARNING_ACCEPT to accept the learned word correction or SpellCheckUIListener.LEARNING_REJECT to reject the learned correction; returning any other value will cause undefined behaviour in the spellcheck engine.

Since:

BlackBerry API 4.5.0