KPimTextEdit

markupdirector.h
1/*
2 SPDX-FileCopyrightText: 2019-2021 Montel Laurent <montel@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5
6*/
7#pragma once
8
9#include "abstractmarkupbuilder.h"
10#include "kpimtextedit_export.h"
11#include <QTextDocument>
12#include <QTextFrame>
13class QTextTable;
14class QTextTableCell;
15class QTextList;
16class QTextCharFormat;
17
18namespace KPIMTextEdit
19{
20class MarkupDirectorPrivate;
21class AbstractMarkupBuilder;
22
23/// @headerfile markupdirector.h grantlee/markupdirector.h
24
25/**
26 @brief Instructs a builder object to create markup output
27
28 The **%MarkupDirector** is used with an implementation of
29 AbstractMarkupBuilder to create a marked up document output.
30
31 Usage can be quite simple.
32
33 @code
34 auto doc = editor->document(); // editor is a QTextEdit
35
36 auto builder = new HTMLBuilder();
37 auto md = new MarkupDirector(builder);
38 md->processDocument(doc);
39 browser->setHtml(builder->getResult()); // browser is a QTextBrowser.
40 @endcode
41
42 Or with a different builder:
43
44 @code
45 auto builder = new PlainTextMarkupBuilder();
46 auto md = new MarkupDirector(builder);
47 md->processDocument(doc);
48 browser->setPlainText(builder->getResult());
49 @endcode
50
51 The **%MarkupDirector** also provides API for processing just part of a
52 QTextDocument, such as a QTextFrame or a QTextBlock. The appropriate method
53 may then be called with an invalid iterator as appropriate.
54
55 @code
56 // ... Do some processing to get a QTextFrame.
57 auto frame = getFrame();
58
59 auto builder = new PlainTextMarkupBuilder();
60 auto md = new MarkupDirector(builder);
61
62 // Create output from only the frame.
63 md->processFrame(QTextFrame::iterator(), frame);
64 browser->setPlainText(builder->getResult());
65 @endcode
66
67 The behaviour of the **%MarkupDirector** can be customized by subclassing.
68 Support for custom types can also be added by implementing the @ref
69 processCustomFragment method.
70
71 @see @ref custom_qtextobject
72
73 @author Stephen Kelly <steveire@gmail.com>
74*/
75class KPIMTEXTEDIT_EXPORT MarkupDirector
76{
77public:
78 /**
79 Constructor
80 */
82
83 /**
84 Destructor
85 */
86 virtual ~MarkupDirector();
87
88 /**
89 Constructs the output by directing the builder to create the markup.
90 */
91 virtual void processDocument(QTextDocument *doc);
92
93 /**
94 Directs the builder to create output for the single @p frame. If calling
95 this method directly, an invalid QTextFrame::iterator may be used.
96 */
97 [[nodiscard]] virtual QTextFrame::iterator processFrame(QTextFrame::iterator it, QTextFrame *frame);
98
99 /**
100 Directs the builder to create output for the single @p block. If calling
101 this method directly, an invalid QTextFrame::iterator may be used.
102
103 This method does not process the contents of the @p block, but uses the
104 @ref processBlockContents method to do so.
105 */
106 [[nodiscard]] virtual QTextFrame::iterator processBlock(QTextFrame::iterator it, const QTextBlock &block);
107
108 /**
109 Directs the builder to create output for the single @p textObject. If
110 calling this method directly, an invalid QTextFrame::iterator may be used.
111
112 The block @p block is the container of the @p textObject.
113 */
114 [[nodiscard]] virtual QTextFrame::iterator processObject(QTextFrame::iterator it, const QTextBlock &block, QTextObject *textObject);
115
116 /**
117 Directs the builder to create output for the single @p textBlockGroup. If
118 calling this method directly, an invalid QTextFrame::iterator may be used.
119
120 The block @p block is the first block in the @p textBlockGroup.
121 */
122 [[nodiscard]] virtual QPair<QTextFrame::iterator, QTextBlock>
123 processBlockGroup(const QTextFrame::iterator &it, const QTextBlock &block, QTextBlockGroup *textBlockGroup);
124
125 /**
126 Directs the builder to create output for the single @p textList. If
127 calling this method directly, an invalid QTextFrame::iterator may be used.
128
129 The block @p block is the first block in the @p textList.
130 */
131 [[nodiscard]] virtual QPair<QTextFrame::iterator, QTextBlock> processList(QTextFrame::iterator it, const QTextBlock &block, QTextList *textList);
132
133 /**
134 Directs the builder to create output for the contents of the single @p
135 block. If calling this method directly, an invalid QTextFrame::iterator
136 may be used.
137 */
138 virtual QTextFrame::iterator processBlockContents(QTextFrame::iterator it, const QTextBlock &block);
139
140 /**
141 Hook for instructing the builder to create output for the @p fragemnt with
142 a custom type. @p doc is the document the fragment is in.
143 */
144 virtual void processCustomFragment(const QTextFragment &fragment, QTextDocument const *doc);
145
146 /**
147 Directs the builder to create output for the contents of the single @p
148 fragment. If calling this method directly, an invalid QTextBlock::iterator
149 may be used. @p doc is the document the fragment is in.
150 */
151 [[nodiscard]] virtual QTextBlock::iterator processFragment(QTextBlock::iterator it, const QTextFragment &fragment, QTextDocument const *doc);
152
153 /**
154 Directs the builder to create output for the contents of the single @p
155 textObject. The @p textObject is represented in the QTextDocument with the
156 QTextFragment @p fragment.
157
158 If calling this method directly, an invalid QTextBlock::iterator may be
159 used.
160 */
161 [[nodiscard]] virtual QTextBlock::iterator processCharTextObject(QTextBlock::iterator it, const QTextFragment &fragment, QTextObject *textObject);
162
163 /**
164 Directs the builder to create output for the image represented by the @p
165 imageFormat.
166
167 If calling this method directly, an invalid QTextBlock::iterator may be
168 used. @p doc is the document the fragment is in.
169 */
170 [[nodiscard]] virtual QTextBlock::iterator processImage(QTextBlock::iterator it, const QTextImageFormat &imageFormat, QTextDocument const *doc);
171
172 /**
173 Directs the builder to create output for the contents of the single @p
174 table.
175
176 If calling this method directly, an invalid QTextFrame::iterator may be
177 used.
178 */
179 [[nodiscard]] virtual QTextFrame::iterator processTable(QTextFrame::iterator it, QTextTable *table);
180
181 /**
182 Directs the builder to create output for the contents of the single @p
183 tableCell. The tableCell is in the @p table.
184 */
185 virtual void processTableCell(const QTextTableCell &tableCell, QTextTable *table);
186
187protected:
188 /**
189 Processes the document between @p begin and @p end
190 */
191 void processDocumentContents(QTextFrame::iterator begin, const QTextFrame::iterator &end);
192
193 /**
194 Iterates the iterator @p it to the first block after @p blockGroup. @p
195 _block is any block in the @p blockGroup.
196
197 The return pair is the iterator pointing after the end of @p blockGroup
198 and the first block after @p blockGroup.
199 */
200 [[nodiscard]] QPair<QTextFrame::iterator, QTextBlock> skipBlockGroup(QTextFrame::iterator it, const QTextBlock &_block, QTextBlockGroup *blockGroup);
201
202 /**
203 Returns a list of tags contained in @p openingTags sorted so they can be
204 opened in order and will be closed in the correct order.
205
206 @p openingTags should be a set of tags opened at the fragment pointed to
207 by @p it.
208 */
209 [[nodiscard]] QList<int> sortOpeningOrder(QSet<int> openingTags, QTextBlock::iterator it) const;
210
211 /**
212 Directs the builder to close the appropriate tags at the position of @p
213 it.
214 */
215 virtual void processClosingElements(const QTextBlock::iterator &it);
216
217 /**
218 Directs the builder to open the appropriate tags at the position of @p it.
219 */
220 virtual void processOpeningElements(const QTextBlock::iterator &it);
221
222 /**
223 Returns the tags that should be closed at the position of @p it.
224 */
225 [[nodiscard]] virtual QSet<int> getElementsToClose(const QTextBlock::iterator &it) const;
226
227 /**
228 Returns the tags that should be opened at the position of @p it.
229 */
230 [[nodiscard]] virtual QList<int> getElementsToOpen(const QTextBlock::iterator &it);
231
232 /**
233 Flags for the tags that may be open.
234 */
236 None = 0x0, /// No tags are open
237 SuperScript = 0x01, /// A superscript tag is open
238 SubScript = 0x02, /// A subscript tag is open
239 Anchor = 0x04, /// An anchor tag is open
240 SpanForeground = 0x08, /// A foreground altering span tag is open.
241 SpanBackground = 0x10, /// A background altering span tag is open.
242 SpanFontFamily = 0x20, /// A font family altering span tag is open.
243 SpanFontPointSize = 0x40, /// A font size altering span tag is open.
244 Strong = 0x80, /// A strong tag is open.
245 Emph = 0x100, /// A emphasis tag is open.
246 Underline = 0x200, /// An underline tag is open.
247 StrikeOut = 0x400 /// A strikeout tag is open.
248 };
249
250protected:
251#ifndef Q_QDOC
252 MarkupDirectorPrivate *const d_ptr;
253#endif
254
255 /**
256 The builder this MarkupDirector is operating on. This is available when
257 subclassing to customize behaviour.
258 */
260
261#ifndef Q_QDOC
262private:
263 Q_DECLARE_PRIVATE(MarkupDirector)
264#endif
265};
266}
Interface for creating marked-up text output.
Instructs a builder object to create markup output.
OpenElementValues
Flags for the tags that may be open.
KPIMTextEdit::AbstractMarkupBuilder *const m_builder
The builder this MarkupDirector is operating on.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:20:45 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.