1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2008 Stephen Kelly <steveire@gmail.com>
4 SPDX-FileCopyrightText: 2008 Thomas McGuire <thomas.mcguire@gmx.net>
5
6 SPDX-License-Identifier: LGPL-2.0-only
7*/
8
9#ifndef KRICHTEXTWIDGET_H
10#define KRICHTEXTWIDGET_H
11
12#include "krichtextedit.h"
13
14#include "ktextwidgets_export.h"
15
16class QAction;
17class KRichTextWidgetPrivate;
18
19/**
20 * @class KRichTextWidget krichtextwidget.h <KRichTextWidget>
21 *
22 * @brief A KRichTextEdit with common actions
23 *
24 * This class implements common actions which are often used with KRichTextEdit.
25 * All you need to do is to call createActions(), and the actions will be
26 * added to your KXMLGUIWindow. Remember to also add the chosen actions to
27 * your application ui.rc file.
28 *
29 * See the KRichTextWidget::RichTextSupportValues enum for an overview of
30 * supported actions.
31 *
32 * @author Stephen Kelly <steveire@gmail.com>
33 * @author Thomas McGuire <thomas.mcguire@gmx.net>
34 *
35 * \image html krichtextedit.png "KRichTextWidget Widget"
36 *
37 * @since 4.1
38 */
39class KTEXTWIDGETS_EXPORT KRichTextWidget : public KRichTextEdit
40{
41 Q_OBJECT
42 Q_PROPERTY(RichTextSupport richTextSupport READ richTextSupport WRITE setRichTextSupport)
43public:
44 /**
45 * These flags describe what actions will be created by createActions() after
46 * passing a combination of these flags to setRichTextSupport().
47 * @see RichTextSupport
48 */
49 enum RichTextSupportValues {
50 /**
51 * No rich text support at all, no actions will be created. Do not use
52 * in combination with other flags.
53 */
54 DisableRichText = 0x00,
55
56 /**
57 * Action to format the selected text as bold. If no text is selected,
58 * the word under the cursor is formatted bold.
59 * This is a KToggleAction. The status is automatically updated when
60 * the text cursor is moved.
61 */
62 SupportBold = 0x01,
63
64 /**
65 * Action to format the selected text as italic. If no text is selected,
66 * the word under the cursor is formatted italic.
67 * This is a KToggleAction. The status is automatically updated when
68 * the text cursor is moved.
69 */
70 SupportItalic = 0x02,
71
72 /**
73 * Action to underline the selected text. If no text is selected,
74 * the word under the cursor is underlined.
75 * This is a KToggleAction. The status is automatically updated when
76 * the text cursor is moved.
77 */
78 SupportUnderline = 0x04,
79
80 /**
81 * Action to strike out the selected text. If no text is selected,
82 * the word under the cursor is struck out.
83 * This is a KToggleAction. The status is automatically updated when
84 * the text cursor is moved.
85 */
86 SupportStrikeOut = 0x08,
87
88 /**
89 * Action to change the font family of the currently selected text. If
90 * no text is selected, the font family of the word under the cursor is
91 * changed.
92 * Displayed as a combobox when inserted into the toolbar.
93 * This is a KFontAction. The status is automatically updated when
94 * the text cursor is moved.
95 */
96 SupportFontFamily = 0x10,
97
98 /**
99 * Action to change the font size of the currently selected text. If no
100 * text is selected, the font size of the word under the cursor is changed.
101 * Displayed as a combobox when inserted into the toolbar.
102 * This is a KFontSizeAction. The status is automatically updated when
103 * the text cursor is moved.
104 */
105 SupportFontSize = 0x20,
106
107 /**
108 * Action to change the text color of the currently selected text. If no
109 * text is selected, the text color of the word under the cursor is
110 * changed.
111 * Opens a QColorDialog to select the color.
112 */
113 SupportTextForegroundColor = 0x40,
114
115 /**
116 * Action to change the background color of the currently selected text. If no
117 * text is selected, the background color of the word under the cursor is
118 * changed.
119 * Opens a QColorDialog to select the color.
120 */
121 SupportTextBackgroundColor = 0x80,
122
123 /**
124 * A combination of all the flags above.
125 * Includes all actions that change the format of the text.
126 */
127 FullTextFormattingSupport = 0xff,
128
129 /**
130 * Action to make the current line a list element, change the
131 * list style or remove list formatting.
132 * Displayed as a combobox when inserted into a toolbar.
133 * This is a KSelectAction. The status is automatically updated when
134 * the text cursor is moved.
135 */
136 SupportChangeListStyle = 0x100,
137
138 /**
139 * Action to increase the current list nesting level. This makes it
140 * possible to create nested lists.
141 */
142 SupportIndentLists = 0x200,
143
144 /**
145 * Action to decrease the current list nesting level.
146 */
147 SupportDedentLists = 0x400,
148
149 /**
150 * All of the three list actions above.
151 * Includes all list-related actions.
152 */
153 FullListSupport = 0xf00,
154
155 // Not implemented yet.
156 // SupportCreateTables = 0x1000,
157 // SupportChangeCellMargin = 0x2000,
158 // SupportChangeCellPadding = 0x4000,
159 // SupportChangeTableBorderWidth = 0x8000,
160 // SupportChangeTableBorderColor = 0x10000,
161 // SupportChangeTableBorderStyle = 0x20000,
162 // SupportChangeCellBackground = 0x40000,
163 // SupportCellFillPatterns = 0x80000,
164 //
165 // FullTableSupport = 0xff000,
166
167 /**
168 * Actions to align the current paragraph left, righ, center or justify.
169 * These actions are KToogleActions. The status is automatically updated when
170 * the text cursor is moved.
171 */
172 SupportAlignment = 0x100000,
173
174 // Not yet implemented SupportImages = 0x200000,
175
176 /**
177 * Action to insert a horizontal line.
178 */
179 SupportRuleLine = 0x400000,
180
181 /**
182 * Action to convert the current text to a hyperlink. If no text is selected,
183 * the word under the cursor is converted.
184 * This action opens a dialog where the user can enter the link target.
185 */
186 SupportHyperlinks = 0x800000,
187
188 /**
189 * Action to make the mouse cursor a format painter. The user can select
190 * text with that painter. The selected text gets the same format as the
191 * text that was previously selected.
192 */
193 SupportFormatPainting = 0x1000000,
194
195 /**
196 * Action to change the text of the whole text edit to plain text.
197 * All rich text formatting will get lost.
198 */
199 SupportToPlainText = 0x2000000,
200
201 /**
202 * Actions to format text as superscript or subscript. If no text is selected,
203 * the word under the cursor is formatted as selected.
204 * This is a KToggleAction. The status is automatically updated when
205 * the text cursor is moved.
206 */
207 SupportSuperScriptAndSubScript = 0x4000000,
208
209 // SupportChangeParagraphSpacing = 0x200000,
210
211 /**
212 * Action to change direction of text to Right-To-Left or Left-To-Right.
213 */
214 SupportDirection = 0x8000000,
215
216 /**
217 * Action to make the current line a heading (up to six levels,
218 * corresponding to HTML h1...h6 tags)
219 * Displayed as a combobox when inserted into a toolbar.
220 * This is a KSelectAction. The status is automatically updated when
221 * the text cursor is moved.
222 *
223 * @since 5.70
224 */
225 SupportHeading = 0x10000000,
226
227 /**
228 * Includes all above actions for full rich text support
229 */
230 FullSupport = 0xffffffff,
231 };
232 /**
233 * Stores a combination of #RichTextSupportValues values.
234 */
235 Q_DECLARE_FLAGS(RichTextSupport, RichTextSupportValues)
236 Q_FLAG(RichTextSupport)
237
238 /**
239 * @brief Constructor
240 * @param parent the parent widget
241 */
242 explicit KRichTextWidget(QWidget *parent);
243
244 /**
245 * Constructs a KRichTextWidget object
246 *
247 * @param text The initial text of the text edit, which is interpreted as
248 * HTML.
249 * @param parent The parent widget
250 */
251 explicit KRichTextWidget(const QString &text, QWidget *parent = nullptr);
252
253 /**
254 * @brief Destructor
255 */
256 ~KRichTextWidget() override;
257
258 /**
259 * @brief Creates the actions and adds them to the given action collection.
260 *
261 * Call this before calling setupGUI() in your application, but after
262 * calling setRichTextSupport().
263 *
264 * The XML file of your KXmlGuiWindow needs to have the action names in
265 * them, so that the actions actually appear in the menu and in the toolbars.
266 *
267 * Below is a list of actions that are created,depending on the supported rich text
268 * subset set by setRichTextSupport(). The list contains action names.
269 * Those names need to be the same in your XML file.
270 *
271 * See the KRichTextWidget::RichTextSupportValues enum documentation for a
272 * detailed explanation of each action.
273 *
274 * <table>
275 * <tr><td><b>XML Name</b></td><td><b>RichTextSupportValues flag</b></td></tr>
276 * <tr><td>format_text_foreground_color</td><td>SupportTextForegroundColor</td></tr>
277 * <tr><td>format_text_background_color</td><td>SupportTextBackgroundColor</td></tr>
278 * <tr><td>format_font_family</td><td>SupportFontFamily</td></tr>
279 * <tr><td>format_font_size</td><td>SupportFontSize</td></tr>
280 * <tr><td>format_text_bold</td><td>SupportBold</td></tr>
281 * <tr><td>format_text_italic</td><td>SupportItalic</td></tr>
282 * <tr><td>format_text_underline</td><td>SupportUnderline</td></tr>
283 * <tr><td>format_text_strikeout</td><td>SupportStrikeOut</td></tr>
284 * <tr><td>format_align_left</td><td>SupportAlignment</td></tr>
285 * <tr><td>format_align_center</td><td>SupportAlignment</td></tr>
286 * <tr><td>format_align_right</td><td>SupportAlignment</td></tr>
287 * <tr><td>format_align_justify</td><td>SupportAlignment</td></tr>
288 * <tr><td>direction_ltr</td><td>SupportDirection</td></tr>
289 * <tr><td>direction_rtl</td><td>SupportDirection</td></tr>
290 * <tr><td>format_list_style</td><td>SupportChangeListStyle</td></tr>
291 * <tr><td>format_list_indent_more</td><td>SupportIndentLists</td></tr>
292 * <tr><td>format_list_indent_less</td><td>SupportDedentLists</td></tr>
293 * <tr><td>insert_horizontal_rule</td><td>SupportRuleLine</td></tr>
294 * <tr><td>manage_link</td><td>SupportHyperlinks</td></tr>
295 * <tr><td>format_painter</td><td>SupportFormatPainting</td></tr>
296 * <tr><td>action_to_plain_text</td><td>SupportToPlainText</td></tr>
297 * <tr><td>format_text_subscript & format_text_superscript</td><td>SupportSuperScriptAndSubScript</td></tr>
298 * <tr><td>format_heading_level</td><td>SupportHeading</td></tr>
299 * </table>
300 *
301 * @since 5.0
302 */
303 virtual QList<QAction *> createActions();
304
305 /**
306 * @brief Sets the supported rich text subset available.
307 *
308 * The default is KRichTextWidget::FullSupport and will be set in the
309 * constructor.
310 *
311 * You need to call createActions() afterwards.
312 *
313 * @param support The supported subset.
314 */
315 void setRichTextSupport(const KRichTextWidget::RichTextSupport &support);
316
317 /**
318 * @brief Returns the supported rich text subset available.
319 * @return The supported subset.
320 */
321 RichTextSupport richTextSupport() const;
322
323 /**
324 * Tells KRichTextWidget to update the state of the actions created by
325 * createActions().
326 * This is normally automatically done, but there might be a few cases where
327 * you'll need to manually call this function.
328 *
329 * Call this function only after calling createActions().
330 */
331 void updateActionStates();
332
333public Q_SLOTS:
334
335 /**
336 * Disables or enables all of the actions created by
337 * createActions().
338 * This may be useful in cases where rich text mode may be set on or off.
339 *
340 * @param enabled Whether to enable or disable the actions.
341 */
342 void setActionsEnabled(bool enabled);
343
344protected:
345 /**
346 * Reimplemented.
347 * Catches mouse release events. Used to know when a selection has been completed.
348 */
349 void mouseReleaseEvent(QMouseEvent *event) override;
350
351private:
352 //@cond PRIVATE
353 Q_DECLARE_PRIVATE(KRichTextWidget)
354 //@endcond
355};
356
357Q_DECLARE_OPERATORS_FOR_FLAGS(KRichTextWidget::RichTextSupport)
358
359#endif
360

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