Add Qt3 development HEAD version

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 0000000..7184c91
--- /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 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 [email protected].
+**
+** 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="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 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 &lt; 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.
+
+
+
+*/