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

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

reference documentation added
File size: 9.6 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-walkthrough.doc:36 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>Walkthrough: How to use the Qt SAX2 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: How to use the Qt SAX2 classes</h1>
33
34
35<p>
36<p> For a general discussion of the XML topics in Qt please refer to
37the document <a href="xml.html">XML Module.</a>
38To learn more about SAX2 see the document describing
39<a href="xml.html#sax2">the Qt SAX2 implementation.</a>
40<p> Before reading on you should at least be familiar with
41the <a href="xml.html#sax2Intro">Introduction to SAX2.</a>
42<p> <a name="quickStart"></a>
43<h2>A tiny parser</h2>
44<p> In this section we will present a small example reader that outputs
45the names of all elements in an XML document on the command line.
46The element names are indented corresponding to their nesting level.
47<p> As mentioned in <a href="xml.html#sax2Intro">Introduction to SAX2</a>
48we have to implement the functions of the handler classes that we are
49interested in. In our case these are only three:
50<a href="qxmlcontenthandler.html#startDocument">QXmlContentHandler::startDocument</a>(),
51<a href="qxmlcontenthandler.html#startElement">QXmlContentHandler::startElement</a>() and
52<a href="qxmlcontenthandler.html#endElement">QXmlContentHandler::endElement</a>().
53<p> For this purpose we use a subclass of the <a href="qxmldefaulthandler.html">QXmlDefaultHandler</a> (remember
54that the special handler classes are all abstract and the default handler class
55provides an implementation that does not change the parsing behavior):
56<p> <pre>/****************************************************************************
57** $Id: xml-sax-walkthrough.html 2051 2007-02-21 10:04:20Z chehrlic $
58**
59** Copyright (C) 1992-2007 Trolltech ASA. All rights reserved.
60**
61** This file is part of an example program for Qt. This example
62** program may be used, distributed and modified without limitation.
63**
64*****************************************************************************/
65
66#ifndef STRUCTUREPARSER_H
67#define STRUCTUREPARSER_H
68
69#include &lt;<a href="qxml-h.html">qxml.h</a>&gt;
70
71class QString;
72
73class StructureParser : public <a href="qxmldefaulthandler.html">QXmlDefaultHandler</a>
74{
75public:
76 bool startDocument();
77 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; ,
78 const <a href="qxmlattributes.html">QXmlAttributes</a>&amp; );
79 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; );
80
81private:
82 <a href="qstring.html">QString</a> indent;
83};
84
85#endif
86</pre>
87
88<p> Apart from the private helper variable <em>indent</em> that we will use to
89get indentation right, there is nothing special about our new
90<em>StructureParser</em> class.
91<p>
92
93<p> Even the implementation is straight-forward:
94<p> <pre> #include "structureparser.h"
95
96 #include &lt;stdio.h&gt;
97 #include &lt;<a href="qstring-h.html">qstring.h</a>&gt;
98</pre>
99<p> First we overload <a href="qxmlcontenthandler.html#startDocument">QXmlContentHandler::startDocument</a>() with a non-empty version.
100<p> <pre> <a name="x2137"></a>bool StructureParser::<a href="qxmlcontenthandler.html#startDocument">startDocument</a>()
101 {
102 indent = "";
103 return TRUE;
104 }
105</pre>
106<p> At the beginning of the document we simply
107set <em>indent</em> to an empty string because we
108want to print out the root element without any indentation.
109Also we return TRUE so that the parser continues without
110reporting an error.
111<p> Because we want to be informed when the parser comes
112accross a start tag of an element and subsequently print it out, we
113have to overload <a href="qxmlcontenthandler.html#startElement">QXmlContentHandler::startElement</a>().
114<p> <pre> <a name="x2138"></a>bool StructureParser::<a href="qxmlcontenthandler.html#startElement">startElement</a>( const <a href="qstring.html">QString</a>&amp;, const <a href="qstring.html">QString</a>&amp;,
115 const <a href="qstring.html">QString</a>&amp; qName,
116 const <a href="qxmlattributes.html">QXmlAttributes</a>&amp; )
117 {
118 printf( "%s%s\n", (const char*)indent, (const char*)qName );
119 indent += " ";
120 return TRUE;
121 }
122</pre>
123<p> This is what the implementation does: The name of the element with
124preceding indentation is printed out followed by a linebreak.
125Strictly speaking <em>qName</em> contains the local element name
126without an eventual prefix denoting the <a href="xml.html#namespaces">namespace.</a>
127<p> If another element follows before the current element's end tag
128it should be indented. Therefore we add four spaces to the
129<em>indent</em> string.
130<p> Finally we return TRUE in order to let the parser continue without
131errors.
132<p> The last functionality we need to add is the parser's behaviour when an
133end tag occurs. This means overloading <a href="qxmlcontenthandler.html#endElement">QXmlContentHandler::endElement</a>().
134<p> <pre> <a name="x2136"></a>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;, const <a href="qstring.html">QString</a>&amp; )
135 {
136 indent.remove( (uint)0, 4 );
137 return TRUE;
138 }
139</pre>
140<p> Obviously we then should shorten the <em>indent</em> string by the four
141whitespaces added in startElement().
142<p> With this we're done with our parser and can start writing the main()
143program.
144<p>
145
146<p> <pre> #include "structureparser.h"
147 #include &lt;<a href="qfile-h.html">qfile.h</a>&gt;
148 #include &lt;<a href="qxml-h.html">qxml.h</a>&gt;
149 #include &lt;<a href="qwindowdefs-h.html">qwindowdefs.h</a>&gt;
150
151 int main( int argc, char **argv )
152 {
153 if ( argc &lt; 2 ) {
154 fprintf( stderr, "Usage: %s &lt;xmlfile&gt; [&lt;xmlfile&gt; ...]\n", argv[0] );
155 return 1;
156 }
157</pre>
158<p> This check ensures that we have a sequence of files from the command
159line to examine.
160<p> <pre> StructureParser handler;
161</pre>
162<p> The next step is to create an instance of the <em>StructureParser</em>.
163<p> <pre> <a href="qxmlsimplereader.html">QXmlSimpleReader</a> reader;
164 <a name="x2140"></a> reader.<a href="qxmlreader.html#setContentHandler">setContentHandler</a>( &amp;handler );
165</pre>
166<p> After that we set up the reader. As our <em>StructureParser</em>
167class deals with <a href="qxmlcontenthandler.html">QXmlContentHandler</a> functionality only
168we simply register it as the content handler of our choice.
169<p> <pre> for ( int i=1; i &lt; argc; i++ ) {
170</pre>
171<p> Successively we deal with all files given as command line arguments.
172<p> <pre> <a href="qfile.html">QFile</a> xmlFile( argv[i] );
173 <a href="qxmlinputsource.html">QXmlInputSource</a> source( &amp;xmlFile );
174</pre>
175<p> Then we create a
176<a href="qxmlinputsource.html">QXmlInputSource</a> for the XML file to be parsed.
177<p> <pre> <a name="x2139"></a> reader.<a href="qxmlsimplereader.html#parse">parse</a>( source );
178</pre>
179<p> Now we take our input source and start parsing.
180<p> <pre> }
181 return 0;
182 }
183</pre>
184<p> Running the program on the following XML file...
185<p> <pre>&lt;animals&gt;
186&lt;mammals&gt;
187 &lt;monkeys&gt; &lt;gorilla/&gt; &lt;orangutan/&gt; &lt;/monkeys&gt;
188&lt;/mammals&gt;
189&lt;birds&gt; &lt;pigeon/&gt; &lt;penguin/&gt; &lt;/birds&gt;
190&lt;/animals&gt;
191
192</pre>
193
194<p> ... produces the following output:
195<pre>
196animals
197 mammals
198 monkeys
199 gorilla
200 orang-utan
201 birds
202 pigeon
203 penguin
204</pre>
205
206<p> It will however refuse to produce the correct result if you e.g. insert
207a whitespace between a &lt; and the element name in your test-XML file.
208To prevent such annoyances
209you should always install an error handler with <a href="qxmlreader.html#setErrorHandler">QXmlReader::setErrorHandler</a>(). This allows you to report
210parsing errors to the user.
211<p> <p>See also <a href="step-by-step-examples.html">Step-by-step Examples</a>.
212
213<!-- eof -->
214<p><address><hr><div align=center>
215<table width=100% cellspacing=0 border=0><tr>
216<td>Copyright &copy; 2007
217<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
218<td align=right><div align=right>Qt 3.3.8</div>
219</table></div></address></body>
220</html>
Note: See TracBrowser for help on using the repository browser.