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 | */ |
45 | class 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 | */ |
90 | class 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 *(); |
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 (QMenu* ); |
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 (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 ( 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 | |