diff options
Diffstat (limited to 'doc/xml-sax-walkthrough.doc')
| -rw-r--r-- | doc/xml-sax-walkthrough.doc | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/doc/xml-sax-walkthrough.doc b/doc/xml-sax-walkthrough.doc new file mode 100644 index 000000000..e732a00aa --- /dev/null +++ b/doc/xml-sax-walkthrough.doc @@ -0,0 +1,190 @@ +/**************************************************************************** +** +** Documentation on the sax interface of the xml module +** +** Copyright (C) 2005-2008 Trolltech ASA. All rights reserved. +** +** This file is part of the Qt 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 Qt Foundation. +** +** Please review the following information to ensure GNU General +** Public Licensing retquirements 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 Qt SAX2 classes + +For a general discussion of the XML topics in Qt 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 Qt SAX2 implementation. \endlink + +Before reading on you should at least be familiar with +the \link xml.html#sax2Intro Introduction to SAX2. \endlink + + +<a name="tquickStart"></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 qstring.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. + + + +*/ |