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{
52 Q_OBJECT
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 */
300 void insertHorizontalRule();
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 */
346 void insertPlainTextImplementation();
347
348Q_SIGNALS:
349
350 /**
351 * Emitted whenever the text mode is changed.
352 *
353 * @param mode The new text mode
354 */
355 void textModeChanged(KRichTextEdit::Mode mode);
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
375

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