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
|
<!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-sax-features-walkthrough.doc:36 -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Walkthrough: Using SAX2 features with the TQt XML classes</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>Walkthrough: Using SAX2 features with the TQt XML classes</h1>
<p>
<p> This document assumes that you are familiar with <a href="xml.html#namespaces">namespaces</a> in XML and the concept of a <a href="xml.html#sax2">SAX2
parser</a>.
If features of SAX2 readers are new to you please read
<a href="xml.html#sax2Features">the feature section</a> of the SAX2 document.
<p> As a novice to the TQt XML classes it is advisable to have a look at the
<a href="xml-sax-walkthrough.html">tiny SAX2 parser walkthrough</a> before
reading on.
<p> This walkthrough covers two topics: First of all it shows how to
set SAX2 features and secondly how to integrate the TQt XML functionality
into a TQt GUI application.
<p> The resulting application allows you to compare the output of the reader
depending on how the two features
<em>http://xml.org/sax/features/namespace-prefixes</em>
and <em>http://xml.org/sax/features/namespaces</em> are set.
To do this it shows tree views of the read XML file
listing the qualified names of elements and attributes and the respective
namespace URIs.
<p> <h3>Setting features</h3>
<p>
<p> Let's begin with the main program of the application. First the boring
part: we include all the classes we need:
<p> <pre> #include "structureparser.h"
#include <<a href="qapplication-h.html">ntqapplication.h</a>>
#include <<a href="qfile-h.html">ntqfile.h</a>>
#include <<a href="tqxml-h.html">tqxml.h</a>>
#include <<a href="qlistview-h.html">ntqlistview.h</a>>
#include <<a href="qgrid-h.html">ntqgrid.h</a>>
#include <<a href="qmainwindow-h.html">ntqmainwindow.h</a>>
#include <<a href="qlabel-h.html">ntqlabel.h</a>>
</pre>
<p> <a href="#structureparser.h">structureparser.h</a> contains the API of
the XML parser that we implement in <a href="#structureparser.cpp">structureparser.cpp.</a>
<p> <pre> int main( int argc, char **argv )
{
<a href="ntqapplication.html">TQApplication</a> app( argc, argv );
</pre>
<p> As usual we then create a TQt application object and hand command line arguments
over to it.
<p> <pre> <a href="ntqfile.html">TQFile</a> xmlFile( argc == 2 ? argv[1] : "fnord.xml" );
</pre>
<p> If the user runs the program with one filename as
an argument we process this file, otherwise we use the <em>fnord.xml</em> file from
the example directory for demonstration purposes.
<p> <pre> <a href="tqxmlinputsource.html">TQXmlInputSource</a> source( &xmlFile );
</pre>
<p> We use <em>xmlFile</em> as the XML Input Source...
<p> <pre> <a href="tqxmlsimplereader.html">TQXmlSimpleReader</a> reader;
</pre>
<p> ... and instantiate a <em>reader</em> object. Later we will manipulate its features
and thus influence how the XML data are read.
<p> <pre> <a href="ntqgrid.html">TQGrid</a> * container = new <a href="ntqgrid.html">TQGrid</a>( 3 );
</pre>
<p> Now let's think about presenting the output: As described in the
<a href="xml.html#sax2Features">TQt SAX2 documentation</a>
there are three valid combinations of <em>http://xml.org/sax/features/namespace-prefixes</em>
and <em>http://xml.org/sax/features/namespaces</em>: TRUE/TRUE, TRUE/FALSE and
FALSE/TRUE. To show the relevant output side by side of each other
and mark them with three labels makes up for a grid layout consisting
of three columns (and thus two lines).
<p> <pre> <a href="ntqlistview.html">TQListView</a> * nameSpace = new <a href="ntqlistview.html">TQListView</a>( container, "table_namespace" );
</pre>
<p> The most natural way of presenting XML elements is in a tree.
Thus we use a listview. Its name <em>nameSpace</em> indicates that this
one will be used to present the combination of <em>http://xml.org/sax/features/namespaces</em> being TRUE and
<em>http://xml.org/sax/features/namespace-prefixes</em>
being FALSE -- the default configuration of a <a href="tqxmlsimplereader.html">TQXmlSimpleReader</a>.
<p> Being the first grid entry the <em>nameSpace</em> listview will
appear in the upper left corner of the virtual grid.
<p> <pre> StructureParser * handler = new StructureParser( nameSpace );
</pre>
<p> Then we create a handler that deals with the XML data read by the reader.
As the provided handler class <a href="tqxmldefaulthandler.html">TQXmlDefaultHandler</a> simply does nothing
with the data from the reader,
we can't use it right away. Instead we have to subclass our
own <a href="#structureparser.cpp">StructureParser</a> from it.
<p> <pre> reader.<a href="tqxmlreader.html#setContentHandler">setContentHandler</a>( handler );
</pre>
<p> The <em>handler</em> serves as content handler for the reader. Note that
for simplicity reasons we don't register e.g. an error handler. Thus
our program will not complain about for example missing closing tags
in the parsed XML document.
<p> <pre> reader.<a href="tqxmlsimplereader.html#parse">parse</a>( source );
</pre>
<p> Finally we parse the document with the reader's default feature settings.
<p> <pre> <a href="ntqlistview.html">TQListView</a> * namespacePrefix = new <a href="ntqlistview.html">TQListView</a>( container,
"table_namespace_prefix" );
</pre>
<p> Now we prepare for the parsing of the same XML input source with
different reader settings. The output will be presented in
a second <a href="ntqlistview.html">TQListView</a>, <em>namespacePrefix</em>. As it is the second
member of the <em>container</em> grid it will appear in the middle of
the upper grid row.
<p> <pre> handler->setListView( namespacePrefix );
</pre>
<p> Then we ask the <em>handler</em> to present the data in the <em>namespacePrefix</em>
listview.
<p> <pre> <a name="x2125"></a> reader.<a href="tqxmlsimplereader.html#setFeature">setFeature</a>( "http://xml.org/sax/features/namespace-prefixes",
TRUE );
</pre>
<p> Now we modify the behaviour of the <em>reader</em> and change
<em>http://xml.org/sax/features/namespace-prefixes</em> from the default FALSE
to TRUE. The <em>http://xml.org/sax/features/namespaces</em> feature has
still its default setting TRUE.
<p> <pre> source.<a href="tqxmlinputsource.html#reset">reset</a>();
</pre>
<p> We have to reset the input source to make the new parsing start from the
beginning of the document again.
<p> <pre> reader.<a href="tqxmlsimplereader.html#parse">parse</a>( source );
</pre>
<p> Finally we parse the XML file a second time with the changed reader
settings (TRUE/TRUE).
<p> <pre> <a href="ntqlistview.html">TQListView</a> * prefix = new <a href="ntqlistview.html">TQListView</a>( container, "table_prefix");
handler->setListView( prefix );
reader.<a href="tqxmlsimplereader.html#setFeature">setFeature</a>( "http://xml.org/sax/features/namespaces", FALSE );
source.<a href="tqxmlinputsource.html#reset">reset</a>();
reader.<a href="tqxmlsimplereader.html#parse">parse</a>( source );
</pre>
<p> Next we prepare and use the upper right listview to show the reader results
with the feature setting <em>http://xml.org/sax/features/namespaces</em>
FALSE and <em>http://xml.org/sax/features/namespace-prefixes</em> TRUE.
<p> <pre> // namespace label
(void) new <a href="ntqlabel.html">TQLabel</a>(
"Default:\n"
"http://xml.org/sax/features/namespaces: TRUE\n"
"http://xml.org/sax/features/namespace-prefixes: FALSE\n",
container );
// namespace prefix label
(void) new <a href="ntqlabel.html">TQLabel</a>(
"\n"
"http://xml.org/sax/features/namespaces: TRUE\n"
"http://xml.org/sax/features/namespace-prefixes: TRUE\n",
container );
// prefix label
(void) new <a href="ntqlabel.html">TQLabel</a>(
"\n"
"http://xml.org/sax/features/namespaces: FALSE\n"
"http://xml.org/sax/features/namespace-prefixes: TRUE\n",
container );
</pre>
<p> The second row of the <em>container</em> grid is filled with three labels
denoting the reader settings that belong to the above listview.
<p> <pre> app.<a href="ntqapplication.html#setMainWidget">setMainWidget</a>( container );
container-><a href="tqwidget.html#show">show</a>();
return app.<a href="ntqapplication.html#exec">exec</a>();
}
</pre>
<p> Same procedure as with every TQt GUI program: the grid serves as the
main widget of our application and is shown. After that we enter
the GUI's event loop.
<p> <h3><a name="structureparser.h">The handler API</a></h3>
<p> Let's have a brief look at the API of our handler class
<em>StructureParser</em>:
<p>
<pre> #include <<a href="tqxml-h.html">tqxml.h</a>>
#include <<a href="tqptrstack-h.html">tqptrstack.h</a>>
class TQListView;
class TQListViewItem;
class TQString;
</pre>
<p> <pre> class StructureParser: public <a href="tqxmldefaulthandler.html">TQXmlDefaultHandler</a>
{
</pre>
<p> We derive it from the <a href="tqxmldefaulthandler.html">TQXmlDefaultHandler</a> class that
implements a handler that simply does nothing.
<p> <pre> public:
StructureParser( <a href="ntqlistview.html">TQListView</a> * );
</pre>
<p> This makes it easy for us to implement only the functionality
we in fact need. In our case this is the constructor that
takes a <a href="ntqlistview.html">TQListView</a> as an argument,
<p> <pre> bool startElement( const <a href="tqstring.html">TQString</a>&, const <a href="tqstring.html">TQString</a>&, const <a href="tqstring.html">TQString</a>& ,
const <a href="tqxmlattributes.html">TQXmlAttributes</a>& );
</pre>
<p> the function to execute at the occurrence of element start tags
(inherited from <a href="tqxmlcontenthandler.html">TQXmlContentHandler</a>), and
<p> <pre> bool endElement( const <a href="tqstring.html">TQString</a>&, const <a href="tqstring.html">TQString</a>&, const <a href="tqstring.html">TQString</a>& );
</pre>
<p> the code to run when an end tag occurs.
<p> All we have to implement so far is content handling.
<p> <pre> void setListView( <a href="ntqlistview.html">TQListView</a> * );
</pre>
<p> In addition we have a function that selects a listview
for the output.
<p> <pre> private:
<a href="tqptrstack.html">TQPtrStack</a><TQListViewItem> stack;
</pre>
<p> Keep in mind that we write a SAX2 parser that doesn't
have an object model to keep all elements and attributes
in memory. To display the elements and attributes in a tree like
structure we must however keep track of all elements
that haven't been closed yet.
<p> To do this we use a LIFO stack
of TQListItems. An element will be added to the stack when
its start tag appears and removed
as soon as its end tag is parsed.
<p> <pre> <a href="ntqlistview.html">TQListView</a> * table;
};
</pre>
<p> Apart from this we define a member variable that contains
the currently used listview.
<p> <h3><a name="structureparser.cpp">The handler itself</a></h3>
<p> Now that we defined the API we have to implement the
relevant functions.
<p>
<pre> #include "structureparser.h"
#include <<a href="tqstring-h.html">tqstring.h</a>>
#include <<a href="qlistview-h.html">ntqlistview.h</a>>
</pre>
<p> <pre> StructureParser::StructureParser( <a href="ntqlistview.html">TQListView</a> * t )
: <a href="tqxmldefaulthandler.html">TQXmlDefaultHandler</a>()
{
</pre>
<p> First we have the constructor that takes a listview pointer as
its argument.
<p> <pre> setListView( t );
}
</pre>
<p> All we have to do here is to prepare the argument <a href="ntqlistview.html">TQListView</a>
before usage. This we do with the <a href="#setListView()">setListView()</a> function.
<p> <a name="setListView()"></a>
<pre> void StructureParser::setListView( <a href="ntqlistview.html">TQListView</a> * t )
{
table = t;
</pre>
<p> First we store the argument away.
<p> <pre> table->setSorting( -1 );
</pre>
<p> We want the elements to be listed as they appear in the
document -- and not for example sorted alphabetically. That's
why we switch off sorting at all.
<p> <pre> table->addColumn( "Qualified name" );
table->addColumn( "Namespace" );
}
</pre>
<p> The listview now consists of two columns: one for the
element's or attribute's qualified names and one for
their namespace URIs. Columns are added from left to right
and with the title as an argument.
<p> Now let's deal with XML content handling.
<p> <pre> bool StructureParser::<a href="tqxmlcontenthandler.html#startElement">startElement</a>( const <a href="tqstring.html">TQString</a>& namespaceURI,
const <a href="tqstring.html">TQString</a>& ,
const <a href="tqstring.html">TQString</a>& qName,
const <a href="tqxmlattributes.html">TQXmlAttributes</a>& attributes)
{
</pre>
<p> When we come across the start tag of an element the handler does
the real work. Although <em>startElement</em> is called with four
arguments we keep track of only three: the namespace URI
of the element, its qualified name and its attributes.
If an element has no namespace assigned or if the feature
settings of the reader don't provide the handler with
namespace URIs at all <em>namespaceURI</em> contains an empty
string.
<p> Note that we don't assign a variable to the second argument --
we're simply not interested in the local name of the element.
<p> <pre> <a href="qlistviewitem.html">TQListViewItem</a> * element;
</pre>
<p> Whenever an element occurs we want to show it in the listview.
Therefore we define a <a href="qlistviewitem.html">TQListViewItem</a> variable.
<p> <pre> if ( ! stack.isEmpty() ){
<a href="qlistviewitem.html">TQListViewItem</a> *lastChild = stack.top()->firstChild();
</pre>
<p> As long as the element <em>stack</em> isn't empty the current element
is a child of the topmost (last unclosed) element on the stack. Thus we
create a new <a href="qlistviewitem.html">TQListViewItem</a> as a child of TQPtrStack::stack.top() with
the new element's qualified name in the first column and the according
namespace URI (or nothing) in the second one.
<p> The <a href="qlistviewitem.html">TQListViewItem</a> is usally inserted as the first child. This means that we
would get the elements in reverse order. So we first search for the last
child of the TQPtrStack::stack.top() element and insert it after this
element.
<p> In a valid XML document this applies to all elements except
the document root.
<p> <pre> if ( lastChild ) {
while ( lastChild-><a href="qlistviewitem.html#nextSibling">nextSibling</a>() )
lastChild = lastChild-><a href="qlistviewitem.html#nextSibling">nextSibling</a>();
}
element = new <a href="qlistviewitem.html">TQListViewItem</a>( stack.top(), lastChild, qName, namespaceURI );
} else {
element = new <a href="qlistviewitem.html">TQListViewItem</a>( table, qName, namespaceURI );
}
</pre>
<p> The root element we have to handle separately because it is
the first element to go onto the <a href="qlistviewitem.html">TQListViewItem</a> stack.
Its listview item is therefore a direct child of the
<em>table</em> listview itself.
<p> <pre> stack.push( element );
</pre>
<p> Now we put the element's listview item on top of the stack.
<p> <pre> element-><a href="qlistviewitem.html#setOpen">setOpen</a>( TRUE );
</pre>
<p> By default a <a href="ntqlistview.html">TQListView</a> presents all of its nodes closed.
The user may then click on the <em>+</em> icon to see the child
entries.
<p> We however want to see the entire element tree
at once when we run the program.
Therefore we open each listview item manually.
<p> <pre> if ( attributes.<a href="tqxmlattributes.html#length">length</a>() > 0 ) {
</pre>
<p> What do we do if an element has attributes?
<p> <pre> <a name="x2105"></a> for ( int i = 0 ; i < attributes.<a href="tqxmlattributes.html#length">length</a>(); i++ ) {
<a name="x2107"></a><a name="x2106"></a> new <a href="qlistviewitem.html">TQListViewItem</a>( element, attributes.<a href="tqxmlattributes.html#qName">qName</a>(i), attributes.<a href="tqxmlattributes.html#uri">uri</a>(i) );
}
}
</pre>
<p> For each of them we create a new listview item to present the attribute's
qualified name and the relevant namespace URI (or nothing).
Obviously <em>attribute</em> is a child of
the current <em>element</em>.
<p> <pre> return TRUE;
}
</pre>
<p> To prevent the reader from throwing an error we have to
return TRUE when we successfully dealt with an
element's start tag.
<p> <pre> bool StructureParser::<a href="tqxmlcontenthandler.html#endElement">endElement</a>( const <a href="tqstring.html">TQString</a>&, const <a href="tqstring.html">TQString</a>&,
const <a href="tqstring.html">TQString</a>& )
{
stack.pop();
</pre>
<p> Whenever we come across an element's closing tag we
have to remove its listview item from the stack as
it can't have children any longer.
<p> <pre> return TRUE;
}
</pre>
<p> And so we're done.
<p> <p>See also <a href="step-by-step-examples.html">Step-by-step Examples</a>.
<!-- 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>
|
