1/*
2 krichtextedit.h
3 SPDX-FileCopyrightText: 2007 Laurent Montel <montel@kde.org>
4 SPDX-FileCopyrightText: 2008 Thomas McGuire <thomas.mcguire@gmx.net>
5 SPDX-FileCopyrightText: 2008 Stephen Kelly <steveire@gmail.com>
6
7 SPDX-License-Identifier: LGPL-2.1-or-later
8*/
9
10#ifndef KRICHTEXTEDIT_H
11#define KRICHTEXTEDIT_H
12
13#include <ktextedit.h>
14
15class QKeyEvent;
16
17class KRichTextEditPrivate;
18
19#include <ktextwidgets_export.h>
20
21/*!
22 * \class KRichTextEdit
23 * \inmodule KTextWidgets
24 *
25 * \brief A KTextEdit that supports both rich text and plain text modes.
26 *
27 * The KRichTextEdit class provides a widget to edit and display rich text.
28 *
29 * It offers several additional rich text editing functions to KTextEdit and makes
30 * them easier to access including:
31 *
32 * \list
33 * \li Changing fonts, sizes.
34 * \li Font formatting, such as bold, underline, italic, foreground and
35 * background color.
36 * \li Paragraph alignment
37 * \li Ability to edit and remove hyperlinks
38 * \li Nested list handling
39 * \li Simple actions to insert tables. TODO
40 * \endlist
41 *
42 * The KRichTextEdit can be in two modes: Rich text mode and plain text mode.
43 * Calling functions which modify the format/style of the text will automatically
44 * enable the rich text mode. Rich text mode is sometimes also referred to as
45 * HTML mode.
46 *
47 * Do not call setAcceptRichText() or acceptRichText() yourself. Instead simply
48 * connect to the slots which insert the rich text, use switchToPlainText() or
49 * enableRichTextMode().
50 *
51 * \image krichtextedit.png "KRichTextEdit Widget"
52 *
53 * \since 4.1
54 */
55class KTEXTWIDGETS_EXPORT KRichTextEdit : public KTextEdit
56{
57 Q_OBJECT
58
59public:
60 /*!
61 * \enum KRichTextEdit::Mode
62 *
63 * The mode the edit widget is in.
64 *
65 * \value Plain
66 * Plain text mode
67 * \value Rich
68 * Rich text mode
69 */
70 enum Mode {
71 Plain,
72 Rich,
73 };
74
75 /*!
76 * Constructs a KRichTextEdit object
77 *
78 * \a text The initial text of the text edit, which is interpreted as
79 * HTML.
80 *
81 * \a parent The parent widget
82 */
83 explicit KRichTextEdit(const QString &text, QWidget *parent = nullptr);
84
85 /*!
86 * Constructs a KRichTextEdit object.
87 *
88 * \a parent The parent widget
89 */
90 explicit KRichTextEdit(QWidget *parent = nullptr);
91
92 ~KRichTextEdit() override;
93
94 /*!
95 * This enables rich text mode. Nothing is done except changing the internal
96 * mode and allowing rich text pastes.
97 */
98 void enableRichTextMode();
99
100 /*!
101 * Returns the current text mode
102 */
103 Mode textMode() const;
104
105 /*!
106 * Returns the plain text string if in plain text mode or the HTML code
107 * if in rich text mode. The text is not word-wrapped.
108 */
109 QString textOrHtml() const;
110
111 /*!
112 * Replaces all the content of the text edit with the given string.
113 * If the string is in rich text format, the text is inserted as rich text,
114 * otherwise it is inserted as plain text.
115 *
116 * \a text The text to insert
117 */
118 void setTextOrHtml(const QString &text);
119
120 /*!
121 * Returns the text of the link at the current position or an empty string
122 * if the cursor is not on a link.
123 *
124 * \sa currentLinkUrl
125 */
126 QString currentLinkText() const;
127
128 /*!
129 * Returns the URL target (href) of the link at the current position or an
130 * empty string if the cursor is not on a link.
131 *
132 * \sa currentLinkText
133 */
134 QString currentLinkUrl() const;
135
136 /*!
137 * If the cursor is on a link, sets the \a cursor to a selection of the
138 * text of the link. If the \a cursor is not on a link, selects the current word
139 * or existing selection.
140 *
141 * \a cursor The cursor to use to select the text.
142 *
143 * \sa updateLink
144 */
145 void selectLinkText(QTextCursor *cursor) const;
146
147 /*!
148 * Convenience function to select the link text using the active cursor.
149 *
150 * \sa selectLinkText
151 */
152 void selectLinkText() const;
153
154 /*!
155 * Replaces the current selection with a hyperlink with the link URL \a linkUrl
156 * and the link text \a linkText.
157 *
158 * \sa selectLinkText
159 * \sa currentLinkUrl
160 * \sa currentLinkText
161 *
162 * \a linkUrl The link will get this URL as href (target)
163 *
164 * \a linkText The link will get this alternative text, which is the
165 * text displayed in the text edit.
166 */
167 void updateLink(const QString &linkUrl, const QString &linkText);
168
169 /*!
170 * Returns true if the list item at the current position can be indented.
171 *
172 * \sa canDedentList
173 */
174 bool canIndentList() const;
175
176 /*!
177 * Returns true if the list item at the current position can be dedented.
178 *
179 * \sa canIndentList
180 */
181 bool canDedentList() const;
182
183public Q_SLOTS:
184
185 /*!
186 * Sets the alignment of the current block to Left Aligned
187 */
188 void alignLeft();
189
190 /*!
191 * Sets the alignment of the current block to Centered
192 */
193 void alignCenter();
194
195 /*!
196 * Sets the alignment of the current block to Right Aligned
197 */
198 void alignRight();
199
200 /*!
201 * Sets the alignment of the current block to Justified
202 */
203 void alignJustify();
204
205 /*!
206 * Sets the direction of the current block to Right-To-Left
207 *
208 * \since 4.6
209 */
210 void makeRightToLeft();
211
212 /*!
213 * Sets the direction of the current block to Left-To-Right
214 *
215 * \since 4.6
216 */
217 void makeLeftToRight();
218
219 /*!
220 * Sets the list style of the current list, or creates a new list using the
221 * current block. The \a _styleindex corresponds to the QTextListFormat::Style
222 *
223 * \a _styleIndex The list will get this style
224 */
225 void setListStyle(int _styleIndex);
226
227 /*!
228 * Increases the nesting level of the current block or selected blocks.
229 *
230 * \sa canIndentList
231 */
232 void indentListMore();
233
234 /*!
235 * Decreases the nesting level of the current block or selected blocks.
236 *
237 * \sa canDedentList
238 */
239 void indentListLess();
240
241 /*!
242 * Sets the current word or selection to the font family \a fontFamily
243 *
244 * \a fontFamily The text's font family will be changed to this one
245 */
246 void setFontFamily(const QString &fontFamily);
247
248 /*!
249 * Sets the current word or selection to the font size \a size
250 *
251 * \a size The text's font will get this size
252 */
253 void setFontSize(int size);
254
255 /*!
256 * Sets the current word or selection to the font \a font
257 *
258 * \a font the font of the text will be set to this font
259 */
260 void setFont(const QFont &font);
261
262 /*!
263 * Toggles the bold formatting of the current word or selection at the current
264 * cursor position.
265 *
266 * \a bold If true, the text will be set to bold
267 */
268 void setTextBold(bool bold);
269
270 /*!
271 * Toggles the italic formatting of the current word or selection at the current
272 * cursor position.
273 *
274 * \a italic If true, the text will be set to italic
275 */
276 void setTextItalic(bool italic);
277
278 /*!
279 * Toggles the underline formatting of the current word or selection at the current
280 * cursor position.
281 *
282 * \a underline If true, the text will be underlined
283 */
284 void setTextUnderline(bool underline);
285
286 /*!
287 * Toggles the strikeout formatting of the current word or selection at the current
288 * cursor position.
289 *
290 * \a strikeOut If true, the text will be struck out
291 */
292 void setTextStrikeOut(bool strikeOut);
293
294 /*!
295 * Sets the foreground color of the current word or selection to \a color.
296 *
297 * \a color The text will get this background color
298 */
299 void setTextForegroundColor(const QColor &color);
300
301 /*!
302 * Sets the background color of the current word or selection to \a color.
303 *
304 * \a color The text will get this foreground color
305 */
306 void setTextBackgroundColor(const QColor &color);
307
308 /*!
309 * Inserts a horizontal rule below the current block.
310 */
311 void insertHorizontalRule();
312
313 /*!
314 * This will switch the editor to plain text mode.
315 * All rich text formatting will be destroyed.
316 */
317 void switchToPlainText();
318
319 /*!
320 * This will clean some of the bad html produced by the underlying QTextEdit
321 * It walks over all lines and cleans up a bit. Should be improved to produce
322 * our own Html.
323 */
324 QString toCleanHtml() const;
325
326 /*!
327 * Toggles the superscript formatting of the current word or selection at the current
328 * cursor position.
329 *
330 * \a superscript If true, the text will be set to superscript
331 */
332 void setTextSuperScript(bool superscript);
333
334 /*!
335 * Toggles the subscript formatting of the current word or selection at the current
336 * cursor position.
337 *
338 * \a subscript If true, the text will be set to subscript
339 */
340 void setTextSubScript(bool subscript);
341
342 /*!
343 * Sets the heading level of a current block or selection
344 *
345 * \a level Heading level (value should be between 0 and 6)
346 * (0 is "normal text", 1 is the largest heading, 6 is the smallest one)
347 *
348 * \since 5.70
349 */
350 void setHeadingLevel(int level);
351
352 /*!
353 * \since 4.10
354 * Because of binary compatibility constraints, insertPlainText
355 * is not virtual. Therefore it must dynamically detect and call this slot.
356 */
357 void insertPlainTextImplementation();
358
359Q_SIGNALS:
360
361 /*!
362 * Emitted whenever the text mode is changed.
363 *
364 * \a mode The new text mode
365 */
366 void textModeChanged(KRichTextEdit::Mode mode);
367
368protected:
369 void keyPressEvent(QKeyEvent *event) override;
370
371protected:
372 KTEXTWIDGETS_NO_EXPORT KRichTextEdit(KRichTextEditPrivate &dd, const QString &text, QWidget *parent);
373 KTEXTWIDGETS_NO_EXPORT KRichTextEdit(KRichTextEditPrivate &dd, QWidget *parent);
374
375private:
376 Q_DECLARE_PRIVATE(KRichTextEdit)
377};
378
379#endif
380

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