You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
380 lines
19 KiB
380 lines
19 KiB
<!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="ntqstring.html">TQString</a>&, const <a href="ntqstring.html">TQString</a>&, const <a href="ntqstring.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="ntqstring.html">TQString</a>&, const <a href="ntqstring.html">TQString</a>&, const <a href="ntqstring.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="qstring-h.html">ntqstring.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="ntqstring.html">TQString</a>& namespaceURI,
|
|
const <a href="ntqstring.html">TQString</a>& ,
|
|
const <a href="ntqstring.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="ntqstring.html">TQString</a>&, const <a href="ntqstring.html">TQString</a>&,
|
|
const <a href="ntqstring.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>
|