net.rim.blackberry.api.spellcheck
Interface SpellCheckUI

public interface SpellCheckUI

An interface describing an object for spell checking a set of fields, presenting the user a UI for resolving spell checking issues as they are found. A listener can be set to manage the fine details of the spell checking.

An application must only use one instance of this interface. See the comments in SpellCheckEngineFactory.createSpellCheckUI() for details.

Concurrent spell checking by this class is NOT supported. At most one spell check may be in progress at any given time. Attempting to perform more than one spell check will result in undefined behaviour, which may include input system crashes, spurious exceptions being thrown, spell checks interfering with each other, spell checks being unexpectedly cancelled, or others.

The locale used for spell checking by instances of this interface follows the system locale. Therefore, the locale cannot be explicitly set programmatically.

Spell Checking Fields

The following conditions must all be satisfied for a field to be a candidate for spell checking:

1. The field must have some notion of textual contents that are user-editable, such as EditField
2. The field's style, as returned from Field.getStyle(), must not have the Field.NON_SPELLCHECKABLE style set
3. The field must not have a text filter set (see TextField.getFilter())

Since:

BlackBerry API 4.5.0

Field Summary
static int	SPELL_CHECK_CANCELLED Code indicating that spell checking has been cancelled.
static int	SPELL_CHECK_COMPLETE Code indicating that spell checking of a field has completed.
static int	SPELL_CHECK_SPAWNED Code indicating that a built-in spell check dialog has been displayed to the user.
static int	STATE_IN_PROGRESS A spell checking state indicating that the spell check is in progress.
static int	STATE_STOPPED A spell checking state indicating that there is no spell check in progress

Method Summary
void	addSpellCheckUIListener(SpellCheckUIListener listener) Adds a SpellCheckUIListener to this object.
boolean	getShowDialogs() Gets whether informational dialogs about the progress of spell checking should be shown.
int	getState() Gets the spell checking state of this object.
void	removeSpellCheckUIListener(SpellCheckUIListener listener) Removes a SpellCheckUIListener from this object.
void	setShowDialogs(boolean showDialogs) Sets whether informational dialogs about the progress of spell checking should be shown.
int	spellCheck(Enumeration fields) Spell checks a collection of fields.
int	spellCheck(Field field) Spell checks a field.
int	spellCheck(Manager fieldManager) Spell checks the top-level fields of a Manager.

Field Detail

SPELL_CHECK_COMPLETE

static final int SPELL_CHECK_COMPLETE

Code indicating that spell checking of a field has completed.

See Also:

Constant Field Values

Since:

BlackBerry API 4.5.0

SPELL_CHECK_SPAWNED

static final int SPELL_CHECK_SPAWNED

Code indicating that a built-in spell check dialog has been displayed to the user. Typically, this occurs when a misspelled word was found and a UI has been presented to the user to resolve the problem.

See Also:

Constant Field Values

Since:

BlackBerry API 4.5.0

SPELL_CHECK_CANCELLED

static final int SPELL_CHECK_CANCELLED

Code indicating that spell checking has been cancelled. Many things can cause a spell check to be cancelled, including, but not limited to, the following events:

1. The user explicitly cancels a spell check, such as by pressing and holding escape or choosing a "Cancel" menu item
2. The user task-switches to another application
3. The security timer times out, causing the device to lock
4. An incoming phone call occurs
5. The device is holstered

Most events that steal focus from the application cause a spell check to be cancelled.

See Also:

Constant Field Values

Since:

BlackBerry API 4.5.0

STATE_STOPPED

static final int STATE_STOPPED

A spell checking state indicating that there is no spell check in progress

See Also:

Constant Field Values

Since:

BlackBerry API 4.5.0

STATE_IN_PROGRESS

static final int STATE_IN_PROGRESS

A spell checking state indicating that the spell check is in progress.

See Also:

Constant Field Values

Since:

BlackBerry API 4.5.0

Method Detail

spellCheck

int spellCheck(Field field)

Spell checks a field.

The specified field must be on the top-level screen of the calling application. If the field does not belong to a screen, the screen is not displayed, or the screen is not on the top of the display stack then the behaviour of this method is undefined. Note that it is acceptable for the field to be scrolled off the screen, as long as it is on the top-level screen.

This method returns a code that specifies the result of the requested spell checking operation. The possible return values and the cases in which they are returned are in the following list.

• If the system's current locale does not support spell-checking then SpellCheckUI.SPELL_CHECK_COMPLETE is returned; use SpellCheckEngineFactory.getEngine() to determine if the current locale supports spell checking.
• If the field is not spell-checkable (see Spell Checking Fields for details) then SpellCheckUI.SPELL_CHECK_COMPLETE is returned.
• If no misspelled words were found in the specified field then SpellCheckUI.SPELL_CHECK_COMPLETE is returned.
• If a misspelled word was found in the specified field then SpellCheckUI.SPELL_CHECK_SPAWNED is returned and a UI is displayed to the user to resolve the spelling error
• If the spellcheck is cancelled before it is completed or before the first misspelled word is found then SpellCheckUI.SPELL_CHECK_CANCELLED is returned.

WARNING: Concurrent spell checks are NOT supported. It is the responsibility of the application to ensure that only one spell check is in progress at any given time. Performing concurrent spell checks will yield undefined behaviour. To determine if a spell check is currently in progress use SpellCheckUI.getState().

Parameters:

field - the field to spell check

Returns:

one of the SPELL_CHECK_ constants defined in this interface, representing the result of this operation.

Throws:

NullPointerException - if any argument is null.

IllegalStateException - if invoked by a non-event thread.

See Also:

SpellCheckUI.SPELL_CHECK_COMPLETE, SpellCheckUI.SPELL_CHECK_SPAWNED

Since:

BlackBerry API 4.5.0

spellCheck

int spellCheck(Enumeration fields)

Spell checks a collection of fields. Each element of the specified Enumeration must be an instance of Field or a subclass of it. Any elements that fail this test will cause a ClassCastException to be thrown, terminating the spellcheck prematurely and not notifying any listeners.

All specified fields must be on the top-level screen of the calling application. If one of the fields does not belong to a screen, the screen is not displayed, or the screen is not on the top of the display stack then the behaviour of this method is undefined. Note that it is acceptable for a field to be scrolled off the screen, as long as it is on the top-level screen.

Any fields in the specified Enumeration that are not spell-checkable (see Spell Checking Fields for details) will be ignored. Also, any null values returned from the enumeration will be ignored.

The return values and conditions under which they are returned are identical to SpellCheckUI.spellCheck(Field) except that SPELL_CHECK_COMPLETE is only returned after all elements of the enumeration have been visited.

WARNING: Concurrent spell checks are NOT supported. It is the responsibility of the application to ensure that only one spell check is in progress at any given time. Performing concurrent spell checks will yield undefined behaviour. To determine if a spell check is currently in progress use SpellCheckUI.getState().

Parameters:

fields - the enumeration over the fields to spellcheck.

Returns:

one of the SPELL_CHECK_ constants defined in this interface, representing the result of this operation.

Throws:

NullPointerException - if any argument is null.

ClassCastException - if any element of the specified enumeration cannot be casted to Field.

IllegalStateException - if invoked by a non-event thread.

See Also:

SpellCheckUI.SPELL_CHECK_COMPLETE, SpellCheckUI.SPELL_CHECK_SPAWNED

Since:

BlackBerry API 4.5.0

spellCheck

int spellCheck(Manager fieldManager)

Spell checks the top-level fields of a Manager.

The specified manager must be on the top-level screen of the calling application. If it does not belong to a screen, the screen is not displayed, or the screen is not on the top of the display stack then the behaviour of this method is undefined. Note that it is acceptable for the manager to be partially or completely scrolled off the screen, as long as it is on the top-level screen.

Any top-level fields in the specified Manager that are not spell-checkable (see Spell Checking Fields for details) will be ignored.

The return values and conditions under which they are returned are identical to SpellCheckUI.spellCheck(Field) except that SPELL_CHECK_COMPLETE is only returned after all top-level fields have been visited.

WARNING: Concurrent spell checks are NOT supported. It is the responsibility of the application to ensure that only one spell check is in progress at any given time. Performing concurrent spell checks will yield undefined behaviour. To determine if a spell check is currently in progress use SpellCheckUI.getState().

Parameters:

fieldManager - the manager whose top-level fields to spellcheck.

Returns:

one of the SPELL_CHECK_ constants defined in this interface, representing the result of this operation.

Throws:

NullPointerException - if any argument is null.

IllegalStateException - if invoked by a non-event thread.

See Also:

SpellCheckUI.SPELL_CHECK_COMPLETE, SpellCheckUI.SPELL_CHECK_SPAWNED

Since:

BlackBerry API 4.5.0

addSpellCheckUIListener

void addSpellCheckUIListener(SpellCheckUIListener listener)

Adds a SpellCheckUIListener to this object. If the specified listener is already registered as a listener then it will not be added again.

Parameters:

listener - the listener to add.

Throws:

NullPointerException - if listener is null.

See Also:

SpellCheckUI.removeSpellCheckUIListener(net.rim.blackberry.api.spellcheck.SpellCheckUIListener)

Since:

BlackBerry API 4.5.0

removeSpellCheckUIListener

void removeSpellCheckUIListener(SpellCheckUIListener listener)

Removes a SpellCheckUIListener from this object. If the specified listener is not registered as a listener then this method does nothing.

Parameters:

listener - the listener to remove; if null then this method does nothing.

See Also:

SpellCheckUI.addSpellCheckUIListener(net.rim.blackberry.api.spellcheck.SpellCheckUIListener)

Since:

BlackBerry API 4.5.0

getState

int getState()

Gets the spell checking state of this object.

Returns:

SpellCheckUI.STATE_STOPPED if no spell check is in progress or SpellCheckUI.STATE_IN_PROGRESS if a spell check is in progress.

Since:

BlackBerry API 4.5.0

setShowDialogs

void setShowDialogs(boolean showDialogs)

Sets whether informational dialogs about the progress of spell checking should be shown.

The dialogs displayed when enabled may include a "completed" dialog or a "progress" dialog.

This method may be invoked at any time; however, if it is invoked while a spell check is in progress (ie. SpellCheckUI.getState() returns STATE_RUNNING) then the dialogs may not display immediately and may not even display until the next spell check is started. Therefore, it is recommended to invoke this method only when a spell check is not in progress.

Parameters:

showDialogs - if true then show informational dialogs during spell checking; otherwise do not display such dialogs.

See Also:

SpellCheckUI.getShowDialogs()

Since:

BlackBerry API 4.5.0

getShowDialogs

boolean getShowDialogs()

Gets whether informational dialogs about the progress of spell checking should be shown.

The default setting is to show informational dialogs.

Returns:

true if informational dialogs will be shown during spell checking; false otherwise.

See Also:

SpellCheckUI.setShowDialogs(boolean)

Since:

BlackBerry API 4.5.0