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