1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \group xml-tools

    44     \title XML Classes

    45 

    46     \brief Classes that support XML, via, for example DOM and SAX.

    47 

    48     These classes are relevant to XML users.

    49     

    50     \generatelist{related}

    51 */

    52 

    53 /*!

    54     \page xml-processing.html

    55     \title XML Processing

    56     \brief An Overview of the XML processing facilities in Qt.

    57 

    58     In addition to core XML support, classes for higher level querying

    59     and manipulation of XML data are provided by the QtXmlPatterns

    60     module. In the QtSvg module, the QSvgRenderer and QSvgGenerator

    61     classes can read and write a subset of SVG, an XML-based file

    62     format. Qt also provides helper functions that may be useful to

    63     those working with XML and XHTML: see Qt::escape() and

    64     Qt::convertFromPlainText().

    65 

    66     \section1 Topics:

    67 

    68     \list

    69     \o \l {Classes for XML Processing}

    70     \o \l {An Introduction to Namespaces}

    71     \o \l {XML Streaming}

    72     \o \l {The SAX Interface}

    73     \o \l {Working with the DOM Tree}

    74     \o \l {Using XML Technologies}{XQuery/XPath and XML Schema}

    75         \list

    76         \o \l{A Short Path to XQuery}

    77         \endlist

    78     \endlist

    79     

    80     \section1 Classes for XML Processing

    81 

    82     These classes are relevant to XML users.

    83 

    84     \annotatedlist xml-tools

    85 */

    86 

    87 /*!

    88     \page xml-namespaces.html

    89     \title An Introduction to Namespaces

    90     \target namespaces

    91 

    92     \contentspage XML Processing

    93     \nextpage XML Streaming

    94 

    95     Parts of the Qt XML module documentation assume that you are familiar

    96     with XML namespaces. Here we present a brief introduction; skip to

    97     \link #namespacesConventions Qt XML documentation conventions \endlink

    98     if you already know this material.

    99 

   100     Namespaces are a concept introduced into XML to allow a more modular

   101     design. With their help data processing software can easily resolve

   102     naming conflicts in XML documents.

   103 

   104     Consider the following example:

   105 

   106     \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 6

   107 

   108     Here we find three different uses of the name \e title. If you wish to

   109     process this document you will encounter problems because each of the

   110     \e titles should be displayed in a different manner -- even though

   111     they have the same name.

   112 

   113     The solution would be to have some means of identifying the first

   114     occurrence of \e title as the title of a book, i.e. to use the \e

   115     title element of a book namespace to distinguish it from, for example,

   116     the chapter title, e.g.:

   117     \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 7

   118 

   119     \e book in this case is a \e prefix denoting the namespace.

   120 

   121     Before we can apply a namespace to element or attribute names we must

   122     declare it.

   123 

   124     Namespaces are URIs like \e http://www.example.com/fnord/book/. This

   125     does not mean that data must be available at this address; the URI is

   126     simply used to provide a unique name.

   127 

   128     We declare namespaces in the same way as attributes; strictly speaking

   129     they \e are attributes. To make for example \e

   130     http://www.example.com/fnord/ the document's default XML namespace \e

   131     xmlns we write

   132 

   133     \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 8

   134 

   135     To distinguish the \e http://www.example.com/fnord/book/ namespace from

   136     the default, we must supply it with a prefix:

   137 

   138     \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 9

   139 

   140     A namespace that is declared like this can be applied to element and

   141     attribute names by prepending the appropriate prefix and a ":"

   142     delimiter. We have already seen this with the \e book:title element.

   143 

   144     Element names without a prefix belong to the default namespace. This

   145     rule does not apply to attributes: an attribute without a prefix does

   146     not belong to any of the declared XML namespaces at all. Attributes

   147     always belong to the "traditional" namespace of the element in which

   148     they appear. A "traditional" namespace is not an XML namespace, it

   149     simply means that all attribute names belonging to one element must be

   150     different. Later we will see how to assign an XML namespace to an

   151     attribute.

   152 

   153     Due to the fact that attributes without prefixes are not in any XML

   154     namespace there is no collision between the attribute \e title (that

   155     belongs to the \e author element) and for example the \e title element

   156     within a \e chapter.

   157 

   158     Let's clarify this with an example:

   159     \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 10

   160 

   161     Within the \e document element we have two namespaces declared. The

   162     default namespace \e http://www.example.com/fnord/ applies to the \e

   163     book element, the \e chapter element, the appropriate \e title element

   164     and of course to \e document itself.

   165 

   166     The \e book:author and \e book:title elements belong to the namespace

   167     with the URI \e http://www.example.com/fnord/book/.

   168 

   169     The two \e book:author attributes \e title and \e name have no XML

   170     namespace assigned. They are only members of the "traditional"

   171     namespace of the element \e book:author, meaning that for example two

   172     \e title attributes in \e book:author are forbidden.

   173 

   174     In the above example we circumvent the last rule by adding a \e title

   175     attribute from the \e http://www.example.com/fnord/ namespace to \e

   176     book:author: the \e fnord:title comes from the namespace with the

   177     prefix \e fnord that is declared in the \e book:author element.

   178 

   179     Clearly the \e fnord namespace has the same namespace URI as the

   180     default namespace. So why didn't we simply use the default namespace

   181     we'd already declared? The answer is quite complex:

   182     \list

   183     \o attributes without a prefix don't belong to any XML namespace at

   184     all, not even to the default namespace;

   185     \o additionally omitting the prefix would lead to a \e title-title clash;

   186     \o writing it as \e xmlns:title would declare a new namespace with the

   187     prefix \e title instead of applying the default \e xmlns namespace.

   188     \endlist

   189 

   190     With the Qt XML classes elements and attributes can be accessed in two

   191     ways: either by refering to their qualified names consisting of the

   192     namespace prefix and the "real" name (or \e local name) or by the

   193     combination of local name and namespace URI.

   194 

   195     More information on XML namespaces can be found at

   196     \l http://www.w3.org/TR/REC-xml-names/.

   197 

   198     \target namespacesConventions

   199     \section1 Conventions Used in the Qt XML Documentation

   200 

   201     The following terms are used to distinguish the parts of names within

   202     the context of namespaces:

   203     \list

   204     \o  The \e {qualified name}

   205         is the name as it appears in the document. (In the above example \e

   206         book:title is a qualified name.)

   207     \o  A \e {namespace prefix} in a qualified name

   208         is the part to the left of the ":". (\e book is the namespace prefix in

   209         \e book:title.)

   210     \o  The \e {local part} of a name (also refered to as the \e {local

   211         name}) appears to the right of the ":". (Thus \e title is the

   212         local part of \e book:title.)

   213     \o  The \e {namespace URI} ("Uniform Resource Identifier") is a unique

   214         identifier for a namespace. It looks like a URL

   215         (e.g. \e http://www.example.com/fnord/ ) but does not require

   216         data to be accessible by the given protocol at the named address.

   217     \endlist

   218 

   219     Elements without a ":" (like \e chapter in the example) do not have a

   220     namespace prefix. In this case the local part and the qualified name

   221     are identical (i.e. \e chapter).

   222 

   223     \sa {DOM Bookmarks Example}, {SAX Bookmarks Example}

   224 */

   225 

   226 /*!

   227     \page xml-streaming.html

   228     \title XML Streaming

   229 

   230     \previouspage An Introduction to Namespaces

   231     \contentspage XML Processing

   232     \nextpage The SAX Interface

   233 

   234     Since version 4.3, Qt provides two new classes for reading and

   235     writing XML: QXmlStreamReader and QXmlStreamWriter.

   236 

   237     The QXmlStreamReader and QXmlStreamWriter are two new classes provided

   238     in Qt 4.3 and later. A stream reader reports an XML document as a stream

   239     of tokens. This differs from SAX as SAX applications provide handlers to

   240     receive XML events from the parser whereas the QXmlStreamReader drives the

   241     loop, pulling tokens from the reader when they are needed.

   242     This pulling approach makes it possible to build recursive descent parsers,

   243     allowing XML parsing code to be split into different methods or classes.

   244 

   245     QXmlStreamReader is a well-formed XML 1.0 parser that excludes external

   246     parsed entities. Hence, data provided by the stream reader adheres to the

   247     W3C's criteria for well-formed XML, as long as no error occurs. Otherwise,

   248     functions such as \l{QXmlStreamReader::atEnd()}{atEnd()},

   249     \l{QXmlStreamReader::error()}{error()} and \l{QXmlStreamReader::hasError()}

   250     {hasError()} can be used to check and view the errors.

   251 

   252     An example of QXmlStreamReader implementation would be the \c XbelReader in

   253     \l{QXmlStream Bookmarks Example}, which is a subclass of QXmlStreamReader.

   254     The constructor takes \a treeWidget as a parameter and the class has Xbel

   255     specific functions:

   256 

   257     \snippet examples/xml/streambookmarks/xbelreader.h 1

   258 

   259     \dots

   260     \snippet examples/xml/streambookmarks/xbelreader.h 2

   261     \dots

   262 

   263     The \c read() function accepts a QIODevice and sets it with

   264     \l{QXmlStreamReader::setDevice()}{setDevice()}. The

   265     \l{QXmlStreamReader::raiseError()}{raiseError()} function is used to

   266     display a custom error message, inidicating that the file's version

   267     is incorrect.

   268 

   269     \snippet examples/xml/streambookmarks/xbelreader.cpp 1

   270 

   271     The pendent to QXmlStreamReader is QXmlStreamWriter, which provides an XML

   272     writer with a simple streaming API. QXmlStreamWriter operates on a

   273     QIODevice and has specialised functions for all XML tokens or events you

   274     want to write, such as \l{QXmlStreamWriter::writeDTD()}{writeDTD()},

   275     \l{QXmlStreamWriter::writeCharacters()}{writeCharacters()},

   276     \l{QXmlStreamWriter::writeComment()}{writeComment()} and so on.

   277 

   278     To write XML document with QXmlStreamWriter, you start a document with the

   279     \l{QXmlStreamWriter::writeStartDocument()}{writeStartDocument()} function

   280     and end it with \l{QXmlStreamWriter::writeEndDocument()}

   281     {writeEndDocument()}, which implicitly closes all remaining open tags.

   282     Element tags are opened with \l{QXmlStreamWriter::writeStartDocument()}

   283     {writeStartDocument()} and followed by 

   284     \l{QXmlStreamWriter::writeAttribute()}{writeAttribute()} or

   285     \l{QXmlStreamWriter::writeAttributes()}{writeAttributes()},

   286     element content, and then \l{QXmlStreamWriter::writeEndDocument()}

   287     {writeEndDocument()}. Also, \l{QXmlStreamWriter::writeEmptyElement()}

   288     {writeEmptyElement()} can be used to write empty elements.

   289 

   290     Element content comprises characters, entity references or nested elements.

   291     Content can be written with \l{QXmlStreamWriter::writeCharacters()}

   292     {writeCharacters()}, a function that also takes care of escaping all

   293     forbidden characters and character sequences,

   294     \l{QXmlStreamWriter::writeEntityReference()}{writeEntityReference()},

   295     or subsequent calls to \l{QXmlStreamWriter::writeStartElement()}

   296     {writeStartElement()}.

   297 

   298     The \c XbelWriter class from \l{QXmlStream Bookmarks Example} is a subclass

   299     of QXmlStreamWriter. Its \c writeFile() function illustrates the core

   300     functions of QXmlStreamWriter mentioned above:

   301 

   302     \snippet examples/xml/streambookmarks/xbelwriter.cpp 1

   303 */

   304 

   305 /*!

   306     \page xml-sax.html

   307     \title The SAX interface

   308 

   309     \previouspage XML Streaming

   310     \contentspage XML Processing

   311     \nextpage Working with the DOM Tree

   312 

   313     SAX is an event-based standard interface for XML parsers.

   314     The Qt interface follows the design of the SAX2 Java implementation.

   315     Its naming scheme was adapted to fit the Qt naming conventions.

   316     Details on SAX2 can be found at \l{http://www.saxproject.org}.

   317 

   318     Support for SAX2 filters and the reader factory are under

   319     development. The Qt implementation does not include the SAX1

   320     compatibility classes present in the Java interface.

   321 

   322     \section1 Introduction to SAX2

   323 

   324     The SAX2 interface is an event-driven mechanism to provide the user with

   325     document information. An "event" in this context means something

   326     reported by the parser, for example, it has encountered a start tag,

   327     or an end tag, etc.

   328 

   329     To make it less abstract consider the following example:

   330     \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 3

   331 

   332     Whilst reading (a SAX2 parser is usually referred to as "reader") 

   333     the above document three events would be triggered:

   334     \list 1

   335     \o A start tag occurs (\c{<quote>}).

   336     \o Character data (i.e. text) is found, "A quotation.".

   337     \o An end tag is parsed (\c{</quote>}).

   338     \endlist

   339 

   340     Each time such an event occurs the parser reports it; you can set up

   341     event handlers to respond to these events.

   342 

   343     Whilst this is a fast and simple approach to read XML documents,

   344     manipulation is difficult because data is not stored, simply handled

   345     and discarded serially. The \l{Working with the DOM Tree}{DOM interface}

   346     reads in and stores the whole document in a tree structure;

   347     this takes more memory, but makes it easier to manipulate the

   348     document's structure.

   349 

   350     The Qt XML module provides an abstract class, \l QXmlReader, that

   351     defines the interface for potential SAX2 readers. Qt includes a reader

   352     implementation, \l QXmlSimpleReader, that is easy to adapt through

   353     subclassing.

   354 

   355     The reader reports parsing events through special handler classes:

   356     \table

   357     \header \o Handler class \o Description

   358     \row \o \l QXmlContentHandler

   359          \o Reports events related to the content of a document (e.g. the start tag

   360             or characters).

   361     \row \o \l QXmlDTDHandler

   362          \o Reports events related to the DTD (e.g. notation declarations).

   363     \row \o \l QXmlErrorHandler

   364          \o Reports errors or warnings that occurred during parsing.

   365     \row \o \l QXmlEntityResolver

   366          \o Reports external entities during parsing and allows users to resolve

   367             external entities themselves instead of leaving it to the reader.

   368     \row \o \l QXmlDeclHandler

   369          \o Reports further DTD related events (e.g. attribute declarations).

   370     \row \o \l QXmlLexicalHandler

   371          \o Reports events related to the lexical structure of the

   372             document (the beginning of the DTD, comments etc.).

   373     \endtable

   374 

   375     These classes are abstract classes describing the interface. The \l

   376     QXmlDefaultHandler class provides a "do nothing" default

   377     implementation for all of them. Therefore users only need to overload

   378     the QXmlDefaultHandler functions they are interested in. 

   379 

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

   381 

   382     Apart from those already mentioned, the following SAX2 support classes 

   383     provide additional useful functionality:

   384     \table

   385     \header \o Class \o Description

   386     \row \o \l QXmlAttributes

   387          \o Used to pass attributes in a start element event.

   388     \row \o \l QXmlLocator

   389          \o Used to obtain the actual parsing position of an event.

   390     \row \o \l QXmlNamespaceSupport

   391          \o Used to implement namespace support for a reader. Note that

   392             namespaces do not change the parsing behavior. They are only

   393             reported through the handler.

   394     \endtable

   395 

   396     The \l{SAX Bookmarks example} illustrates how to subclass

   397     QXmlDefaultHandler to read an XML bookmark file (XBEL) and

   398     how to generate XML by hand.

   399 

   400     \section1 SAX2 Features

   401 

   402     The behavior of an XML reader depends on its support for certain

   403     optional features. For example, a reader may have the feature "report

   404     attributes used for namespace declarations and prefixes along with

   405     the local name of a tag". Like every other feature this has a unique

   406     name represented by a URI: it is called

   407     \e http://xml.org/sax/features/namespace-prefixes.

   408 

   409     The Qt SAX2 implementation can report whether the reader has

   410     particular functionality using the QXmlReader::hasFeature()

   411     function. Available features can be tested with QXmlReader::feature(),

   412     and switched on or off using QXmlReader::setFeature(). 

   413 

   414     Consider the example 

   415     \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 4

   416     A reader that does not support the \e

   417     http://xml.org/sax/features/namespace-prefixes feature would report

   418     the element name \e document but not its attributes \e xmlns:book and

   419     \e xmlns with their values. A reader with the feature \e

   420     http://xml.org/sax/features/namespace-prefixes reports the namespace

   421     attributes if the \link QXmlReader::feature() feature\endlink is

   422     switched on.

   423 

   424     Other features include \e http://xml.org/sax/features/namespace

   425     (namespace processing, implies \e

   426     http://xml.org/sax/features/namespace-prefixes) and \e

   427     http://xml.org/sax/features/validation (the ability to report

   428     validation errors). 

   429 

   430     Whilst SAX2 leaves it to the user to define and implement whatever

   431     features are required, support for \e

   432     http://xml.org/sax/features/namespace (and thus \e

   433     http://xml.org/sax/features/namespace-prefixes) is mandantory.

   434     The \l QXmlSimpleReader implementation of \l QXmlReader,

   435     supports them, and can do namespace processing.

   436 

   437     \l QXmlSimpleReader is not validating, so it

   438     does not support \e http://xml.org/sax/features/validation.

   439 

   440     \section1 Namespace Support via Features

   441 

   442     As we have seen in the previous section, we can configure the

   443     behavior of the reader when it comes to namespace

   444     processing. This is done by setting and unsetting the 

   445     \e http://xml.org/sax/features/namespaces and

   446     \e http://xml.org/sax/features/namespace-prefixes features.

   447 

   448     They influence the reporting behavior in the following way:

   449     \list 1

   450     \o Namespace prefixes and local parts of elements and attributes can

   451     be reported.

   452     \o The qualified names of elements and attributes are reported.

   453     \o \l QXmlContentHandler::startPrefixMapping() and \l

   454     QXmlContentHandler::endPrefixMapping() are called by the reader.

   455     \o Attributes that declare namespaces (i.e. the attribute \e xmlns and

   456     attributes starting with \e{xmlns:}) are reported.

   457     \endlist

   458 

   459     Consider the following element:

   460     \snippet doc/src/snippets/code/doc_src_qtxml.qdoc 5

   461     With \e http://xml.org/sax/features/namespace-prefixes set to true 

   462     the reader will report four attributes; but with the \e

   463     namespace-prefixes feature set to false only three, with the \e

   464     xmlns:fnord attribute defining a namespace being "invisible" to the

   465     reader.

   466 

   467     The \e http://xml.org/sax/features/namespaces feature is responsible

   468     for reporting local names, namespace prefixes and URIs. With \e

   469     http://xml.org/sax/features/namespaces set to true the parser will

   470     report \e title as the local name of the \e fnord:title attribute, \e

   471     fnord being the namespace prefix and \e http://example.com/fnord/ as

   472     the namespace URI. When \e http://xml.org/sax/features/namespaces is

   473     false none of them are reported.

   474 

   475     In the current implementation the Qt XML classes follow the definition

   476     that the prefix \e xmlns itself isn't associated with any namespace at all

   477     (see \link http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-using 

   478     http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-using \endlink).

   479     Therefore even with \e http://xml.org/sax/features/namespaces and

   480     \e http://xml.org/sax/features/namespace-prefixes both set to true

   481     the reader won't return either a local name, a namespace prefix or

   482     a namespace URI for \e xmlns:fnord.

   483 

   484     This might be changed in the future following the W3C suggestion

   485     \link http://www.w3.org/2000/xmlns/ http://www.w3.org/2000/xmlns/ \endlink

   486     to associate \e xmlns with the namespace \e http://www.w3.org/2000/xmlns. 

   487 

   488     As the SAX2 standard suggests, \l QXmlSimpleReader defaults to having

   489     \e http://xml.org/sax/features/namespaces set to true and

   490     \e http://xml.org/sax/features/namespace-prefixes set to false.

   491     When changing this behavior using \l QXmlSimpleReader::setFeature() 

   492     note that the combination of both features set to

   493     false is illegal.

   494 

   495     \section2 Summary

   496 

   497     \l QXmlSimpleReader implements the following behavior:

   498 

   499     \table

   500     \header \o (namespaces, namespace-prefixes)

   501             \o Namespace prefix and local part

   502             \o Qualified names

   503             \o Prefix mapping

   504             \o xmlns attributes

   505     \row \o (true, false) \o Yes \o Yes* \o Yes \o No

   506     \row \o (true, true) \o Yes \o Yes \o Yes \o Yes

   507     \row \o (false, true) \o No* \o Yes \o No* \o Yes

   508     \row \o (false, false) \i41 Illegal

   509     \endtable

   510 

   511     The behavior of the entries marked with an asterisk (*) is not specified by SAX.

   512 

   513     \section1 Properties

   514 

   515     Properties are a more general concept. They have a unique name,

   516     represented as an URI, but their value is \c void*. Thus nearly

   517     anything can be used as a property value. This concept involves some

   518     danger, though: there is no means of ensuring type-safety; the user

   519     must take care that they pass the right type. Properties are

   520     useful if a reader supports special handler classes.

   521 

   522     The URIs used for features and properties often look like URLs, e.g.

   523     \c http://xml.org/sax/features/namespace. This does not mean that the

   524     data required is at this address. It is simply a way of defining

   525     unique names.

   526 

   527     Anyone can define and use new SAX2 properties for their readers.

   528     Property support is not mandatory.

   529 

   530     To set or query properties the following functions are provided: \l

   531     QXmlReader::setProperty(), \l QXmlReader::property() and \l

   532     QXmlReader::hasProperty().                     

   533 */

   534 

   535 /*!

   536     \page xml-dom.tml

   537     \title Working with the DOM Tree

   538     \target dom

   539 

   540     \previouspage The SAX Interface

   541     \contentspage XML Processing

   542     \nextpage {Using XML Technologies}{XQuery/XPath and XML Schema}

   543 

   544     DOM Level 2 is a W3C Recommendation for XML interfaces that maps the

   545     constituents of an XML document to a tree structure. The specification

   546     of DOM Level 2 can be found at \l{http://www.w3.org/DOM/}.

   547 

   548     \target domIntro

   549     \section1 Introduction to DOM

   550 

   551     DOM provides an interface to access and change the content and

   552     structure of an XML file. It makes a hierarchical view of the document

   553     (a tree view). Thus -- in contrast to the SAX2 interface -- an object

   554     model of the document is resident in memory after parsing which makes

   555     manipulation easy. 

   556 

   557     All DOM nodes in the document tree are subclasses of \l QDomNode. The

   558     document itself is represented as a \l QDomDocument object.

   559 

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

   561 

   562     \list

   563     \o \l QDomDocument: Possible children are

   564             \list

   565             \o \l QDomElement (at most one)

   566             \o \l QDomProcessingInstruction

   567             \o \l QDomComment

   568             \o \l QDomDocumentType

   569             \endlist

   570     \o \l QDomDocumentFragment: Possible children are

   571             \list

   572             \o \l QDomElement

   573             \o \l QDomProcessingInstruction

   574             \o \l QDomComment

   575             \o \l QDomText

   576             \o \l QDomCDATASection

   577             \o \l QDomEntityReference

   578             \endlist

   579     \o \l QDomDocumentType: No children

   580     \o \l QDomEntityReference: Possible children are

   581             \list

   582             \o \l QDomElement

   583             \o \l QDomProcessingInstruction

   584             \o \l QDomComment

   585             \o \l QDomText

   586             \o \l QDomCDATASection

   587             \o \l QDomEntityReference

   588             \endlist

   589     \o \l QDomElement: Possible children are

   590             \list

   591             \o \l QDomElement

   592             \o \l QDomText

   593             \o \l QDomComment

   594             \o \l QDomProcessingInstruction

   595             \o \l QDomCDATASection

   596             \o \l QDomEntityReference

   597             \endlist

   598     \o \l QDomAttr: Possible children are

   599             \list

   600             \o \l QDomText

   601             \o \l QDomEntityReference

   602             \endlist

   603     \o \l QDomProcessingInstruction: No children

   604     \o \l QDomComment: No children

   605     \o \l QDomText: No children

   606     \o \l QDomCDATASection: No children

   607     \o \l QDomEntity: Possible children are

   608             \list

   609             \o \l QDomElement

   610             \o \l QDomProcessingInstruction

   611             \o \l QDomComment

   612             \o \l QDomText

   613             \o \l QDomCDATASection

   614             \o \l QDomEntityReference

   615             \endlist

   616     \o \l QDomNotation: No children

   617     \endlist

   618 

   619     With \l QDomNodeList and \l QDomNamedNodeMap two collection classes 

   620     are provided: \l QDomNodeList is a list of nodes,

   621     and \l QDomNamedNodeMap is used to handle unordered sets of nodes

   622     (often used for attributes).

   623 

   624     The \l QDomImplementation class allows the user to query features of the

   625     DOM implementation.

   626 

   627     To get started please refer to the \l QDomDocument documentation.

   628     You might also want to take a look at the \l{DOM Bookmarks example},

   629     which illustrates how to read and write an XML bookmark file (XBEL)

   630     using DOM.

   631 */