/* This file is part of the KDE libraries
Copyright (C) 1997 David Sweet
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License version 2 as published by the Free Software Foundation.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to
the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
*/
#ifndef __KSPELL_H__
#define __KSPELL_H__
#include "ksconfig.h"
#include
#include
#include
class QTextCodec;
class KProcIO;
class KProcess;
class KSpellDlg;
/**
* KDE Spellchecker
*
* A KDE programmer's interface to International ISpell 3.1. (GPL 1997)
* A static method, @ref modalCheck() is provided for convenient
* access to the spellchecker.
*
* @author David Sweet
* @version $Id: kspell_h.html 149726 2002-04-16 07:39:43Z dfaure $
* @see KSpellConfig
*/
class KSpell : public QObject
{
Q_OBJECT
public:
/**
* Possible states of the spell checker.
*
* @li @p Starting - After creation of KSpell.
* @li @p Running - After the ready signal has been emitted.
* @li @p Cleaning - After @ref cleanUp() has been called.
* @li @p Finished - After @ref cleanUp() has been completed.
*
* The following error states exist:
*
* @li @p Error - An error occurred in the @p Starting state.
* @li @p Crashed - An error occurred in the @p Running state.
**/
enum spellStatus { Starting = 0, Running, Cleaning, Finished, Error, Crashed };
/**
* Starts the spellchecker.
*
* KSpell emits @ref ready() when it has verified that
* ISpell/ASpell is working properly. Pass the name of a slot -- do not pass zero!
* Be sure to call @ref cleanUp() when you are done with KSpell.
*
* If KSpell could not be started correctly, @ref death() is emitted.
*
* @param parent Parent of @ref KSpellConfig dialog..
* @param caption Caption of @ref KSpellConfig dialog.
* @param receiver Receiver object for the ready(KSpell *) signal.
* @param slot Receiver's slot, will be connected to the ready(KSpell *) signal.
* @param kcs Configuration for KSpell.
* @param progressbar Indicates if progress bar should be shown.
* @param modal Indicates modal or non-modal dialog.
*/
KSpell(QWidget *parent, const QString &caption,
QObject *receiver, const char *slot, KSpellConfig *kcs=0,
bool progressbar = TRUE, bool modal = FALSE );
/**
* Returns the status of KSpell.
*
* @see spellStatus()
*/
spellStatus status() const { return m_status; }
/**
* Cleans up ISpell.
*
* Write out the personal dictionary and close ISpell's
* stdin. A @ref death() signal will be emitted when the cleanup is
* complete, but this method will return immediately.
*/
virtual void cleanUp ();
/**
* Sets the auto-delete flag. If this is set, the KSpell object
* is automatically deleted after emitting @ref death().
*/
void setAutoDelete(bool _autoDelete) { autoDelete = _autoDelete; }
/**
* Spellchecks a buffer of many words in plain text
* format.
*
* The @p _buffer is not modified. The signal @ref done() will be
* sent when @ref check() is finished and the argument will be a
* spell-corrected version of @p _buffer.
*
* The spell check may be stopped by the user before the entire buffer
* has been checked. You can check @ref lastPosition() to see how far
* in @p _buffer @ref check() reached before stopping.
*/
virtual bool check (const QString &_buffer, bool usedialog = TRUE);
/**
* Returns the position (when using @ref check()) or word
* number (when using @ref checkList()) of
* the last word checked.
*/
int lastPosition() const
{ return lastpos;}
/**
* Spellchecks a list of words.
*
* @ref checkList() is more flexible than @ref check(). You could parse
* any type
* of document (HTML, TeX, etc.) into a list of spell-checkable words
* and send the list to @ref checkList(). Sending a marked-up document
* to @ref check() would result in the mark-up tags being
* spell checked.
*/
virtual bool checkList (QStringList *_wordlist, bool usedialog = TRUE);
/**
* Spellchecks a single word.
*
* checkWord() is the most flexible function. Some applications
* might need this flexibility but will sacrifice speed when
* checking large numbers of words. Consider @ref checkList() for
* checking many words.
*
* Use this method for implementing "online" spellchecking (i.e.,
* spellcheck as-you-type).
*
* checkWord() returns @p false if @p buffer is not a single word (e.g.
* if it contains white space), otherwise it returns @p true;
*
* If @p usedialog is set to @p true, KSpell will open the standard
* dialog if the word is not found. The dialog results can be queried
* by using @ref dlgResult() and @ref replacement().
*
* The signal @ref corrected() is emitted when the check is
* complete. You can look at @ref suggestions() to see what the
* suggested replacements were.
*/
virtual bool checkWord (const QString &_buffer, bool usedialog = FALSE);
/**
* Hides the dialog box.
*
* You'll need to do this when you are done with @ref checkWord();
*/
void hide ();
/**
* Returns list of suggested word replacements.
*
* After calling @ref checkWord() (an in response to
* a @ref misspelled() signal you can
* use this to get the list of
* suggestions (if any were available).
*/
QStringList suggestions () const { return sugg; }
/**
* Gets the result code of the dialog box.
*
* After calling checkWord, you can use this to get the dialog box's
* result code.
* The possible
* values are (from kspelldlg.h):
* @li KS_CANCEL
* @li KS_REPLACE
* @li KS_REPLACEALL
* @li KS_IGNORE
* @li KS_IGNOREALL
* @li KS_ADD
* @li KS_STOP
*
*/
int dlgResult () const
{ return dlgresult; }
/**
* Moves the dialog.
*
* If the dialog is not currently visible, it will
* be placed at this position when it becomes visible.
* Use this to get the dialog out of the way of a highlighted
* misspelled word in a document.
*/
void moveDlg (int x, int y);
/**
* Returns the height of the dialog box.
*/
int heightDlg () const;
/**
* Returns the width of the dialog box.
*/
int widthDlg () const;
/**
* Returns the partially spellchecked buffer.
*
* You might want the full buffer in its partially-checked state.
*/
QString intermediateBuffer () const {return newbuffer;}
/**
* Tells ISpell/ASpell to ignore this word for the life of this KSpell instance.
*
* @return false if @p word is not a word or there was an error
* communicating with ISpell/ASpell.
*/
virtual bool ignore (const QString & word);
/**
* Adds a word to the user's personal dictionary.
*
* @return false if @p word
* is not a word or there was an error communicating with ISpell/ASpell.
*/
virtual bool addPersonal (const QString & word);
/**
* @return the @ref KSpellConfig object being used by this KSpell instance.
*/
KSpellConfig ksConfig () const;
/**
* Sets the resolution (in percent) of the @ref progress() signals.
*
* E.g. @ref setProgressResolution (10) instructs KSpell to send progress
* signals (at most) every 10% (10%, 20%, 30%...).
* The default is 10%.
*/
void setProgressResolution (unsigned res);
/**
* The destructor instructs ISpell/ASpell to write out the personal
* dictionary and then terminates ISpell/ASpell.
*/
virtual ~KSpell();
/**
* Performs a synchronous spellcheck.
*
* This method does not return until spellchecking is done or canceled.
* Your application's GUI will still be updated, however.
*/
static int modalCheck( QString& text ); // marked as deprecated
/**
* Performs a synchronous spellcheck.
*
* This method does not return until spellchecking is done or canceled.
* Your application's GUI will still be updated, however.
*
* This overloaded method uses the spell-check configuration passed as parameter.
*/
static int modalCheck( QString& text, KSpellConfig * kcs );
/**
* Call @ref setIgnoreUpperWords(true) to tell the spell-checker to ignore
* words that are completely uppercase. They are spell-checked by default.
*/
void setIgnoreUpperWords(bool b);
/**
* Call @ref setIgnoreTitleCase(true) to tell the spell-checker to ignore
* words with a 'title' case, i.e. starting with an uppercase letter.
* They are spell-checked by default.
*/
void setIgnoreTitleCase(bool b);
signals:
/**
* Emitted whenever a misspelled word is found by @ref check() or
* by @ref checkWord().
* If it is emitted by @ref checkWord(), @p pos=0.
* If it is emitted by @ref check(), then @p pos indicates the position of
* the misspelled word in the (original) @p _buffer.
* (The first position is zero.)
* If it is emitted by @ref checkList(), @p pos is the index to
* the misspelled
* word in the @ref QStringList passed to @ref checkList().
* Note, that @p originalword can be only a word part, if it's
* word with hyphens.
*
* These are called _before_ the dialog is opened, so that the
* calling program's GUI may be updated. (e.g. the misspelled word may
* be highlighted).
*/
void misspelling (const QString & originalword, const QStringList & suggestions,
unsigned int pos);
/**
* Emitted after the "Replace" or "Replace All" buttons of the dialog
* was pressed, or if the word was
* corrected without calling the dialog (i.e., the user previously chose
* "Replace All" for this word).
*
* Results from the dialog may be checked with @ref dlgResult()
* and @ref replacement().
*
* Note, that when using @ref checkList() this signal can occur
* more then once with same list position, when checking a word with
* hyphens. In this case @p originalword is the last replacement.
*
* @see check()
*/
void corrected (const QString & originalword, const QString & newword, unsigned int pos);
/**
* Emitted when the user pressed "Ignore All" in the dialog.
* This could be used to make an application or file specific
* user dictionary.
*
*/
void ignoreall (const QString & originalword);
/**
* Emitted when the user pressed "Ignore" in the dialog.
* Don't know if this could be useful.
*
*/
void ignoreword (const QString & originalword);
/**
* Emitted when the user pressed "Add" in the dialog.
* This could be used to make an external user dictionary
* independent of the ISpell personal dictionary.
*
*/
void addword (const QString & originalword);
/**
* Emitted after KSpell has verified that ISpell/ASpell is running
* and working properly.
*/
void ready(KSpell *);
/**
* Emitted during a @ref check().
* @p i is between 1 and 100.
*/
void progress (unsigned int i);
/**
* Emitted when @ref check() is done.
*
* Be sure to copy the results of @p buffer if you need them.
* You can only rely
* on the contents of buffer for the life of the slot which was signaled
* by @ref done().
*/
void done (const QString &buffer);
/**
* Emitted when @ref checkList() is done.
*
* If the argument is
* @p true, then you should update your text from the
* wordlist, otherwise not.
*/
void done(bool);
/**
* Emitted on terminal errors and after clean up.
*
* You can delete the KSpell object in this signal.
*
* You can check @ref status() to see what caused the death:
* @li @p Error - KSpell could not start.
* @li @p Crashed - KSpell encountered an unexpected error during execution.
* @li @p Finished - Clean up finished.
*/
void death( );
protected slots:
/* All of those signals from KProcIO get sent here. */
void KSpell2 (KProcIO *);
void checkWord2 (KProcIO *);
void checkWord3 ();
void check2 (KProcIO *);
void checkList2 ();
void checkList3a (KProcIO *);
void checkListReplaceCurrent ();
void checkList4 ();
void dialog2 (int dlgresult);
void check3 ();
void slotStopCancel (int);
void ispellExit (KProcess *);
void emitDeath();
void ispellErrors (KProcess *, char *, int);
private slots:
/**
* Used for @ref modalCheck().
*/
void slotModalReady();
/**
* Used for @ref modalCheck().
*/
void slotModalDone( const QString & );
/**
* Used for @ref modalCheck().
*/
void slotSpellCheckerCorrected( const QString & oldText, const QString & newText, unsigned int );
/**
* Used for @ref modalCheck().
*/
void slotModalSpellCheckerFinished( );
signals:
void dialog3 ();
protected:
KProcIO *proc;
QWidget *parent;
KSpellConfig *ksconfig;
KSpellDlg *ksdlg;
QStringList *wordlist;
QStringList::Iterator wlIt;
QStringList ignorelist;
QStringList replacelist;
QStringList sugg;
QTextCodec* codec;
spellStatus m_status;
bool usedialog;
bool texmode;
bool dlgon;
bool personaldict;
bool dialogwillprocess;
bool progressbar;
bool dialogsetup;
bool autoDelete;
QString caption;
QString orig;
QString origbuffer;
QString newbuffer;
QString cwword;
QString dlgorigword;
QString dlgreplacement;
QString dialog3slot;
int dlgresult;
int trystart;
int maxtrystart;
unsigned int lastpos;
unsigned int totalpos;
unsigned int lastline;
unsigned int posinline;
unsigned int lastlastline;
unsigned int offset;
unsigned int progres;
unsigned int curprog;
/**
* Used for @ref #modalCheck.
*/
bool modaldlg;
static QString modaltext;
static int modalreturn;
static QWidget* modalWidgetHack;
static QStringList modalListText;
int parseOneResponse (const QString &_buffer, QString &word, QStringList &sugg);
QString funnyWord (const QString & word);
void dialog (const QString & word, QStringList & sugg, const char* _slot);
QString replacement () const
{ return dlgreplacement; }
void setUpDialog ( bool reallyusedialogbox = TRUE);
void emitProgress ();
bool cleanFputs (const QString & s, bool appendCR=TRUE);
bool cleanFputsWord (const QString & s, bool appendCR=TRUE);
void startIspell();
bool writePersonalDictionary ();
private:
class KSpellPrivate;
KSpellPrivate *d;
};
/**
* @libdoc Spelling Checker Library
*
* @ref KSpell offers easy access to International ISpell or ASpell
* (at the user's option) as well as a spell-checker GUI
* ("Add", "Replace", etc.).
*
* You can use @ref KSpell to
* automatically spell-check an ASCII file as well as to implement
* online spell-checking and to spell-check proprietary format and
* marked up (e.g. HTML, TeX) documents. The relevant methods for
* these three procedures are @ref check(), @ref checkWord(), and
* @ref checkList(), respectively.
*
* @ref KSpellConfig holds configuration information about @ref KSpell as well
* as acting as an options-setting dialog.
*
* KSpell usually works asynchronously. If you do not need that, you should
* simply use @ref KSpell::modalCheck(). It won't return until the
* passed string is processed or the spell checking canceled.
* During modal spell checking your GUI is still repainted, but the user may
* only interact with the @ref KSpell dialog.
*
* @see KSpell, KSpellConfig
**/
#endif
| Generated by: dfaure on faure on Tue Apr 16 08:51:00 2002, using kdoc 2.0a53. |