Skip to content
Permalink
Browse files

Update the TextDocument apidox

  • Loading branch information...
steveire committed Aug 22, 2019
1 parent 160b14d commit 139bd74a413799de896fe608db30472fbc6fde35
@@ -5,7 +5,7 @@ namespace Grantlee
/**
@page custom_qtextobject Handling custom QTextObjects

It is possible using the QTextObjectInterface API to construct QTextDocuments containing custom text objects. If processing a QTextDocument
It is possible using the QTextObjectInterface API to construct QTextDocument instances containing custom text objects. If processing a QTextDocument
containing custom objects through the MarkupDirector and AbstractMarkupBuilder classes, it is necessary to implement support for the custom types
in %Grantlee.

@@ -20,8 +20,8 @@ namespace Grantlee
};
@endcode

We create a small interface for supporting the addition of audio markup. The interface should inherit virtually from the
AbstractMarkupBuilder interface, so that functionality from through that interface is also available.
We create a small interface for supporting the addition of audio markup. The interface should inherit from the
AbstractMarkupBuilder interface, so that functionality from that interface is also available.

Customized builders inheriting from an existing builder and the new interface can then be created.

@@ -36,10 +36,9 @@ class AbstractMarkupBuilderPrivate;
/// @headerfile abstractmarkupbuilder.h grantlee/abstractmarkupbuilder.h

/**
@brief The AbstractMarkupBuilder class serves as a base class for creating
marked up plain text output.
@brief Interface for creating marked-up text output.
The AbstractMarkupBuilder is used by a MarkupDirector to create marked up
The **%AbstractMarkupBuilder** is used by a MarkupDirector to create marked-up
output such as html or markdown.
See PlainTextMarkupBuilder and TextHTMLBuilder for example implementations.
@@ -79,16 +78,19 @@ class GRANTLEE_TEXTDOCUMENT_EXPORT AbstractMarkupBuilder
/** Close the struck out element in the markup */
virtual void endStrikeout() = 0;

/** Begin a decorarated foreground element in the markup (A text color)
* using
* @p brush */
/**
Begin a decorarated foreground element in the markup (A text color)
using @p brush
*/
virtual void beginForeground(const QBrush &brush) = 0;

/** Close the decorarated foreground element in the markup */
virtual void endForeground() = 0;

/** Begin a decorarated background element in the markup (A text background
* color) using @p brush */
/**
Begin a decorarated background element in the markup (A text background
color) using @p brush
*/
virtual void beginBackground(const QBrush &brush) = 0;

/** Close the decorarated background element in the markup */
@@ -198,7 +200,7 @@ class GRANTLEE_TEXTDOCUMENT_EXPORT AbstractMarkupBuilder
= 0;

/**
Begins a new table row.
Begin a new table row
*/
virtual void beginTableRow() = 0;

@@ -234,33 +236,33 @@ class GRANTLEE_TEXTDOCUMENT_EXPORT AbstractMarkupBuilder
virtual void endTableCell() = 0;

/**
Begin a level @p level header.
Begin a level @p level header
@param level An integer between 1 and 6
*/
virtual void beginHeader(int level) = 0;

/**
End a level @p level header.
End a level @p level header
@param level An integer between 1 and 6
*/
virtual void endHeader(int level) = 0;

/**
Append the plain text @p text to the markup.
Append the plain text @p text to the markup
@param text The text to append.
*/
virtual void appendLiteralText(const QString &text) = 0;

/**
Appends the raw text @p text to the markup. @p text is added unescaped.
Append the raw text @p text to the markup. @p text is added unescaped
*/
virtual void appendRawText(const QString &text) = 0;

/**
Return the fully marked up result of the building process. This may
contain
metadata etc, such as a head element in html.
Return the fully marked up result of the building process.
This may contain metadata etc, such as a head element in html.
@return The fully marked up text.
*/
@@ -59,9 +59,7 @@ class BBCodeBuilder : public AbstractMarkupBuilder

/**
Begin an element of font size @p size. Note that this size is in pixels,
and
must be converted before
it is suitable for use in BBCode.
and must be converted before it is suitable for use in BBCode.
@param size The size of font to begin.
*/
void beginFontPointSize(int size) override;
@@ -40,53 +40,50 @@ class MarkupDirectorPrivate;
/// @headerfile markupdirector.h grantlee/markupdirector.h

/**
@brief The MarkupDirector class controls and instructs a builder object to
create markup output.
@brief Instructs a builder object to create markup output
The MarkupDirector is used with a subclass of AbstractMarkupBuilder to create
a marked up document output.
The **%MarkupDirector** is used with an implementation of
AbstractMarkupBuilder to create a marked up document output.
Usage can be quite simple.
@code
auto doc = editor->document(); // editor is a QTextEdit
QTextDocument *doc = editor->document(); // editor is a QTextEdit
AbstractMarkupBuilder *builder = new HTMLBuilder();
MarkupDirector *md = new MarkupDirector(builder);
auto builder = new HTMLBuilder();
auto md = new MarkupDirector(builder);
md->processDocument(doc);
browser->setHtml(builder->getResult()); // browser is a QTextBrowser.
@endcode
Or with a different builder:
@code
AbstractMarkupBuilder *builder = new PlainTextMarkupBuilder();
MarkupDirector *md = new MarkupDirector(builder);
auto builder = new PlainTextMarkupBuilder();
auto md = new MarkupDirector(builder);
md->processDocument(doc);
browser->setPlainText(builder->getResult());
@endcode
The MarkupDirector also provides API for processing just part of a
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.
@code
// ... Do some processing to get a QTextFrame.
QTextFrame *frame = getFrame();
auto frame = getFrame();
AbstractMarkupBuilder *builder = new PlainTextMarkupBuilder();
MarkupDirector *md = new MarkupDirector(builder);
auto builder = new PlainTextMarkupBuilder();
auto md = new MarkupDirector(builder);
// Create output from only the frame.
md->processFrame(QTextFrame::iterator(), frame);
browser->setPlainText(builder->getResult());
@endcode
The behaviour of the MarkupDirector can be customized by subclassing. Support
for custom types can also be added by implementing the processCustomFragment
method.
The behaviour of the **%MarkupDirector** can be customized by subclassing.
Support for custom types can also be added by implementing the @ref
processCustomFragment method.
@see @ref custom_qtextobject
@@ -96,7 +93,7 @@ class GRANTLEE_TEXTDOCUMENT_EXPORT MarkupDirector
{
public:
/**
Construct a new MarkupDirector
Constructor
*/
MarkupDirector(AbstractMarkupBuilder *builder);

@@ -122,7 +119,7 @@ class GRANTLEE_TEXTDOCUMENT_EXPORT MarkupDirector
this method directly, an invalid QTextFrame::iterator may be used.
This method does not process the contents of the @p block, but uses the
processBlockContents method to do so.
@ref processBlockContents method to do so.
*/
virtual QTextFrame::iterator processBlock(QTextFrame::iterator it,
const QTextBlock &block);
@@ -149,8 +146,7 @@ class GRANTLEE_TEXTDOCUMENT_EXPORT MarkupDirector

/**
Directs the builder to create output for the single @p textList. If
calling
this method directly, an invalid QTextFrame::iterator may be used.
calling this method directly, an invalid QTextFrame::iterator may be used.
The block @p block is the first block in the @p textList.
*/
@@ -161,16 +157,14 @@ class GRANTLEE_TEXTDOCUMENT_EXPORT MarkupDirector
/**
Directs the builder to create output for the contents of the single @p
block. If calling this method directly, an invalid QTextFrame::iterator
may
be used.
may be used.
*/
virtual QTextFrame::iterator processBlockContents(QTextFrame::iterator it,
const QTextBlock &block);

/**
Hook for instructing the builder to create output for the @p fragemnt with
a
custom type. @p doc is the document the fragment is in.
a custom type. @p doc is the document the fragment is in.
*/
virtual void processCustomFragment(const QTextFragment &fragment,
QTextDocument const *doc);
@@ -236,8 +230,7 @@ class GRANTLEE_TEXTDOCUMENT_EXPORT MarkupDirector
_block is any block in the @p blockGroup.
The return pair is the iterator pointing after the end of @p blockGroup
and
the first block after @p blockGroup.
and the first block after @p blockGroup.
*/
QPair<QTextFrame::iterator, QTextBlock>
skipBlockGroup(QTextFrame::iterator it, const QTextBlock &_block,
@@ -248,8 +241,7 @@ class GRANTLEE_TEXTDOCUMENT_EXPORT MarkupDirector
opened in order and will be closed in the correct order.
@p openingTags should be a set of tags opened at the fragment pointed to
by
@p it.
by @p it.
*/
QList<int> sortOpeningOrder(QSet<int> openingTags,
QTextBlock::iterator it) const;
@@ -32,9 +32,6 @@ namespace Grantlee
class MediaWikiMarkupBuilder : public AbstractMarkupBuilder
{
public:
/**
Creates a new MediaWikiMarkupBuilder
*/
MediaWikiMarkupBuilder();
~MediaWikiMarkupBuilder() override;

@@ -42,22 +42,22 @@ class PlainTextMarkupBuilderPrivate;
/// @headerfile plaintextmarkupbuilder.h grantlee/plaintextmarkupbuilder.h

/**
@brief The PlainTextHTMLMarkupBuilder creates a simple marked up plain text
document.
@brief Creates a simple marked up plain text document
This class creates a simple plain text markup.
Text that may be represented as
@code
A paragraph with <b>bold</b> text, <i>italic</i> text, and <u>underlined</u>
text.
A paragraph with <b>bold</b> text, <i>italic</i> text,
and <u>underlined</u> text.
@endcode
would be output as
@code
A paragraph with *bold* text /italic/ text, and _underlined_ text.
A paragraph with *bold* text /italic/ text,
and _underlined_ text.
@endcode
The markup is intended to be simple, plain and easily human readable. No
@@ -66,8 +66,7 @@ class PlainTextMarkupBuilderPrivate;
Lists are marked up by preceding the list element with '*' for disc, 'o' for
circle, 'X' for square, or a letter or number. Lists are also indented if
nested.
eg:
nested. eg:
@code
A. One
@@ -85,14 +84,15 @@ class PlainTextMarkupBuilderPrivate;
Eg,
@code
Here is a link to <a href="http://www.kde.org">KDE</a> and the <a
href="http://pim.kde.org">KDEPIM project</a>.
Here is a link to <a href="http://www.kde.org">KDE</a> and
the <a href="http://pim.kde.org">KDEPIM project</a>.
@endcode
becomes:
@code
Here is a link to KDE[1], and the KDEPIM project[2].
Here is a link to KDE[1], and
the KDEPIM project[2].
---- References ----
[1] http://www.kde.org
@@ -105,7 +105,6 @@ class GRANTLEE_TEXTDOCUMENT_EXPORT PlainTextMarkupBuilder
: virtual public AbstractMarkupBuilder
{
public:
/** Construct a new PlainTextHTMLMarkupBuilder. */
PlainTextMarkupBuilder();

~PlainTextMarkupBuilder() override;

0 comments on commit 139bd74

Please sign in to comment.
You can’t perform that action at this time.