KPimTextEdit

texthtmlbuilder.h
1/*
2 SPDX-FileCopyrightText: 2020-2024 Laurent Montel <montel@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#pragma once
8#include "abstractmarkupbuilder.h"
9#include "kpimtextedit_export.h"
10
11namespace KPIMTextEdit
12{
13class TextHTMLBuilderPrivate;
14
15/// @headerfile texthtmlbuilder.h grantlee/texthtmlbuilder.h
16
17/**
18 @brief The TextHTMLBuilder creates a clean html markup output.
19
20 This class creates html output which is as minimal as possible and restricted
21 to the rich text features supported in %Qt.
22 (https://doc.qt.io/qt-5/richtext-html-subset.html)
23
24 The output contains only the body content, not the head element or other
25 metadata.
26
27 eg:
28
29 @code
30 <p>
31 This is some <strong>formatted content</strong> in a paragraph.
32 </p>
33 @endcode
34
35 instead of the content produced by %Qt:
36
37 @code
38 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"
39 "http://www.w3.org/TR/REC-html40/strict.dtd">
40 <html><head><meta name="qrichtext" content="1" /><meta
41 http-equiv="Content-Type" content="text/html; charset=UTF-8" /><style
42 type="text/css">
43 p, li { white-space: pre-wrap; }
44 </style></head><body style=" font-family:'Sans Serif'; font-size:10pt;
45 font-weight:400; font-style:normal;">
46 <p style=" margin-top:12px; margin-bottom:12px; margin-left:0px;
47 margin-right:0px; -qt-block-indent:0; text-indent:0px;">This is some <span
48 style=" font-weight:600;">formatted content</span> in a paragraph.
49 </p></body></html>
50 @endcode
51
52 Such tags should be created separately. For example:
53
54 @code
55 auto b = new TextHTMLBuilder();
56 auto md = new MarkupDirector(b);
57 md->constructContent();
58 QString cleanHtml(
59 "<head>\n<title>%1</title>\n</head>\n<body>%2</body>\n</html>")
60 .arg(document.metaInformation(QTextDocument::DocumentTitle))
61 .arg(b->getOutput());
62 file.write(cleanHtml);
63 @endcode
64
65 Font formatting information on elements is represented by individual span
66 elements.
67
68 eg:
69 @code
70 <span style"color:blue;">
71 <span style="background-color:red;">
72 Blue text on red background
73 </span>
74 </span>
75 @endcode
76
77 instead of
78
79 @code
80 <span style="color:blue;background-color:red;">
81 Blue text on red background
82 </span>
83 @endcode
84
85 It my be possible to change this if necessary.
86
87 @author Stephen Kelly <steveire@gmail.com>
88*/
89class KPIMTEXTEDIT_EXPORT TextHTMLBuilder : virtual public KPIMTextEdit::AbstractMarkupBuilder
90{
91public:
92 TextHTMLBuilder();
93 ~TextHTMLBuilder() override;
94
95 void beginStrong() override;
96 void endStrong() override;
97 void beginEmph() override;
98 void endEmph() override;
99 void beginUnderline() override;
100 void endUnderline() override;
101 void beginStrikeout() override;
102 void endStrikeout() override;
103 void beginForeground(const QBrush &brush) override;
104 void endForeground() override;
105 void beginBackground(const QBrush &brush) override;
106 void endBackground() override;
107 void beginAnchor(const QString &href = {}, const QString &name = {}) override;
108 void endAnchor() override;
109
110 // Maybe this stuff should just be added to a list, and then when I add
111 // literal text,
112 // add some kind of style attribute in one span instead of many.
113 void beginFontFamily(const QString &family) override;
114 void endFontFamily() override;
115
116 /**
117 Begin a new font point size
118 @param size The new size to begin.
119 */
120 void beginFontPointSize(int size) override;
121 void endFontPointSize() override;
122
123 /**
124 Begin a new paragraph
125 @param al The new paragraph alignment
126 @param topMargin The new paragraph topMargin
127 @param bottomMargin The new paragraph bottomMargin
128 @param leftMargin The new paragraph leftMargin
129 @param rightMargin The new paragraph rightMargin
130 */
131 void beginParagraph(Qt::Alignment al = Qt::AlignLeft,
132 qreal topMargin = 0.0,
133 qreal bottomMargin = 0.0,
134 qreal leftMargin = 0.0,
135 qreal rightMargin = 0.0,
136 bool leftToRightText = false) override;
137
138 /**
139 Begin a new header element.
140 @param level The new level to begin.
141 */
142 void beginHeader(int level) override;
143
144 /**
145 End a header element.
146 @param level The new level to end.
147 */
148 void endHeader(int level) override;
149
150 void endParagraph() override;
151 void addNewline() override;
152
153 void insertHorizontalRule(int width = -1) override;
154
155 void insertImage(const QString &src, qreal width, qreal height) override;
156
157 void beginList(QTextListFormat::Style type) override;
158
159 void endList() override;
160
161 void beginListItem() override;
162 void endListItem() override;
163
164 void beginSuperscript() override;
165
166 void endSuperscript() override;
167
168 void beginSubscript() override;
169
170 void endSubscript() override;
171
172 void beginTable(qreal cellpadding, qreal cellspacing, const QString &width) override;
173
174 void beginTableRow() override;
175 void beginTableHeaderCell(const QString &width, int colspan, int rowspan) override;
176
177 void beginTableCell(const QString &width, int colspan, int rowspan) override;
178
179 void endTable() override;
180 void endTableRow() override;
181 void endTableHeaderCell() override;
182 void endTableCell() override;
183
184 /**
185 Reimplemented from AbstractMarkupBuilder.
186
187 This implementation escapes the text before appending so that
188
189 @verbatim
190 A sample <b>bold</b> word.
191 @endverbatim
192
193 becomes
194
195 @verbatim
196 A sample &lt;b&gt;bold&lt;/b&gt; word.
197 @endverbatim
198 */
199 void appendLiteralText(const QString &text) override;
200
201 /**
202 Append @p text without escaping.
203
204 This is useful if extending MarkupDirector
205 */
206 void appendRawText(const QString &text) override;
207
208 [[nodiscard]] QString getResult() override;
209
210 void addSingleBreakLine() override;
211
212private:
213 TextHTMLBuilderPrivate *d_ptr;
214 Q_DECLARE_PRIVATE(TextHTMLBuilder)
215};
216
217}
KPIMTextEdit::AbstractMarkupBuilder
Interface for creating marked-up text output.
Definition abstractmarkupbuilder.h:37
KPIMTextEdit::TextHTMLBuilder
The TextHTMLBuilder creates a clean html markup output.
Definition texthtmlbuilder.h:86
Qt::Alignment
typedef Alignment
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 20 2024 11:58:50 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.