source: trunk/doc/html/xml-sax-features-walkthrough.html

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

reference documentation added
File size: 19.0 KB
RevLine 
[190]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-sax-features-walkthrough.doc:36 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>Walkthrough: Using SAX2 features with the Qt XML classes</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>Walkthrough: Using SAX2 features with the Qt XML classes</h1>
33
34
35<p>
36<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
37parser</a>.
38If features of SAX2 readers are new to you please read
39<a href="xml.html#sax2Features">the feature section</a> of the SAX2 document.
40<p> As a novice to the Qt XML classes it is advisable to have a look at the
41<a href="xml-sax-walkthrough.html">tiny SAX2 parser walkthrough</a> before
42reading on.
43<p> This walkthrough covers two topics: First of all it shows how to
44set SAX2 features and secondly how to integrate the Qt XML functionality
45into a Qt GUI application.
46<p> The resulting application allows you to compare the output of the reader
47depending on how the two features
48<em>http://xml.org/sax/features/namespace-prefixes</em>
49and <em>http://xml.org/sax/features/namespaces</em> are set.
50To do this it shows tree views of the read XML file
51listing the qualified names of elements and attributes and the respective
52namespace URIs.
53<p> <h3>Setting features</h3>
54<p>
55
56<p> Let's begin with the main program of the application. First the boring
57part: we include all the classes we need:
58<p> <pre> #include "structureparser.h"
59 #include &lt;<a href="qapplication-h.html">qapplication.h</a>&gt;
60 #include &lt;<a href="qfile-h.html">qfile.h</a>&gt;
61 #include &lt;<a href="qxml-h.html">qxml.h</a>&gt;
62 #include &lt;<a href="qlistview-h.html">qlistview.h</a>&gt;
63 #include &lt;<a href="qgrid-h.html">qgrid.h</a>&gt;
64 #include &lt;<a href="qmainwindow-h.html">qmainwindow.h</a>&gt;
65 #include &lt;<a href="qlabel-h.html">qlabel.h</a>&gt;
66</pre>
67<p> <a href="#structureparser.h">structureparser.h</a> contains the API of
68the XML parser that we implement in <a href="#structureparser.cpp">structureparser.cpp.</a>
69<p> <pre> int main( int argc, char **argv )
70 {
71 <a href="qapplication.html">QApplication</a> app( argc, argv );
72</pre>
73<p> As usual we then create a Qt application object and hand command line arguments
74over to it.
75<p> <pre> <a href="qfile.html">QFile</a> xmlFile( argc == 2 ? argv[1] : "fnord.xml" );
76</pre>
77<p> If the user runs the program with one filename as
78an argument we process this file, otherwise we use the <em>fnord.xml</em> file from
79the example directory for demonstration purposes.
80<p> <pre> <a href="qxmlinputsource.html">QXmlInputSource</a> source( &amp;xmlFile );
81</pre>
82<p> We use <em>xmlFile</em> as the XML Input Source...
83<p> <pre> <a href="qxmlsimplereader.html">QXmlSimpleReader</a> reader;
84</pre>
85<p> ... and instantiate a <em>reader</em> object. Later we will manipulate its features
86and thus influence how the XML data are read.
87<p> <pre> <a href="qgrid.html">QGrid</a> * container = new <a href="qgrid.html">QGrid</a>( 3 );
88</pre>
89<p> Now let's think about presenting the output: As described in the
90<a href="xml.html#sax2Features">Qt SAX2 documentation</a>
91there are three valid combinations of <em>http://xml.org/sax/features/namespace-prefixes</em>
92and <em>http://xml.org/sax/features/namespaces</em>: TRUE/TRUE, TRUE/FALSE and
93FALSE/TRUE. To show the relevant output side by side of each other
94and mark them with three labels makes up for a grid layout consisting
95of three columns (and thus two lines).
96<p> <pre> <a href="qlistview.html">QListView</a> * nameSpace = new <a href="qlistview.html">QListView</a>( container, "table_namespace" );
97</pre>
98<p> The most natural way of presenting XML elements is in a tree.
99Thus we use a listview. Its name <em>nameSpace</em> indicates that this
100one will be used to present the combination of <em>http://xml.org/sax/features/namespaces</em> being TRUE and
101<em>http://xml.org/sax/features/namespace-prefixes</em>
102being FALSE -- the default configuration of a <a href="qxmlsimplereader.html">QXmlSimpleReader</a>.
103<p> Being the first grid entry the <em>nameSpace</em> listview will
104appear in the upper left corner of the virtual grid.
105<p> <pre> StructureParser * handler = new StructureParser( nameSpace );
106</pre>
107<p> Then we create a handler that deals with the XML data read by the reader.
108As the provided handler class <a href="qxmldefaulthandler.html">QXmlDefaultHandler</a> simply does nothing
109with the data from the reader,
110we can't use it right away. Instead we have to subclass our
111own <a href="#structureparser.cpp">StructureParser</a> from it.
112<p> <pre> reader.<a href="qxmlreader.html#setContentHandler">setContentHandler</a>( handler );
113</pre>
114<p> The <em>handler</em> serves as content handler for the reader. Note that
115for simplicity reasons we don't register e.g. an error handler. Thus
116our program will not complain about for example missing closing tags
117in the parsed XML document.
118<p> <pre> reader.<a href="qxmlsimplereader.html#parse">parse</a>( source );
119</pre>
120<p> Finally we parse the document with the reader's default feature settings.
121<p> <pre> <a href="qlistview.html">QListView</a> * namespacePrefix = new <a href="qlistview.html">QListView</a>( container,
122 "table_namespace_prefix" );
123</pre>
124<p> Now we prepare for the parsing of the same XML input source with
125different reader settings. The output will be presented in
126a second <a href="qlistview.html">QListView</a>, <em>namespacePrefix</em>. As it is the second
127member of the <em>container</em> grid it will appear in the middle of
128the upper grid row.
129<p> <pre> handler-&gt;setListView( namespacePrefix );
130</pre>
131<p> Then we ask the <em>handler</em> to present the data in the <em>namespacePrefix</em>
132listview.
133<p> <pre> <a name="x2125"></a> reader.<a href="qxmlsimplereader.html#setFeature">setFeature</a>( "http://xml.org/sax/features/namespace-prefixes",
134 TRUE );
135</pre>
136<p> Now we modify the behaviour of the <em>reader</em> and change
137<em>http://xml.org/sax/features/namespace-prefixes</em> from the default FALSE
138to TRUE. The <em>http://xml.org/sax/features/namespaces</em> feature has
139still its default setting TRUE.
140<p> <pre> source.<a href="qxmlinputsource.html#reset">reset</a>();
141</pre>
142<p> We have to reset the input source to make the new parsing start from the
143beginning of the document again.
144<p> <pre> reader.<a href="qxmlsimplereader.html#parse">parse</a>( source );
145</pre>
146<p> Finally we parse the XML file a second time with the changed reader
147settings (TRUE/TRUE).
148<p> <pre> <a href="qlistview.html">QListView</a> * prefix = new <a href="qlistview.html">QListView</a>( container, "table_prefix");
149 handler-&gt;setListView( prefix );
150 reader.<a href="qxmlsimplereader.html#setFeature">setFeature</a>( "http://xml.org/sax/features/namespaces", FALSE );
151 source.<a href="qxmlinputsource.html#reset">reset</a>();
152 reader.<a href="qxmlsimplereader.html#parse">parse</a>( source );
153</pre>
154<p> Next we prepare and use the upper right listview to show the reader results
155with the feature setting <em>http://xml.org/sax/features/namespaces</em>
156FALSE and <em>http://xml.org/sax/features/namespace-prefixes</em> TRUE.
157<p> <pre> // namespace label
158 (void) new <a href="qlabel.html">QLabel</a>(
159 "Default:\n"
160 "http://xml.org/sax/features/namespaces: TRUE\n"
161 "http://xml.org/sax/features/namespace-prefixes: FALSE\n",
162 container );
163
164 // namespace prefix label
165 (void) new <a href="qlabel.html">QLabel</a>(
166 "\n"
167 "http://xml.org/sax/features/namespaces: TRUE\n"
168 "http://xml.org/sax/features/namespace-prefixes: TRUE\n",
169 container );
170
171 // prefix label
172 (void) new <a href="qlabel.html">QLabel</a>(
173 "\n"
174 "http://xml.org/sax/features/namespaces: FALSE\n"
175 "http://xml.org/sax/features/namespace-prefixes: TRUE\n",
176 container );
177</pre>
178<p> The second row of the <em>container</em> grid is filled with three labels
179denoting the reader settings that belong to the above listview.
180<p> <pre> app.<a href="qapplication.html#setMainWidget">setMainWidget</a>( container );
181 container-&gt;<a href="qwidget.html#show">show</a>();
182 return app.<a href="qapplication.html#exec">exec</a>();
183 }
184</pre>
185<p> Same procedure as with every Qt GUI program: the grid serves as the
186main widget of our application and is shown. After that we enter
187the GUI's event loop.
188<p> <h3><a name="structureparser.h">The handler API</a></h3>
189<p> Let's have a brief look at the API of our handler class
190<em>StructureParser</em>:
191<p>
192
193<pre> #include &lt;<a href="qxml-h.html">qxml.h</a>&gt;
194 #include &lt;<a href="qptrstack-h.html">qptrstack.h</a>&gt;
195
196 class QListView;
197 class QListViewItem;
198 class QString;
199</pre>
200<p> <pre> class StructureParser: public <a href="qxmldefaulthandler.html">QXmlDefaultHandler</a>
201 {
202</pre>
203<p> We derive it from the <a href="qxmldefaulthandler.html">QXmlDefaultHandler</a> class that
204implements a handler that simply does nothing.
205<p> <pre> public:
206 StructureParser( <a href="qlistview.html">QListView</a> * );
207</pre>
208<p> This makes it easy for us to implement only the functionality
209we in fact need. In our case this is the constructor that
210takes a <a href="qlistview.html">QListView</a> as an argument,
211<p> <pre> bool startElement( const <a href="qstring.html">QString</a>&amp;, const <a href="qstring.html">QString</a>&amp;, const <a href="qstring.html">QString</a>&amp; ,
212 const <a href="qxmlattributes.html">QXmlAttributes</a>&amp; );
213</pre>
214<p> the function to execute at the occurrence of element start tags
215(inherited from <a href="qxmlcontenthandler.html">QXmlContentHandler</a>), and
216<p> <pre> bool endElement( const <a href="qstring.html">QString</a>&amp;, const <a href="qstring.html">QString</a>&amp;, const <a href="qstring.html">QString</a>&amp; );
217</pre>
218<p> the code to run when an end tag occurs.
219<p> All we have to implement so far is content handling.
220<p> <pre> void setListView( <a href="qlistview.html">QListView</a> * );
221</pre>
222<p> In addition we have a function that selects a listview
223for the output.
224<p> <pre> private:
225 <a href="qptrstack.html">QPtrStack</a>&lt;QListViewItem&gt; stack;
226</pre>
227<p> Keep in mind that we write a SAX2 parser that doesn't
228have an object model to keep all elements and attributes
229in memory. To display the elements and attributes in a tree like
230structure we must however keep track of all elements
231that haven't been closed yet.
232<p> To do this we use a LIFO stack
233of QListItems. An element will be added to the stack when
234its start tag appears and removed
235as soon as its end tag is parsed.
236<p> <pre> <a href="qlistview.html">QListView</a> * table;
237 };
238</pre>
239<p> Apart from this we define a member variable that contains
240the currently used listview.
241<p> <h3><a name="structureparser.cpp">The handler itself</a></h3>
242<p> Now that we defined the API we have to implement the
243relevant functions.
244<p>
245
246<pre> #include "structureparser.h"
247
248 #include &lt;<a href="qstring-h.html">qstring.h</a>&gt;
249 #include &lt;<a href="qlistview-h.html">qlistview.h</a>&gt;
250</pre>
251<p> <pre> StructureParser::StructureParser( <a href="qlistview.html">QListView</a> * t )
252 : <a href="qxmldefaulthandler.html">QXmlDefaultHandler</a>()
253 {
254</pre>
255<p> First we have the constructor that takes a listview pointer as
256its argument.
257<p> <pre> setListView( t );
258 }
259</pre>
260<p> All we have to do here is to prepare the argument <a href="qlistview.html">QListView</a>
261before usage. This we do with the <a href="#setListView()">setListView()</a> function.
262<p> <a name="setListView()"></a>
263<pre> void StructureParser::setListView( <a href="qlistview.html">QListView</a> * t )
264 {
265 table = t;
266</pre>
267<p> First we store the argument away.
268<p> <pre> table-&gt;setSorting( -1 );
269</pre>
270<p> We want the elements to be listed as they appear in the
271document -- and not for example sorted alphabetically. That's
272why we switch off sorting at all.
273<p> <pre> table-&gt;addColumn( "Qualified name" );
274 table-&gt;addColumn( "Namespace" );
275 }
276</pre>
277<p> The listview now consists of two columns: one for the
278element's or attribute's qualified names and one for
279their namespace URIs. Columns are added from left to right
280and with the title as an argument.
281<p> Now let's deal with XML content handling.
282<p> <pre> bool StructureParser::<a href="qxmlcontenthandler.html#startElement">startElement</a>( const <a href="qstring.html">QString</a>&amp; namespaceURI,
283 const <a href="qstring.html">QString</a>&amp; ,
284 const <a href="qstring.html">QString</a>&amp; qName,
285 const <a href="qxmlattributes.html">QXmlAttributes</a>&amp; attributes)
286 {
287</pre>
288<p> When we come across the start tag of an element the handler does
289the real work. Although <em>startElement</em> is called with four
290arguments we keep track of only three: the namespace URI
291of the element, its qualified name and its attributes.
292If an element has no namespace assigned or if the feature
293settings of the reader don't provide the handler with
294namespace URIs at all <em>namespaceURI</em> contains an empty
295string.
296<p> Note that we don't assign a variable to the second argument --
297we're simply not interested in the local name of the element.
298<p> <pre> <a href="qlistviewitem.html">QListViewItem</a> * element;
299</pre>
300<p> Whenever an element occurs we want to show it in the listview.
301Therefore we define a <a href="qlistviewitem.html">QListViewItem</a> variable.
302<p> <pre> if ( ! stack.isEmpty() ){
303 <a href="qlistviewitem.html">QListViewItem</a> *lastChild = stack.top()-&gt;firstChild();
304</pre>
305<p> As long as the element <em>stack</em> isn't empty the current element
306is a child of the topmost (last unclosed) element on the stack. Thus we
307create a new <a href="qlistviewitem.html">QListViewItem</a> as a child of QPtrStack::stack.top() with
308the new element's qualified name in the first column and the according
309namespace URI (or nothing) in the second one.
310<p> The <a href="qlistviewitem.html">QListViewItem</a> is usally inserted as the first child. This means that we
311would get the elements in reverse order. So we first search for the last
312child of the QPtrStack::stack.top() element and insert it after this
313element.
314<p> In a valid XML document this applies to all elements except
315the document root.
316<p> <pre> if ( lastChild ) {
317 while ( lastChild-&gt;<a href="qlistviewitem.html#nextSibling">nextSibling</a>() )
318 lastChild = lastChild-&gt;<a href="qlistviewitem.html#nextSibling">nextSibling</a>();
319 }
320 element = new <a href="qlistviewitem.html">QListViewItem</a>( stack.top(), lastChild, qName, namespaceURI );
321 } else {
322 element = new <a href="qlistviewitem.html">QListViewItem</a>( table, qName, namespaceURI );
323 }
324</pre>
325<p> The root element we have to handle separately because it is
326the first element to go onto the <a href="qlistviewitem.html">QListViewItem</a> stack.
327Its listview item is therefore a direct child of the
328<em>table</em> listview itself.
329<p> <pre> stack.push( element );
330</pre>
331<p> Now we put the element's listview item on top of the stack.
332<p> <pre> element-&gt;<a href="qlistviewitem.html#setOpen">setOpen</a>( TRUE );
333</pre>
334<p> By default a <a href="qlistview.html">QListView</a> presents all of its nodes closed.
335The user may then click on the <em>+</em> icon to see the child
336entries.
337<p> We however want to see the entire element tree
338at once when we run the program.
339Therefore we open each listview item manually.
340<p> <pre> if ( attributes.<a href="qxmlattributes.html#length">length</a>() &gt; 0 ) {
341</pre>
342<p> What do we do if an element has attributes?
343<p> <pre> <a name="x2105"></a> for ( int i = 0 ; i &lt; attributes.<a href="qxmlattributes.html#length">length</a>(); i++ ) {
344 <a name="x2107"></a><a name="x2106"></a> new <a href="qlistviewitem.html">QListViewItem</a>( element, attributes.<a href="qxmlattributes.html#qName">qName</a>(i), attributes.<a href="qxmlattributes.html#uri">uri</a>(i) );
345 }
346 }
347</pre>
348<p> For each of them we create a new listview item to present the attribute's
349qualified name and the relevant namespace URI (or nothing).
350Obviously <em>attribute</em> is a child of
351the current <em>element</em>.
352<p> <pre> return TRUE;
353 }
354</pre>
355<p> To prevent the reader from throwing an error we have to
356return TRUE when we successfully dealt with an
357element's start tag.
358<p> <pre> bool StructureParser::<a href="qxmlcontenthandler.html#endElement">endElement</a>( const <a href="qstring.html">QString</a>&amp;, const <a href="qstring.html">QString</a>&amp;,
359 const <a href="qstring.html">QString</a>&amp; )
360 {
361 stack.pop();
362</pre>
363<p> Whenever we come across an element's closing tag we
364have to remove its listview item from the stack as
365it can't have children any longer.
366<p> <pre> return TRUE;
367 }
368</pre>
369<p> And so we're done.
370<p> <p>See also <a href="step-by-step-examples.html">Step-by-step Examples</a>.
371
372<!-- eof -->
373<p><address><hr><div align=center>
374<table width=100% cellspacing=0 border=0><tr>
375<td>Copyright &copy; 2007
376<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
377<td align=right><div align=right>Qt 3.3.8</div>
378</table></div></address></body>
379</html>
Note: See TracBrowser for help on using the repository browser.