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 | |
29 | class QMouseEvent; |
30 | class QKeyEvent; |
31 | |
32 | class 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 | */ |
65 | class KDEUI_EXPORT KRichTextEdit : public KTextEdit |
66 | { |
67 | Q_OBJECT |
68 | |
69 | public: |
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 | |
188 | public 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 | |
354 | Q_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 | |
368 | protected: |
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 | |
376 | private: |
377 | //@cond PRIVATE |
378 | KRichTextEditPrivate *const d; |
379 | friend class KRichTextEditPrivate; |
380 | //@endcond |
381 | }; |
382 | |
383 | |
384 | |
385 | #endif |
386 | |