10.3. Checking Spelling

KDE contains a spell-checking class called KSpell, which has four spell checking methods:

  • modalCheck()—Spell checks a plain text buffer using a modal spell checker dialog.

  • check()—Spell checks a plain text buffer using a nonmodal spell checker dialog.

  • checkList()—Spell checks a list of words. Useful for checking non-plain text formats, such as HTML, SGML, or internal formats.

  • checkWord()—Spell checks a single word. Useful for implementing "online" (or check-as-you-type) spell checking.

KSpell can use International Ispell (http://fmg-www.cs.ucla.edu/geoff/ispell.html) or ASpell (http://metalab.unc.edu/kevina/aspell/) as a "back end" to check the spelling of words. Dictionaries are available for these programs in 19 languages at http://fmg-www.cs.ucla.edu/geoff/ispell-dictionaries.html.

10.3.1. Using KSpell in an Application

We'll use modalCheck() in this section because it's the simplest method. If you want to include features such as highlighting misspelled words in the user's document as the spell checking proceeds, then you will need to use check(). KEdit, KWrite, and the KMail/KRN composer all use check() so that they can highlight misspelled words.

When using KSpell in an application, you need to offer the user a menu entry to configure the spell checker and one to start it. These menu entries have standard places. The spell checker configuration entry goes in the Options menu, and the entry to start the spell checker goes in Tools and is called "Spelling…".

The following code, Listings 10.7 and 10.8, demonstrates the use of KSpell in an application. This application, KSpellDemo, puts some text in its content area and offers you the option to check the spelling of the text. After the spell check is complete, the corrected text is shown (see Figure 10.3).


Example 10.7. kspelldemo.h: Class Declaration for KSpellDemo, a Simple Application that Uses KSpell

   1 
   2  1: #ifndef __KSPELLDEMO_H__
   3  2: #define __KSPELLDEMO_H__
   4  3:
   5  4: #include <ktmainwindow.h>
   6  5:
   7  6: class QLabel;
   8  7:
   9  8: /**
  10 9:  * KSpellDemo
  11 10:  * Spell check some text with KSpell.
  12 11:  **/
  13 12: class KSpellDemo : public KTMainWindow
  14 13: {
  15 14:  Q_OBJECT
  16 15:  public:
  17 16:   KSpellDemo (const char *name=0);
  18 17:
  19 18:  public slots:
  20 19:   void slotSpellCheck();
  21 20:   void slotConfigure();
  22 21:
  23 22:  protected:
  24 23:   QLabel *label;
  25 24: };
  26 25:
  27 26: #endif
  28 

We derive from KTMainWindow here so that you can add the menubar and toolbar (see Figure 10.3). The two slots, slotSpellCheck() and slotConfigure(), start the spell checker and configure it, respectively.


Example 10.8. kspelldemo.cpp: Class Definition for KSpellDemo

   1 
   2  1: #include <stdio.h>
   3  2:
   4  3: #include <qtabdialog.h>
   5  4:
   6  5: #include <kspell.h>
   7  6: #include <ktmainwindow.h>
   8  7: #include <ksconfig.h>
   9  8: #include <kstdaction.h>
  10  9: #include <kaction.h>
  11 10:
  12 11: #include "kspelldemo.moc"
  13 12:
  14 13: KSpellDemo::KSpellDemo (const char *name=0) :
  15 14:   KTMainWindow (name)
  16 15: {
  17 16:
  18 17:   KAction *spelling = KStdAction::spelling (this, SLOT(slotSpellCheck()),
  19 18:       actionCollection());
  20 19:
  21 20:   new KAction ( "&Configure spellchecker..., 0,
  22 21:         this, SLOT (slotConfigure()), actionCollection(),
  23 22:         "configure_spellchecker" );
  24 23:
  25 24:   createGUI();
  26 25:
  27 26:
  28 27:   label = new QLabel ("Som words are mispelled!", this);
  29 28:   setView (label);
  30 29: }
  31 30:
  32 31: void
  33 32: KSpellDemo::slotSpellCheck()
  34 33: {
  35 34:   QString text (label->text());
  36 35:
  37 36:   KSpell::modalCheck (text);
  38 37:   label->setText (text);
  39 38:}
  40 39:
  41 40: void
  42 41: KSpellDemo::slotConfigure()
  43 42: {
  44 43:   QTabDialog qtabdialog (0, 0, true);
  45 44:   qtabdialog.setCancelButton();
  46 45:   KSpellConfig ksconfig (&qtabdialog);
  47 46:   qtabdialog.addTab (&ksconfig, "&Spellchecker");
  48 47:   if (qtabdialog.exec())
  49 48:     ksconfig.writeGlobalSettings();
  50 49: }
  51 


Figure 10.3. KSpellDemo shows some misspelled text.


In the constructor, you put the Spelling… and Configure spellchecker… entries in their appropriate places and also put a spell checker button on the toolbar (see lines 17–24 The layout of the user interface is described in the XML GUI file kspelldemoui.rc included on the web site. Be sure to copy this file to its appropriate directory before running KSpellDemo: $KDEDIR/share/apps/kspelldemo/.

10.3.2. Modal Spell Checking

In slotSpellCheck(), you use the method modalCheck(). Checking spelling this way is especially simple because the method is static. You fill a QString, called text here, with the text that needs checking and call


   1 
   2 KSpell::modalCheck (text);
   3 

When the method returns, text contains the spell checked text. Interactive word replacement is handled by KSpell. Figure 10.4 shows the KSpell dialog offering suggested replacements for the misspelled word to the user. This dialog is created and maintained by KSpell.


Figure 10.4. The KSpell dialog box shows the misspelled word and offers suggestions for replacement.


Note

While the spell check proceeds, the user will be able to interact only with the KSpell dialog, but the rest of your GUI will still repaint itself when necessary.

10.3.3. Configuring KSpell

A standard configuration dialog called KSpellConfig is available for use in applications that use KSpell. The dialog lets the user choose which dictionary will be used and which back end client will be used, among other things. Standard code to use KSpellConfig is shown on lines 43–48. A screen shot of the KSpellConfig dialog box is shown in Figure 10.5.


Figure 10.5. The KSpellConfig dialog box lets the user configure KSpell.


If you want to save the KSpell settings, you should call writeGlobalSettings() when the user clicks OK (that is, if qtabdialog.exec() returns true). If not, you will need to pass the instance of KSpellConfig that you just created to a new instance of KSpell so that KSpell knows the new configuration, and then use a method other than modalCheck(). See the KSpell reference documentation for details.

You can use the main() function given in Listing 10.9 to try KSpellDemo. Be sure to link to the library libkspell by passing the option -lkspell to g++.


Example 10.9. main.cpp: A main() Function Suitable for Testing KSpellDemo

   1 
   2  1: #include <kapp.h>
   3  2:
   4  3: #include "kspelldemo.h"
   5  4:
   6  5: int
   7  6: main (int argc, char *argv[])
   8  7: {
   9  8:   KApplication kapplication (argc, argv, "kspelldemo");
  10  9:
  11 10:   KSpellDemo *kspelldemo = new KSpellDemo;
  12 11:
  13 12:   kspelldemo->show();
  14 13:
  15 14:   return kapplication.exec();
  16 15: }
  17