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. It is also invoked with a null field when the spell checking for all fields for a particular SpellCheckUI spell check session has been processed.

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. If the field is null then all fields for a particular SpellCheckUI spell check session has been processed.
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





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal