Home · Examples

[Previous: QtSvg Module][Qt's Modules][Next: QtXmlPatterns Module]

Classes

Support for SAX2 filters and the reader factory are under development. The Qt implementation does not include the SAX1 compatibility classes present in the Java interface. For an introduction to Qt's SAX2 classes, see The Qt SAX2 Classes.

DOM Level 2 is a W3C Recommendation for XML interfaces that maps the constituents of an XML document to a tree structure. The specification of DOM Level 2 can be found at http://www.w3.org/DOM/. For more information about the DOM classes in Qt is provided, see The Qt DOM Classes.

Since version 4.3, Qt provides two new classes for reading and writing XML: QXmlStreamReader and QXmlStreamWriter.

In addition to core XML support, classes for higher level querying and manipulation of XML data, are provided by the QtXmlPatterns module. In the QtSvg module, the QSvgRenderer and QSvgGenerator classes can read and write a subset of SVG, an XML-based file format. Qt also provides helper functions that may be useful to those working with XML and XHTML: see Qt::escape() and Qt::convertFromPlainText().

Further XML support is provided by the Qt Solutions group who provide, for example, classes that support SOAP and MML with the Qt XML classes.

This module is part of the Qt Full Framework Edition and the Qt Open Source Edition.

Topics:

• Configuring the Build Process
• The QtXml Stream Classes
• The Qt SAX2 Classes
• Introduction to SAX2
• SAX2 Features
• Namespace Support via Features
• Summary
• Properties
• The Qt DOM Classes
• Introduction to DOM
• An Introduction to Namespaces
• Conventions Used in the Qt XML Documentation

To include the definitions of the module's classes, use the following directive:

#include <QtXml>

QT += xml

QXmlStreamReader is a well-formed XML 1.0 parser that excludes external parsed entities. Hence, data provided by the stream reader adheres to the W3C's criteria for well-formed XML, as long as no error occurs. Otherwise, functions such as atEnd(), error() and hasError() can be used to check and view the errors.

An example of QXmlStreamReader implementation would be the XbelReader in QXmlStream Bookmarks Example, which is a subclass of QXmlStreamReader. The constructor takes treeWidget as a parameter and the class has Xbel specific functions:

    XbelReader(QTreeWidget *treeWidget);
...
    void readUnknownElement();
    void readXBEL();
    void readTitle(QTreeWidgetItem *item);
    void readSeparator(QTreeWidgetItem *item);
    void readFolder(QTreeWidgetItem *item);
    void readBookmark(QTreeWidgetItem *item);

    QTreeWidgetItem *createChildItem(QTreeWidgetItem *item);

    QTreeWidget *treeWidget;
...

bool XbelReader::read(QIODevice *device)
{
    setDevice(device);

    while (!atEnd()) {
        readNext();

        if (isStartElement()) {
            if (name() == "xbel" && attributes().value("version") == "1.0")
                readXBEL();
            else
                raiseError(QObject::tr("The file is not an XBEL version 1.0 file."));
        }
    }

    return !error();
}

To write XML document with QXmlStreamWriter, you start a document with the writeStartDocument() function and end it with writeEndDocument(), which implicitly closes all remaining open tags. Element tags are opened with writeStartDocument() and followed by writeAttribute() or writeAttributes(), element content, and then writeEndDocument(). Also, writeEmptyElement() can be used to write empty elements.

Element content comprises characters, entity references or nested elements. Content can be written with writeCharacters(), a function that also takes care of escaping all forbidden characters and character sequences, writeEntityReference(), or subsequent calls to writeStartElement().

The XbelWriter class from QXmlStream Bookmarks Example is a subclass of QXmlStreamWriter. Its writeFile() function illustrates the core functions of QXmlStreamWriter mentioned above:

The following code example is written in c++.

bool XbelWriter::writeFile(QIODevice *device)
{
    setDevice(device);

    writeStartDocument();
    writeDTD("<!DOCTYPE xbel>");
    writeStartElement("xbel");
    writeAttribute("version", "1.0");
    for (int i = 0; i < treeWidget->topLevelItemCount(); ++i)
        writeItem(treeWidget->topLevelItem(i));

    writeEndDocument();
    return true;
}

<quote>A quotation.</quote>

Whilst this is a fast and simple approach to read XML documents, manipulation is difficult because data is not stored, simply handled and discarded serially. The DOM interface reads in and stores the whole document in a tree structure; this takes more memory, but makes it easier to manipulate the document's structure..

The Qt XML module provides an abstract class, QXmlReader, that defines the interface for potential SAX2 readers. Qt includes a reader implementation, QXmlSimpleReader, that is easy to adapt through subclassing.

The reader reports parsing events through special handler classes:

To read input XML data a special class QXmlInputSource is used.

Apart from those already mentioned, the following SAX2 support classes provide additional useful functionality:

The Qt SAX2 implementation can report whether the reader has particular functionality using the QXmlReader::hasFeature() function. Available features can be tested with QXmlReader::feature(), and switched on or off using QXmlReader::setFeature().

Consider the example

<document xmlns:book = 'http://qtsoftware.com/fnord/book/'
          xmlns      = 'http://qtsoftware.com/fnord/' >

Other features include http://xml.org/sax/features/namespace (namespace processing, implies http://xml.org/sax/features/namespace-prefixes) and http://xml.org/sax/features/validation (the ability to report validation errors).

Whilst SAX2 leaves it to the user to define and implement whatever features are required, support for http://xml.org/sax/features/namespace (and thus http://xml.org/sax/features/namespace-prefixes) is mandantory. The QXmlSimpleReader implementation of QXmlReader, supports them, and can do namespace processing.

QXmlSimpleReader is not validating, so it does not support http://xml.org/sax/features/validation.

Namespace Support via Features

1. Namespace prefixes and local parts of elements and attributes can be reported.
2. The qualified names of elements and attributes are reported.
3. QXmlContentHandler::startPrefixMapping() and QXmlContentHandler::endPrefixMapping() are called by the reader.
4. Attributes that declare namespaces (i.e. the attribute xmlns and attributes starting with xmlns:) are reported.

<author xmlns:fnord = 'http://qtsoftware.com/fnord/'
             title="Ms" 
             fnord:title="Goddess" 
             name="Eris Kallisti"/>

The http://xml.org/sax/features/namespaces feature is responsible for reporting local names, namespace prefixes and URIs. With http://xml.org/sax/features/namespaces set to true the parser will report title as the local name of the fnord:title attribute, fnord being the namespace prefix and http://qtsoftware.com/fnord/ as the namespace URI. When http://xml.org/sax/features/namespaces is false none of them are reported.

In the current implementation the Qt XML classes follow the definition that the prefix xmlns itself isn't associated with any namespace at all (see http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-using). Therefore even with http://xml.org/sax/features/namespaces and http://xml.org/sax/features/namespace-prefixes both set to true the reader won't return either a local name, a namespace prefix or a namespace URI for xmlns:fnord.

This might be changed in the future following the W3C suggestion http://www.w3.org/2000/xmlns/ to associate xmlns with the namespace http://www.w3.org/2000/xmlns.

As the SAX2 standard suggests, QXmlSimpleReader defaults to having http://xml.org/sax/features/namespaces set to true and http://xml.org/sax/features/namespace-prefixes set to false. When changing this behavior using QXmlSimpleReader::setFeature() note that the combination of both features set to false is illegal.

Summary

To set or query properties the following functions are provided: QXmlReader::setProperty(), QXmlReader::property() and QXmlReader::hasProperty().

The Qt DOM Classes

All DOM nodes in the document tree are subclasses of QDomNode. The document itself is represented as a QDomDocument object.

Here are the available node classes and their potential child classes:

• QDomDocument: Possible children are
  • QDomElement (at most one)
  • QDomProcessingInstruction
  • QDomComment
  • QDomDocumentType
• QDomDocumentFragment: Possible children are
  • QDomElement
  • QDomProcessingInstruction
  • QDomComment
  • QDomText
  • QDomCDATASection
  • QDomEntityReference
• QDomDocumentType: No children
• QDomEntityReference: Possible children are
  • QDomElement
  • QDomProcessingInstruction
  • QDomComment
  • QDomText
  • QDomCDATASection
  • QDomEntityReference
• QDomElement: Possible children are
  • QDomElement
  • QDomText
  • QDomComment
  • QDomProcessingInstruction
  • QDomCDATASection
  • QDomEntityReference
• QDomAttr: Possible children are
  • QDomText
  • QDomEntityReference
• QDomProcessingInstruction: No children
• QDomComment: No children
• QDomText: No children
• QDomCDATASection: No children
• QDomEntity: Possible children are
  • QDomElement
  • QDomProcessingInstruction
  • QDomComment
  • QDomText
  • QDomCDATASection
  • QDomEntityReference
• QDomNotation: No children

The QDomImplementation class allows the user to query features of the DOM implementation.

To get started please refer to the QDomDocument documentation. You might also want to take a look at the DOM Bookmarks example, which illustrates how to read and write an XML bookmark file (XBEL) using DOM.

An Introduction to Namespaces

Namespaces are a concept introduced into XML to allow a more modular design. With their help data processing software can easily resolve naming conflicts in XML documents.

Consider the following example:

<document>
<book>
  <title>Practical XML</title>
  <author title="Ms" name="Eris Kallisti"/>
  <chapter>
    <title>A Namespace Called fnord</title>
  </chapter>
</book>
</document>

The solution would be to have some means of identifying the first occurrence of title as the title of a book, i.e. to use the title element of a book namespace to distinguish it from, for example, the chapter title, e.g.:

<book:title>Practical XML</book:title>

Before we can apply a namespace to element or attribute names we must declare it.

Namespaces are URIs like http://qtsoftware.com/fnord/book/. This does not mean that data must be available at this address; the URI is simply used to provide a unique name.

We declare namespaces in the same way as attributes; strictly speaking they are attributes. To make for example http://qtsoftware.com/fnord/ the document's default XML namespace xmlns we write

xmlns="http://qtsoftware.com/fnord/"

xmlns:book="http://qtsoftware.com/fnord/book/"

Element names without a prefix belong to the default namespace. This rule does not apply to attributes: an attribute without a prefix does not belong to any of the declared XML namespaces at all. Attributes always belong to the "traditional" namespace of the element in which they appear. A "traditional" namespace is not an XML namespace, it simply means that all attribute names belonging to one element must be different. Later we will see how to assign an XML namespace to an attribute.

Due to the fact that attributes without prefixes are not in any XML namespace there is no collision between the attribute title (that belongs to the author element) and for example the title element within a chapter.

Let's clarify this with an example:

<document xmlns:book = 'http://qtsoftware.com/fnord/book/'
          xmlns      = 'http://qtsoftware.com/fnord/' >
<book>
  <book:title>Practical XML</book:title>
  <book:author xmlns:fnord = 'http://qtsoftware.com/fnord/'
               title="Ms"
               fnord:title="Goddess"
               name="Eris Kallisti"/>
  <chapter>
    <title>A Namespace Called fnord</title>
  </chapter>
</book>
</document>

The book:author and book:title elements belong to the namespace with the URI http://qtsoftware.com/fnord/book/.

The two book:author attributes title and name have no XML namespace assigned. They are only members of the "traditional" namespace of the element book:author, meaning that for example two title attributes in book:author are forbidden.

In the above example we circumvent the last rule by adding a title attribute from the http://qtsoftware.com/fnord/ namespace to book:author: the fnord:title comes from the namespace with the prefix fnord that is declared in the book:author element.

Clearly the fnord namespace has the same namespace URI as the default namespace. So why didn't we simply use the default namespace we'd already declared? The answer is quite complex:

• attributes without a prefix don't belong to any XML namespace at all, not even to the default namespace;
• additionally omitting the prefix would lead to a title-title clash;
• writing it as xmlns:title would declare a new namespace with the prefix title instead of applying the default xmlns namespace.

More information on XML namespaces can be found at http://www.w3.org/TR/REC-xml-names/.

Conventions Used in the Qt XML Documentation