Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

1 files changed, 403 insertions, 0 deletions

diff --git a/tests/auto/xmlpatternssdk/XMLWriter.h b/tests/auto/xmlpatternssdk/XMLWriter.h
new file mode 100644
index 0000000..dd7b548
--- /dev/null
+++ b/tests/auto/xmlpatternssdk/XMLWriter.h
@@ -0,0 +1,403 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the test suite of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef PatternistSDK_XMLWriter_H
+#define PatternistSDK_XMLWriter_H
+
+#include "Global.h"
+
+#include <QtXml/QXmlContentHandler>
+#include <QtXml/QXmlLexicalHandler>
+
+QT_BEGIN_HEADER
+
+QT_BEGIN_NAMESPACE
+
+class QIODevice;
+
+namespace QPatternistSDK
+{
+    /**
+     * @short Serializes a stream of SAX events into XML, sent to a QIODevice.
+     *
+     * XMLWriter is a fast and simple XML serializer which takes care of
+     * all the low level details of well-formedness and character escaping, allowing
+     * the user to focus on higher level issues and increasing the chances of producing
+     * valid, interoperable XML.
+     *
+     * The content XMLWriter produces is sent to a QIODevice, which is either
+     * specified in XMLWriter's constructor or via setDevice(). If writing to
+     * the device fails, the content functions such as startElement() returns @c false.
+     *
+     * XMLWriter sub-classes QXmlContentHandler meaning it can serialize content
+     * from any code that produces SAX events. The class can also be used manually,
+     * by calling startElement(), endCDATA(), and so forth.
+     *
+     * XMLWriter cannot be used to serialize multiple documents. One instance per
+     * document must be used.
+     *
+     * XMLWriter takes care of escaping content into character references as necessary. Thus,
+     * it should not be done manually. In fact, it would most likely
+     * result in invalid XML or an unintended result. XMLWriter always serializes into UTF-8.
+     *
+     * When compiled in debug mode, XMLWriter contains several tests that helps
+     * ensuring that XMLWriter produces valid XML. Some of these tests ensures that:
+     *
+     * - The @c xmlns and @c xml prefixes are used properly
+     * - Content of comments and processing instructions is valid
+     * - Element, attribute and DOCTYPE names are sensible
+     * - Elements are properly nested and balanced
+     * - To some extent that things occur in the proper order. For example, that
+     *   the document type definition isn't added inside an element
+     * - That namespaces prefixes are declared
+     *
+     * Not triggering XMLWriter's tests does not guarantee valid XML is produced,
+     * but they do help catching common mistakes and some of the corner cases in the
+     * specifications. When XMLWriter is compiled in release mode, these tests are not enabled
+     * and the error handling in effect is concerning writing to the QIODevice.
+     *
+     * Often it is of interest to add a note at the beginning of the file communicating
+     * it is auto-generated. setMessage() and setAddMessage() provides
+     * a convenient way of doing that.
+     *
+     * Namespace declarations are added with startPrefixMapping(), not by sending attributes
+     * with name <tt>xmlns:*</tt> to startElement().
+     *
+     * @see <a href="http://hsivonen.iki.fi/producing-xml/">HOWTO Avoid Being
+     * Called a Bozo When Producing XML</a>
+     * @see <a href="http://www.w3.org/TR/REC-xml/">Extensible Markup
+     * Language (XML) 1.0 (Third Edition)</a>
+     * @see <a href="http://www.w3.org/TR/REC-xml-names/">Namespaces in XML</a>
+     * @todo Replace this class with QXmlStreamWriter
+     * @author Frans Englich <frans.englich@nokia.com>
+     * @ingroup PatternistSDK
+     */
+    class Q_PATTERNISTSDK_EXPORT XMLWriter : public QXmlContentHandler
+                                           , public QXmlLexicalHandler
+    {
+    public:
+        /**
+         * Creates a XMLWriter which serializes its received events
+         * to @p outStream.
+         *
+         * @note XMLWriter does not claim ownership of @p outStream. Thus,
+         * @p outStream may not be destroyed as long as
+         * this XMLWriter instance uses it.
+         */
+        XMLWriter(QIODevice *outStream = 0);
+
+        virtual ~XMLWriter();
+
+        /**
+         * @returns @c true if opening the output device succeeds, otherwise @c false
+         */
+        virtual bool startDocument();
+
+        /**
+         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
+         * @c true
+         */
+        virtual bool characters(const QString &ch);
+
+        /**
+         * Starts an element with name @p qName and attributes @p atts. The prefix
+         * in @p qName must first be declared with startPrefixMapping(), if it has one.
+         *
+         * A call to startElement() must always at some point be balanced with a call
+         * to endElement().
+         *
+         * To declare namespaces, don't put attributes with name <tt>xmlns:*</tt> in @p atts,
+         * but use startPrefixMapping().
+         */
+        virtual bool startElement(const QString &qName, const QXmlAttributes &atts = QXmlAttributes());
+
+        /**
+         *
+         * Behaves essentially as startElement(const QString &qName, const QXmlAttributes &atts). This
+         * function is used in conjunction with other SAX classes.
+         *
+         * The call:
+         *
+         * @code
+         * startElement(QString(), QString(), qName, atts);
+         * @endcode
+         *
+         * is equivalent to:
+         *
+         * @code
+         * startElement(qName, atts);
+         * @endcode
+         *
+         * @p namespaceURI and @p localName are not used. This function is
+         * used in conjunction with other SAX classes.
+         *
+         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
+         * @c true
+         */
+        virtual bool startElement(const QString &namespaceURI,
+                                  const QString &localName,
+                                  const QString &qName,
+                                  const QXmlAttributes &atts);
+
+        /**
+         * Signals the end of an element with name @p qName. @p qName must
+         * be supplied.
+         *
+         * Calls to startElement() and endElement() must always be balanced.
+         *
+         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
+         * @c true
+         */
+        virtual bool endElement(const QString &qName);
+
+        /**
+         * Behaves essentially as endElement(const QString &qName). This function
+         * is used when XMLWriter is used in SAX code.
+         *
+         * @p namespaceURI and @p localName are not used.
+         *
+         * The call:
+         *
+         * @code
+         * endElement(QString(), QString(), qName);
+         * @endcode
+         *
+         * is equivalent to:
+         *
+         * @code
+         * endElement(qName);
+         * @endcode
+         *
+         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
+         * @c true
+         */
+        virtual bool endElement(const QString &namespaceURI,
+                                const QString &localName,
+                                const QString &qName);
+
+        /**
+         * A description of an error if it occurred. This is typically
+         * QIODevice::errorString(). If no error has occurred, an empty
+         * string is returned.
+         */
+        virtual QString errorString() const;
+
+        /**
+         * Starts a CDATA section. Content sent with characters() will not be escaped
+         * except for ">" if occurring in "]]>".
+         *
+         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
+         * @c true
+         */
+        virtual bool startCDATA();
+
+        /**
+         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
+         * @c true
+         */
+        virtual bool endCDATA();
+
+        /**
+         * Creates a document type definition.
+         *
+         * For example, the code snippet:
+         *
+         * @code
+         * writer.startDTD("html", "-//W3C//DTD XHTML 1.0 Strict//EN",
+         *                 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd");
+         * writer.endDTD();
+         * @endcode
+         *
+         * would create:
+         * @verbatim
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+@endverbatim
+         *
+         * @note A system identifier must always be specified, but a public identifier may
+         * be left out.
+         *
+         * A call to startDTD() must be followed by a call to endDTD().
+         */
+        virtual bool startDTD(const QString &name,
+                              const QString &publicId,
+                              const QString &systemId);
+
+        /**
+         * Apart from closing the DTD, an new line is also added at end.
+         */
+        virtual bool endDTD();
+
+        /**
+         * Creates a processing instruction by name @p target, and content
+         * @p data.
+         *
+         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
+         * @c true
+         */
+        virtual bool processingInstruction(const QString &target,
+                                           const QString &data);
+
+        /**
+         * Declares a namespace which maps @p prefix to @p namespaceURI. For example, the call:
+         *
+         * @code
+         * startPrefixMapping("xhtml", "http://www.w3.org/1999/xhtml");
+         * @endcode
+         *
+         * would result in:
+         *
+         * @code
+         * xmlns="http://www.w3.org/1999/xhtml"
+         * @endcode
+         */
+        virtual bool startPrefixMapping(const QString &prefix,
+                                        const QString &namespaceURI);
+
+        /**
+         * Creates a comment with content @p ch. @p ch is escaped, there's
+         * no need to do it manually. For example, calling comment() with @p ch
+         * set to "my comment", results in "<!--my comment-->" in the output.
+         *
+         * @note if @p ch contains double hyphen("--"), the produced XML will
+         * not be well formed.
+         *
+         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
+         * @c true
+         */
+        virtual bool comment(const QString &ch);
+
+        virtual bool startEntity(const QString &name);
+        virtual bool endEntity(const QString &name);
+
+        /**
+         * Sets the message which is added as a comment if addModificationMessage()
+         * is set to @c true. If no message is specified and addModificationMessage()
+         * is set to @c true, a default message is used.
+         *
+         * @see modificationMessage(), setAddMessage()
+         */
+        virtual void setMessage(const QString &msg);
+
+        /**
+         * The message that is added at the beginning of the XML events
+         * in a comment node. If no modificationMessage is set via modificationMessage(),
+         * and addModificationMessage is set to @c true, this message will be used:
+         * "NOTE: This file was automatically generated by [the application name] at
+         * [the current date time]. All changes to this file will be lost."
+         *
+         * @see setMessage()
+         */
+        virtual QString modificationMessage() const;
+
+        /**
+         * Closes the QIODevice XMLWriter writes to.
+         */
+        virtual bool endDocument();
+
+        /**
+         * Serializes @p ch as if it was sent to characters().
+         *
+         * @returns @c false if failure occurs in writing to the QIODevice, otherwise
+         * @c true
+         */
+        virtual bool ignorableWhitespace(const QString &ch);
+
+        /**
+         * This function is not used by XMLWriter, but is implemented
+         * in order to satisfy QXmlContentHandler's interface.
+         */
+        virtual bool endPrefixMapping(const QString &prefix);
+
+        /**
+         * This function is not used by XMLWriter, but is implemented
+         * in order to satisfy QXmlContentHandler's interface.
+         */
+        virtual bool skippedEntity(const QString &name);
+
+        /**
+         * This function is not used by XMLWriter, but is implemented
+         * in order to satisfy QXmlContentHandler's interface.
+         */
+        virtual void setDocumentLocator(QXmlLocator *);
+
+        /**
+         * @returns the device XMLWriter writes its output to.
+         * XMLWriter does not own the device.
+         */
+        virtual QIODevice *device() const;
+
+        /**
+         * Sets the QIODevice XMLWriter writes to, to @p device. A device must be specified
+         * either via this function or in the constructor before XMLWriter is used.
+         *
+         * XMLWriter does not claim ownership of @p device.
+         */
+        virtual void setDevice(QIODevice *device);
+
+        /**
+         * Determines whether the modification message should be inserted as a comment
+         * before the document element. The message returned by modificationMessage() is used.
+         *
+         * If @p toggle is @c true, the message will be added, otherwise not.
+         */
+        virtual void setAddMessage(const bool toggle);
+
+        /**
+         * Tells whether a modification message will be added.
+         *
+         * @see setAddMessage(), modificationMessage()
+         */
+        virtual bool addModificationMessage() const;
+
+    private:
+        Q_DISABLE_COPY(XMLWriter)
+
+        class Private;
+        Private *d;
+    };
+}
+
+QT_END_NAMESPACE
+
+QT_END_HEADER
+
+#endif
+// vim: et:ts=4:sw=4:sts=4