The first step is to create an instance of SpellChecker.

This is performed directly. The simplest constructor has one argument, which is a "dictpath", the name of a directory where dictionaries are installed.

For a discussion of the dictionary storage conventions, see the "Dictionary Management" section below.

String dictPath = ... // application-dependent
SpellChecker checker = new SpellChecker( dictPath );

Then it is possible to set a number of options: see the 'Options' section for more details.

It is important to set the current language: setSelectedLanguage(languageCode) performs this task. Available languages can be obtained by listLanguages().

Something useful is the load and save path for the personal dictionaries (There is a distinct personal dictionary for each language). This is probably application and system-dependent.

String path = homeDir + File.separatorChar 
                      + "myapp_spell" + File.separatorChar + "%L%" ;
checker.setPersonalDictionaryPath( path );

Actually the path set is a pattern that has to contain a marker for the language name. The marker for the language name is "%L%", as it can be seen in the example above.

Then we come to the spell-checking main loop. The model we use is very simple and attempts to make as few hypotheses as possible about the client application.

The actual implementation of your text is abstracted by an interface called CharSequence (the same as in the JRE 1.4).

The Spell Checker accepts a piece of text so a CharSequence) through SpellChecker.setInput(...), then checkNext() is invoked.

CharSequence myInput = ... // get from your application
checker.setInput( myInput );
int err = checker.checkNext();

If checkNext() returns ERR_NONE, the piece of text set as input is correct, and the application has to proceed on the next piece of text or to finish.

Processing the errors returned by checkNext():

Notes about setInput() and the checking loop:

The character sequence set with setInput() is assumed to stay unmodified by the application until checkNext() reaches its end. Depending on the implementation, this can often be unrealistic if a replacement is performed. Therefore:

A skeleton of the search loop:

Note: The text source (here mySource) typically implements the TextSource interface defined in package com.xmlmind.spellcheck.ui.

   void doSearch() {
       for(;;) 
       {
            ... // prepare 
            // acquire next fragment from application:
            input = mySource.getText(checker.getCharChecker());
            if (input == null) {
                ... // no more input
                return;
            }
            checker.setInput(input);
            int err = checker.checkNext();
            if (err == SpellChecker.ERR_NONE) {
                // end reached: update position in source
                ...
                continue;
            }
            String failingWord = checker.getWord();
            int replacePos = checker.getPosition();
            int replaceSize = failingWord_.length();
            // application dependent:
            mySource.highlight(replacePos, replaceSize);

            switch(err) {
            case SpellChecker.ERR_DUPLICATE:
                showStatus("duplicate word: " + failingWord);
                break;
            case SpellChecker.ERR_REPLACE:
                mySource.replace(replacePos, replaceSize,
                                 checker.getReplacement(failingWord));
                continue;
            case SpellChecker.ERR_WRONG_CAP:
                showSuggestions("word should be capitalized");
                break;
            case SpellChecker.ERR_PUNCTUATION:
                showSuggestions("punctuation problem");
                break;
            case SpellChecker.ERR_UNKNOWN_WORD:
                showSuggestions("unrecognized word");
                break;
            }
            // get and process user commands:
            break;
       }
   }

Displaying suggestions:

The interface Suggestions returned by SpellChecker.getSuggestions() provides methods to retrieve suggestions individually: getSuggestion(int index) or as an array: String[] Suggestions.toArray().

Suggestions are ordered by decreasing pertinence and their number is given by Suggestions.getCount().

The maximum number of returned suggestions can be set by setSuggestionLimit.

Example:

String[] suggestions = checker.getSuggestions().toArray();
JList displayList = new JList(suggestions);
if (suggestions.length > 0)
    displayList.setSelectedIndex(0);

Smarter suggestions:

There is a mechanism to teach the SpellChecker to make better suggestions. When a word entered by a user to correct an erroneous word is not among the first suggestions found, it is possible to invoke learnSuggestion() with the wrong word and its correction as arguments: the next time this word is encountered, the learned suggestion will be put atop the suggestion list.

void doReplace() {
    String correction = ...; // get correction from user
    // if not among the 3 first , learn it:
    if (!suggestions.contain( correction, 3 ))
        checker.learnSuggestion( failingWord, correction, 
                                 SpellChecker.TEMPORARY_DICT );
    ...
}

In this example, the learned suggestion is put into the temporary dictionary, therefore lost at the end of the session. It is also possible to put it in the persistent personal dictionary (SpellChecker.PERSONAL_DICT).