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.
191 lines
6.0 KiB
191 lines
6.0 KiB
/****************************************************************************
|
|
**
|
|
** Documentation on the sax interface of the xml module
|
|
**
|
|
** Copyright (C) 2005-2008 Trolltech ASA. All rights reserved.
|
|
**
|
|
** This file is part of the TQt GUI Toolkit.
|
|
**
|
|
** This file may be used under the terms of the GNU General
|
|
** Public License versions 2.0 or 3.0 as published by the Free
|
|
** Software Foundation and appearing in the files LICENSE.GPL2
|
|
** and LICENSE.GPL3 included in the packaging of this file.
|
|
** Alternatively you may (at your option) use any later version
|
|
** of the GNU General Public License if such license has been
|
|
** publicly approved by Trolltech ASA (or its successors, if any)
|
|
** and the KDE Free TQt Foundation.
|
|
**
|
|
** Please review the following information to ensure GNU General
|
|
** Public Licensing requirements will be met:
|
|
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
|
|
** If you are unsure which license is appropriate for your use, please
|
|
** review the following information:
|
|
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
|
|
** or contact the sales department at sales@trolltech.com.
|
|
**
|
|
** This file may be used under the terms of the Q Public License as
|
|
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
|
|
** included in the packaging of this file. Licensees holding valid Qt
|
|
** Commercial licenses may use this file in accordance with the Qt
|
|
** Commercial License Agreement provided with the Software.
|
|
**
|
|
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
|
|
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
|
|
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
|
|
** herein.
|
|
**
|
|
**********************************************************************/
|
|
|
|
/*! \page xml-sax-walkthrough.html
|
|
|
|
\ingroup step-by-step-examples
|
|
|
|
\title Walkthrough: How to use the TQt SAX2 classes
|
|
|
|
For a general discussion of the XML topics in TQt please refer to
|
|
the document \link xml.html XML Module. \endlink
|
|
To learn more about SAX2 see the document describing
|
|
\link xml.html#sax2 the TQt SAX2 implementation. \endlink
|
|
|
|
Before reading on you should at least be familiar with
|
|
the \link xml.html#sax2Intro Introduction to SAX2. \endlink
|
|
|
|
|
|
<a name="quickStart"></a>
|
|
<h2>A tiny parser</h2>
|
|
|
|
In this section we will present a small example reader that outputs
|
|
the names of all elements in an XML document on the command line.
|
|
The element names are indented corresponding to their nesting level.
|
|
|
|
As mentioned in \link xml.html#sax2Intro Introduction to SAX2 \endlink
|
|
we have to implement the functions of the handler classes that we are
|
|
interested in. In our case these are only three:
|
|
\l QXmlContentHandler::startDocument(),
|
|
\l QXmlContentHandler::startElement() and
|
|
\l QXmlContentHandler::endElement().
|
|
|
|
For this purpose we use a subclass of the \l QXmlDefaultHandler (remember
|
|
that the special handler classes are all abstract and the default handler class
|
|
provides an implementation that does not change the parsing behavior):
|
|
|
|
\include xml/tagreader/structureparser.h
|
|
|
|
Apart from the private helper variable \e indent that we will use to
|
|
get indentation right, there is nothing special about our new
|
|
\e StructureParser class.
|
|
|
|
\quotefile xml/tagreader/structureparser.cpp
|
|
|
|
Even the implementation is straight-forward:
|
|
|
|
\skipto include
|
|
\printuntil ntqstring.h
|
|
|
|
First we overload \l QXmlContentHandler::startDocument() with a non-empty version.
|
|
|
|
\printline startDocument
|
|
\printuntil }
|
|
|
|
At the beginning of the document we simply
|
|
set \e indent to an empty string because we
|
|
want to print out the root element without any indentation.
|
|
Also we return TRUE so that the parser continues without
|
|
reporting an error.
|
|
|
|
Because we want to be informed when the parser comes
|
|
accross a start tag of an element and subsequently print it out, we
|
|
have to overload \l QXmlContentHandler::startElement().
|
|
|
|
\printline startElement
|
|
\printuntil }
|
|
|
|
This is what the implementation does: The name of the element with
|
|
preceding indentation is printed out followed by a linebreak.
|
|
Strictly speaking \e qName contains the local element name
|
|
without an eventual prefix denoting the \link xml.html#namespaces namespace.
|
|
\endlink
|
|
|
|
If another element follows before the current element's end tag
|
|
it should be indented. Therefore we add four spaces to the
|
|
\e indent string.
|
|
|
|
Finally we return TRUE in order to let the parser continue without
|
|
errors.
|
|
|
|
The last functionality we need to add is the parser's behaviour when an
|
|
end tag occurs. This means overloading \l QXmlContentHandler::endElement().
|
|
|
|
\printline endElement
|
|
\printuntil }
|
|
|
|
Obviously we then should shorten the \e indent string by the four
|
|
whitespaces added in startElement().
|
|
|
|
With this we're done with our parser and can start writing the main()
|
|
program.
|
|
|
|
\quotefile xml/tagreader/tagreader.cpp
|
|
|
|
\skipto include
|
|
\printto handler
|
|
|
|
This check ensures that we have a sequence of files from the command
|
|
line to examine.
|
|
|
|
\printline handler
|
|
|
|
The next step is to create an instance of the \e StructureParser.
|
|
|
|
\printline reader
|
|
\printline setContentHandler
|
|
|
|
After that we set up the reader. As our \e StructureParser
|
|
class deals with \l QXmlContentHandler functionality only
|
|
we simply register it as the content handler of our choice.
|
|
|
|
\printuntil for
|
|
|
|
Successively we deal with all files given as command line arguments.
|
|
|
|
\printline xmlFile
|
|
\printline QXmlInputSource
|
|
|
|
Then we create a
|
|
\l QXmlInputSource for the XML file to be parsed.
|
|
|
|
\printline parse
|
|
|
|
Now we take our input source and start parsing.
|
|
|
|
\printline }
|
|
\printuntil }
|
|
|
|
|
|
Running the program on the following XML file...
|
|
|
|
\include xml/tagreader/animals.xml
|
|
|
|
... produces the following output:
|
|
\code
|
|
animals
|
|
mammals
|
|
monkeys
|
|
gorilla
|
|
orang-utan
|
|
birds
|
|
pigeon
|
|
penguin
|
|
\endcode
|
|
|
|
It will however refuse to produce the correct result if you e.g. insert
|
|
a whitespace between a < and the element name in your test-XML file.
|
|
To prevent such annoyances
|
|
you should always install an error handler with \l
|
|
QXmlReader::setErrorHandler(). This allows you to report
|
|
parsing errors to the user.
|
|
|
|
|
|
|
|
*/
|