source: trunk/doc/html/xml.html@ 203

Last change on this file since 203 was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 31.4 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/xml.doc:36 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>XML Module</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<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>
33
34
35<p>
36<p> <!-- toc -->
37<ul>
38<li><a href="#1"> Overview of the XML architecture in Qt
39</a>
40<li><a href="#2"> The Qt SAX2 classes
41</a>
42<ul>
43<li><a href="#2-1"> Introduction to SAX2
44</a>
45<li><a href="#2-2"> Features
46</a>
47<li><a href="#2-3"> Namespace support via features
48</a>
49<ul>
50<li><a href="#2-3-1"> Summary
51</a>
52</ul>
53<li><a href="#2-4"> Properties
54</a>
55<li><a href="#2-5"> Further reading
56</a>
57</ul>
58<li><a href="#3"> The Qt DOM classes
59</a>
60<ul>
61<li><a href="#3-1"> Introduction to DOM
62</a>
63<li><a href="#3-2"> Further reading
64</a>
65</ul>
66<li><a href="#4"> An introduction to namespaces
67</a>
68<ul>
69<li><a href="#4-1"> Conventions used in Qt XML documentation
70</a>
71</ul>
72</ul>
73<!-- endtoc -->
74
75<p> <a name="overview"></a>
76<h2> Overview of the XML architecture in Qt
77</h2>
78<a name="1"></a><p> The XML module provides a well-formed XML parser using the SAX2
79(Simple API for XML) interface plus an implementation of the DOM Level
802 (Document Object Model).
81<p> SAX is an event-based standard interface for XML parsers.
82The Qt interface follows the design of the SAX2 Java implementation.
83Its naming scheme was adapted to fit the Qt naming conventions.
84Details on SAX2 can be found at
85<a href="http://www.saxproject.org">http://www.saxproject.org</a>.
86<p> Support for SAX2 filters and the reader factory are under
87development. The Qt implementation does not include the SAX1
88compatibility classes present in the Java interface.
89<p> For an introduction to Qt's SAX2 classes see
90"<a href="#sax2">The Qt SAX2 classes</a>".
91<p> DOM Level 2 is a W3C Recommendation for XML interfaces that maps the
92constituents of an XML document to a tree structure. Details and the
93specification of DOM Level 2 can be found at
94<a href="http://www.w3.org/DOM/">http://www.w3.org/DOM/</a>.
95More information about the DOM classes in Qt is provided in the
96<a href="#dom">Qt DOM classes</a>.
97<p> Qt provides the following XML related classes:
98<p> <center><table cellpadding="4" cellspacing="2" border="0">
99<tr bgcolor="#a2c511"> <th valign="top">Class <th valign="top">Short description
100<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomattr.html">QDomAttr</a>
101<td valign="top">Represents one attribute of a <a href="qdomelement.html">QDomElement</a>
102<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomcdatasection.html">QDomCDATASection</a>
103<td valign="top">Represents an XML CDATA section
104<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomcharacterdata.html">QDomCharacterData</a>
105<td valign="top">Represents a generic string in the DOM
106<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomcomment.html">QDomComment</a>
107<td valign="top">Represents an XML comment
108<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomdocument.html">QDomDocument</a>
109<td valign="top">The representation of an XML document
110<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomdocumentfragment.html">QDomDocumentFragment</a>
111<td valign="top">Tree of QDomNodes which is usually not a complete <a href="qdomdocument.html">QDomDocument</a>
112<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomdocumenttype.html">QDomDocumentType</a>
113<td valign="top">The representation of the DTD in the document tree
114<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomelement.html">QDomElement</a>
115<td valign="top">Represents one element in the DOM tree
116<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomentity.html">QDomEntity</a>
117<td valign="top">Represents an XML entity
118<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomentityreference.html">QDomEntityReference</a>
119<td valign="top">Represents an XML entity reference
120<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomimplementation.html">QDomImplementation</a>
121<td valign="top">Information about the features of the DOM implementation
122<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomnamednodemap.html">QDomNamedNodeMap</a>
123<td valign="top">Collection of nodes that can be accessed by name
124<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomnode.html">QDomNode</a>
125<td valign="top">The base class for all nodes of the DOM tree
126<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomnodelist.html">QDomNodeList</a>
127<td valign="top">List of <a href="qdomnode.html">QDomNode</a> objects
128<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomnotation.html">QDomNotation</a>
129<td valign="top">Represents an XML notation
130<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a>
131<td valign="top">Represents an XML processing instruction
132<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qdomtext.html">QDomText</a>
133<td valign="top">Represents textual data in the parsed XML document
134<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlattributes.html">QXmlAttributes</a>
135<td valign="top">XML attributes
136<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlcontenthandler.html">QXmlContentHandler</a>
137<td valign="top">Interface to report logical content of XML data
138<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmldeclhandler.html">QXmlDeclHandler</a>
139<td valign="top">Interface to report declaration content of XML data
140<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmldefaulthandler.html">QXmlDefaultHandler</a>
141<td valign="top">Default implementation of all XML handler classes
142<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmldtdhandler.html">QXmlDTDHandler</a>
143<td valign="top">Interface to report DTD content of XML data
144<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlentityresolver.html">QXmlEntityResolver</a>
145<td valign="top">Interface to resolve extern entities contained in XML data
146<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlerrorhandler.html">QXmlErrorHandler</a>
147<td valign="top">Interface to report errors in XML data
148<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlinputsource.html">QXmlInputSource</a>
149<td valign="top">The input data for the <a href="qxmlreader.html">QXmlReader</a> subclasses
150<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmllexicalhandler.html">QXmlLexicalHandler</a>
151<td valign="top">Interface to report lexical content of XML data
152<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmllocator.html">QXmlLocator</a>
153<td valign="top">The XML handler classes with information about the actual parsing position
154<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlnamespacesupport.html">QXmlNamespaceSupport</a>
155<td valign="top">Helper class for XML readers which want to include namespace support
156<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlparseexception.html">QXmlParseException</a>
157<td valign="top">Used to report errors with the <a href="qxmlerrorhandler.html">QXmlErrorHandler</a> interface
158<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlreader.html">QXmlReader</a>
159<td valign="top">Interface for XML readers (i.e. for SAX2 parsers)
160<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlsimplereader.html">QXmlSimpleReader</a>
161<td valign="top">Implementation of a simple XML reader (a SAX2 parser)
162</table></center>
163<p> <a name="sax2"></a>
164<h2> The Qt SAX2 classes
165</h2>
166<a name="2"></a><p> <a name="sax2Intro"></a>
167<h3> Introduction to SAX2
168</h3>
169<a name="2-1"></a><p> The SAX2 interface is an event-driven mechanism to provide the user with
170document information. An "event" in this context means something
171reported by the parser, for example, it has encountered a start tag,
172or an end tag, etc.
173<p> To make it less abstract consider the following example:
174<pre>
175&lt;quote&gt;A quotation.&lt;/quote&gt;
176</pre>
177
178<p> Whilst reading (a SAX2 parser is usually referred to as "reader")
179the above document three events would be triggered:
180<ol type=1>
181<li> A start tag occurs (<tt>&lt;quote&gt;</tt>).
182<li> Character data (i.e. text) is found, "A quotation.".
183<li> An end tag is parsed (<tt>&lt;/quote&gt;</tt>).
184</ol>
185<p> Each time such an event occurs the parser reports it; you can set up
186event handlers to respond to these events.
187<p> Whilst this is a fast and simple approach to read XML documents,
188manipulation is difficult because data is not stored, simply handled
189and discarded serially. The <a href="#dom">DOM interface</a> reads in and stores the whole document in a tree structure;
190this takes more memory, but makes it easier to manipulate the
191document's structure..
192<p> The Qt XML module provides an abstract class, <a href="qxmlreader.html">QXmlReader</a>, that
193defines the interface for potential SAX2 readers. Qt includes a reader
194implementation, <a href="qxmlsimplereader.html">QXmlSimpleReader</a>, that is easy to adapt through
195subclassing.
196<p> The reader reports parsing events through special handler classes:
197<center><table cellpadding="4" cellspacing="2" border="0">
198<tr bgcolor="#a2c511"> <th valign="top">Handler class <th valign="top">Description
199<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlcontenthandler.html">QXmlContentHandler</a>
200<td valign="top">Reports events related to the content of a document (e.g. the start tag
201or characters).
202<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmldtdhandler.html">QXmlDTDHandler</a>
203<td valign="top">Reports events related to the DTD (e.g. notation declarations).
204<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlerrorhandler.html">QXmlErrorHandler</a>
205<td valign="top">Reports errors or warnings that occurred during parsing.
206<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmlentityresolver.html">QXmlEntityResolver</a>
207<td valign="top">Reports external entities during parsing and allows users to resolve
208external entities themselves instead of leaving it to the reader.
209<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmldeclhandler.html">QXmlDeclHandler</a>
210<td valign="top">Reports further DTD related events (e.g. attribute declarations).
211<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmllexicalhandler.html">QXmlLexicalHandler</a>
212<td valign="top">Reports events related to the lexical structure of the
213document (the beginning of the DTD, comments etc.).
214</table></center>
215<p> These classes are abstract classes describing the interface. The <a href="qxmldefaulthandler.html">QXmlDefaultHandler</a> class provides a "do nothing" default
216implementation for all of them. Therefore users only need to overload
217the <a href="qxmldefaulthandler.html">QXmlDefaultHandler</a> functions they are interested in.
218<p> To read input XML data a special class <a href="qxmlinputsource.html">QXmlInputSource</a> is used.
219<p> Apart from those already mentioned, the following SAX2 support classes
220provide additional useful functionality:
221<center><table cellpadding="4" cellspacing="2" border="0">
222<tr bgcolor="#a2c511"> <th valign="top">Class <th valign="top">Description
223<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlattributes.html">QXmlAttributes</a>
224<td valign="top">Used to pass attributes in a start element event.
225<tr bgcolor="#f0f0f0"> <td valign="top"><a href="qxmllocator.html">QXmlLocator</a>
226<td valign="top">Used to obtain the actual parsing position of an event.
227<tr bgcolor="#d0d0d0"> <td valign="top"><a href="qxmlnamespacesupport.html">QXmlNamespaceSupport</a>
228<td valign="top">Used to implement <a href="xml.html#namespaces">namespace</a>
229support for a reader. Note that namespaces do not change the
230parsing behavior. They are only reported through the handler.
231</table></center>
232<p> <a name="sax2Features"></a>
233<h3> Features
234</h3>
235<a name="2-2"></a><p> The behaviour of an XML reader depends on its support for certain
236optional features. For example, a reader may have the feature "report
237attributes used for <a href="xml.html#namespaces">namespace</a>
238declarations and prefixes along with the local name of a tag". Like
239every other feature this has a unique name represented by a URI: it is
240called <em>http://xml.org/sax/features/namespace-prefixes</em>.
241<p> The Qt SAX2 implementation can report whether the reader has
242particular functionality using the <a href="qxmlreader.html#hasFeature">QXmlReader::hasFeature</a>()
243function. Available features can be tested with <a href="qxmlreader.html#feature">QXmlReader::feature</a>(),
244and switched on or off using <a href="qxmlreader.html#setFeature">QXmlReader::setFeature</a>().
245<p> Consider the example
246<pre>
247&lt;document xmlns:book = 'http://trolltech.com/fnord/book/'
248 xmlns = 'http://trolltech.com/fnord/' &gt;
249</pre>
250
251A reader that does not support the <em>http://xml.org/sax/features/namespace-prefixes</em> feature would report
252the element name <em>document</em> but not its attributes <em>xmlns:book</em> and
253<em>xmlns</em> with their values. A reader with the feature <em>http://xml.org/sax/features/namespace-prefixes</em> reports the namespace
254attributes if the <a href="qxmlreader.html#feature">feature</a> is
255switched on.
256<p> Other features include <em>http://xml.org/sax/features/namespace</em>
257(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
258validation errors).
259<p> Whilst SAX2 leaves it to the user to define and implement whatever
260features 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.
261The <a href="qxmlsimplereader.html">QXmlSimpleReader</a> implementation of <a href="qxmlreader.html">QXmlReader</a>,
262supports them, and can do namespace processing.
263<p> <a href="qxmlsimplereader.html">QXmlSimpleReader</a> is not validating, so it
264does not support <em>http://xml.org/sax/features/validation</em>.
265<p> <a name="sax2Namespaces"></a>
266<h3> Namespace support via features
267</h3>
268<a name="2-3"></a><p> As we have seen in the <a href="#sax2Features">previous section</a>
269we can configure the behavior of the reader when it comes to namespace
270processing. This is done by setting and unsetting the
271<em>http://xml.org/sax/features/namespaces</em> and
272<em>http://xml.org/sax/features/namespace-prefixes</em> features.
273<p> They influence the reporting behavior in the following way:
274<ol type=1>
275<li> Namespace prefixes and local parts of elements and attributes can
276be reported.
277<li> The qualified names of elements and attributes are reported.
278<li> <a href="qxmlcontenthandler.html#startPrefixMapping">QXmlContentHandler::startPrefixMapping</a>() and <a href="qxmlcontenthandler.html#endPrefixMapping">QXmlContentHandler::endPrefixMapping</a>() are called by the reader.
279<li> Attributes that declare namespaces (i.e. the attribute <em>xmlns</em> and
280attributes starting with <em>xmlns:</em>) are reported.
281</ol>
282<p> Consider the following element:
283<pre>
284&lt;author xmlns:fnord = 'http://trolltech.com/fnord/'
285 title="Ms"
286 fnord:title="Goddess"
287 name="Eris Kallisti"/&gt;
288</pre>
289
290With <em>http://xml.org/sax/features/namespace-prefixes</em> set to TRUE
291the 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
292reader.
293<p> The <em>http://xml.org/sax/features/namespaces</em> feature is responsible
294for reporting local names, namespace prefixes and URIs. With <em>http://xml.org/sax/features/namespaces</em> set to TRUE the parser will
295report <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
296the namespace URI. When <em>http://xml.org/sax/features/namespaces</em> is
297FALSE none of them are reported.
298<p> In the current implementation the Qt XML classes follow the definition
299that the prefix <em>xmlns</em> itself isn't associated with any namespace at all
300(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>).
301Therefore even with <em>http://xml.org/sax/features/namespaces</em> and
302<em>http://xml.org/sax/features/namespace-prefixes</em> both set to TRUE
303the reader won't return either a local name, a namespace prefix or
304a namespace URI for <em>xmlns:fnord</em>.
305<p> This might be changed in the future following the W3C suggestion
306<a href="http://www.w3.org/2000/xmlns/">http://www.w3.org/2000/xmlns/</a>
307to associate <em>xmlns</em> with the namespace <em>http://www.w3.org/2000/xmlns</em>.
308<p> As the SAX2 standard suggests, <a href="qxmlsimplereader.html">QXmlSimpleReader</a> defaults to having
309<em>http://xml.org/sax/features/namespaces</em> set to TRUE and
310<em>http://xml.org/sax/features/namespace-prefixes</em> set to FALSE.
311When changing this behavior using <a href="qxmlsimplereader.html#setFeature">QXmlSimpleReader::setFeature</a>()
312note that the combination of both features set to
313FALSE is illegal.
314<p> For a practical demonstration of how the two features affect the
315output of the reader run the <a href="tagreader-with-features-example.html">tagreader with features example.</a>
316<p> <a name="sax2NamespacesSummary"></a>
317<h4> Summary
318</h4>
319<a name="2-3-1"></a><p> <a href="qxmlsimplereader.html">QXmlSimpleReader</a> implements the following behavior:
320<p> <center><table cellpadding="4" cellspacing="2" border="0">
321<tr bgcolor="#a2c511"> <th valign="top">(namespaces, namespace-prefixes)
322<th valign="top">Namespace prefix and local part
323<th valign="top">Qualified names
324<th valign="top">Prefix mapping
325<th valign="top">xmlns attributes
326<tr bgcolor="#f0f0f0"> <td valign="top">(TRUE, FALSE) <td valign="top">Yes <td valign="top">Yes* <td valign="top">Yes <td valign="top">No
327<tr bgcolor="#d0d0d0"> <td valign="top">(TRUE, TRUE) <td valign="top">Yes <td valign="top">Yes <td valign="top">Yes <td valign="top">Yes
328<tr bgcolor="#f0f0f0"> <td valign="top">(FALSE, TRUE) <td valign="top">No* <td valign="top">Yes <td valign="top">No* <td valign="top">Yes
329<tr bgcolor="#d0d0d0"> <td valign="top">(FALSE, FALSE) <td valign="top" colspan="4" rowspan="1"> Illegal
330</table></center>
331<p> <sup>*</sup> The behavior of these entries is not specified by SAX.
332<p> <a name="sax2Properties"></a>
333<h3> Properties
334</h3>
335<a name="2-4"></a><p> Properties are a more general concept. They have a unique name,
336represented as an URI, but their value is <tt>void*</tt>. Thus nearly
337anything can be used as a property value. This concept involves some
338danger, though: there is no means of ensuring type-safety; the user
339must take care that they pass the right type. Properties are
340useful if a reader supports special handler classes.
341<p> The URIs used for features and properties often look like URLs, e.g.
342<a href="http://xml.org/sax/features/namespace">http://xml.org/sax/features/namespace</a>. This does not mean that the
343data required is at this address. It is simply a way of defining
344unique names.
345<p> Anyone can define and use new SAX2 properties for their readers.
346Property support is not mandatory.
347<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>().
348<p> <a name="sax2Reading"></a>
349<h3> Further reading
350</h3>
351<a name="2-5"></a><p> More information about XML (e.g. <a href="xml.html#namespaces">namespaces</a>)
352can be found in the <a href="xml.html">introduction to the Qt XML module.</a>
353<p> <a name="dom"></a>
354<h2> The Qt DOM classes
355</h2>
356<a name="3"></a><p> <a name="domIntro"></a>
357<h3> Introduction to DOM
358</h3>
359<a name="3-1"></a><p> DOM provides an interface to access and change the content and
360structure of an XML file. It makes a hierarchical view of the document
361(a tree view). Thus -- in contrast to the SAX2 interface -- an object
362model of the document is resident in memory after parsing which makes
363manipulation easy.
364<p> All DOM nodes in the document tree are subclasses of <a href="qdomnode.html">QDomNode</a>. The
365document itself is represented as a <a href="qdomdocument.html">QDomDocument</a> object.
366<p> Here are the available node classes and their potential child classes:
367<p> <ul>
368<li> <a href="qdomdocument.html">QDomDocument</a>: Possible children are
369<ul>
370<li> <a href="qdomelement.html">QDomElement</a> (at most one)
371<li> <a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a>
372<li> <a href="qdomcomment.html">QDomComment</a>
373<li> <a href="qdomdocumenttype.html">QDomDocumentType</a>
374</ul>
375<li> <a href="qdomdocumentfragment.html">QDomDocumentFragment</a>: Possible children are
376<ul>
377<li> <a href="qdomelement.html">QDomElement</a>
378<li> <a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a>
379<li> <a href="qdomcomment.html">QDomComment</a>
380<li> <a href="qdomtext.html">QDomText</a>
381<li> <a href="qdomcdatasection.html">QDomCDATASection</a>
382<li> <a href="qdomentityreference.html">QDomEntityReference</a>
383</ul>
384<li> <a href="qdomdocumenttype.html">QDomDocumentType</a>: No children
385<li> <a href="qdomentityreference.html">QDomEntityReference</a>: Possible children are
386<ul>
387<li> <a href="qdomelement.html">QDomElement</a>
388<li> <a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a>
389<li> <a href="qdomcomment.html">QDomComment</a>
390<li> <a href="qdomtext.html">QDomText</a>
391<li> <a href="qdomcdatasection.html">QDomCDATASection</a>
392<li> <a href="qdomentityreference.html">QDomEntityReference</a>
393</ul>
394<li> <a href="qdomelement.html">QDomElement</a>: Possible children are
395<ul>
396<li> <a href="qdomelement.html">QDomElement</a>
397<li> <a href="qdomtext.html">QDomText</a>
398<li> <a href="qdomcomment.html">QDomComment</a>
399<li> <a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a>
400<li> <a href="qdomcdatasection.html">QDomCDATASection</a>
401<li> <a href="qdomentityreference.html">QDomEntityReference</a>
402</ul>
403<li> <a href="qdomattr.html">QDomAttr</a>: Possible children are
404<ul>
405<li> <a href="qdomtext.html">QDomText</a>
406<li> <a href="qdomentityreference.html">QDomEntityReference</a>
407</ul>
408<li> <a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a>: No children
409<li> <a href="qdomcomment.html">QDomComment</a>: No children
410<li> <a href="qdomtext.html">QDomText</a>: No children
411<li> <a href="qdomcdatasection.html">QDomCDATASection</a>: No children
412<li> <a href="qdomentity.html">QDomEntity</a>: Possible children are
413<ul>
414<li> <a href="qdomelement.html">QDomElement</a>
415<li> <a href="qdomprocessinginstruction.html">QDomProcessingInstruction</a>
416<li> <a href="qdomcomment.html">QDomComment</a>
417<li> <a href="qdomtext.html">QDomText</a>
418<li> <a href="qdomcdatasection.html">QDomCDATASection</a>
419<li> <a href="qdomentityreference.html">QDomEntityReference</a>
420</ul>
421<li> <a href="qdomnotation.html">QDomNotation</a>: No children
422</ul>
423<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>
424are provided: <a href="qdomnodelist.html">QDomNodeList</a> is a list of nodes,
425and <a href="qdomnamednodemap.html">QDomNamedNodeMap</a> is used to handle unordered sets of nodes
426(often used for attributes).
427<p> The <a href="qdomimplementation.html">QDomImplementation</a> class allows the user to query features of the
428DOM implementation.
429<p> <h3> Further reading
430</h3>
431<a name="3-2"></a><p> To get started please refer to the <a href="qdomdocument.html">QDomDocument</a> documentation.
432<p> <a name="namespaces"></a>
433<h2> An introduction to namespaces
434</h2>
435<a name="4"></a><p> Parts of the Qt XML module documentation assume that you are familiar
436with XML namespaces. Here we present a brief introduction; skip to
437<a href="#namespacesConventions">Qt XML documentation conventions</a>
438if you already know this material.
439<p> Namespaces are a concept introduced into XML to allow a more modular
440design. With their help data processing software can easily resolve
441naming conflicts in XML documents.
442<p> Consider the following example:
443<p> <pre>
444&lt;document&gt;
445&lt;book&gt;
446 &lt;title&gt;Practical XML&lt;/title&gt;
447 &lt;author title="Ms" name="Eris Kallisti"/&gt;
448 &lt;chapter&gt;
449 &lt;title&gt;A Namespace Called fnord&lt;/title&gt;
450 &lt;/chapter&gt;
451&lt;/book&gt;
452&lt;/document&gt;
453</pre>
454
455<p> Here we find three different uses of the name <em>title</em>. If you wish to
456process this document you will encounter problems because each of the
457<em>titles</em> should be displayed in a different manner -- even though
458they have the same name.
459<p> The solution would be to have some means of identifying the first
460occurrence 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,
461the chapter title, e.g.:
462<pre>
463&lt;book:title&gt;Practical XML&lt;/book:title&gt;
464</pre>
465
466<p> <em>book</em> in this case is a <em>prefix</em> denoting the namespace.
467<p> Before we can apply a namespace to element or attribute names we must
468declare it.
469<p> Namespaces are URIs like <em>http://trolltech.com/fnord/book/</em>. This
470does not mean that data must be available at this address; the URI is
471simply used to provide a unique name.
472<p> We declare namespaces in the same way as attributes; strictly speaking
473they <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
474<p> <pre>
475xmlns="http://trolltech.com/fnord/"
476</pre>
477
478<p> To distinguish the <em>http://trolltech.com/fnord/book/</em> namespace from
479the default, we must supply it with a prefix:
480<p> <pre>
481xmlns:book="http://trolltech.com/fnord/book/"
482</pre>
483
484<p> A namespace that is declared like this can be applied to element and
485attribute names by prepending the appropriate prefix and a ":"
486delimiter. We have already seen this with the <em>book:title</em> element.
487<p> Element names without a prefix belong to the default namespace. This
488rule does not apply to attributes: an attribute without a prefix does
489not belong to any of the declared XML namespaces at all. Attributes
490always belong to the "traditional" namespace of the element in which
491they appear. A "traditional" namespace is not an XML namespace, it
492simply means that all attribute names belonging to one element must be
493different. Later we will see how to assign an XML namespace to an
494attribute.
495<p> Due to the fact that attributes without prefixes are not in any XML
496namespace there is no collision between the attribute <em>title</em> (that
497belongs to the <em>author</em> element) and for example the <em>title</em> element
498within a <em>chapter</em>.
499<p> Let's clarify this with an example:
500<pre>
501&lt;document xmlns:book = 'http://trolltech.com/fnord/book/'
502 xmlns = 'http://trolltech.com/fnord/' &gt;
503&lt;book&gt;
504 &lt;book:title&gt;Practical XML&lt;/book:title&gt;
505 &lt;book:author xmlns:fnord = 'http://trolltech.com/fnord/'
506 title="Ms"
507 fnord:title="Goddess"
508 name="Eris Kallisti"/&gt;
509 &lt;chapter&gt;
510 &lt;title&gt;A Namespace Called fnord&lt;/title&gt;
511 &lt;/chapter&gt;
512&lt;/book&gt;
513&lt;/document&gt;
514</pre>
515
516<p> Within the <em>document</em> element we have two namespaces declared. The
517default 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
518and of course to <em>document</em> itself.
519<p> The <em>book:author</em> and <em>book:title</em> elements belong to the namespace
520with the URI <em>http://trolltech.com/fnord/book/</em>.
521<p> The two <em>book:author</em> attributes <em>title</em> and <em>name</em> have no XML
522namespace assigned. They are only members of the "traditional"
523namespace of the element <em>book:author</em>, meaning that for example two
524<em>title</em> attributes in <em>book:author</em> are forbidden.
525<p> In the above example we circumvent the last rule by adding a <em>title</em>
526attribute 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
527prefix <em>fnord</em> that is declared in the <em>book:author</em> element.
528<p> Clearly the <em>fnord</em> namespace has the same namespace URI as the
529default namespace. So why didn't we simply use the default namespace
530we'd already declared? The answer is quite complex:
531<ul>
532<li> attributes without a prefix don't belong to any XML namespace at
533all, not even to the default namespace;
534<li> additionally omitting the prefix would lead to a <em>title-title</em> clash;
535<li> writing it as <em>xmlns:title</em> would declare a new namespace with the
536prefix <em>title</em> instead of applying the default <em>xmlns</em> namespace.
537</ul>
538<p> With the Qt XML classes elements and attributes can be accessed in two
539ways: either by refering to their qualified names consisting of the
540namespace prefix and the "real" name (or <em>local</em> name) or by the
541combination of local name and namespace URI.
542<p> More information on XML namespaces can be found at
543<a href="http://www.w3.org/TR/REC-xml-names/">http://www.w3.org/TR/REC-xml-names/</a>.
544<p> <a name="namespacesConventions"></a>
545<h3> Conventions used in Qt XML documentation
546</h3>
547<a name="4-1"></a><p> The following terms are used to distinguish the parts of names within
548the context of namespaces:
549<ul>
550<li> The <em>qualified name</em>
551is the name as it appears in the document. (In the above example <em>book:title</em> is a qualified name.)
552<li> A <em>namespace prefix</em> in a qualified name
553is the part to the left of the ":". (<em>book</em> is the namespace prefix in
554<em>book:title</em>.)
555<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
556local part of <em>book:title</em>.)
557<li> The <em>namespace URI</em> ("Uniform Resource Identifier") is a unique
558identifier for a namespace. It looks like a URL
559(e.g. <em>http://trolltech.com/fnord/</em> ) but does not require
560data to be accessible by the given protocol at the named address.
561</ul>
562<p> Elements without a ":" (like <em>chapter</em> in the example) do not have a
563namespace prefix. In this case the local part and the qualified name
564are identical (i.e. <em>chapter</em>).
565
566<!-- eof -->
567<p><address><hr><div align=center>
568<table width=100% cellspacing=0 border=0><tr>
569<td>Copyright &copy; 2007
570<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
571<td align=right><div align=right>Qt 3.3.8</div>
572</table></div></address></body>
573</html>
Note: See TracBrowser for help on using the repository browser.