Qt Toolkit - Qt XML Module

| Classes - Annotated - Tree - Functions - Home - Structure

# Qt XML Module

The XML module provides a well-formed XML parser with SAX2 (Simple API for XML) interface plus an implementation of the DOM Level 1 (Document Object Model).

This document assumes that you are familiar with the XML terminology. It provides you with information how to use the XML classes in Qt. For basic information on XML you should look at another place (e.g. http://www.w3.org/XML/).

## Overview of the XML architecture in Qt

The Qt XML Module provides two interfaces for XML: SAX2 and DOM Level 1.

SAX2 is a very popular Java interface for XML parsers. It was also adopted for other languages. The interface in Qt is designed after the Java interface. The naming was adjusted to fit the Qt naming conventions. Details on SAX2 can be found at http://www.megginson.com/SAX/.

Support for SAX2 filters and the reader factory are missing at the moment. Furthermore all classes that are in the Java interface for SAX1 compatibility are omitted.

DOM Level 1 is a W3C Recommendation for XML interfaces. Details and the specification of DOM Level 1 can be found at http://www.w3.org/DOM/.

See also the file "How to use the Qt SAX2 classes" for a description of the usage of SAX2.

## Introduction to SAX2

The SAX2 interface is a event-driven mechanism to provide the user with document information. "Event" in this context has nothing to do with the term "event" you probably know from windowing systems; it means that the parser reports certain document information while he parses the document. These reported information is referred to as "event".

The parser in SAX2 is normally referred to as "reader". There is an abstract class, QXmlReader, which defines the interface for all readers. At the moment Qt provides one implementation of a reader, QXmlSimpleReader.

The SAX2 interface gives you a serial access to the information in the document; i.e. the reader will parse the document serially and he will report the parsing events as soon as he finds the information in the document.

The reader reports parsing events through special handler classes. The user has to install a certain handler class if he wants to get informed about parsing events. The following handler classes are available:

- QXmlContentHandler reports events related to the content of a document (e.g. a start tag, characters, etc.)
- QXmlDTDHandler reports events related to the DTD (e.g. a notation declaration)
- QXmlErrorHandler reports errors or warnings that occurred during parsing
- QXmlEntityResolver reports external entities during parsing and allows the user to resolve external entities himself instead of letting the reader to try it.
- QXmlDeclHandler reports more DTD related events (e.g. an attribute declaration, etc.). There might be rare occasions you are intrested in these.
- QXmlLexicalHandler reports events related to the lexical structure of the document (e.g. the beginning of the DTD, comments, etc.) There might be rare occasions you are intrested in these.

These classes are all abstract classes describing the interface. SAX2 provides a default implementation of all these handler classes (QXmlDefaultHandler). So a user has only to implement the functions he is really intrested in. The default implementation is "do nothing".

The input XML data is read through a special class, QXmlInputSource.

There are some more classes for SAX2 support:

- QXmlAttributes is used to pass attributes in a start element event.
- QXmlLocator is used to get the actual parsing position of an event.
- QXmlNamespaceSupport is used to easily implement namespace support for a reader.

For a more detailed description of the usage see the document "How to use the Qt SAX2 classes".

## Introduction to DOM

DOM provides an interface to access and change the content and structore of an XML file. DOM gives a hierarchical view of the document (tree). All nodes in this tree are subclasses of QDomNode.

The following table lists all node classes and the node classes that can be children of them:

Node type | Possible children
--- | ---
QDomDocument | QDomElement (maximum of one), QDomProcessingInstruction, QDomComment, QDomDocumentType
QDomDocumentFragment | QDomElement, QDomProcessingInstruction, QDomComment, QDomText, QDomCDATASection, QDomEntityReference
QDomDocumentType | no children
QDomEntityReference | QDomElement, QDomProcessingInstruction, QDomComment, QDomText, QDomCDATASection, QDomEntityReference
QDomElement | QDomElement, QDomText, QDomComment, QDomProcessingInstruction, QDomCDATASection, QDomEntityReference
QDomAttr | QDomText, QDomEntityReference
QDomProcessingInstruction | no children
QDomComment | no children
QDomText | no children
QDomCDATASection | no children
QDomEntity | QDomElement, QDomProcessingInstruction, QDomComment, QDomText, QDomCDATASection, QDomEntityReference
QDomNotation | no children

There are also two collection classes: QDomNodeList is a list of nodes and QDomNamedNodeMap is used to handle unordered sets of nodes (especially used for attributes).

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

For getting started and for a description of the basic usage, take a look at the documentation of QDomDocument.