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

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