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