1/**
2 * krichtextedit.h
3 *
4 * Copyright 2007 Laurent Montel <montel@kde.org>
5 * Copyright 2008 Thomas McGuire <thomas.mcguire@gmx.net>
6 * Copyright 2008 Stephen Kelly <steveire@gmail.com>
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library; if not, write to the Free Software
20 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21 * 02110-1301 USA
22 */
23
24#ifndef KRICHTEXTEDIT_H
25#define KRICHTEXTEDIT_H
26
27#include <ktextedit.h>
28
29class QMouseEvent;
30class QKeyEvent;
31
32class KRichTextEditPrivate;
33
34#include <kdeui_export.h>
35
36#define HAVE_INSERTPLAINTEXT 1
37
38/**
39 * The KRichTextEdit class provides a widget to edit and display rich text.
40 *
41 * It offers several additional rich text editing functions to KTextEdit and makes
42 * them easier to access including:
43 *
44 * @li Changing fonts, sizes.
45 * @li Font formatting, such as bold, underline, italic, foreground and
46 * background color.
47 * @li Paragraph alignment
48 * @li Ability to edit and remove hyperlinks
49 * @li Nested list handling
50 * @li Simple actions to insert tables. TODO
51 *
52 * The KRichTextEdit can be in two modes: Rich text mode and plain text mode.
53 * Calling functions which modify the format/style of the text will automatically
54 * enable the rich text mode. Rich text mode is sometimes also referred to as
55 * HTML mode.
56 *
57 * Do not call setAcceptRichText() or acceptRichText() yourself. Instead simply
58 * connect to the slots which insert the rich text, use switchToPlainText() or
59 * enableRichTextMode().
60 *
61 * \image html krichtextedit.png "KDE Rich Text Edit Widget"
62 *
63 * @since 4.1
64 */
65class KDEUI_EXPORT KRichTextEdit : public KTextEdit
66{
67 Q_OBJECT
68
69public:
70
71 /**
72 * The mode the edit widget is in.
73 */
74 enum Mode { Plain, ///< Plain text mode
75 Rich ///< Rich text mode
76 };
77
78 /**
79 * Constructs a KRichTextEdit object
80 *
81 * @param text The initial text of the text edit, which is interpreted as
82 * HTML.
83 * @param parent The parent widget
84 */
85 explicit KRichTextEdit(const QString& text, QWidget *parent = 0);
86
87 /**
88 * Constructs a KRichTextEdit object.
89 *
90 * @param parent The parent widget
91 */
92 explicit KRichTextEdit(QWidget *parent = 0);
93
94 /**
95 * Destructor.
96 */
97 virtual ~KRichTextEdit();
98
99 /**
100 * This enables rich text mode. Nothing is done except changing the internal
101 * mode and allowing rich text pastes.
102 */
103 void enableRichTextMode();
104
105 /**
106 * @return The current text mode
107 */
108 Mode textMode() const;
109
110 /**
111 * @return The plain text string if in plain text mode or the HTML code
112 * if in rich text mode. The text is not word-wrapped.
113 */
114 QString textOrHtml() const;
115
116 /**
117 * Replaces all the content of the text edit with the given string.
118 * If the string is in rich text format, the text is inserted as rich text,
119 * otherwise it is inserted as plain text.
120 *
121 * @param text The text to insert
122 */
123 void setTextOrHtml(const QString &text);
124
125
126 /**
127 * Returns the text of the link at the current position or an empty string
128 * if the cursor is not on a link.
129 *
130 * @sa currentLinkUrl
131 * @return The link text
132 */
133 QString currentLinkText() const;
134
135 /**
136 * Returns the URL target (href) of the link at the current position or an
137 * empty string if the cursor is not on a link.
138 *
139 * @sa currentLinkText
140 * @return The link target URL
141 */
142 QString currentLinkUrl() const;
143
144 /**
145 * If the cursor is on a link, sets the @a cursor to a selection of the
146 * text of the link. If the @a cursor is not on a link, selects the current word
147 * or existing selection.
148 *
149 * @param cursor The cursor to use to select the text.
150 * @sa updateLink
151 */
152 void selectLinkText(QTextCursor* cursor) const;
153
154 /**
155 * Convenience function to select the link text using the active cursor.
156 *
157 * @sa selectLinkText
158 */
159 void selectLinkText() const;
160
161 /**
162 * Replaces the current selection with a hyperlink with the link URL @a linkUrl
163 * and the link text @a linkText.
164 *
165 * @sa selectLinkText
166 * @sa currentLinkUrl
167 * @sa currentLinkText
168 * @param linkUrl The link will get this URL as href (target)
169 * @param linkText The link will get this alternative text, which is the
170 * text displayed in the text edit.
171 */
172 void updateLink(const QString &linkUrl, const QString &linkText);
173
174 /**
175 * Returns true if the list item at the current position can be indented.
176 *
177 * @sa canDedentList
178 */
179 bool canIndentList() const;
180
181 /**
182 * Returns true if the list item at the current position can be dedented.
183 *
184 * @sa canIndentList
185 */
186 bool canDedentList() const;
187
188public Q_SLOTS:
189
190 /**
191 * Sets the alignment of the current block to Left Aligned
192 */
193 void alignLeft();
194
195 /**
196 * Sets the alignment of the current block to Centered
197 */
198 void alignCenter();
199
200 /**
201 * Sets the alignment of the current block to Right Aligned
202 */
203 void alignRight();
204
205 /**
206 * Sets the alignment of the current block to Justified
207 */
208 void alignJustify();
209
210 /**
211 * Sets the direction of the current block to Right-To-Left
212 *
213 * @since 4.6
214 */
215 void makeRightToLeft();
216
217 /**
218 * Sets the direction of the current block to Left-To-Right
219 *
220 * @since 4.6
221 */
222 void makeLeftToRight();
223
224 /**
225 * Sets the list style of the current list, or creates a new list using the
226 * current block. The @a _styleindex corresponds to the QTextListFormat::Style
227 *
228 * @param _styleIndex The list will get this style
229 */
230 void setListStyle(int _styleIndex);
231
232 /**
233 * Increases the nesting level of the current block or selected blocks.
234 *
235 * @sa canIndentList
236 */
237 void indentListMore();
238
239 /**
240 * Decreases the nesting level of the current block or selected blocks.
241 *
242 * @sa canDedentList
243 */
244 void indentListLess();
245
246 /**
247 * Sets the current word or selection to the font family @a fontFamily
248 *
249 * @param fontFamily The text's font family will be changed to this one
250 */
251 void setFontFamily(const QString &fontFamily);
252
253 /**
254 * Sets the current word or selection to the font size @a size
255 *
256 * @param size The text's font will get this size
257 */
258 void setFontSize(int size);
259
260 /**
261 * Sets the current word or selection to the font @a font
262 *
263 * @param font the font of the text will be set to this font
264 */
265 void setFont(const QFont &font);
266
267 /**
268 * Toggles the bold formatting of the current word or selection at the current
269 * cursor position.
270 *
271 * @param bold If true, the text will be set to bold
272 */
273 void setTextBold(bool bold);
274
275 /**
276 * Toggles the italic formatting of the current word or selection at the current
277 * cursor position.
278 *
279 * @param italic If true, the text will be set to italic
280 */
281 void setTextItalic(bool italic);
282
283 /**
284 * Toggles the underline formatting of the current word or selection at the current
285 * cursor position.
286 *
287 * @param underline If true, the text will be underlined
288 */
289 void setTextUnderline(bool underline);
290
291 /**
292 * Toggles the strikeout formatting of the current word or selection at the current
293 * cursor position.
294 *
295 * @param strikeOut If true, the text will be struck out
296 */
297 void setTextStrikeOut(bool strikeOut);
298
299 /**
300 * Sets the foreground color of the current word or selection to @a color.
301 *
302 * @param color The text will get this background color
303 */
304 void setTextForegroundColor(const QColor &color);
305
306 /**
307 * Sets the background color of the current word or selection to @a color.
308 *
309 * @param color The text will get this foreground color
310 */
311 void setTextBackgroundColor(const QColor &color);
312
313 /**
314 * Inserts a horizontal rule below the current block.
315 */
316 void insertHorizontalRule();
317
318 /**
319 * This will switch the editor to plain text mode.
320 * All rich text formatting will be destroyed.
321 */
322 void switchToPlainText();
323
324 /**
325 * This will clean some of the bad html produced by the underlying QTextEdit
326 * It walks over all lines and cleans up a bit. Should be improved to produce
327 * our own Html.
328 */
329 QString toCleanHtml() const;
330
331 /**
332 * Toggles the superscript formatting of the current word or selection at the current
333 * cursor position.
334 *
335 * @param superscript If true, the text will be set to superscript
336 */
337 void setTextSuperScript(bool superscript);
338
339 /**
340 * Toggles the subscript formatting of the current word or selection at the current
341 * cursor position.
342 *
343 * @param subscript If true, the text will be set to subscript
344 */
345 void setTextSubScript(bool subscript);
346
347 /**
348 * @since 4.10
349 * Because of binary compatibility constraints, insertPlainText
350 * is not virtual. Therefore it must dynamically detect and call this slot.
351 */
352 void insertPlainTextImplementation();
353
354Q_SIGNALS:
355
356 /**
357 * Emitted whenever the text mode is changed.
358 *
359 * @param mode The new text mode
360 */
361 void textModeChanged(KRichTextEdit::Mode mode);
362
363 /**
364 * Emitted whenever the user has finished making a selection. (on mouse up)
365 */
366 void selectionFinished();
367
368protected:
369
370 /**
371 * Reimplemented.
372 * Catches key press events. Used to handle some key presses on lists.
373 */
374 virtual void keyPressEvent(QKeyEvent *event);
375
376private:
377 //@cond PRIVATE
378 KRichTextEditPrivate *const d;
379 friend class KRichTextEditPrivate;
380 //@endcond
381};
382
383
384
385#endif
386