QXmlFormatter Class Reference

The QXmlFormatter class is an implementation of QXmlSerializer for transforming XQuery output into formatted XML. More...

#include <qxmlformatter.h>

Inheritance diagram for QXmlFormatter:

Public Functions
virtual void	atomicValue (const QVariant &value)
	Reimplemented Function More...
virtual void	attribute (const QXmlName &name, const QStringRef &value)
	Reimplemented Function More...
virtual void	characters (const QStringRef &value)
	Reimplemented Function More...
virtual void	comment (const QString &value)
	Reimplemented Function More...
virtual void	endDocument ()
	Reimplemented Function More...
virtual void	endElement ()
	Reimplemented Function More...
virtual void	endOfSequence ()
	Reimplemented Function More...
int	indentationDepth () const
	Returns the number of spaces QXmlFormatter will output for each indentation level. More...
virtual void	item (const QPatternist::Item &item)
virtual void	processingInstruction (const QXmlName &name, const QString &value)
	Reimplemented Function More...
	QXmlFormatter (const QXmlQuery &query, QIODevice *outputDevice)
	Constructs a formatter that uses the name pool and message handler in query, and writes the result to outputDevice as formatted XML. More...
void	setIndentationDepth (int depth)
	Sets depth to be the number of spaces QXmlFormatter will output for level of indentation. More...
virtual void	startDocument ()
	Reimplemented Function More...
virtual void	startElement (const QXmlName &name)
	Reimplemented Function More...
virtual void	startOfSequence ()
	Reimplemented Function More...
Public Functions inherited from QXmlSerializer
const QTextCodec *	codec () const
	Returns the codec being used by the serializer for encoding its XML output. More...
virtual void	namespaceBinding (const QXmlName &nb)
	Reimplemented Function More...
QIODevice *	outputDevice () const
	Returns a pointer to the output device. More...
	QXmlSerializer (const QXmlQuery &query, QIODevice *outputDevice)
	Constructs a serializer that uses the name pool and message handler in query, and writes the output to outputDevice. More...
void	setCodec (const QTextCodec *codec)
	Sets the codec the serializer will use for encoding its XML output. More...
Public Functions inherited from QAbstractXmlReceiver
	QAbstractXmlReceiver ()
	Constructs an abstract xml receiver. More...
virtual void	whitespaceOnly (const QStringRef &value)
	This function may be called instead of characters() if, and only if, value consists only of whitespace. More...
virtual	~QAbstractXmlReceiver ()
	Destroys the xml receiver. More...

Private Functions
void	startFormattingContent ()

Additional Inherited Members
Protected Functions inherited from QXmlSerializer
	QXmlSerializer (QAbstractXmlReceiverPrivate *d)
Protected Functions inherited from QAbstractXmlReceiver
	QAbstractXmlReceiver (QAbstractXmlReceiverPrivate *d)
void	sendAsNode (const QPatternist::Item &outputItem)
	Treats outputItem as a node and calls the appropriate function, e. More...
Protected Variables inherited from QAbstractXmlReceiver
QScopedPointer< QAbstractXmlReceiverPrivate >	d_ptr

Detailed Description

The QXmlFormatter class is an implementation of QXmlSerializer for transforming XQuery output into formatted XML.

Note

This class or function is reentrant.

Since

4.4

QXmlFormatter is a subclass of QXmlSerializer that formats the XML output to make it easier for humans to read.

QXmlSerializer outputs XML without adding unnecessary whitespace. In particular, it does not add {newlines} and indentation. To make the XML output easier to read, QXmlFormatter adds newlines and indentation by adding, removing, and modifying XQuery Sequence{sequence nodes} that only consist of whitespace. It also modifies whitespace in other places where it is not significant; e.g., between attributes and in the document prologue.

For example, where the base class QXmlSerializer would output this:

<a><b/><c/><p>Some Text</p></a>

QXmlFormatter outputs this:

<a>
   <b/>
   <c/>
   <p>Some Text</p>
</a>

If you just want to serialize your XML in a human-readable format, use QXmlFormatter as it is. The default indentation level is 4 spaces, but you can set your own indentation value setIndentationDepth().

The newlines and indentation added by QXmlFormatter are suitable for common formats, such as XHTML, SVG, or Docbook, where whitespace is not significant. However, if your XML will be used as input where whitespace is significant, then you must write your own subclass of QXmlSerializer or QAbstractXmlReceiver.

Note that using QXmlFormatter instead of QXmlSerializer will increase computational overhead and document storage size due to the insertion of whitespace.

Note also that the indentation style used by QXmlFormatter remains loosely defined and may change in future versions of Qt. If a specific indentation style is required then either use the base class QXmlSerializer directly, or write your own subclass of QXmlSerializer or QAbstractXmlReceiver. Alternatively, you can subclass QXmlFormatter and reimplement the callbacks there.

QXmlQuery query;
query.setQuery("doc('index.html')/html/body/p[1]");

QXmlFormatter formatter(query, myOutputDevice);
formatter.setIndentationDepth(2);
query.evaluateTo(&formatter);

Definition at line 58 of file qxmlformatter.h.

Constructors and Destructors

QXmlFormatter()

QXmlFormatter::QXmlFormatter	(	const QXmlQuery &	query,
		QIODevice *	outputDevice
	)

Constructs a formatter that uses the name pool and message handler in query, and writes the result to outputDevice as formatted XML.

outputDevice is passed directly to QXmlSerializer's constructor.

See also

QXmlSerializer

Definition at line 146 of file qxmlformatter.cpp.

                                                      : QXmlSerializer(new QXmlFormatterPrivate(query, outputDevice))
{
}

Functions

atomicValue()

void QXmlFormatter::atomicValue ( const QVariant &  value )

virtual

Reimplemented Function

Reimplemented from QXmlSerializer.

Definition at line 250 of file qxmlformatter.cpp.

{
    Q_D(QXmlFormatter);
    d->canIndent.top() = false;
    QXmlSerializer::atomicValue(value);
}

attribute()

void QXmlFormatter::attribute ( const QXmlName &  name, const QStringRef &  value  )

virtual

Reimplemented Function

Reimplemented from QXmlSerializer.

Definition at line 208 of file qxmlformatter.cpp.

{
    QXmlSerializer::attribute(name, value);
}

characters()

void QXmlFormatter::characters ( const QStringRef &  value )

virtual

Reimplemented Function

Reimplemented from QXmlSerializer.

Definition at line 228 of file qxmlformatter.cpp.

{
    Q_D(QXmlFormatter);
    d->isPreviousAtomic = false;
    d->characterBuffer += value.toString();
}

comment()

void QXmlFormatter::comment ( const QString &  value )

virtual

Reimplemented Function

Reimplemented from QXmlSerializer.

Definition at line 217 of file qxmlformatter.cpp.

{
    Q_D(QXmlFormatter);
    startFormattingContent();
    QXmlSerializer::comment(value);
    d->canIndent.top() = true;
}

endDocument()

void QXmlFormatter::endDocument ( )

virtual

Reimplemented Function

Reimplemented from QXmlSerializer.

Definition at line 268 of file qxmlformatter.cpp.

{
    QXmlSerializer::endDocument();
}

endElement()

void QXmlFormatter::endElement ( )

virtual

Reimplemented Function

Reimplemented from QXmlSerializer.

Definition at line 189 of file qxmlformatter.cpp.

{
    Q_D(QXmlFormatter);
    --d->currentDepth;
    d->indentString.chop(d->indentationDepth);

    if(!d->hasClosedElement.top().second)
        d->canIndent.top() = false;

    startFormattingContent();

    d->canIndent.pop();
    d->canIndent.top() = true;
    QXmlSerializer::endElement();
}

endOfSequence()

void QXmlFormatter::endOfSequence ( )

virtual

Reimplemented Function

Reimplemented from QXmlSerializer.

Definition at line 284 of file qxmlformatter.cpp.

{
    Q_D(QXmlFormatter);

    /* Flush any buffered content. */
    if(!d->characterBuffer.isEmpty())
        QXmlSerializer::characters(QStringRef(&d->characterBuffer));

    d->write('\n');
    QXmlSerializer::endOfSequence();
}

indentationDepth()

int QXmlFormatter::indentationDepth

(

)

const

Returns the number of spaces QXmlFormatter will output for each indentation level.

The default is four.

See also

setIndentationDepth()

Definition at line 323 of file qxmlformatter.cpp.

{
    Q_D(const QXmlFormatter);
    return d->indentationDepth;
}

item()

void QXmlFormatter::item ( const QPatternist::Item &  item )

virtual

Warning

This function is not part of the public interface.

Reimplemented from QXmlSerializer.

Definition at line 299 of file qxmlformatter.cpp.

{
    Q_D(QXmlFormatter);

    if(item.isAtomicValue())
    {
        if(QPatternist::XPathHelper::isWhitespaceOnly(item.stringValue()))
           return;
        else
        {
            d->canIndent.top() = false;
            startFormattingContent();
        }
    }

    QXmlSerializer::item(item);
}

processingInstruction()

void QXmlFormatter::processingInstruction ( const QXmlName &  name, const QString &  value  )

virtual

Reimplemented Function

Reimplemented from QXmlSerializer.

Definition at line 238 of file qxmlformatter.cpp.

{
    Q_D(QXmlFormatter);
    startFormattingContent();
    QXmlSerializer::processingInstruction(name, value);
    d->canIndent.top() = true;
}

setIndentationDepth()

void QXmlFormatter::setIndentationDepth

(

int

depth

)

Sets depth to be the number of spaces QXmlFormatter will output for level of indentation.

The default is four.

See also

indentationDepth()

Definition at line 335 of file qxmlformatter.cpp.

{
    Q_D(QXmlFormatter);
    d->indentationDepth = depth;
}

startDocument()

void QXmlFormatter::startDocument ( )

virtual

Reimplemented Function

Reimplemented from QXmlSerializer.

Definition at line 260 of file qxmlformatter.cpp.

{
    QXmlSerializer::startDocument();
}

startElement()

void QXmlFormatter::startElement ( const QXmlName &  name )

virtual

Reimplemented Function

Reimplemented from QXmlSerializer.

Definition at line 175 of file qxmlformatter.cpp.

{
    Q_D(QXmlFormatter);
    startFormattingContent();
    ++d->currentDepth;
    d->indentString.append(QString(d->indentationDepth, QLatin1Char(' ')));
    d->canIndent.push(true);

    QXmlSerializer::startElement(name);
}

startFormattingContent()

void QXmlFormatter::startFormattingContent ( )

inlineprivate

Warning

This function is not part of the public interface.

Definition at line 154 of file qxmlformatter.cpp.

Referenced by comment(), endElement(), item(), processingInstruction(), and startElement().

{
    Q_D(QXmlFormatter);

    if(QPatternist::XPathHelper::isWhitespaceOnly(d->characterBuffer))
    {
        if(d->canIndent.top())
            QXmlSerializer::characters(QStringRef(&d->indentString));
    }
    else
    {
        if(!d->characterBuffer.isEmpty()) /* Significant data, we don't touch it. */
            QXmlSerializer::characters(QStringRef(&d->characterBuffer));
    }

    d->characterBuffer.clear();
}

startOfSequence()

void QXmlFormatter::startOfSequence ( )

virtual

Reimplemented Function

Reimplemented from QXmlSerializer.

Definition at line 276 of file qxmlformatter.cpp.

{
    QXmlSerializer::startOfSequence();
}

---

The documentation for this class was generated from the following files:

• /src/xmlpatterns/api/qxmlformatter.h
• /src/xmlpatterns/api/qxmlformatter.cpp