In order to popup the Spell Checker dialog in your Swing Text Component, you need only to import the com.xmlmind.spellcheck.ui.JSpellDialog class, then place the following code in the implementation of your "spell-check" command (for example a menu item, or a tool-bar button):

JSpellDialog.check( textComponent, language )

where textComponent is a Swing Text component (an object inheriting JTextComponent), and language is the short name of a dictionary or language (in the standard distribution: "en", "fr", "de" or a country variant "en-US", "fr-CA", etc). It can be null (the previous dictionary is then used). By default, "en" is used.

Note that this assumes a standard installation of the dictionaries (typically in a directory dicts/ located at the same place as the SDK's jar, xsc.jar, or in a Dictionary Archive .dar similar to a Jar file and placed in the CLASSPATH).

Also referred to in literature as "Continuous", "On the fly", "Real Time",etc, spell-checking, this feature marks erroneous words with red underlining during normal edition, without the need to invoke a Spell Checker dialog.

It is very easily activated (typically just after the document is loaded into the text component):

JSpellDialog.enableAutoCheck( textComponent, language )

The textComponent and language parameters have the same meaning as before.

It is safe to invoke this method twice on the same component (for example to change the dictionary).

To deactivate the feature (typically when the document is closed), call:

JSpellDialog.disableAutoCheck( myTextComponent )

When an erroneous word is underlined, the user expects to be able to right-click on it to display a popup menu which will allow her/him to fix the spelling error. In order to achieve that, include the following code snippet in your application.

textComponent.addMouseListener(new MouseAdapter() {
    public void mousePressed(MouseEvent e) {
        showAutoCheckMenu(e);
    }

    public void mouseReleased(MouseEvent e) { 
        showAutoCheckMenu(e);
    }

    private void showAutoCheckMenu(MouseEvent e) {
        if (e.isPopupTrigger())
            JSpellDialog.showAutoCheckMenu(textComponent, 
                                           e.getX(), e.getY());
    }
});

The following API (which returns a boolean) can be used to test if it makes sense to display the spell-checking popup menu in the current context and for the specified location.

JSpellDialog.canShowAutoCheckMenu( textComponent, mouseClickX, mouseClickY )

This API is useful

The static convenience methods described above use a static JSpellDialog object.

If this is a problem, it is possible to instantiate one's own JSpellDialog, for example like this:.

JSpellDialog dialog = 
    new JSpellDialog( myFrame, myTextComponent, null, language );
// ... 
dialog.popup(true);

For fine control of the Spell Checker, it is generally necessary to get the JSpellComponent contained in the JSpellDialog, and then use its methods.

JSpellComponent implements the actual spell-checking interaction, it is a component embeddable in any Swing user interface. JSpellDialog simply embeds it in a Swing dialog. To know more about JSpellComponent, please see its Java documentation.

JSpellComponent has an associated option dialog (JSpellOptions).

The XSpell sample application (source code found in samples/xspell/src/XSpell.java) shows an example of use of the GUI package. It also defines and uses different text parsers to create styled documents from common text formats (Javadoc comments, HTML, etc)

To make the Spell Checker work on text sources different than JTextComponent, the recommended way is to create an adapter that implements the interface com.xmlmind.spellcheck.ui.TextSource. Then JSpellDialog can be used with this adapter.

If one is not satisfied with this scheme, it is necessary to work directly with the Core Engine (see following section).

There are additional classes in com.xmlmind.spellcheck.ui that provide a framework and sample code for parsing miscellaneous text formats: TextParser is an abstract class, and MLParser an implementation that can read XML/HTML/SGML or other XML-like markup formats. An example of utilization of these classes is provided in samples/mlscan/MLScan.java.