1/* This file is part of the KDE libraries
2 Copyright (C) 2002 Carsten Pfeiffer <pfeiffer@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18*/
19
20#ifndef KTEXTEDIT_H
21#define KTEXTEDIT_H
22
23#include <kdeui_export.h>
24#include <sonnet/highlighter.h>
25#include <QtGui/QTextEdit>
26
27#define HAVE_SHOWTABACTION 1
28#define HAVE_AUTOCORRECTFEATURE 1
29#define HAVE_FORCESPELLCHECKING 1
30#define HAVE_MOUSEPOPUPMENUIMPLEMENTATION 1
31/**
32 * This interface is a workaround to keep binary compatibility in KDE4, because
33 * adding the virtual keyword to functions is not BC.
34 *
35 * Call KTextEdit::setSpellInterface() to set this interface to a KTextEdit,
36 * and some functions of KTextEdit will delegate their calls to this interface
37 * instead, which provides a way for derived classes to modifiy the behavior
38 * or those functions.
39 *
40 * @since 4.2
41 *
42 * TODO: Get rid of this class in KDE5 and add the methods to KTextEdit instead,
43 * by making them virtual there.
44 */
45class KTextEditSpellInterface
46{
47 public:
48
49 /**
50 * @return true if spellchecking for the text edit is enabled.
51 */
52 virtual bool isSpellCheckingEnabled() const = 0;
53
54 /**
55 * Sets whether to enable spellchecking for the KTextEdit.
56 * @param enable true if spellchecking should be enabled, false otherwise
57 */
58 virtual void setSpellCheckingEnabled(bool enable) = 0;
59
60 /**
61 * Returns true if the given paragraph or block should be spellcheck.
62 * For example, a mail client does not want to check quoted text, and
63 * would return false here (by checking whether the block starts with a
64 * quote sign).
65 */
66 virtual bool shouldBlockBeSpellChecked(const QString& block) const = 0;
67
68 virtual ~KTextEditSpellInterface() {}
69};
70
71/**
72 * @short A KDE'ified QTextEdit
73 *
74 * This is just a little subclass of QTextEdit, implementing
75 * some standard KDE features, like cursor auto-hiding, configurable
76 * wheelscrolling (fast-scroll or zoom), spell checking and deleting of entire
77 * words with Ctrl-Backspace or Ctrl-Delete.
78 *
79 * This text edit provides two ways of spell checking: background checking,
80 * which will mark incorrectly spelled words red, and a spell check dialog,
81 * which lets the user check and correct all incorrectly spelled words.
82 *
83 * Basic rule: whenever you want to use QTextEdit, use KTextEdit!
84 *
85 * \image html ktextedit.png "KDE Text Edit Widget"
86 *
87 * @see QTextEdit
88 * @author Carsten Pfeiffer <pfeiffer@kde.org>
89 */
90class KDEUI_EXPORT KTextEdit : public QTextEdit //krazy:exclude=qclasses
91{
92 Q_OBJECT
93 Q_PROPERTY( QString clickMessage READ clickMessage WRITE setClickMessage )
94 Q_PROPERTY( bool checkSpellingEnabled READ checkSpellingEnabled WRITE setCheckSpellingEnabled )
95 Q_PROPERTY( QString spellCheckingLanguage READ spellCheckingLanguage WRITE setSpellCheckingLanguage )
96
97 public:
98 /**
99 * Constructs a KTextEdit object. See QTextEdit::QTextEdit
100 * for details.
101 */
102 explicit KTextEdit( const QString& text, QWidget *parent = 0 );
103
104 /**
105 * Constructs a KTextEdit object. See QTextEdit::QTextEdit
106 * for details.
107 */
108 explicit KTextEdit( QWidget *parent = 0 );
109
110 /**
111 * Destroys the KTextEdit object.
112 */
113 ~KTextEdit();
114
115 /**
116 * Reimplemented to set a proper "deactivated" background color.
117 */
118 virtual void setReadOnly( bool readOnly );
119
120 /**
121 * Turns background spell checking for this text edit on or off.
122 * Note that spell checking is only available in read-writable KTextEdits.
123 *
124 * Enabling spell checking will set back the current highlighter to the one
125 * returned by createHighlighter().
126 *
127 * If a spell interface is set by setSpellInterface(),
128 * the call will be delegated to there instead.
129 *
130 * @see checkSpellingEnabled()
131 * @see isReadOnly()
132 * @see setReadOnly()
133 */
134 void setCheckSpellingEnabled( bool check );
135
136 /**
137 * Returns true if background spell checking is enabled for this text edit.
138 * Note that it even returns true if this is a read-only KTextEdit,
139 * where spell checking is actually disabled.
140 * By default spell checking is disabled.
141 *
142 * If a spell interface is set by setSpellInterface(),
143 * the call will be delegated to there instead.
144 *
145 * @see setCheckSpellingEnabled()
146 */
147 bool checkSpellingEnabled() const;
148
149 /**
150 * Selects the characters at the specified position. Any previous
151 * selection will be lost. The cursor is moved to the first character
152 * of the new selection.
153 *
154 * @param length The length of the selection, in number of characters
155 * @param pos The position of the first character of the selection
156 */
157 void highlightWord( int length, int pos );
158
159 /**
160 * Allows to override the config file where the settings for spell checking,
161 * like the current language or encoding, are stored.
162 * By default, the global config file (kdeglobals) is used, to share
163 * spell check settings between all applications.
164 *
165 * This has to be called before any spell checking is initiated.
166 *
167 * @param fileName the URL of the config file which will be used to
168 * read spell settings
169 * @bug this has no effect for the spell dialog, only for the background
170 * check
171 */
172 void setSpellCheckingConfigFileName(const QString &fileName);
173
174 /**
175 * Allows to create a specific highlighter if reimplemented.
176 *
177 * By default, it creates a normal highlighter, based on the config
178 * file given to setSpellCheckingConfigFileName().
179 *
180 * This highlighter is set each time spell checking is toggled on by
181 * calling setCheckSpellingEnabled(), but can later be overridden by calling
182 * setHighlighter().
183 *
184 * @see setHighlighter()
185 * @see highlighter()
186 * @see setSpellCheckingConfigFileName()
187 */
188 virtual void createHighlighter();
189
190 /**
191 * Returns the current highlighter, which is 0 if spell checking is disabled.
192 * The default highlighter is the one created by createHighlighter(), but
193 * might be overridden by setHighlighter().
194 *
195 * @see setHighlighter()
196 * @see createHighlighter()
197 */
198 Sonnet::Highlighter* highlighter() const;
199
200 /**
201 * Sets a custom backgound spell highlighter for this text edit.
202 * Normally, the highlighter returned by createHighlighter() will be
203 * used to detect and highlight incorrectly spelled words, but this
204 * function allows to set a custom highlighter.
205 *
206 * This has to be called after enabling spell checking with
207 * setCheckSpellingEnabled(), otherwise it has no effect.
208 *
209 * @see highlighter()
210 * @see createHighlighter()
211 * @param highLighter the new highlighter which will be used now
212 */
213 void setHighlighter(Sonnet::Highlighter *_highLighter);
214
215 /**
216 * Return standard KTextEdit popupMenu
217 * @since 4.1
218 */
219 QMenu *mousePopupMenu();
220
221 /**
222 * Enable find replace action.
223 * @since 4.1
224 */
225 void enableFindReplace( bool enabled);
226
227 /**
228 * Sets the spell interface, which is used to delegate certain function
229 * calls to the interface.
230 * This is a workaround for binary compatibility and should be removed in
231 * KDE5.
232 *
233 * @since 4.2
234 */
235 void setSpellInterface( KTextEditSpellInterface *spellInterface );
236
237 /**
238 * @return the spell checking language which was set by
239 * setSpellCheckingLanguage(), the spellcheck dialog or the spellcheck
240 * config dialog, or an empty string if that has never been called.
241 * @since 4.2
242 */
243 const QString& spellCheckingLanguage() const;
244
245 /**
246 * This makes the text edit display a grayed-out hinting text as long as
247 * the user didn't enter any text. It is often used as indication about
248 * the purpose of the text edit.
249 * @since 4.4
250 */
251 void setClickMessage(const QString &msg);
252
253 /**
254 * @return the message set with setClickMessage
255 * @since 4.4
256 */
257 QString clickMessage() const;
258
259
260 /**
261 * @since 4.10
262 */
263 void showTabAction(bool show);
264
265 /**
266 * @since 4.10
267 */
268 void showAutoCorrectButton(bool show);
269
270 /**
271 * @since 4.10
272 * create a modal spellcheck dialogbox and spellCheckingFinished signal we sent when
273 * we finish spell checking or spellCheckingCanceled signal when we cancel spell checking
274 */
275 void forceSpellChecking();
276
277 Q_SIGNALS:
278 /**
279 * emit signal when we activate or not autospellchecking
280 *
281 * @since 4.1
282 */
283 void checkSpellingChanged( bool );
284
285 /**
286 * Signal sends when spell checking is finished/stopped/completed
287 * @since 4.1
288 */
289 void spellCheckStatus(const QString &);
290
291 /**
292 * Emitted when the user changes the language in the spellcheck dialog
293 * shown by checkSpelling() or when calling setSpellCheckingLanguage().
294 *
295 * @param language the new language the user selected
296 * @since 4.1
297 */
298 void languageChanged(const QString &language);
299
300 /**
301 * Emitted before the context menu is displayed.
302 *
303 * The signal allows you to add your own entries into the
304 * the context menu that is created on demand.
305 *
306 * NOTE: Do not store the pointer to the QMenu
307 * provided through since it is created and deleted
308 * on demand.
309 *
310 * @param p the context menu about to be displayed
311 * @since 4.5
312 */
313 void aboutToShowContextMenu(QMenu* menu);
314
315 /**
316 * @since 4.10
317 */
318 void spellCheckerAutoCorrect(const QString& currentWord, const QString& autoCorrectWord);
319
320 /**
321 * signal spellCheckingFinished is sent when we finish spell check or we click on "Terminate" button in sonnet dialogbox
322 * @since 4.10
323 */
324 void spellCheckingFinished();
325
326 /**
327 * signal spellCheckingCanceled is sent when we cancel spell checking.
328 * @since 4.10
329 */
330 void spellCheckingCanceled();
331
332 public Q_SLOTS:
333
334 /**
335 * Set the spell check language which will be used for highlighting spelling
336 * mistakes and for the spellcheck dialog.
337 * The languageChanged() signal will be emitted when the new language is
338 * different from the old one.
339 *
340 * @since 4.1
341 */
342 void setSpellCheckingLanguage(const QString &language);
343
344 /**
345 * Show a dialog to check the spelling. The spellCheckStatus() signal
346 * will be emitted when the spell checking dialog is closed.
347 */
348 void checkSpelling();
349
350 /**
351 * Opens a Sonnet::ConfigDialog for this text edit. The config settings the
352 * user makes are read from and stored to the given config file.
353 * The spellcheck language of the config dialog is set to the current spellcheck
354 * language of the textedit. If the user changes the language in that dialog,
355 * the languageChanged() signal is emitted.
356 *
357 * @param configFileName The file which is used to store and load the config
358 * settings
359 * @param windowIcon the icon which is used for the titlebar of the spell dialog
360 * window. Can be empty, then no icon is set.
361 *
362 * @since 4.2
363 */
364 void showSpellConfigDialog(const QString &configFileName,
365 const QString &windowIcon = QString());
366
367 /**
368 * Create replace dialogbox
369 * @since 4.1
370 */
371 void replace();
372
373
374 /**
375 * @since 4.10
376 * Because of binary compatibility constraints, mousePopupMenu()
377 * is not virtual. Therefore it must dynamically detect and call this slot.
378 */
379 void mousePopupMenuImplementation(const QPoint& pos);
380
381 protected Q_SLOTS:
382 /**
383 * @since 4.1
384 */
385 void slotDoReplace();
386 void slotReplaceNext();
387 void slotDoFind();
388 void slotFind();
389 void slotFindNext();
390 void slotReplace();
391 /**
392 * @since 4.3
393 */
394 void slotSpeakText();
395
396 protected:
397 /**
398 * Reimplemented to catch "delete word" shortcut events.
399 */
400 virtual bool event(QEvent*);
401
402 /**
403 * Reimplemented to paint clickMessage.
404 */
405 virtual void paintEvent(QPaintEvent *);
406 virtual void focusOutEvent(QFocusEvent *);
407
408 /**
409 * Reimplemented for internal reasons
410 */
411 virtual void keyPressEvent( QKeyEvent* );
412
413 /**
414 * Reimplemented to instantiate a KDictSpellingHighlighter, if
415 * spellchecking is enabled.
416 */
417 virtual void focusInEvent( QFocusEvent* );
418
419 /**
420 * Reimplemented to allow fast-wheelscrolling with Ctrl-Wheel
421 * or zoom.
422 */
423 virtual void wheelEvent( QWheelEvent* );
424
425 /**
426 * Deletes a word backwards from the current cursor position,
427 * if available.
428 */
429 virtual void deleteWordBack();
430
431 /**
432 * Deletes a word forwards from the current cursor position,
433 * if available.
434 */
435 virtual void deleteWordForward();
436
437 /**
438 * Reimplemented from QTextEdit to add spelling related items
439 * when appropriate.
440 */
441 virtual void contextMenuEvent( QContextMenuEvent* );
442
443 // TODO: KDE5: get rid of these as soon as BIC changes are allowed, they
444 // should be folded back into the normal public version, which
445 // should be made virtual.
446 // These methods just provide a way for derived classes to call
447 // the base class version of the normal methods.
448
449 /**
450 * Enable or disable the spellchecking. This is what setCheckSpellingEnabled()
451 * calls if there is no spell interface.
452 * @since 4.2
453 */
454 void setCheckSpellingEnabledInternal(bool check);
455
456 /**
457 * Checks whether spellchecking is enabled or disabled. This is what
458 * checkSpellingEnabled calls if there is no spell interface.
459 * @since 4.2
460 */
461 bool checkSpellingEnabledInternal() const;
462
463 private:
464 class Private;
465 Private *const d;
466
467 Q_PRIVATE_SLOT( d, void spellCheckerMisspelling( const QString&, int ) )
468 Q_PRIVATE_SLOT( d, void spellCheckerCorrected(const QString&, int,const QString&) )
469 Q_PRIVATE_SLOT( d, void spellCheckerCanceled())
470 Q_PRIVATE_SLOT( d, void spellCheckerAutoCorrect(const QString&,const QString&) )
471 Q_PRIVATE_SLOT( d, void spellCheckerFinished() )
472 Q_PRIVATE_SLOT( d, void undoableClear() )
473 Q_PRIVATE_SLOT( d, void toggleAutoSpellCheck() )
474 Q_PRIVATE_SLOT( d, void slotAllowTab() )
475 Q_PRIVATE_SLOT( d, void menuActivated( QAction* ) )
476 Q_PRIVATE_SLOT( d, void slotFindHighlight(const QString&, int, int))
477 Q_PRIVATE_SLOT( d, void slotReplaceText(const QString &, int, int, int))
478};
479
480#endif // KTEXTEDIT_H
481