diff options
| author | Timothy Pearson <kb9vqf@pearsoncomputing.net> | 2011-07-10 15:24:15 -0500 |
|---|---|---|
| committer | Timothy Pearson <kb9vqf@pearsoncomputing.net> | 2011-07-10 15:24:15 -0500 |
| commit | bd0f3345a938b35ce6a12f6150373b0955b8dd12 (patch) | |
| tree | 7a520322212d48ebcb9fbe1087e7fca28b76185c /doc/html/xml.html | |
| download | qt3-bd0f3345a938b35ce6a12f6150373b0955b8dd12.tar.gz qt3-bd0f3345a938b35ce6a12f6150373b0955b8dd12.zip | |
Add Qt3 development HEAD version
Diffstat (limited to 'doc/html/xml.html')
| -rw-r--r-- | doc/html/xml.html | 573 |
1 files changed, 573 insertions, 0 deletions
diff --git a/doc/html/xml.html b/doc/html/xml.html new file mode 100644 index 0000000..319168a --- /dev/null +++ b/doc/html/xml.html @@ -0,0 +1,573 @@ +<!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 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.saxproject.org">http://www.saxproject.org</a>. +<p> Support for SAX2 filters and the reader factory are under +development. The Qt implementation does not include the SAX1 +compatibility classes present in the Java interface. +<p> For an introduction to Qt's SAX2 classes see +"<a href="#sax2">The Qt 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 Qt is provided in the +<a href="#dom">Qt DOM classes</a>. +<p> Qt 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">QDomAttr</a> +<td valign="top">Represents one attribute of a <a href="qdomelement.html">QDomElement</a> +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomcdatasection.html">QDomCDATASection</a> +<td valign="top">Represents an XML CDATA section +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomcharacterdata.html">QDomCharacterData</a> +<td valign="top">Represents a generic string in the DOM +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomcomment.html">QDomComment</a> +<td valign="top">Represents an XML comment +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomdocument.html">QDomDocument</a> +<td valign="top">The representation of an XML document +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomdocumentfragment.html">QDomDocumentFragment</a> +<td valign="top">Tree of QDomNodes which is usually not a complete <a href="qdomdocument.html">QDomDocument</a> +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomdocumenttype.html">QDomDocumentType</a> +<td valign="top">The representation of the DTD in the document tree +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomelement.html">QDomElement</a> +<td valign="top">Represents one element in the DOM tree +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomentity.html">QDomEntity</a> +<td valign="top">Represents an XML entity +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomentityreference.html">QDomEntityReference</a> +<td valign="top">Represents an XML entity reference +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomimplementation.html">QDomImplementation</a> +<td valign="top">Information about the features of the DOM implementation +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomnamednodemap.html">QDomNamedNodeMap</a> +<td valign="top">Collection of nodes that can be accessed by name +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomnode.html">QDomNode</a> +<td valign="top">The base class for all nodes of the DOM tree +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomnodelist.html">QDomNodeList</a> +<td valign="top">List of <a href="qdomnode.html">QDomNode</a> objects +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomnotation.html">QDomNotation</a> +<td valign="top">Represents an XML notation +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a> +<td valign="top">Represents an XML processing instruction +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomtext.html">QDomText</a> +<td valign="top">Represents textual data in the parsed XML document +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlattributes.html">QXmlAttributes</a> +<td valign="top">XML attributes +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlcontenthandler.html">QXmlContentHandler</a> +<td valign="top">Interface to report logical content of XML data +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmldeclhandler.html">QXmlDeclHandler</a> +<td valign="top">Interface to report declaration content of XML data +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmldefaulthandler.html">QXmlDefaultHandler</a> +<td valign="top">Default implementation of all XML handler classes +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmldtdhandler.html">QXmlDTDHandler</a> +<td valign="top">Interface to report DTD content of XML data +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlentityresolver.html">QXmlEntityResolver</a> +<td valign="top">Interface to resolve extern entities contained in XML data +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlerrorhandler.html">QXmlErrorHandler</a> +<td valign="top">Interface to report errors in XML data +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlinputsource.html">QXmlInputSource</a> +<td valign="top">The input data for the <a href="qxmlreader.html">QXmlReader</a> subclasses +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmllexicalhandler.html">QXmlLexicalHandler</a> +<td valign="top">Interface to report lexical content of XML data +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmllocator.html">QXmlLocator</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">QXmlNamespaceSupport</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">QXmlParseException</a> +<td valign="top">Used to report errors with the <a href="qxmlerrorhandler.html">QXmlErrorHandler</a> interface +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlreader.html">QXmlReader</a> +<td valign="top">Interface for XML readers (i.e. for SAX2 parsers) +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlsimplereader.html">QXmlSimpleReader</a> +<td valign="top">Implementation of a simple XML reader (a SAX2 parser) +</table></center> +<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. 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 Qt XML module provides an abstract class, <a href="qxmlreader.html">QXmlReader</a>, that +defines the interface for potential SAX2 readers. Qt includes a reader +implementation, <a href="qxmlsimplereader.html">QXmlSimpleReader</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">QXmlContentHandler</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">QXmlDTDHandler</a> +<td valign="top">Reports events related to the DTD (e.g. notation declarations). +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlerrorhandler.html">QXmlErrorHandler</a> +<td valign="top">Reports errors or warnings that occurred during parsing. +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlentityresolver.html">QXmlEntityResolver</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">QXmlDeclHandler</a> +<td valign="top">Reports further DTD related events (e.g. attribute declarations). +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmllexicalhandler.html">QXmlLexicalHandler</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">QXmlDefaultHandler</a> class provides a "do nothing" default +implementation for all of them. Therefore users only need to overload +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 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">QXmlAttributes</a> +<td valign="top">Used to pass attributes in a start element event. +<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmllocator.html">QXmlLocator</a> +<td valign="top">Used to obtain the actual parsing position of an event. +<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlnamespacesupport.html">QXmlNamespaceSupport</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 Qt SAX2 implementation can report whether the reader has +particular functionality using the <a href="qxmlreader.html#hasFeature">QXmlReader::hasFeature</a>() +function. Available features can be tested with <a href="qxmlreader.html#feature">QXmlReader::feature</a>(), +and switched on or off using <a href="qxmlreader.html#setFeature">QXmlReader::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">QXmlSimpleReader</a> implementation of <a href="qxmlreader.html">QXmlReader</a>, +supports them, and can do namespace processing. +<p> <a href="qxmlsimplereader.html">QXmlSimpleReader</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">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: +<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 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> 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">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> <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">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> 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 +(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">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 child 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, +and <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. +<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 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 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 © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>Qt 3.3.8</div> +</table></div></address></body> +</html> |