1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2002 Carsten Pfeiffer <pfeiffer@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KTEXTEDIT_H
9#define KTEXTEDIT_H
10
11#include "ktextwidgets_export.h"
12
13#include <QTextEdit>
14#include <memory>
15#include <sonnet/highlighter.h>
16
17namespace Sonnet
18{
19class SpellCheckDecorator;
20}
21
22class KTextEditPrivate;
23
24/**
25 * @class KTextEdit ktextedit.h <KTextEdit>
26 *
27 * @short A KDE'ified QTextEdit
28 *
29 * This is just a little subclass of QTextEdit, implementing
30 * some standard KDE features, like cursor auto-hiding, configurable
31 * wheelscrolling (fast-scroll or zoom), spell checking and deleting of entire
32 * words with Ctrl-Backspace or Ctrl-Delete.
33 *
34 * This text edit provides two ways of spell checking: background checking,
35 * which will mark incorrectly spelled words red, and a spell check dialog,
36 * which lets the user check and correct all incorrectly spelled words.
37 *
38 * Basic rule: whenever you want to use QTextEdit, use KTextEdit!
39 *
40 * \image html ktextedit.png "KTextEdit Widget"
41 *
42 * @see QTextEdit
43 * @author Carsten Pfeiffer <pfeiffer@kde.org>
44 */
45class KTEXTWIDGETS_EXPORT KTextEdit : public QTextEdit // krazy:exclude=qclasses
46{
47 Q_OBJECT
48 Q_PROPERTY(bool checkSpellingEnabled READ checkSpellingEnabled WRITE setCheckSpellingEnabled)
49 Q_PROPERTY(QString spellCheckingLanguage READ spellCheckingLanguage WRITE setSpellCheckingLanguage)
50
51public:
52 /**
53 * Constructs a KTextEdit object. See QTextEdit::QTextEdit
54 * for details.
55 */
56 explicit KTextEdit(const QString &text, QWidget *parent = nullptr);
57
58 /**
59 * Constructs a KTextEdit object. See QTextEdit::QTextEdit
60 * for details.
61 */
62 explicit KTextEdit(QWidget *parent = nullptr);
63
64 /**
65 * Destroys the KTextEdit object.
66 */
67 ~KTextEdit() override;
68
69 /**
70 * Reimplemented to set a proper "deactivated" background color.
71 */
72 virtual void setReadOnly(bool readOnly);
73
74 /**
75 * Turns background spell checking for this text edit on or off.
76 * Note that spell checking is only available in read-writable KTextEdits.
77 *
78 * Enabling spell checking will set back the current highlighter to the one
79 * returned by createHighlighter().
80 *
81 * @see checkSpellingEnabled()
82 * @see isReadOnly()
83 * @see setReadOnly()
84 */
85 virtual void setCheckSpellingEnabled(bool check);
86
87 /**
88 * Returns true if background spell checking is enabled for this text edit.
89 * Note that it even returns true if this is a read-only KTextEdit,
90 * where spell checking is actually disabled.
91 * By default spell checking is disabled.
92 *
93 * @see setCheckSpellingEnabled()
94 */
95 virtual bool checkSpellingEnabled() const;
96
97 /**
98 * Returns true if the given paragraph or block should be spellcheck.
99 * For example, a mail client does not want to check quoted text, and
100 * would return false here (by checking whether the block starts with a
101 * quote sign).
102 *
103 * Always returns true by default.
104 *
105 */
106 virtual bool shouldBlockBeSpellChecked(const QString &block) const;
107
108 /**
109 * Selects the characters at the specified position. Any previous
110 * selection will be lost. The cursor is moved to the first character
111 * of the new selection.
112 *
113 * @param length The length of the selection, in number of characters
114 * @param pos The position of the first character of the selection
115 */
116 void highlightWord(int length, int pos);
117
118 /**
119 * Allows to create a specific highlighter if reimplemented.
120 *
121 * By default, it creates a normal highlighter, based on the config
122 * file given to setSpellCheckingConfigFileName().
123 *
124 * This highlighter is set each time spell checking is toggled on by
125 * calling setCheckSpellingEnabled(), but can later be overridden by calling
126 * setHighlighter().
127 *
128 * @see setHighlighter()
129 * @see highlighter()
130 * @see setSpellCheckingConfigFileName()
131 */
132 virtual void createHighlighter();
133
134 /**
135 * Returns the current highlighter, which is 0 if spell checking is disabled.
136 * The default highlighter is the one created by createHighlighter(), but
137 * might be overridden by setHighlighter().
138 *
139 * @see setHighlighter()
140 * @see createHighlighter()
141 */
142 Sonnet::Highlighter *highlighter() const;
143
144 /**
145 * Sets a custom background spell highlighter for this text edit.
146 * Normally, the highlighter returned by createHighlighter() will be
147 * used to detect and highlight incorrectly spelled words, but this
148 * function allows to set a custom highlighter.
149 *
150 * This has to be called after enabling spell checking with
151 * setCheckSpellingEnabled(), otherwise it has no effect.
152 *
153 * Ownership is transferred to the KTextEdit
154 *
155 * @see highlighter()
156 * @see createHighlighter()
157 * @param highLighter the new highlighter which will be used now
158 */
159 void setHighlighter(Sonnet::Highlighter *_highLighter);
160
161 /**
162 * Return standard KTextEdit popupMenu
163 * @since 4.1
164 */
165 virtual QMenu *mousePopupMenu();
166
167 /**
168 * Enable find replace action.
169 * @since 4.1
170 */
171 void enableFindReplace(bool enabled);
172
173 /**
174 * @return the spell checking language which was set by
175 * setSpellCheckingLanguage(), the spellcheck dialog or the spellcheck
176 * config dialog, or an empty string if that has never been called.
177 * @since 4.2
178 */
179 const QString &spellCheckingLanguage() const;
180
181 /**
182 * @since 4.10
183 */
184 void showTabAction(bool show);
185
186 /**
187 * @since 4.10
188 */
189 void showAutoCorrectButton(bool show);
190
191 /**
192 * @since 4.10
193 * create a modal spellcheck dialogbox and spellCheckingFinished signal we sent when
194 * we finish spell checking or spellCheckingCanceled signal when we cancel spell checking
195 */
196 void forceSpellChecking();
197
198Q_SIGNALS:
199 /**
200 * emit signal when we activate or not autospellchecking
201 *
202 * @since 4.1
203 */
204 void checkSpellingChanged(bool);
205
206 /**
207 * Signal sends when spell checking is finished/stopped/completed
208 * @since 4.1
209 */
210 void spellCheckStatus(const QString &);
211
212 /**
213 * Emitted when the user changes the language in the spellcheck dialog
214 * shown by checkSpelling() or when calling setSpellCheckingLanguage().
215 *
216 * @param language the new language the user selected
217 * @since 4.1
218 */
219 void languageChanged(const QString &language);
220
221 /**
222 * Emitted before the context menu is displayed.
223 *
224 * The signal allows you to add your own entries into the
225 * the context menu that is created on demand.
226 *
227 * NOTE: Do not store the pointer to the QMenu
228 * provided through since it is created and deleted
229 * on demand.
230 *
231 * @param p the context menu about to be displayed
232 * @since 4.5
233 */
234 void aboutToShowContextMenu(QMenu *menu);
235
236 /**
237 * @since 4.10
238 */
239 void spellCheckerAutoCorrect(const QString &currentWord, const QString &autoCorrectWord);
240
241 /**
242 * signal spellCheckingFinished is sent when we finish spell check or we click on "Terminate" button in sonnet dialogbox
243 * @since 4.10
244 */
245 void spellCheckingFinished();
246
247 /**
248 * signal spellCheckingCanceled is sent when we cancel spell checking.
249 * @since 4.10
250 */
251 void spellCheckingCanceled();
252
253public Q_SLOTS:
254
255 /**
256 * Set the spell check language which will be used for highlighting spelling
257 * mistakes and for the spellcheck dialog.
258 * The languageChanged() signal will be emitted when the new language is
259 * different from the old one.
260 *
261 * @since 4.1
262 */
263 void setSpellCheckingLanguage(const QString &language);
264
265 /**
266 * Show a dialog to check the spelling. The spellCheckStatus() signal
267 * will be emitted when the spell checking dialog is closed.
268 */
269 void checkSpelling();
270
271 /**
272 * Opens a Sonnet::ConfigDialog for this text edit.
273 * The spellcheck language of the config dialog is set to the current spellcheck
274 * language of the textedit. If the user changes the language in that dialog,
275 * the languageChanged() signal is emitted.
276 *
277 * @param configFileName The file which is used to store and load the config
278 * settings
279 * @param windowIcon the icon which is used for the titlebar of the spell dialog
280 * window. Can be empty, then no icon is set.
281 *
282 * @since 4.2
283 */
284 void showSpellConfigDialog(const QString &windowIcon = QString());
285
286 /**
287 * Create replace dialogbox
288 * @since 4.1
289 */
290 void replace();
291
292 /**
293 * Add custom spell checker decorator
294 * @since 5.11
295 */
296 void addTextDecorator(Sonnet::SpellCheckDecorator *decorator);
297
298 /**
299 * @brief clearDecorator clear the spellcheckerdecorator
300 * @since 5.11
301 */
302 void clearDecorator();
303
304protected Q_SLOTS:
305 /**
306 * @since 4.1
307 */
308 void slotDoReplace();
309 void slotReplaceNext();
310 void slotDoFind();
311 void slotFind();
312 void slotFindNext();
313 /**
314 * @since 5.11
315 */
316 void slotFindPrevious();
317 void slotReplace();
318 /**
319 * @since 4.3
320 */
321 void slotSpeakText();
322
323protected:
324 /**
325 * Reimplemented to catch "delete word" shortcut events.
326 */
327 bool event(QEvent *) override;
328
329 /**
330 * Reimplemented for internal reasons
331 */
332 void keyPressEvent(QKeyEvent *) override;
333
334 /**
335 * Reimplemented to instantiate a KDictSpellingHighlighter, if
336 * spellchecking is enabled.
337 */
338 void focusInEvent(QFocusEvent *) override;
339
340 /**
341 * Deletes a word backwards from the current cursor position,
342 * if available.
343 */
344 virtual void deleteWordBack();
345
346 /**
347 * Deletes a word forwards from the current cursor position,
348 * if available.
349 */
350 virtual void deleteWordForward();
351
352 /**
353 * Reimplemented from QTextEdit to add spelling related items
354 * when appropriate.
355 */
356 void contextMenuEvent(QContextMenuEvent *) override;
357
358protected:
359 KTEXTWIDGETS_NO_EXPORT KTextEdit(KTextEditPrivate &dd, const QString &text, QWidget *parent);
360 KTEXTWIDGETS_NO_EXPORT KTextEdit(KTextEditPrivate &dd, QWidget *parent);
361
362protected:
363 std::unique_ptr<class KTextEditPrivate> const d_ptr;
364
365private:
366 Q_DECLARE_PRIVATE(KTextEdit)
367};
368
369#endif // KTEXTEDIT_H
370

source code of ktextwidgets/src/widgets/ktextedit.h