<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- /tmp/qt-3.0-reggie-28534/qt-x11-free-3.0.2/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"><!--
h3.fn,span.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> This module is part of the <a href="editions.html">Qt Enterprise Edition</a>.
<p> <!-- toc -->
<ul>
<li><a href="#1"> Overview of the XML architecture in Qt
</a>
<li><a href="#2"> The Qt 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 Qt 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 Qt XML documentation
</a>
</ul>
</ul>
<!-- endtoc -->
<p> <a name="overview"></a>
<h2> Overview of the XML architecture in Qt
</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 Qt interface follows the design of the SAX2 Java implementation.
Its naming scheme was adapted to fit the Qt naming conventions.
Details on SAX2 can be found at
<a href="http://www.megginson.com/SAX/">http://www.megginson.com/SAX/</a>.
<p> Support for SAX2 filters and the reader factory are under
development. Furthermore the Qt implementation does not include the
SAX1 compatibility classes present in the Java interface.
<p> For an introduction to Qt's SAX2 classes see
"<a href="#sax2">The Qt SAX2 classes</a>".
A code example is discussed in the "<a href="xml-sax-walkthrough.html">tagreader
walkthrough</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 Qt is provided in the
<a href="#dom">Qt DOM classes</a>.
<p> Qt provides the following XML related classes:
<p> <ul>
<li> <a href="qdomattr.html">QDomAttr</a> -- Represents one attribute of a <a href="qdomelement.html">QDomElement</a>
<li> <a href="qdomcdatasection.html">QDomCDATASection</a> -- Represents an XML CDATA section
<li> <a href="qdomcharacterdata.html">QDomCharacterData</a> -- Represents a generic string in the DOM
<li> <a href="qdomcomment.html">QDomComment</a> -- Represents an XML comment
<li> <a href="qdomdocument.html">QDomDocument</a> -- The representation of an XML document
<li> <a href="qdomdocumentfragment.html">QDomDocumentFragment</a> -- Tree of QDomNodes which is usually not a complete <a href="qdomdocument.html">QDomDocument</a>
<li> <a href="qdomdocumenttype.html">QDomDocumentType</a> -- The representation of the DTD in the document tree
<li> <a href="qdomelement.html">QDomElement</a> -- Represents one element in the DOM tree
<li> <a href="qdomentity.html">QDomEntity</a> -- Represents an XML entity
<li> <a href="qdomentityreference.html">QDomEntityReference</a> -- Represents an XML entity reference
<li> <a href="qdomimplementation.html">QDomImplementation</a> -- Information about the features of the DOM implementation
<li> <a href="qdomnamednodemap.html">QDomNamedNodeMap</a> -- Collection of nodes that can be accessed by name
<li> <a href="qdomnode.html">QDomNode</a> -- The base class for all nodes of the DOM tree
<li> <a href="qdomnodelist.html">QDomNodeList</a> -- List of <a href="qdomnode.html">QDomNode</a> objects
<li> <a href="qdomnotation.html">QDomNotation</a> -- Represents an XML notation
<li> <a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a> -- Represents an XML processing instruction
<li> <a href="qdomtext.html">QDomText</a> -- Represents textual data in the parsed XML document
<li> <a href="qxmlattributes.html">QXmlAttributes</a> -- XML attributes
<li> <a href="qxmlcontenthandler.html">QXmlContentHandler</a> -- Interface to report logical content of XML data
<li> <a href="qxmldeclhandler.html">QXmlDeclHandler</a> -- Interface to report declaration content of XML data
<li> <a href="qxmldefaulthandler.html">QXmlDefaultHandler</a> -- Default implementation of all XML handler classes
<li> <a href="qxmldtdhandler.html">QXmlDTDHandler</a> -- Interface to report DTD content of XML data
<li> <a href="qxmlentityresolver.html">QXmlEntityResolver</a> -- Interface to resolve extern entities contained in XML data
<li> <a href="qxmlerrorhandler.html">QXmlErrorHandler</a> -- Interface to report errors in XML data
<li> <a href="qxmlinputsource.html">QXmlInputSource</a> -- The input data for the <a href="qxmlreader.html">QXmlReader</a> subclasses
<li> <a href="qxmllexicalhandler.html">QXmlLexicalHandler</a> -- Interface to report lexical content of XML data
<li> <a href="qxmllocator.html">QXmlLocator</a> -- The XML handler classes with information about the actual parsing position
<li> <a href="qxmlnamespacesupport.html">QXmlNamespaceSupport</a> -- Helper class for XML readers which want to include namespace support
<li> <a href="qxmlparseexception.html">QXmlParseException</a> -- Used to report errors with the <a href="qxmlerrorhandler.html">QXmlErrorHandler</a> interface
<li> <a href="qxmlreader.html">QXmlReader</a> -- Interface for XML readers (i.e. for SAX2 parsers)
<li> <a href="qxmlsimplereader.html">QXmlSimpleReader</a> -- Implementation of a simple XML reader (a SAX2 parser)
</ul>
<p> <a name="sax2"></a>
<h2> The Qt 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. "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 parsing the document.
These reported information is referred to as "event".
<p> To make it less abstract consider the following example:
<pre>
<quote>To make it less abstract consider the following example:</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.
<li> An end tag is parsed (<tt></quote></tt>).
</ol>
<p> Each time such an event occurs the parser reports it so that
a suitable event handling routine can be invoked.
<p> Whilst this is a fast and simple approach to read XML documents
manipulation is difficult because data are not stored, simply handled
and discarded serially. This is when the <a href="#dom">DOM interface</a> comes handy.
<p> The Qt XML module provides an
abstract class, <a href="qxmlreader.html">QXmlReader</a>, that defines the interface for potential
SAX2 readers.
At the moment Qt ships with one reader implementation, <a href="qxmlsimplereader.html">QXmlSimpleReader</a>.
<p> The reader reports parsing events through special handler classes. In Qt
the following ones are available:
<ul>
<li> <a href="qxmlcontenthandler.html">QXmlContentHandler</a>
reports events related to the content of a document (e.g. the start tag
or characters).
<li> <a href="qxmldtdhandler.html">QXmlDTDHandler</a>
reports events related to the DTD (e.g. notation declarations).
<li> <a href="qxmlerrorhandler.html">QXmlErrorHandler</a>
reports errors or warnings that occurred during parsing.
<li> <a href="qxmlentityresolver.html">QXmlEntityResolver</a>
reports external entities during parsing and allows the user to resolve
external entities him- or herself instead of leaving it to the reader.
<li> <a href="qxmldeclhandler.html">QXmlDeclHandler</a>
reports further DTD related events (e.g. attribute declarations).
Usually users are not interested in them, but under certain circumstances
this class comes handy.
<li> <a href="qxmllexicalhandler.html">QXmlLexicalHandler</a>
reports events related to the lexical structure of the document
(the beginning of the DTD, comments etc.). Occasionally this
might be useful.
</ul>
<p> These classes are abstract classes describing the interface. The
<a href="qxmldefaulthandler.html">QXmlDefaultHandler</a> class provides a "do nothing" default implementation for
all of them. Therefore users need to overload only the
<a href="qxmldefaulthandler.html">QXmlDefaultHandler</a> functions they are interested in.
<p> To read input XML data a special class <a href="qxmlinputsource.html">QXmlInputSource</a> is used.
<p> Apart from the already mentioned ones the following SAX2 support classes
provide the user with useful functionality:
<ul>
<li> <a href="qxmlattributes.html">QXmlAttributes</a>
is used to pass attributes in a start element event.
<li> <a href="qxmllocator.html">QXmlLocator</a>
is used to obtain the actual parsing position of an event.
<li> <a href="qxmlnamespacesupport.html">QXmlNamespaceSupport</a>
is used to easily 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.
</ul>
<p> <a name="sax2Features"></a>
<h3> Features
</h3>
<a name="2-2"></a><p> The behaviour of an XML reader depends on whether it supports certain
optional features or not.
As an example a reader can 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 Qt SAX2 implementation allows you to find out whether the
reader has this ability using <a href="qxmlreader.html#hasFeature">QXmlReader::hasFeature</a>().
If the return value is TRUE it is possible to
turn the relevant feature on and off.
To do this use <a href="qxmlreader.html#setFeature">QXmlReader::setFeature</a>(). Whether a supported feature
is on or off (TRUE or FALSE) can be queried using <a href="qxmlreader.html#feature">QXmlReader::feature</a>().
<p> Consider the example
<pre>
<document xmlns:book = 'http://trolltech.com/fnord/book/'
xmlns = 'http://trolltech.com/fnord/' >
</pre>
A reader not supporting the
<em>http://xml.org/sax/features/namespace-prefixes</em> feature would clearly
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 <a href="qxmlreader.html#feature">QXmlReader::feature</a>() is TRUE and
disregards them if the feature is FALSE.
<p> Other features include <em>http://xml.org/sax/features/namespace</em> (namespace
processing, implies <em>http://xml.org/sax/features/namespace-prefixes</em>) or
<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. Accordingly <a href="qxmlsimplereader.html">QXmlSimpleReader</a>, the implementation
of <a href="qxmlreader.html">QXmlReader</a> that comes with the Qt XML module, supports both of them,
and therefore can do namespace processing.
<p> Being a non-validating parser <a href="qxmlsimplereader.html">QXmlSimpleReader</a>
does not support <em>http://xml.org/sax/features/validation</em>
and other features.
<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">QXmlContentHandler::startPrefixMapping</a>() and <a href="qxmlcontenthandler.html#endPrefixMapping">QXmlContentHandler::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:
<p> <pre>
<author xmlns:fnord = 'http://trolltech.com/fnord/'
title="Ms"
fnord:title="Goddess"
name="Eris Kallisti"/>
</pre>
<p> With <em>http://xml.org/sax/features/namespace-prefixes</em> set to TRUE
the reader will report four attributes, with the <em>namespace-prefixes</em>
feature set to FALSE only three: The <em>xmlns:fnord</em> attribute defining
a namespace is then "unvisible" for the reader.
<p> The <em>http://xml.org/sax/features/namespaces</em> feature on the other hand
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 <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 Qt 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">QXmlSimpleReader</a> by default has
<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="qxmlreader.html#setFeature">QXmlSimpleReader::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">QXmlSimpleReader</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> For the entries marked with a "*", SAX does not require a particuliar
behavior.
<p> <a name="sax2Properties"></a>
<h3> Properties
</h3>
<a name="2-4"></a><p> Properties are a more general concept. They also have a unique name,
represented as an URI, but their value is <tt>void*</tt>. Thus nearly everything
can be used as a property value. This concept involves some danger,
though: there are no means to ensure type-safety; the user must take care
that he or she passes the correct type. Properties are useful if a reader supports
special handler classes.
<p>
<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 whatsoever
data is required at this address. It is simply a way to define unique names.
<p> Everybody can define and use new SAX2 properties for his or her
readers. Property support is however not
required.
<p> To set or query properties the following functions are provided:
<a href="qxmlreader.html#setProperty">QXmlReader::setProperty</a>(), <a href="qxmlreader.html#property">QXmlReader::property</a>() and <a href="qxmlreader.html#hasProperty">QXmlReader::hasProperty</a>().
<p> <a name="sax2Reading"></a>
<h3> Further reading
</h3>
<a name="2-5"></a><p> For a practical example on how to use the Qt SAX2 classes see the
<a href="xml-sax-walkthrough.html">tagreader walkthrough.</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 Qt XML module.</a>
<p> <a name="dom"></a>
<h2> The Qt 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 (tree)
available with the root element of the XML file serving as its root.
Thus -- in contrast to the SAX2 interface -- an object model of the document
is resident in memory after parsing which makes manipulation easy.
<p> In the Qt implementation of the DOM all
nodes in the document tree are subclasses of <a href="qdomnode.html">QDomNode</a>.
The document itself is represented as a <a href="qdomdocument.html">QDomDocument</a> object.
<p> Here are the available node classes and their potential children classes:
<p> <ul>
<li> <a href="qdomdocument.html">QDomDocument</a>: Possible children are
<ul>
<li> <a href="qdomelement.html">QDomElement</a> (at most one)
<li> <a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a>
<li> <a href="qdomcomment.html">QDomComment</a>
<li> <a href="qdomdocumenttype.html">QDomDocumentType</a>
</ul>
<li> <a href="qdomdocumentfragment.html">QDomDocumentFragment</a>: Possible children are
<ul>
<li> <a href="qdomelement.html">QDomElement</a>
<li> <a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a>
<li> <a href="qdomcomment.html">QDomComment</a>
<li> <a href="qdomtext.html">QDomText</a>
<li> <a href="qdomcdatasection.html">QDomCDATASection</a>
<li> <a href="qdomentityreference.html">QDomEntityReference</a>
</ul>
<li> <a href="qdomdocumenttype.html">QDomDocumentType</a>: No children
<li> <a href="qdomentityreference.html">QDomEntityReference</a>: Possible children are
<ul>
<li> <a href="qdomelement.html">QDomElement</a>
<li> <a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a>
<li> <a href="qdomcomment.html">QDomComment</a>
<li> <a href="qdomtext.html">QDomText</a>
<li> <a href="qdomcdatasection.html">QDomCDATASection</a>
<li> <a href="qdomentityreference.html">QDomEntityReference</a>
</ul>
<li> <a href="qdomelement.html">QDomElement</a>: Possible children are
<ul>
<li> <a href="qdomelement.html">QDomElement</a>
<li> <a href="qdomtext.html">QDomText</a>
<li> <a href="qdomcomment.html">QDomComment</a>
<li> <a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a>
<li> <a href="qdomcdatasection.html">QDomCDATASection</a>
<li> <a href="qdomentityreference.html">QDomEntityReference</a>
</ul>
<li> <a href="qdomattr.html">QDomAttr</a>: Possible children are
<ul>
<li> <a href="qdomtext.html">QDomText</a>
<li> <a href="qdomentityreference.html">QDomEntityReference</a>
</ul>
<li> <a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a>: No children
<li> <a href="qdomcomment.html">QDomComment</a>: No children
<li> <a href="qdomtext.html">QDomText</a>: No children
<li> <a href="qdomcdatasection.html">QDomCDATASection</a>: No children
<li> <a href="qdomentity.html">QDomEntity</a>: Possible children are
<ul>
<li> <a href="qdomelement.html">QDomElement</a>
<li> <a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a>
<li> <a href="qdomcomment.html">QDomComment</a>
<li> <a href="qdomtext.html">QDomText</a>
<li> <a href="qdomcdatasection.html">QDomCDATASection</a>
<li> <a href="qdomentityreference.html">QDomEntityReference</a>
</ul>
<li> <a href="qdomnotation.html">QDomNotation</a>: No children
</ul>
<p> With <a href="qdomnodelist.html">QDomNodeList</a> and <a href="qdomnamednodemap.html">QDomNamedNodeMap</a> two <a href="collection.html#collection-classes">collection classes</a>
are provided: <a href="qdomnodelist.html">QDomNodeList</a> is a list of nodes
whereas <a href="qdomnamednodemap.html">QDomNamedNodeMap</a> is used to handle unordered sets of nodes
(often used for attributes).
<p> The <a href="qdomimplementation.html">QDomImplementation</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">QDomDocument</a> documentation that
describes basic usage.
<p> More information about Qt and XML can be found in the <a href="xml.html">Introduction to the Qt XML module.</a>
<p> <a name="namespaces"></a>
<h2> An introduction to namespaces
</h2>
<a name="4"></a><p> Parts of the Qt XML module documentation assume that you are
familiar with XML namespaces. Here we present a brief introduction;
skip to <a href="#namespacesConventions">Qt XML
documentation conventions</a> if you 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 have to 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 matters 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,
even not 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 Qt 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 Qt 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 © 2001
<a href="http://www.trolltech.com">Trolltech</a><td><a href="http://www.trolltech.com/trademarks.html">Trademarks</a>
<td align=right><div align=right>Qt version 3.0.2</div>
</table></div></address></body>
</html>
distrib
>
Mandriva
>
8.2
>
i586
>
media
>
contrib
>
by-pkgid
>
112b0974ad288f6cd55bf971ee6026a9
>
files
>
2332
