KPIMTextEdit::MarkupDirector Class

class KPIMTextEdit::MarkupDirector

Instructs a builder object to create markup output. More...

Header: #include <KPIMTextEdit/MarkupDirector>
CMake: find_package(KPim6TextEdit REQUIRED)
target_link_libraries(mytarget PRIVATE KPim6::TextEdit)

Public Functions

MarkupDirector(KPIMTextEdit::AbstractMarkupBuilder *builder)
virtual ~MarkupDirector()
virtual QTextFrame::iterator processBlock(QTextFrame::iterator it, const QTextBlock &block)
virtual QTextFrame::iterator processBlockContents(QTextFrame::iterator it, const QTextBlock &block)
virtual std::pair<QTextFrame::iterator, QTextBlock> processBlockGroup(const QTextFrame::iterator &it, const QTextBlock &block, QTextBlockGroup *textBlockGroup)
virtual QTextBlock::iterator processCharTextObject(QTextBlock::iterator it, const QTextFragment &fragment, QTextObject *textObject)
virtual void processCustomFragment(const QTextFragment &fragment, const QTextDocument *doc)
virtual void processDocument(QTextDocument *doc)
virtual QTextBlock::iterator processFragment(QTextBlock::iterator it, const QTextFragment &fragment, const QTextDocument *doc)
virtual QTextFrame::iterator processFrame(QTextFrame::iterator it, QTextFrame *frame)
virtual QTextBlock::iterator processImage(QTextBlock::iterator it, const QTextImageFormat &imageFormat, const QTextDocument *doc)
virtual std::pair<QTextFrame::iterator, QTextBlock> processList(QTextFrame::iterator it, const QTextBlock &block, QTextList *textList)
virtual QTextFrame::iterator processObject(QTextFrame::iterator it, const QTextBlock &block, QTextObject *textObject)
virtual QTextFrame::iterator processTable(QTextFrame::iterator it, QTextTable *table)
virtual void processTableCell(const QTextTableCell &tableCell, QTextTable *table)

Protected Types

enum OpenElementValues { None, SuperScript, SubScript, Anchor, SpanForeground, …, StrikeOut }

Protected Functions

virtual QSet<int> getElementsToClose(const QTextBlock::iterator &it) const
virtual QList<int> getElementsToOpen(const QTextBlock::iterator &it)
virtual void processClosingElements(const QTextBlock::iterator &it)
void processDocumentContents(QTextFrame::iterator begin, const QTextFrame::iterator &end)
virtual void processOpeningElements(const QTextBlock::iterator &it)
std::pair<QTextFrame::iterator, QTextBlock> skipBlockGroup(QTextFrame::iterator it, const QTextBlock &_block, QTextBlockGroup *blockGroup)
QList<int> sortOpeningOrder(QSet<int> openingTags, QTextBlock::iterator it) const

Protected Variables

KPIMTextEdit::AbstractMarkupBuilder *const m_builder

Detailed Description

* * * *

The MarkupDirector is used with an implementation of AbstractMarkupBuilder to create a marked up document output.

Usage can be quite simple.

auto doc = editor->document(); // editor is a QTextEdit

auto builder = new HTMLBuilder();
auto md = new MarkupDirector(builder);
md->processDocument(doc);
browser->setHtml(builder->getResult()); // browser is a QTextBrowser.

Or with a different builder:

auto builder = new PlainTextMarkupBuilder();
auto md = new MarkupDirector(builder);
md->processDocument(doc);
browser->setPlainText(builder->getResult());

The MarkupDirector also provides API for processing just part of a QTextDocument, such as a QTextFrame or a QTextBlock. The appropriate method may then be called with an invalid iterator as appropriate.

// ... Do some processing to get a QTextFrame.
auto frame = getFrame();

auto builder = new PlainTextMarkupBuilder();
auto md = new MarkupDirector(builder);

// Create output from only the frame.
md->processFrame(QTextFrame::iterator(), frame);
browser->setPlainText(builder->getResult());

The behaviour of the MarkupDirector can be customized by subclassing. Support for custom types can also be added by implementing the processCustomFragment method.

Author: Stephen Kelly <steveire@gmail.com>

Member Type Documentation

enum MarkupDirector::OpenElementValues

Flags for the tags that may be open.

ConstantValueDescription
KPIMTextEdit::MarkupDirector::None0x0No tags are open
KPIMTextEdit::MarkupDirector::SuperScript0x01A superscript tag is open
KPIMTextEdit::MarkupDirector::SubScript0x02A subscript tag is open
KPIMTextEdit::MarkupDirector::Anchor0x04An anchor tag is open
KPIMTextEdit::MarkupDirector::SpanForeground0x08A foreground altering span tag is open.
KPIMTextEdit::MarkupDirector::SpanBackground0x10A background altering span tag is open.
KPIMTextEdit::MarkupDirector::SpanFontFamily0x20A font family altering span tag is open.
KPIMTextEdit::MarkupDirector::SpanFontPointSize0x40A font size altering span tag is open.
KPIMTextEdit::MarkupDirector::Strong0x80A strong tag is open.
KPIMTextEdit::MarkupDirector::Emph0x100A emphasis tag is open.
KPIMTextEdit::MarkupDirector::Underline0x200An underline tag is open.
KPIMTextEdit::MarkupDirector::StrikeOut0x400A strikeout tag is open.

Member Function Documentation

[explicit] MarkupDirector::MarkupDirector(KPIMTextEdit::AbstractMarkupBuilder *builder)

Constructs a MarkupDirector with the given builder.

[virtual noexcept] MarkupDirector::~MarkupDirector()

Destroys the MarkupDirector.

[virtual protected] QSet<int> MarkupDirector::getElementsToClose(const QTextBlock::iterator &it) const

Returns the tags that should be closed at the position of it.

[virtual protected] QList<int> MarkupDirector::getElementsToOpen(const QTextBlock::iterator &it)

Returns the tags that should be opened at the position of it.

[virtual] QTextFrame::iterator MarkupDirector::processBlock(QTextFrame::iterator it, const QTextBlock &block)

Directs the builder to create output for the single block at the position it. If calling this method directly, an invalid QTextFrame::iterator may be used. This method does not process the contents of the block, but uses the processBlockContents method to do so. Returns the iterator position after processing the block.

[virtual] QTextFrame::iterator MarkupDirector::processBlockContents(QTextFrame::iterator it, const QTextBlock &block)

Directs the builder to create output for the contents of the single block at the position it. If calling this method directly, an invalid QTextFrame::iterator may be used. Returns the iterator position after processing the block contents.

[virtual] std::pair<QTextFrame::iterator, QTextBlock> MarkupDirector::processBlockGroup(const QTextFrame::iterator &it, const QTextBlock &block, QTextBlockGroup *textBlockGroup)

Directs the builder to create output for the single textBlockGroup at the position it. If calling this method directly, an invalid QTextFrame::iterator may be used. The block block is the first block in the textBlockGroup. Returns a pair containing the iterator and block after processing.

[virtual] QTextBlock::iterator MarkupDirector::processCharTextObject(QTextBlock::iterator it, const QTextFragment &fragment, QTextObject *textObject)

Directs the builder to create output for the contents of the single textObject. The textObject is represented in the QTextDocument with the QTextFragment fragment at the position it. If calling this method directly, an invalid QTextBlock::iterator may be used. Returns the iterator position after processing the character text object.

[virtual protected] void MarkupDirector::processClosingElements(const QTextBlock::iterator &it)

Directs the builder to close the appropriate tags at the position of it.

[virtual] void MarkupDirector::processCustomFragment(const QTextFragment &fragment, const QTextDocument *doc)

Hook for instructing the builder to create output for the fragment with a custom type. doc is the document the fragment is in.

[virtual] void MarkupDirector::processDocument(QTextDocument *doc)

Processes the entire doc and constructs the output by directing the builder to create the markup.

[protected] void MarkupDirector::processDocumentContents(QTextFrame::iterator begin, const QTextFrame::iterator &end)

Processes the document between begin and end

[virtual] QTextBlock::iterator MarkupDirector::processFragment(QTextBlock::iterator it, const QTextFragment &fragment, const QTextDocument *doc)

Directs the builder to create output for the contents of the single fragment at the position it. If calling this method directly, an invalid QTextBlock::iterator may be used. doc is the document the fragment is in. Returns the iterator position after processing the fragment.

[virtual] QTextFrame::iterator MarkupDirector::processFrame(QTextFrame::iterator it, QTextFrame *frame)

Directs the builder to create output for the single frame at the position it. If calling this method directly, an invalid QTextFrame::iterator may be used. Returns the iterator position after processing the frame.

[virtual] QTextBlock::iterator MarkupDirector::processImage(QTextBlock::iterator it, const QTextImageFormat &imageFormat, const QTextDocument *doc)

Directs the builder to create output for the image represented by the imageFormat at the position it. If calling this method directly, an invalid QTextBlock::iterator may be used. doc is the document the fragment is in. Returns the iterator position after processing the image.

[virtual] std::pair<QTextFrame::iterator, QTextBlock> MarkupDirector::processList(QTextFrame::iterator it, const QTextBlock &block, QTextList *textList)

Directs the builder to create output for the single textList at the position it. If calling this method directly, an invalid QTextFrame::iterator may be used. The block block is the first block in the textList. Returns a pair containing the iterator and block after processing.

[virtual] QTextFrame::iterator MarkupDirector::processObject(QTextFrame::iterator it, const QTextBlock &block, QTextObject *textObject)

Directs the builder to create output for the single textObject at the position it. If calling this method directly, an invalid QTextFrame::iterator may be used. The block block is the container of the textObject. Returns the iterator position after processing the object.

[virtual protected] void MarkupDirector::processOpeningElements(const QTextBlock::iterator &it)

Directs the builder to open the appropriate tags at the position of it.

[virtual] QTextFrame::iterator MarkupDirector::processTable(QTextFrame::iterator it, QTextTable *table)

* Directs the builder to create output for the contents of the single table at the position it.

If calling this method directly, an invalid QTextFrame::iterator may be used.

[virtual] void MarkupDirector::processTableCell(const QTextTableCell &tableCell, QTextTable *table)

Directs the builder to create output for the contents of the single tableCell. The tableCell is in the table.

[protected] std::pair<QTextFrame::iterator, QTextBlock> MarkupDirector::skipBlockGroup(QTextFrame::iterator it, const QTextBlock &_block, QTextBlockGroup *blockGroup)

Iterates the iterator it to the first block after blockGroup. _block is any block in the blockGroup.

The return pair is the iterator pointing after the end of blockGroup and the first block after blockGroup.

[protected] QList<int> MarkupDirector::sortOpeningOrder(QSet<int> openingTags, QTextBlock::iterator it) const

Returns a list of tags contained in openingTags sorted so they can be opened in order and will be closed in the correct order.

openingTags should be a set of tags opened at the fragment pointed to by it.

Member Variable Documentation

KPIMTextEdit::AbstractMarkupBuilder *const MarkupDirector::m_builder

The builder this MarkupDirector is operating on. This is available when subclassing to customize behaviour.