KTextWidgets

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

KDE's Doxygen guidelines are available online.