You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
574 lines
31 KiB
574 lines
31 KiB
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/xml.doc:36 -->
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>XML Module</title>
|
|
<style type="text/css"><!--
|
|
fn { margin-left: 1cm; text-indent: -1cm; }
|
|
a:link { color: #004faf; text-decoration: none }
|
|
a:visited { color: #672967; text-decoration: none }
|
|
body { background: #ffffff; color: black; }
|
|
--></style>
|
|
</head>
|
|
<body>
|
|
|
|
<table border="0" cellpadding="0" cellspacing="0" width="100%">
|
|
<tr bgcolor="#E5E5E5">
|
|
<td valign=center>
|
|
<a href="index.html">
|
|
<font color="#004faf">Home</font></a>
|
|
| <a href="classes.html">
|
|
<font color="#004faf">All Classes</font></a>
|
|
| <a href="mainclasses.html">
|
|
<font color="#004faf">Main Classes</font></a>
|
|
| <a href="annotated.html">
|
|
<font color="#004faf">Annotated</font></a>
|
|
| <a href="groups.html">
|
|
<font color="#004faf">Grouped Classes</font></a>
|
|
| <a href="functions.html">
|
|
<font color="#004faf">Functions</font></a>
|
|
</td>
|
|
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>XML Module</h1>
|
|
|
|
|
|
<p>
|
|
<p> <!-- toc -->
|
|
<ul>
|
|
<li><a href="#1"> Overview of the XML architecture in TQt
|
|
</a>
|
|
<li><a href="#2"> The TQt SAX2 classes
|
|
</a>
|
|
<ul>
|
|
<li><a href="#2-1"> Introduction to SAX2
|
|
</a>
|
|
<li><a href="#2-2"> Features
|
|
</a>
|
|
<li><a href="#2-3"> Namespace support via features
|
|
</a>
|
|
<ul>
|
|
<li><a href="#2-3-1"> Summary
|
|
</a>
|
|
</ul>
|
|
<li><a href="#2-4"> Properties
|
|
</a>
|
|
<li><a href="#2-5"> Further reading
|
|
</a>
|
|
</ul>
|
|
<li><a href="#3"> The TQt DOM classes
|
|
</a>
|
|
<ul>
|
|
<li><a href="#3-1"> Introduction to DOM
|
|
</a>
|
|
<li><a href="#3-2"> Further reading
|
|
</a>
|
|
</ul>
|
|
<li><a href="#4"> An introduction to namespaces
|
|
</a>
|
|
<ul>
|
|
<li><a href="#4-1"> Conventions used in TQt XML documentation
|
|
</a>
|
|
</ul>
|
|
</ul>
|
|
<!-- endtoc -->
|
|
|
|
<p> <a name="overview"></a>
|
|
<h2> Overview of the XML architecture in TQt
|
|
</h2>
|
|
<a name="1"></a><p> The XML module provides a well-formed XML parser using the SAX2
|
|
(Simple API for XML) interface plus an implementation of the DOM Level
|
|
2 (Document Object Model).
|
|
<p> SAX is an event-based standard interface for XML parsers.
|
|
The TQt interface follows the design of the SAX2 Java implementation.
|
|
Its naming scheme was adapted to fit the TQt naming conventions.
|
|
Details on SAX2 can be found at
|
|
<a href="http://www.saxproject.org">http://www.saxproject.org</a>.
|
|
<p> Support for SAX2 filters and the reader factory are under
|
|
development. The TQt implementation does not include the SAX1
|
|
compatibility classes present in the Java interface.
|
|
<p> For an introduction to TQt's SAX2 classes see
|
|
"<a href="#sax2">The TQt SAX2 classes</a>".
|
|
<p> DOM Level 2 is a W3C Recommendation for XML interfaces that maps the
|
|
constituents of an XML document to a tree structure. Details and the
|
|
specification of DOM Level 2 can be found at
|
|
<a href="http://www.w3.org/DOM/">http://www.w3.org/DOM/</a>.
|
|
More information about the DOM classes in TQt is provided in the
|
|
<a href="#dom">TQt DOM classes</a>.
|
|
<p> TQt provides the following XML related classes:
|
|
<p> <center><table cellpadding="4" cellspacing="2" border="0">
|
|
<tr bgcolor="#a2c511"> <th valign="top">Class <th valign="top">Short description
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomattr.html">TQDomAttr</a>
|
|
<td valign="top">Represents one attribute of a <a href="qdomelement.html">TQDomElement</a>
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomcdatasection.html">TQDomCDATASection</a>
|
|
<td valign="top">Represents an XML CDATA section
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomcharacterdata.html">TQDomCharacterData</a>
|
|
<td valign="top">Represents a generic string in the DOM
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomcomment.html">TQDomComment</a>
|
|
<td valign="top">Represents an XML comment
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomdocument.html">TQDomDocument</a>
|
|
<td valign="top">The representation of an XML document
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomdocumentfragment.html">TQDomDocumentFragment</a>
|
|
<td valign="top">Tree of TQDomNodes which is usually not a complete <a href="qdomdocument.html">TQDomDocument</a>
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomdocumenttype.html">TQDomDocumentType</a>
|
|
<td valign="top">The representation of the DTD in the document tree
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomelement.html">TQDomElement</a>
|
|
<td valign="top">Represents one element in the DOM tree
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomentity.html">TQDomEntity</a>
|
|
<td valign="top">Represents an XML entity
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomentityreference.html">TQDomEntityReference</a>
|
|
<td valign="top">Represents an XML entity reference
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomimplementation.html">TQDomImplementation</a>
|
|
<td valign="top">Information about the features of the DOM implementation
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomnamednodemap.html">TQDomNamedNodeMap</a>
|
|
<td valign="top">Collection of nodes that can be accessed by name
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomnode.html">TQDomNode</a>
|
|
<td valign="top">The base class for all nodes of the DOM tree
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomnodelist.html">TQDomNodeList</a>
|
|
<td valign="top">List of <a href="qdomnode.html">TQDomNode</a> objects
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomnotation.html">TQDomNotation</a>
|
|
<td valign="top">Represents an XML notation
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomprocessinginstruction.html">TQDomProcessingInstruction</a>
|
|
<td valign="top">Represents an XML processing instruction
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomtext.html">TQDomText</a>
|
|
<td valign="top">Represents textual data in the parsed XML document
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlattributes.html">TQXmlAttributes</a>
|
|
<td valign="top">XML attributes
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlcontenthandler.html">TQXmlContentHandler</a>
|
|
<td valign="top">Interface to report logical content of XML data
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmldeclhandler.html">TQXmlDeclHandler</a>
|
|
<td valign="top">Interface to report declaration content of XML data
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmldefaulthandler.html">TQXmlDefaultHandler</a>
|
|
<td valign="top">Default implementation of all XML handler classes
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmldtdhandler.html">TQXmlDTDHandler</a>
|
|
<td valign="top">Interface to report DTD content of XML data
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlentityresolver.html">TQXmlEntityResolver</a>
|
|
<td valign="top">Interface to resolve extern entities contained in XML data
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlerrorhandler.html">TQXmlErrorHandler</a>
|
|
<td valign="top">Interface to report errors in XML data
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlinputsource.html">TQXmlInputSource</a>
|
|
<td valign="top">The input data for the <a href="qxmlreader.html">TQXmlReader</a> subclasses
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmllexicalhandler.html">TQXmlLexicalHandler</a>
|
|
<td valign="top">Interface to report lexical content of XML data
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmllocator.html">TQXmlLocator</a>
|
|
<td valign="top">The XML handler classes with information about the actual parsing position
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlnamespacesupport.html">TQXmlNamespaceSupport</a>
|
|
<td valign="top">Helper class for XML readers which want to include namespace support
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlparseexception.html">TQXmlParseException</a>
|
|
<td valign="top">Used to report errors with the <a href="qxmlerrorhandler.html">TQXmlErrorHandler</a> interface
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlreader.html">TQXmlReader</a>
|
|
<td valign="top">Interface for XML readers (i.e. for SAX2 parsers)
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlsimplereader.html">TQXmlSimpleReader</a>
|
|
<td valign="top">Implementation of a simple XML reader (a SAX2 parser)
|
|
</table></center>
|
|
<p> <a name="sax2"></a>
|
|
<h2> The TQt SAX2 classes
|
|
</h2>
|
|
<a name="2"></a><p> <a name="sax2Intro"></a>
|
|
<h3> Introduction to SAX2
|
|
</h3>
|
|
<a name="2-1"></a><p> The SAX2 interface is an event-driven mechanism to provide the user with
|
|
document information. An "event" in this context means something
|
|
reported by the parser, for example, it has encountered a start tag,
|
|
or an end tag, etc.
|
|
<p> To make it less abstract consider the following example:
|
|
<pre>
|
|
<quote>A quotation.</quote>
|
|
</pre>
|
|
|
|
<p> Whilst reading (a SAX2 parser is usually referred to as "reader")
|
|
the above document three events would be triggered:
|
|
<ol type=1>
|
|
<li> A start tag occurs (<tt><quote></tt>).
|
|
<li> Character data (i.e. text) is found, "A quotation.".
|
|
<li> An end tag is parsed (<tt></quote></tt>).
|
|
</ol>
|
|
<p> Each time such an event occurs the parser reports it; you can set up
|
|
event handlers to respond to these events.
|
|
<p> 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 <a href="#dom">DOM interface</a> 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..
|
|
<p> The TQt XML module provides an abstract class, <a href="qxmlreader.html">TQXmlReader</a>, that
|
|
defines the interface for potential SAX2 readers. TQt includes a reader
|
|
implementation, <a href="qxmlsimplereader.html">TQXmlSimpleReader</a>, that is easy to adapt through
|
|
subclassing.
|
|
<p> The reader reports parsing events through special handler classes:
|
|
<center><table cellpadding="4" cellspacing="2" border="0">
|
|
<tr bgcolor="#a2c511"> <th valign="top">Handler class <th valign="top">Description
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlcontenthandler.html">TQXmlContentHandler</a>
|
|
<td valign="top">Reports events related to the content of a document (e.g. the start tag
|
|
or characters).
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmldtdhandler.html">TQXmlDTDHandler</a>
|
|
<td valign="top">Reports events related to the DTD (e.g. notation declarations).
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlerrorhandler.html">TQXmlErrorHandler</a>
|
|
<td valign="top">Reports errors or warnings that occurred during parsing.
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlentityresolver.html">TQXmlEntityResolver</a>
|
|
<td valign="top">Reports external entities during parsing and allows users to resolve
|
|
external entities themselves instead of leaving it to the reader.
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmldeclhandler.html">TQXmlDeclHandler</a>
|
|
<td valign="top">Reports further DTD related events (e.g. attribute declarations).
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmllexicalhandler.html">TQXmlLexicalHandler</a>
|
|
<td valign="top">Reports events related to the lexical structure of the
|
|
document (the beginning of the DTD, comments etc.).
|
|
</table></center>
|
|
<p> These classes are abstract classes describing the interface. The <a href="qxmldefaulthandler.html">TQXmlDefaultHandler</a> class provides a "do nothing" default
|
|
implementation for all of them. Therefore users only need to overload
|
|
the <a href="qxmldefaulthandler.html">TQXmlDefaultHandler</a> functions they are interested in.
|
|
<p> To read input XML data a special class <a href="qxmlinputsource.html">TQXmlInputSource</a> is used.
|
|
<p> Apart from those already mentioned, the following SAX2 support classes
|
|
provide additional useful functionality:
|
|
<center><table cellpadding="4" cellspacing="2" border="0">
|
|
<tr bgcolor="#a2c511"> <th valign="top">Class <th valign="top">Description
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlattributes.html">TQXmlAttributes</a>
|
|
<td valign="top">Used to pass attributes in a start element event.
|
|
<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmllocator.html">TQXmlLocator</a>
|
|
<td valign="top">Used to obtain the actual parsing position of an event.
|
|
<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlnamespacesupport.html">TQXmlNamespaceSupport</a>
|
|
<td valign="top">Used to implement <a href="xml.html#namespaces">namespace</a>
|
|
support for a reader. Note that namespaces do not change the
|
|
parsing behavior. They are only reported through the handler.
|
|
</table></center>
|
|
<p> <a name="sax2Features"></a>
|
|
<h3> Features
|
|
</h3>
|
|
<a name="2-2"></a><p> The behaviour of an XML reader depends on its support for certain
|
|
optional features. For example, a reader may have the feature "report
|
|
attributes used for <a href="xml.html#namespaces">namespace</a>
|
|
declarations and prefixes along with the local name of a tag". Like
|
|
every other feature this has a unique name represented by a URI: it is
|
|
called <em>http://xml.org/sax/features/namespace-prefixes</em>.
|
|
<p> The TQt SAX2 implementation can report whether the reader has
|
|
particular functionality using the <a href="qxmlreader.html#hasFeature">TQXmlReader::hasFeature</a>()
|
|
function. Available features can be tested with <a href="qxmlreader.html#feature">TQXmlReader::feature</a>(),
|
|
and switched on or off using <a href="qxmlreader.html#setFeature">TQXmlReader::setFeature</a>().
|
|
<p> Consider the example
|
|
<pre>
|
|
<document xmlns:book = 'http://trolltech.com/fnord/book/'
|
|
xmlns = 'http://trolltech.com/fnord/' >
|
|
</pre>
|
|
|
|
A reader that does not support the <em>http://xml.org/sax/features/namespace-prefixes</em> feature would report
|
|
the element name <em>document</em> but not its attributes <em>xmlns:book</em> and
|
|
<em>xmlns</em> with their values. A reader with the feature <em>http://xml.org/sax/features/namespace-prefixes</em> reports the namespace
|
|
attributes if the <a href="qxmlreader.html#feature">feature</a> is
|
|
switched on.
|
|
<p> Other features include <em>http://xml.org/sax/features/namespace</em>
|
|
(namespace processing, implies <em>http://xml.org/sax/features/namespace-prefixes</em>) and <em>http://xml.org/sax/features/validation</em> (the ability to report
|
|
validation errors).
|
|
<p> Whilst SAX2 leaves it to the user to define and implement whatever
|
|
features are required, support for <em>http://xml.org/sax/features/namespace</em> (and thus <em>http://xml.org/sax/features/namespace-prefixes</em>) is mandantory.
|
|
The <a href="qxmlsimplereader.html">TQXmlSimpleReader</a> implementation of <a href="qxmlreader.html">TQXmlReader</a>,
|
|
supports them, and can do namespace processing.
|
|
<p> <a href="qxmlsimplereader.html">TQXmlSimpleReader</a> is not validating, so it
|
|
does not support <em>http://xml.org/sax/features/validation</em>.
|
|
<p> <a name="sax2Namespaces"></a>
|
|
<h3> Namespace support via features
|
|
</h3>
|
|
<a name="2-3"></a><p> As we have seen in the <a href="#sax2Features">previous section</a>
|
|
we can configure the behavior of the reader when it comes to namespace
|
|
processing. This is done by setting and unsetting the
|
|
<em>http://xml.org/sax/features/namespaces</em> and
|
|
<em>http://xml.org/sax/features/namespace-prefixes</em> features.
|
|
<p> They influence the reporting behavior in the following way:
|
|
<ol type=1>
|
|
<li> Namespace prefixes and local parts of elements and attributes can
|
|
be reported.
|
|
<li> The qualified names of elements and attributes are reported.
|
|
<li> <a href="qxmlcontenthandler.html#startPrefixMapping">TQXmlContentHandler::startPrefixMapping</a>() and <a href="qxmlcontenthandler.html#endPrefixMapping">TQXmlContentHandler::endPrefixMapping</a>() are called by the reader.
|
|
<li> Attributes that declare namespaces (i.e. the attribute <em>xmlns</em> and
|
|
attributes starting with <em>xmlns:</em>) are reported.
|
|
</ol>
|
|
<p> Consider the following element:
|
|
<pre>
|
|
<author xmlns:fnord = 'http://trolltech.com/fnord/'
|
|
title="Ms"
|
|
fnord:title="Goddess"
|
|
name="Eris Kallisti"/>
|
|
</pre>
|
|
|
|
With <em>http://xml.org/sax/features/namespace-prefixes</em> set to TRUE
|
|
the reader will report four attributes; but with the <em>namespace-prefixes</em> feature set to FALSE only three, with the <em>xmlns:fnord</em> attribute defining a namespace being "invisible" to the
|
|
reader.
|
|
<p> The <em>http://xml.org/sax/features/namespaces</em> feature is responsible
|
|
for reporting local names, namespace prefixes and URIs. With <em>http://xml.org/sax/features/namespaces</em> set to TRUE the parser will
|
|
report <em>title</em> as the local name of the <em>fnord:title</em> attribute, <em>fnord</em> being the namespace prefix and <em>http://trolltech.com/fnord/</em> as
|
|
the namespace URI. When <em>http://xml.org/sax/features/namespaces</em> is
|
|
FALSE none of them are reported.
|
|
<p> In the current implementation the TQt XML classes follow the definition
|
|
that the prefix <em>xmlns</em> itself isn't associated with any namespace at all
|
|
(see <a href="http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-using">http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-using</a>).
|
|
Therefore even with <em>http://xml.org/sax/features/namespaces</em> and
|
|
<em>http://xml.org/sax/features/namespace-prefixes</em> both set to TRUE
|
|
the reader won't return either a local name, a namespace prefix or
|
|
a namespace URI for <em>xmlns:fnord</em>.
|
|
<p> This might be changed in the future following the W3C suggestion
|
|
<a href="http://www.w3.org/2000/xmlns/">http://www.w3.org/2000/xmlns/</a>
|
|
to associate <em>xmlns</em> with the namespace <em>http://www.w3.org/2000/xmlns</em>.
|
|
<p> As the SAX2 standard suggests, <a href="qxmlsimplereader.html">TQXmlSimpleReader</a> defaults to having
|
|
<em>http://xml.org/sax/features/namespaces</em> set to TRUE and
|
|
<em>http://xml.org/sax/features/namespace-prefixes</em> set to FALSE.
|
|
When changing this behavior using <a href="qxmlsimplereader.html#setFeature">TQXmlSimpleReader::setFeature</a>()
|
|
note that the combination of both features set to
|
|
FALSE is illegal.
|
|
<p> For a practical demonstration of how the two features affect the
|
|
output of the reader run the <a href="tagreader-with-features-example.html">tagreader with features example.</a>
|
|
<p> <a name="sax2NamespacesSummary"></a>
|
|
<h4> Summary
|
|
</h4>
|
|
<a name="2-3-1"></a><p> <a href="qxmlsimplereader.html">TQXmlSimpleReader</a> implements the following behavior:
|
|
<p> <center><table cellpadding="4" cellspacing="2" border="0">
|
|
<tr bgcolor="#a2c511"> <th valign="top">(namespaces, namespace-prefixes)
|
|
<th valign="top">Namespace prefix and local part
|
|
<th valign="top">Qualified names
|
|
<th valign="top">Prefix mapping
|
|
<th valign="top">xmlns attributes
|
|
<tr bgcolor="#f0f0f0"> <td valign="top">(TRUE, FALSE) <td valign="top">Yes <td valign="top">Yes* <td valign="top">Yes <td valign="top">No
|
|
<tr bgcolor="#d0d0d0"> <td valign="top">(TRUE, TRUE) <td valign="top">Yes <td valign="top">Yes <td valign="top">Yes <td valign="top">Yes
|
|
<tr bgcolor="#f0f0f0"> <td valign="top">(FALSE, TRUE) <td valign="top">No* <td valign="top">Yes <td valign="top">No* <td valign="top">Yes
|
|
<tr bgcolor="#d0d0d0"> <td valign="top">(FALSE, FALSE) <td valign="top" colspan="4" rowspan="1"> Illegal
|
|
</table></center>
|
|
<p> <sup>*</sup> The behavior of these entries is not specified by SAX.
|
|
<p> <a name="sax2Properties"></a>
|
|
<h3> Properties
|
|
</h3>
|
|
<a name="2-4"></a><p> Properties are a more general concept. They have a unique name,
|
|
represented as an URI, but their value is <tt>void*</tt>. Thus nearly
|
|
anything can be used as a property value. This concept involves some
|
|
danger, though: there is no means of ensuring type-safety; the user
|
|
must take care that they pass the right type. Properties are
|
|
useful if a reader supports special handler classes.
|
|
<p> The URIs used for features and properties often look like URLs, e.g.
|
|
<a href="http://xml.org/sax/features/namespace">http://xml.org/sax/features/namespace</a>. This does not mean that the
|
|
data required is at this address. It is simply a way of defining
|
|
unique names.
|
|
<p> Anyone can define and use new SAX2 properties for their readers.
|
|
Property support is not mandatory.
|
|
<p> To set or query properties the following functions are provided: <a href="qxmlreader.html#setProperty">TQXmlReader::setProperty</a>(), <a href="qxmlreader.html#property">TQXmlReader::property</a>() and <a href="qxmlreader.html#hasProperty">TQXmlReader::hasProperty</a>().
|
|
<p> <a name="sax2Reading"></a>
|
|
<h3> Further reading
|
|
</h3>
|
|
<a name="2-5"></a><p> More information about XML (e.g. <a href="xml.html#namespaces">namespaces</a>)
|
|
can be found in the <a href="xml.html">introduction to the TQt XML module.</a>
|
|
<p> <a name="dom"></a>
|
|
<h2> The TQt DOM classes
|
|
</h2>
|
|
<a name="3"></a><p> <a name="domIntro"></a>
|
|
<h3> Introduction to DOM
|
|
</h3>
|
|
<a name="3-1"></a><p> DOM provides an interface to access and change the content and
|
|
structure of an XML file. It makes a hierarchical view of the document
|
|
(a tree view). Thus -- in contrast to the SAX2 interface -- an object
|
|
model of the document is resident in memory after parsing which makes
|
|
manipulation easy.
|
|
<p> All DOM nodes in the document tree are subclasses of <a href="qdomnode.html">TQDomNode</a>. The
|
|
document itself is represented as a <a href="qdomdocument.html">TQDomDocument</a> object.
|
|
<p> Here are the available node classes and their potential child classes:
|
|
<p> <ul>
|
|
<li> <a href="qdomdocument.html">TQDomDocument</a>: Possible children are
|
|
<ul>
|
|
<li> <a href="qdomelement.html">TQDomElement</a> (at most one)
|
|
<li> <a href="qdomprocessinginstruction.html">TQDomProcessingInstruction</a>
|
|
<li> <a href="qdomcomment.html">TQDomComment</a>
|
|
<li> <a href="qdomdocumenttype.html">TQDomDocumentType</a>
|
|
</ul>
|
|
<li> <a href="qdomdocumentfragment.html">TQDomDocumentFragment</a>: Possible children are
|
|
<ul>
|
|
<li> <a href="qdomelement.html">TQDomElement</a>
|
|
<li> <a href="qdomprocessinginstruction.html">TQDomProcessingInstruction</a>
|
|
<li> <a href="qdomcomment.html">TQDomComment</a>
|
|
<li> <a href="qdomtext.html">TQDomText</a>
|
|
<li> <a href="qdomcdatasection.html">TQDomCDATASection</a>
|
|
<li> <a href="qdomentityreference.html">TQDomEntityReference</a>
|
|
</ul>
|
|
<li> <a href="qdomdocumenttype.html">TQDomDocumentType</a>: No children
|
|
<li> <a href="qdomentityreference.html">TQDomEntityReference</a>: Possible children are
|
|
<ul>
|
|
<li> <a href="qdomelement.html">TQDomElement</a>
|
|
<li> <a href="qdomprocessinginstruction.html">TQDomProcessingInstruction</a>
|
|
<li> <a href="qdomcomment.html">TQDomComment</a>
|
|
<li> <a href="qdomtext.html">TQDomText</a>
|
|
<li> <a href="qdomcdatasection.html">TQDomCDATASection</a>
|
|
<li> <a href="qdomentityreference.html">TQDomEntityReference</a>
|
|
</ul>
|
|
<li> <a href="qdomelement.html">TQDomElement</a>: Possible children are
|
|
<ul>
|
|
<li> <a href="qdomelement.html">TQDomElement</a>
|
|
<li> <a href="qdomtext.html">TQDomText</a>
|
|
<li> <a href="qdomcomment.html">TQDomComment</a>
|
|
<li> <a href="qdomprocessinginstruction.html">TQDomProcessingInstruction</a>
|
|
<li> <a href="qdomcdatasection.html">TQDomCDATASection</a>
|
|
<li> <a href="qdomentityreference.html">TQDomEntityReference</a>
|
|
</ul>
|
|
<li> <a href="qdomattr.html">TQDomAttr</a>: Possible children are
|
|
<ul>
|
|
<li> <a href="qdomtext.html">TQDomText</a>
|
|
<li> <a href="qdomentityreference.html">TQDomEntityReference</a>
|
|
</ul>
|
|
<li> <a href="qdomprocessinginstruction.html">TQDomProcessingInstruction</a>: No children
|
|
<li> <a href="qdomcomment.html">TQDomComment</a>: No children
|
|
<li> <a href="qdomtext.html">TQDomText</a>: No children
|
|
<li> <a href="qdomcdatasection.html">TQDomCDATASection</a>: No children
|
|
<li> <a href="qdomentity.html">TQDomEntity</a>: Possible children are
|
|
<ul>
|
|
<li> <a href="qdomelement.html">TQDomElement</a>
|
|
<li> <a href="qdomprocessinginstruction.html">TQDomProcessingInstruction</a>
|
|
<li> <a href="qdomcomment.html">TQDomComment</a>
|
|
<li> <a href="qdomtext.html">TQDomText</a>
|
|
<li> <a href="qdomcdatasection.html">TQDomCDATASection</a>
|
|
<li> <a href="qdomentityreference.html">TQDomEntityReference</a>
|
|
</ul>
|
|
<li> <a href="qdomnotation.html">TQDomNotation</a>: No children
|
|
</ul>
|
|
<p> With <a href="qdomnodelist.html">TQDomNodeList</a> and <a href="qdomnamednodemap.html">TQDomNamedNodeMap</a> two <a href="collection.html#collection-classes">collection classes</a>
|
|
are provided: <a href="qdomnodelist.html">TQDomNodeList</a> is a list of nodes,
|
|
and <a href="qdomnamednodemap.html">TQDomNamedNodeMap</a> is used to handle unordered sets of nodes
|
|
(often used for attributes).
|
|
<p> The <a href="qdomimplementation.html">TQDomImplementation</a> class allows the user to query features of the
|
|
DOM implementation.
|
|
<p> <h3> Further reading
|
|
</h3>
|
|
<a name="3-2"></a><p> To get started please refer to the <a href="qdomdocument.html">TQDomDocument</a> documentation.
|
|
<p> <a name="namespaces"></a>
|
|
<h2> An introduction to namespaces
|
|
</h2>
|
|
<a name="4"></a><p> Parts of the TQt XML module documentation assume that you are familiar
|
|
with XML namespaces. Here we present a brief introduction; skip to
|
|
<a href="#namespacesConventions">TQt XML documentation conventions</a>
|
|
if you already know this material.
|
|
<p> 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.
|
|
<p> Consider the following example:
|
|
<p> <pre>
|
|
<document>
|
|
<book>
|
|
<title>Practical XML</title>
|
|
<author title="Ms" name="Eris Kallisti"/>
|
|
<chapter>
|
|
<title>A Namespace Called fnord</title>
|
|
</chapter>
|
|
</book>
|
|
</document>
|
|
</pre>
|
|
|
|
<p> Here we find three different uses of the name <em>title</em>. If you wish to
|
|
process this document you will encounter problems because each of the
|
|
<em>titles</em> should be displayed in a different manner -- even though
|
|
they have the same name.
|
|
<p> The solution would be to have some means of identifying the first
|
|
occurrence of <em>title</em> as the title of a book, i.e. to use the <em>title</em> element of a book namespace to distinguish it from, for example,
|
|
the chapter title, e.g.:
|
|
<pre>
|
|
<book:title>Practical XML</book:title>
|
|
</pre>
|
|
|
|
<p> <em>book</em> in this case is a <em>prefix</em> denoting the namespace.
|
|
<p> Before we can apply a namespace to element or attribute names we must
|
|
declare it.
|
|
<p> Namespaces are URIs like <em>http://trolltech.com/fnord/book/</em>. This
|
|
does not mean that data must be available at this address; the URI is
|
|
simply used to provide a unique name.
|
|
<p> We declare namespaces in the same way as attributes; strictly speaking
|
|
they <em>are</em> attributes. To make for example <em>http://trolltech.com/fnord/</em> the document's default XML namespace <em>xmlns</em> we write
|
|
<p> <pre>
|
|
xmlns="http://trolltech.com/fnord/"
|
|
</pre>
|
|
|
|
<p> To distinguish the <em>http://trolltech.com/fnord/book/</em> namespace from
|
|
the default, we must supply it with a prefix:
|
|
<p> <pre>
|
|
xmlns:book="http://trolltech.com/fnord/book/"
|
|
</pre>
|
|
|
|
<p> A namespace that is declared like this can be applied to element and
|
|
attribute names by prepending the appropriate prefix and a ":"
|
|
delimiter. We have already seen this with the <em>book:title</em> element.
|
|
<p> 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.
|
|
<p> Due to the fact that attributes without prefixes are not in any XML
|
|
namespace there is no collision between the attribute <em>title</em> (that
|
|
belongs to the <em>author</em> element) and for example the <em>title</em> element
|
|
within a <em>chapter</em>.
|
|
<p> Let's clarify this with an example:
|
|
<pre>
|
|
<document xmlns:book = 'http://trolltech.com/fnord/book/'
|
|
xmlns = 'http://trolltech.com/fnord/' >
|
|
<book>
|
|
<book:title>Practical XML</book:title>
|
|
<book:author xmlns:fnord = 'http://trolltech.com/fnord/'
|
|
title="Ms"
|
|
fnord:title="Goddess"
|
|
name="Eris Kallisti"/>
|
|
<chapter>
|
|
<title>A Namespace Called fnord</title>
|
|
</chapter>
|
|
</book>
|
|
</document>
|
|
</pre>
|
|
|
|
<p> Within the <em>document</em> element we have two namespaces declared. The
|
|
default namespace <em>http://trolltech.com/fnord/</em> applies to the <em>book</em> element, the <em>chapter</em> element, the appropriate <em>title</em> element
|
|
and of course to <em>document</em> itself.
|
|
<p> The <em>book:author</em> and <em>book:title</em> elements belong to the namespace
|
|
with the URI <em>http://trolltech.com/fnord/book/</em>.
|
|
<p> The two <em>book:author</em> attributes <em>title</em> and <em>name</em> have no XML
|
|
namespace assigned. They are only members of the "traditional"
|
|
namespace of the element <em>book:author</em>, meaning that for example two
|
|
<em>title</em> attributes in <em>book:author</em> are forbidden.
|
|
<p> In the above example we circumvent the last rule by adding a <em>title</em>
|
|
attribute from the <em>http://trolltech.com/fnord/</em> namespace to <em>book:author</em>: the <em>fnord:title</em> comes from the namespace with the
|
|
prefix <em>fnord</em> that is declared in the <em>book:author</em> element.
|
|
<p> Clearly the <em>fnord</em> 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:
|
|
<ul>
|
|
<li> attributes without a prefix don't belong to any XML namespace at
|
|
all, not even to the default namespace;
|
|
<li> additionally omitting the prefix would lead to a <em>title-title</em> clash;
|
|
<li> writing it as <em>xmlns:title</em> would declare a new namespace with the
|
|
prefix <em>title</em> instead of applying the default <em>xmlns</em> namespace.
|
|
</ul>
|
|
<p> With the TQt XML classes elements and attributes can be accessed in two
|
|
ways: either by refering to their qualified names consisting of the
|
|
namespace prefix and the "real" name (or <em>local</em> name) or by the
|
|
combination of local name and namespace URI.
|
|
<p> More information on XML namespaces can be found at
|
|
<a href="http://www.w3.org/TR/REC-xml-names/">http://www.w3.org/TR/REC-xml-names/</a>.
|
|
<p> <a name="namespacesConventions"></a>
|
|
<h3> Conventions used in TQt XML documentation
|
|
</h3>
|
|
<a name="4-1"></a><p> The following terms are used to distinguish the parts of names within
|
|
the context of namespaces:
|
|
<ul>
|
|
<li> The <em>qualified name</em>
|
|
is the name as it appears in the document. (In the above example <em>book:title</em> is a qualified name.)
|
|
<li> A <em>namespace prefix</em> in a qualified name
|
|
is the part to the left of the ":". (<em>book</em> is the namespace prefix in
|
|
<em>book:title</em>.)
|
|
<li> The <em>local part</em> of a name (also refered to as the <em>local name</em>) appears to the right of the ":". (Thus <em>title</em> is the
|
|
local part of <em>book:title</em>.)
|
|
<li> The <em>namespace URI</em> ("Uniform Resource Identifier") is a unique
|
|
identifier for a namespace. It looks like a URL
|
|
(e.g. <em>http://trolltech.com/fnord/</em> ) but does not require
|
|
data to be accessible by the given protocol at the named address.
|
|
</ul>
|
|
<p> Elements without a ":" (like <em>chapter</em> in the example) do not have a
|
|
namespace prefix. In this case the local part and the qualified name
|
|
are identical (i.e. <em>chapter</em>).
|
|
|
|
<!-- eof -->
|
|
<p><address><hr><div align=center>
|
|
<table width=100% cellspacing=0 border=0><tr>
|
|
<td>Copyright © 2007
|
|
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
|
|
<td align=right><div align=right>TQt 3.3.8</div>
|
|
</table></div></address></body>
|
|
</html>
|