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 | |
25 | class 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 | */ |
45 | class KDEUI_EXPORT KRichTextWidget : public KRichTextEdit |
46 | { |
47 | Q_OBJECT |
48 | Q_FLAGS(RichTextSupport) |
49 | Q_PROPERTY(RichTextSupport richTextSupport READ richTextSupport WRITE setRichTextSupport) |
50 | public: |
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 | |
324 | public 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 | |
335 | protected: |
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 | |
343 | private: |
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 | |
358 | Q_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 | |