diff options
Diffstat (limited to 'doc/html/xml-sax-features-walkthrough.html')
| -rw-r--r-- | doc/html/xml-sax-features-walkthrough.html | 379 |
1 files changed, 379 insertions, 0 deletions
diff --git a/doc/html/xml-sax-features-walkthrough.html b/doc/html/xml-sax-features-walkthrough.html new file mode 100644 index 0000000..90d1603 --- /dev/null +++ b/doc/html/xml-sax-features-walkthrough.html @@ -0,0 +1,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 Qt 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 Qt 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 Qt 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 Qt XML functionality +into a Qt 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">qapplication.h</a>> + #include <<a href="qfile-h.html">qfile.h</a>> + #include <<a href="qxml-h.html">qxml.h</a>> + #include <<a href="qlistview-h.html">qlistview.h</a>> + #include <<a href="qgrid-h.html">qgrid.h</a>> + #include <<a href="qmainwindow-h.html">qmainwindow.h</a>> + #include <<a href="qlabel-h.html">qlabel.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="qapplication.html">QApplication</a> app( argc, argv ); +</pre> +<p> As usual we then create a Qt application object and hand command line arguments +over to it. +<p> <pre> <a href="qfile.html">QFile</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="qxmlinputsource.html">QXmlInputSource</a> source( &xmlFile ); +</pre> +<p> We use <em>xmlFile</em> as the XML Input Source... +<p> <pre> <a href="qxmlsimplereader.html">QXmlSimpleReader</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="qgrid.html">QGrid</a> * container = new <a href="qgrid.html">QGrid</a>( 3 ); +</pre> +<p> Now let's think about presenting the output: As described in the +<a href="xml.html#sax2Features">Qt 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="qlistview.html">QListView</a> * nameSpace = new <a href="qlistview.html">QListView</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="qxmlsimplereader.html">QXmlSimpleReader</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="qxmldefaulthandler.html">QXmlDefaultHandler</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="qxmlreader.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="qxmlsimplereader.html#parse">parse</a>( source ); +</pre> +<p> Finally we parse the document with the reader's default feature settings. +<p> <pre> <a href="qlistview.html">QListView</a> * namespacePrefix = new <a href="qlistview.html">QListView</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="qlistview.html">QListView</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="qxmlsimplereader.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="qxmlinputsource.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="qxmlsimplereader.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="qlistview.html">QListView</a> * prefix = new <a href="qlistview.html">QListView</a>( container, "table_prefix"); + handler->setListView( prefix ); + reader.<a href="qxmlsimplereader.html#setFeature">setFeature</a>( "http://xml.org/sax/features/namespaces", FALSE ); + source.<a href="qxmlinputsource.html#reset">reset</a>(); + reader.<a href="qxmlsimplereader.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="qlabel.html">QLabel</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="qlabel.html">QLabel</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="qlabel.html">QLabel</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="qapplication.html#setMainWidget">setMainWidget</a>( container ); + container-><a href="qwidget.html#show">show</a>(); + return app.<a href="qapplication.html#exec">exec</a>(); + } +</pre> +<p> Same procedure as with every Qt 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="qxml-h.html">qxml.h</a>> + #include <<a href="qptrstack-h.html">qptrstack.h</a>> + + class QListView; + class QListViewItem; + class QString; +</pre> +<p> <pre> class StructureParser: public <a href="qxmldefaulthandler.html">QXmlDefaultHandler</a> + { +</pre> +<p> We derive it from the <a href="qxmldefaulthandler.html">QXmlDefaultHandler</a> class that +implements a handler that simply does nothing. +<p> <pre> public: + StructureParser( <a href="qlistview.html">QListView</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="qlistview.html">QListView</a> as an argument, +<p> <pre> bool startElement( const <a href="qstring.html">QString</a>&, const <a href="qstring.html">QString</a>&, const <a href="qstring.html">QString</a>& , + const <a href="qxmlattributes.html">QXmlAttributes</a>& ); +</pre> +<p> the function to execute at the occurrence of element start tags +(inherited from <a href="qxmlcontenthandler.html">QXmlContentHandler</a>), and +<p> <pre> bool endElement( const <a href="qstring.html">QString</a>&, const <a href="qstring.html">QString</a>&, const <a href="qstring.html">QString</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="qlistview.html">QListView</a> * ); +</pre> +<p> In addition we have a function that selects a listview +for the output. +<p> <pre> private: + <a href="qptrstack.html">QPtrStack</a><QListViewItem> 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 QListItems. 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="qlistview.html">QListView</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="qstring-h.html">qstring.h</a>> + #include <<a href="qlistview-h.html">qlistview.h</a>> +</pre> +<p> <pre> StructureParser::StructureParser( <a href="qlistview.html">QListView</a> * t ) + : <a href="qxmldefaulthandler.html">QXmlDefaultHandler</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="qlistview.html">QListView</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="qlistview.html">QListView</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="qxmlcontenthandler.html#startElement">startElement</a>( const <a href="qstring.html">QString</a>& namespaceURI, + const <a href="qstring.html">QString</a>& , + const <a href="qstring.html">QString</a>& qName, + const <a href="qxmlattributes.html">QXmlAttributes</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">QListViewItem</a> * element; +</pre> +<p> Whenever an element occurs we want to show it in the listview. +Therefore we define a <a href="qlistviewitem.html">QListViewItem</a> variable. +<p> <pre> if ( ! stack.isEmpty() ){ + <a href="qlistviewitem.html">QListViewItem</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">QListViewItem</a> as a child of QPtrStack::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">QListViewItem</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 QPtrStack::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">QListViewItem</a>( stack.top(), lastChild, qName, namespaceURI ); + } else { + element = new <a href="qlistviewitem.html">QListViewItem</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">QListViewItem</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="qlistview.html">QListView</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="qxmlattributes.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="qxmlattributes.html#length">length</a>(); i++ ) { + <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) ); + } + } +</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="qxmlcontenthandler.html#endElement">endElement</a>( const <a href="qstring.html">QString</a>&, const <a href="qstring.html">QString</a>&, + const <a href="qstring.html">QString</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>Qt 3.3.8</div> +</table></div></address></body> +</html> |