QXmlStreamWriter Class

The QXmlStreamWriter class provides an XML writer with a simple streaming API. More…

List of all members, including inherited members

Public Functions

Detailed Description

The writer is the counterpart of QXmlStreamReader: the program writes a document token by token, and the writer takes care of the syntax. It escapes text and values, keeps track of the elements that are open, and declares namespaces.

QXmlStreamWriter xml(&file);
xml.setAutoFormatting(true);
xml.writeStartDocument();
xml.writeStartElement("library");
xml.writeStartElement("book");
xml.writeAttribute("isbn", "0-201-63361-2");
xml.writeCharacters("Design Patterns");
xml.writeEndElement();
xml.writeEndDocument();

The writer does not check that what it is asked to write is a well-formed document: names are written as given, and it is for the program to write one root element.

See also QXmlStreamReader.

Differences from Qt

Member Function Documentation

QXmlStreamWriter::QXmlStreamWriter()

Constructs a writer without a place to write to. Give it one with setDevice().

[explicit] QXmlStreamWriter::QXmlStreamWriter(QIODevice *device)

Constructs a writer that writes UTF-8 to device, which must be open for writing.

[explicit] QXmlStreamWriter::QXmlStreamWriter(QByteArray *array)

Constructs a writer that appends UTF-8 to array.

[explicit] QXmlStreamWriter::QXmlStreamWriter(QString *string)

Constructs a writer that appends to string. The XML declaration it writes names no encoding, as a string has none.

QXmlStreamWriter::~QXmlStreamWriter()

Destroys the writer. Elements that are still open are not closed: call writeEndDocument().

bool QXmlStreamWriter::autoFormatting() const

Returns true if auto formatting is on.

See also setAutoFormatting().

int QXmlStreamWriter::autoFormattingIndent() const

Returns the number of spaces, or if negative of tabs, that auto formatting indents with.

See also setAutoFormattingIndent().

QIODevice * QXmlStreamWriter::device() const

Returns the device that the writer writes to, or nullptr if it writes to a byte array, a string or nothing.

See also setDevice().

bool QXmlStreamWriter::hasError() const

Returns true if writing to the device has failed, or the writer has nothing to write to. What is written after an error is lost.

void QXmlStreamWriter::setAutoFormatting(bool enable)

Turns auto formatting on or off, according to enable. With it the writer starts a line for each element and indents it by its depth, which makes the document readable. An element that has text is kept on one line, so that the text is not changed. It is off by default.

See also autoFormatting() and setAutoFormattingIndent().

void QXmlStreamWriter::setAutoFormattingIndent(int spacesOrTabs)

Sets what auto formatting indents each level with: spacesOrTabs spaces if it is positive, and that many tabs if it is negative. The default is 4 spaces.

See also autoFormattingIndent() and setAutoFormatting().

void QXmlStreamWriter::setDevice(QIODevice *device)

Makes the writer write to device from now on, which must be open for writing.

See also device().

void QXmlStreamWriter::writeAttribute(const QString &qualifiedName, const QString &value)

Writes an attribute with the name qualifiedName and the value value to the start element that was just written. Attributes can be written only before the element gets content.

void QXmlStreamWriter::writeAttribute(const QString &namespaceUri, const QString &name, const QString &value)

This is an overloaded function.

Writes an attribute with the local name name in the namespace namespaceUri and the value value. If the namespace has no prefix yet, the writer makes one up and declares it.

void QXmlStreamWriter::writeAttribute(const QXmlStreamAttribute &attribute)

This is an overloaded function.

Writes attribute, in its namespace if it has one.

void QXmlStreamWriter::writeAttributes(const QXmlStreamAttributes &attributes)

Writes each of attributes.

See also writeAttribute().

void QXmlStreamWriter::writeCDATA(const QString &text)

Writes text as a CDATA section, in which nothing needs to be escaped. If the text has the characters that end a section, it is written as two sections.

See also writeCharacters().

void QXmlStreamWriter::writeCharacters(const QString &text)

Writes text, with the characters <, >, & and " written as references.

See also writeCDATA() and writeTextElement().

void QXmlStreamWriter::writeComment(const QString &text)

Writes text as a comment. The text must not contain two hyphens in a row or end with one.

void QXmlStreamWriter::writeCurrentToken(const QXmlStreamReader &reader)

Writes the token that reader is at. A loop that calls this for every token copies a document, which is a way to change parts of one and keep the rest.

See also QXmlStreamReader::tokenType().

void QXmlStreamWriter::writeDefaultNamespace(const QString &namespaceUri)

Declares namespaceUri as the default namespace, which elements without a prefix are in. The declaration goes where that of writeNamespace() does.

See also writeNamespace().

void QXmlStreamWriter::writeDTD(const QString &dtd)

Writes dtd, which is a whole document type declaration, as it is.

void QXmlStreamWriter::writeEmptyElement(const QString &qualifiedName)

Writes an element with the name qualifiedName that has no content. Attributes can follow.

See also writeStartElement().

void QXmlStreamWriter::writeEmptyElement(const QString &namespaceUri, const QString &name)

This is an overloaded function.

Writes an element with the local name name in the namespace namespaceUri that has no content.

void QXmlStreamWriter::writeEndDocument()

Closes every element that is open, and with auto formatting ends the last line.

See also writeStartDocument().

void QXmlStreamWriter::writeEndElement()

Closes the element that was started last. An element that got no content is written as an empty-element tag.

See also writeStartElement().

void QXmlStreamWriter::writeEntityReference(const QString &name)

Writes a reference to the entity name, as &name;.

void QXmlStreamWriter::writeNamespace(const QString &namespaceUri, const QString &prefix = QString())

Declares the namespace namespaceUri with the prefix prefix, or with a prefix that the writer makes up if prefix is empty. Right after writeStartElement() the declaration goes into that element; anywhere else it goes into the element that is started next. Elements and attributes that are written with this namespace then use the prefix.

See also writeDefaultNamespace() and writeStartElement().

void QXmlStreamWriter::writeProcessingInstruction(const QString &target, const QString &data = QString())

Writes a processing instruction with the given target and data.

void QXmlStreamWriter::writeStartDocument()

Writes the XML declaration for version 1.0. A writer that writes bytes names UTF-8 as the encoding.

See also writeEndDocument().

void QXmlStreamWriter::writeStartDocument(const QString &version)

This is an overloaded function.

Writes the XML declaration with the version version.

void QXmlStreamWriter::writeStartDocument(const QString &version, bool standalone)

This is an overloaded function.

Writes the XML declaration with the version version and the statement that the document is standalone, or is not, according to standalone.

void QXmlStreamWriter::writeStartElement(const QString &qualifiedName)

Starts an element with the name qualifiedName. Attributes and namespace declarations can follow, then the content, and writeEndElement() closes it.

See also writeEndElement() and writeEmptyElement().

void QXmlStreamWriter::writeStartElement(const QString &namespaceUri, const QString &name)

This is an overloaded function.

Starts an element with the local name name in the namespace namespaceUri. If the namespace has no prefix yet, the writer makes one up and declares it in the element.

See also writeNamespace().

void QXmlStreamWriter::writeTextElement(const QString &qualifiedName, const QString &text)

Writes an element with the name qualifiedName that holds text.

See also writeStartElement() and writeCharacters().

void QXmlStreamWriter::writeTextElement(const QString &namespaceUri, const QString &name, const QString &text)

This is an overloaded function.

Writes an element with the local name name in the namespace namespaceUri that holds text.