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:
JDE 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_CANCELLED

public 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.
Since:
JDE 4.5.0

SPELL_CHECK_COMPLETE

public static final int SPELL_CHECK_COMPLETE
Code indicating that spell checking of a field has completed.
Since:
JDE 4.5.0

SPELL_CHECK_SPAWNED

public 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.
Since:
JDE 4.5.0

STATE_IN_PROGRESS

public static final int STATE_IN_PROGRESS
A spell checking state indicating that the spell check is in progress.
Since:
JDE 4.5.0

STATE_STOPPED

public static final int STATE_STOPPED
A spell checking state indicating that there is no spell check in progress
Since:
JDE 4.5.0
Method Detail

addSpellCheckUIListener

public 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.
Since:
JDE 4.5.0
See Also:
removeSpellCheckUIListener(net.rim.blackberry.api.spellcheck.SpellCheckUIListener)

getShowDialogs

public 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.
Since:
JDE 4.5.0
See Also:
setShowDialogs(boolean)

getState

public int getState()
Gets the spell checking state of this object.
Returns:
STATE_STOPPED if no spell check is in progress or STATE_IN_PROGRESS if a spell check is in progress.
Since:
JDE 4.5.0

removeSpellCheckUIListener

public 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.
Since:
JDE 4.5.0
See Also:
addSpellCheckUIListener(net.rim.blackberry.api.spellcheck.SpellCheckUIListener)

setShowDialogs

public 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. 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.
Since:
JDE 4.5.0
See Also:
getShowDialogs()

spellCheck

public 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 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 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.
Since:
JDE 4.5.0
See Also:
SPELL_CHECK_COMPLETE, SPELL_CHECK_SPAWNED

spellCheck

public 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.

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 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.
Since:
JDE 4.5.0
See Also:
SPELL_CHECK_COMPLETE, SPELL_CHECK_SPAWNED

spellCheck

public 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 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 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.
Since:
JDE 4.5.0
See Also:
SPELL_CHECK_COMPLETE, SPELL_CHECK_SPAWNED



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.