From 8d9cb38a66e01356bd41d24e5e3b8b206065f941 Mon Sep 17 00:00:00 2001 From: Casper van Donderen Date: Sat, 21 Apr 2012 09:17:40 +0200 Subject: Doc: Fix most QDoc errors in QtXml. Changes: - XML processing document moved from Qt XML Patterns. - Moves documentation from /doc/src to /src/xml/doc - Add new qdocconf file. Change-Id: I4bc2104714a28905304997e5ff252e662ddf0bee Reviewed-by: Jerome Pasion --- src/xml/doc/qtxml.qdocconf | 92 ++++ src/xml/doc/snippets/code/doc_src_qtxml.cpp | 43 ++ src/xml/doc/snippets/code/doc_src_qtxml.pro | 43 ++ src/xml/doc/snippets/code/doc_src_qtxml.qdoc | 102 ++++ src/xml/doc/snippets/code/src_xml_dom_qdom.cpp | 218 +++++++++ src/xml/doc/snippets/code/src_xml_sax_qxml.cpp | 43 ++ src/xml/doc/snippets/rsslisting/handler.cpp | 182 ++++++++ src/xml/doc/snippets/rsslisting/rsslisting.cpp | 251 ++++++++++ src/xml/doc/snippets/simpleparse/main.cpp | 87 ++++ src/xml/doc/src/external-resources.qdoc | 36 ++ src/xml/doc/src/qtxml.qdoc | 46 ++ src/xml/doc/src/xml-processing.qdoc | 613 +++++++++++++++++++++++++ 12 files changed, 1756 insertions(+) create mode 100644 src/xml/doc/qtxml.qdocconf create mode 100644 src/xml/doc/snippets/code/doc_src_qtxml.cpp create mode 100644 src/xml/doc/snippets/code/doc_src_qtxml.pro create mode 100644 src/xml/doc/snippets/code/doc_src_qtxml.qdoc create mode 100644 src/xml/doc/snippets/code/src_xml_dom_qdom.cpp create mode 100644 src/xml/doc/snippets/code/src_xml_sax_qxml.cpp create mode 100644 src/xml/doc/snippets/rsslisting/handler.cpp create mode 100644 src/xml/doc/snippets/rsslisting/rsslisting.cpp create mode 100644 src/xml/doc/snippets/simpleparse/main.cpp create mode 100644 src/xml/doc/src/external-resources.qdoc create mode 100644 src/xml/doc/src/qtxml.qdoc create mode 100644 src/xml/doc/src/xml-processing.qdoc (limited to 'src/xml/doc') diff --git a/src/xml/doc/qtxml.qdocconf b/src/xml/doc/qtxml.qdocconf new file mode 100644 index 0000000000..9050364ec9 --- /dev/null +++ b/src/xml/doc/qtxml.qdocconf @@ -0,0 +1,92 @@ +include(../../../doc/global/qt-cpp-ignore.qdocconf) + +project = QtXml +description = Qt XML Reference Documentation +url = http://qt-project.org/doc/qt-5.0/qtcore +version = 5.0.0 + +sourceencoding = UTF-8 +outputencoding = UTF-8 +naturallanguage = en_US +qhp.projects = QtXml + +qhp.QtCore.file = qtxml.qhp +qhp.Qt.namespace = org.qt-project.qtxml.500 +qhp.Qt.virtualFolder = qdoc +qhp.Qt.indexTitle = Qt XML Reference Documentation +qhp.Qt.indexRoot = + +qhp.Qt.filterAttributes = qtxml 5.0.0 qtrefdoc +qhp.Qt.customFilters.Qt.name = QtXml 5.0.0 +qhp.Qt.customFilters.Qt.filterAttributes = qtxml 5.0.0 +qhp.Qt.subprojects = classes overviews examples +qhp.Qt.subprojects.classes.title = Classes +qhp.Qt.subprojects.classes.indexTitle = Qt XML's Classes +qhp.Qt.subprojects.classes.selectors = class fake:headerfile +qhp.Qt.subprojects.classes.sortPages = true +qhp.Qt.subprojects.overviews.title = Overviews +qhp.Qt.subprojects.overviews.indexTitle = All Overviews and HOWTOs +qhp.Qt.subprojects.overviews.selectors = fake:page,group,module +qhp.Qt.subprojects.examples.title = Qt Core Tutorials and Examples +qhp.Qt.subprojects.examples.indexTitle = Qt Core Examples +qhp.Qt.subprojects.examples.selectors = fake:example + +dita.metadata.default.author = Qt Project +dita.metadata.default.permissions = all +dita.metadata.default.publisher = Qt Project +dita.metadata.default.copyryear = 2012 +dita.metadata.default.copyrholder = Nokia +dita.metadata.default.audience = programmer + +sources.fileextensions = "*.c++ *.cc *.cpp *.cxx *.mm *.qml *.qdoc" +headers.fileextensions = "*.ch *.h *.h++ *.hh *.hpp *.hxx" + +examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml *.css" +examples.imageextensions = "*.png" + +outputdir = ../../../doc/qtxml +tagfile = ../../../doc/qtxml/qtxml.tags + +HTML.generatemacrefs = "true" +HTML.nobreadcrumbs = "true" + +HTML.templatedir = . + +HTML.stylesheets = ../../../doc/global/style/offline.css + +HTML.headerstyles = \ + " \n" + +HTML.endheader = \ + "\n" \ + +defines = Q_QDOC \ + QT_.*_SUPPORT \ + QT_.*_LIB \ + QT_COMPAT \ + QT_KEYPAD_NAVIGATION \ + QT_NO_EGL \ + Q_WS_.* \ + Q_OS_.* \ + Q_BYTE_ORDER \ + QT_DEPRECATED \ + QT_DEPRECATED_* \ + Q_NO_USING_KEYWORD \ + __cplusplus \ + Q_COMPILER_INITIALIZER_LISTS + +versionsym = QT_VERSION_STR + +codeindent = 1 + +depends += qtcore + +headerdirs += .. + +sourcedirs += .. + +exampledirs += ../../../examples \ + ../ \ + snippets + +imagedirs += images diff --git a/src/xml/doc/snippets/code/doc_src_qtxml.cpp b/src/xml/doc/snippets/code/doc_src_qtxml.cpp new file mode 100644 index 0000000000..976fffa1ae --- /dev/null +++ b/src/xml/doc/snippets/code/doc_src_qtxml.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#include +//! [0] diff --git a/src/xml/doc/snippets/code/doc_src_qtxml.pro b/src/xml/doc/snippets/code/doc_src_qtxml.pro new file mode 100644 index 0000000000..b0a38e3432 --- /dev/null +++ b/src/xml/doc/snippets/code/doc_src_qtxml.pro @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [1] +QT += xml +#! [1] diff --git a/src/xml/doc/snippets/code/doc_src_qtxml.qdoc b/src/xml/doc/snippets/code/doc_src_qtxml.qdoc new file mode 100644 index 0000000000..9640a1410b --- /dev/null +++ b/src/xml/doc/snippets/code/doc_src_qtxml.qdoc @@ -0,0 +1,102 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [3] +A quotation. +//! [3] + + +//! [4] + +//! [4] + + +//! [5] + +//! [5] + + +//! [6] + + + Practical XML + + + A Namespace Called fnord + + + +//! [6] + + +//! [7] +Practical XML +//! [7] + + +//! [8] +xmlns="http://example.com/fnord/" +//! [8] + + +//! [9] +xmlns:book="http://example.com/fnord/book/" +//! [9] + + +//! [10] + + + Practical XML + + + A Namespace Called fnord + + + +//! [10] diff --git a/src/xml/doc/snippets/code/src_xml_dom_qdom.cpp b/src/xml/doc/snippets/code/src_xml_dom_qdom.cpp new file mode 100644 index 0000000000..f8c2382f04 --- /dev/null +++ b/src/xml/doc/snippets/code/src_xml_dom_qdom.cpp @@ -0,0 +1,218 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QDomDocument doc; +QDomImplementation impl; + +// This will create the element, but the resulting XML document will +// be invalid, because '~' is not a valid character in a tag name. +impl.setInvalidDataPolicy(QDomImplementation::AcceptInvalidData); +QDomElement elt1 = doc.createElement("foo~bar"); + +// This will create an element with the tag name "foobar". +impl.setInvalidDataPolicy(QDomImplementation::DropInvalidData); +QDomElement elt2 = doc.createElement("foo~bar"); + +// This will create a null element. +impl.setInvalidDataPolicy(QDomImplementation::ReturnNullNode); +QDomElement elt3 = doc.createElement("foo~bar"); +//! [0] + + +//! [1] +QDomDocument d; +d.setContent(someXML); +QDomNode n = d.firstChild(); +while (!n.isNull()) { + if (n.isElement()) { + QDomElement e = n.toElement(); + cout << "Element name: " << e.tagName() << endl; + break; + } + n = n.nextSibling(); +} +//! [1] + + +//! [2] +QDomDocument document; +QDomElement element1 = document.documentElement(); +QDomElement element2 = element1; +//! [2] + + +//! [3] +QDomElement element3 = document.createElement("MyElement"); +QDomElement element4 = document.createElement("MyElement"); +//! [3] + + +//! [4] + +

Heading

+

Hello you

+ +//! [4] + + +//! [5] +

Heading

+

The text...

+

Next heading

+//! [5] + + +//! [6] +

Heading

+

The text...

+

Next heading

+//! [6] + + +//! [7] + +//! [7] + + +//! [8] +QDomElement e = //... +//... +QDomAttr a = e.attributeNode("href"); +cout << a.value() << endl; // prints "http://qt.nokia.com" +a.setValue("http://qt.nokia.com/doc"); // change the node's attribute +QDomAttr a2 = e.attributeNode("href"); +cout << a2.value() << endl; // prints "http://qt.nokia.com/doc" +//! [8] + + +//! [9] +QDomElement e = //... +//... +QString s = e.text() +//! [9] + + +//! [10] +QString text; +QDomElement element = doc.documentElement(); +for(QDomNode n = element.firstChild(); !n.isNull(); n = n.nextSibling()) +{ + QDomText t = n.toText(); + if (!t.isNull()) + text += t.data(); +} +//! [10] + + +//! [11] +QDomDocument doc = // ... +QDomElement root = doc.firstChildElement("database"); +QDomElement elt = root.firstChildElement("entry"); +for (; !elt.isNull(); elt = elt.nextSiblingElement("entry")) { + // ... +} +//! [11] + + +//! [12] + +//! [12] + + +//! [13] +

Hello Qt ]]>

+//! [13] + + +//! [14] +Hello Qt +//! [14] + + +//! [15] + +//! [15] + + +//! [16] +QDomDocument doc("mydocument"); +QFile file("mydocument.xml"); +if (!file.open(QIODevice::ReadOnly)) + return; +if (!doc.setContent(&file)) { + file.close(); + return; +} +file.close(); + +// print out the element names of all elements that are direct children +// of the outermost element. +QDomElement docElem = doc.documentElement(); + +QDomNode n = docElem.firstChild(); +while(!n.isNull()) { + QDomElement e = n.toElement(); // try to convert the node to an element. + if(!e.isNull()) { + cout << qPrintable(e.tagName()) << endl; // the node really is an element. + } + n = n.nextSibling(); +} + +// Here we append a new element to the end of the document +QDomElement elem = doc.createElement("img"); +elem.setAttribute("src", "myimage.png"); +docElem.appendChild(elem); +//! [16] + + +//! [17] +QDomDocument doc("MyML"); +QDomElement root = doc.createElement("MyML"); +doc.appendChild(root); + +QDomElement tag = doc.createElement("Greeting"); +root.appendChild(tag); + +QDomText t = doc.createTextNode("Hello World"); +tag.appendChild(t); + +QString xml = doc.toString(); +//! [17] diff --git a/src/xml/doc/snippets/code/src_xml_sax_qxml.cpp b/src/xml/doc/snippets/code/src_xml_sax_qxml.cpp new file mode 100644 index 0000000000..4b9dc4a129 --- /dev/null +++ b/src/xml/doc/snippets/code/src_xml_sax_qxml.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +xmlReader.setFeature("http://xml.org/sax/features/namespace-prefixes", true); +//! [0] diff --git a/src/xml/doc/snippets/rsslisting/handler.cpp b/src/xml/doc/snippets/rsslisting/handler.cpp new file mode 100644 index 0000000000..5cd2c45023 --- /dev/null +++ b/src/xml/doc/snippets/rsslisting/handler.cpp @@ -0,0 +1,182 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/* +handler.cpp + +Provides a handler for processing XML elements found by the reader. + +The handler looks for and <link> elements within <item> elements, +and records the text found within them. Link information stored within +rdf:about attributes of <item> elements is also recorded when it is +available. + +For each item found, a signal is emitted which specifies its title and +link information. This may be used by user interfaces for the purpose of +displaying items as they are read. +*/ + +#include <QtGui> + +#include "handler.h" + +/* + Reset the state of the handler to ensure that new documents are + read correctly. + + We return true to indicate that parsing should continue. +*/ + +bool Handler::startDocument() +{ + inItem = false; + inTitle = false; + inLink = false; + + return true; +} + +/* + Process each starting element in the XML document. + + Nested item, title, or link elements are not allowed, so we return false + if we encounter any of these. We also prohibit multiple definitions of + title strings. + + Link destinations are read by this function if they are specified as + attributes in item elements. + + For all cases not explicitly checked for, we return true to indicate that + the element is acceptable, and that parsing should continue. By doing + this, we can ignore elements in which we are not interested. +*/ + +bool Handler::startElement(const QString &, const QString &, + const QString & qName, const QXmlAttributes &attr) +{ + if (qName == "item") { + + if (inItem) + return false; + else { + inItem = true; + linkString = attr.value("rdf:about"); + } + } + else if (qName == "title") { + + if (inTitle) + return false; + else if (!titleString.isEmpty()) + return false; + else if (inItem) + inTitle = true; + } + else if (qName == "link") { + + if (inLink) + return false; + else if (inItem) + inLink = true; + } + + return true; +} + +/* + Process each ending element in the XML document. + + For recognized elements, we reset flags to ensure that we can read new + instances of these elements. If we have read an item element, emit a + signal to indicate that a new item is available for display. + + We return true to indicate that parsing should continue. +*/ + +bool Handler::endElement(const QString &, const QString &, + const QString & qName) +{ + if (qName == "title" && inTitle) + inTitle = false; + else if (qName == "link" && inLink) + inLink = false; + else if (qName == "item") { + if (!titleString.isEmpty() && !linkString.isEmpty()) + emit newItem(titleString, linkString); + inItem = false; + titleString = ""; + linkString = ""; + } + + return true; +} + +/* + Collect characters when reading the contents of title or link elements + when they occur within an item element. + + We return true to indicate that parsing should continue. +*/ + +bool Handler::characters (const QString &chars) +{ + if (inTitle) + titleString += chars; + else if (inLink) + linkString += chars; + + return true; +} + +/* + Report a fatal parsing error, and return false to indicate to the reader + that parsing should stop. +*/ + +//! [0] +bool Handler::fatalError (const QXmlParseException & exception) +{ + qWarning() << "Fatal error on line" << exception.lineNumber() + << ", column" << exception.columnNumber() << ":" + << exception.message(); + + return false; +} +//! [0] diff --git a/src/xml/doc/snippets/rsslisting/rsslisting.cpp b/src/xml/doc/snippets/rsslisting/rsslisting.cpp new file mode 100644 index 0000000000..5fb7c28da9 --- /dev/null +++ b/src/xml/doc/snippets/rsslisting/rsslisting.cpp @@ -0,0 +1,251 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/* +rsslisting.cpp + +Provides a widget for displaying news items from RDF news sources. +RDF is an XML-based format for storing items of information (see +http://www.w3.org/RDF/ for details). + +The widget itself provides a simple user interface for specifying +the URL of a news source, and controlling the downloading of news. + +The widget downloads and parses the XML asynchronously, feeding the +data to an XML reader in pieces. This allows the user to interrupt +its operation, and also allows very large data sources to be read. +*/ + + +#include <QtCore> +#include <QtGui> +#include <QtNetwork> +#include <QtXml> + +#include "rsslisting.h" + + +/* + Constructs an RSSListing widget with a simple user interface, and sets + up the XML reader to use a custom handler class. + + The user interface consists of a line edit, two push buttons, and a + list view widget. The line edit is used for entering the URLs of news + sources; the push buttons start and abort the process of reading the + news. +*/ + +RSSListing::RSSListing(QWidget *parent) + : QWidget(parent) +{ + lineEdit = new QLineEdit(this); + + fetchButton = new QPushButton(tr("Fetch"), this); + abortButton = new QPushButton(tr("Abort"), this); + abortButton->setEnabled(false); + + treeWidget = new QTreeWidget(this); + QStringList headerLabels; + headerLabels << tr("Title") << tr("Link"); + treeWidget->setHeaderLabels(headerLabels); + + handler = 0; + + connect(&http, SIGNAL(readyRead(const QHttpResponseHeader &)), + this, SLOT(readData(const QHttpResponseHeader &))); + + connect(&http, SIGNAL(requestFinished(int, bool)), + this, SLOT(finished(int, bool))); + + connect(lineEdit, SIGNAL(returnPressed()), this, SLOT(fetch())); + connect(fetchButton, SIGNAL(clicked()), this, SLOT(fetch())); + connect(abortButton, SIGNAL(clicked()), &http, SLOT(abort())); + + QVBoxLayout *layout = new QVBoxLayout(this); + + QHBoxLayout *hboxLayout = new QHBoxLayout; + + hboxLayout->addWidget(lineEdit); + hboxLayout->addWidget(fetchButton); + hboxLayout->addWidget(abortButton); + + layout->addLayout(hboxLayout); + layout->addWidget(treeWidget); + + setWindowTitle(tr("RSS listing example")); +} + +/* + Starts fetching data from a news source specified in the line + edit widget. + + The line edit is made read only to prevent the user from modifying its + contents during the fetch; this is only for cosmetic purposes. + The fetch button is disabled, and the abort button is enabled to allow + the user to interrupt processing. The list view is cleared, and we + define the last list view item to be 0, meaning that there are no + existing items in the list. + + We reset the flag used to determine whether parsing should begin again + or continue. A new handler is created, if required, and made available + to the reader. + + The HTTP handler is supplied with the raw contents of the line edit and + a fetch is initiated. We keep the ID value returned by the HTTP handler + for future reference. +*/ + +void RSSListing::fetch() +{ + lineEdit->setReadOnly(true); + fetchButton->setEnabled(false); + abortButton->setEnabled(true); + treeWidget->clear(); + + lastItemCreated = 0; + + newInformation = true; + + if (handler != 0) + delete handler; + handler = new Handler; + +//! [0] + xmlReader.setContentHandler(handler); + xmlReader.setErrorHandler(handler); +//! [0] + + connect(handler, SIGNAL(newItem(QString &, QString &)), + this, SLOT(addItem(QString &, QString &))); + + QUrl url(lineEdit->text()); + + http.setHost(url.host()); + connectionId = http.get(url.path()); +} + +/* + Reads data received from the RDF source. + + We read all the available data, and pass it to the XML + input source. The first time we receive new information, + the reader is set up for a new incremental parse; + we continue parsing using a different function on + subsequent calls involving the same data source. + + If parsing fails for any reason, we abort the fetch. +*/ + +//! [1] +void RSSListing::readData(const QHttpResponseHeader &resp) +{ + bool ok; + + if (resp.statusCode() != 200) + http.abort(); + else { + xmlInput.setData(http.readAll()); + + if (newInformation) { + ok = xmlReader.parse(&xmlInput, true); + newInformation = false; + } + else + ok = xmlReader.parseContinue(); + + if (!ok) + http.abort(); + } +} +//! [1] + +/* + Finishes processing an HTTP request. + + The default behavior is to keep the text edit read only. + + If an error has occurred, the user interface is made available + to the user for further input, allowing a new fetch to be + started. + + If the HTTP get request has finished, we perform a final + parsing operation on the data returned to ensure that it was + well-formed. Whether this is successful or not, we make the + user interface available to the user for further input. +*/ + +void RSSListing::finished(int id, bool error) +{ + if (error) { + qWarning("Received error during HTTP fetch."); + lineEdit->setReadOnly(false); + abortButton->setEnabled(false); + fetchButton->setEnabled(true); + } + else if (id == connectionId) { + + bool ok = xmlReader.parseContinue(); + if (!ok) + qWarning("Parse error at the end of input."); + + lineEdit->setReadOnly(false); + abortButton->setEnabled(false); + fetchButton->setEnabled(true); + } +} + +/* + Adds an item to the list view as it is reported by the handler. + + We keep a record of the last item created to ensure that the + items are created in sequence. +*/ + +void RSSListing::addItem(QString &title, QString &link) +{ + QTreeWidgetItem *item; + + item = new QTreeWidgetItem(treeWidget, lastItemCreated); + item->setText(0, title); + item->setText(1, link); + + lastItemCreated = item; +} + diff --git a/src/xml/doc/snippets/simpleparse/main.cpp b/src/xml/doc/snippets/simpleparse/main.cpp new file mode 100644 index 0000000000..bd00885d78 --- /dev/null +++ b/src/xml/doc/snippets/simpleparse/main.cpp @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <qfile.h> +#include <qxml.h> +#include "handler.h" + +#include <iostream> + +int main(int argc, char **argv) +{ + if (argc != 2) { + std::cout << "Usage: " << argv[0] << " <filename>" << std::endl; + return 1; + } + + QFile *file = new QFile(argv[1]); + +//! [0] + QXmlSimpleReader xmlReader; + QXmlInputSource *source = new QXmlInputSource(file); +//! [0] + +//! [1] + Handler *handler = new Handler; + xmlReader.setContentHandler(handler); + xmlReader.setErrorHandler(handler); +//! [1] + +//! [2] + bool ok = xmlReader.parse(source); + + if (!ok) + std::cout << "Parsing failed." << std::endl; +//! [2] + else { + QStringList names = handler->names(); + QList<int> indentations = handler->indentations(); + + int items = names.count(); + + for (int i = 0; i < items; ++i) { + for (int j = 0; j < indentations[i]; ++j) + std::cout << " "; + std::cout << names[i].toLocal8Bit().constData() << std::endl; + } + } + + return 0; +} diff --git a/src/xml/doc/src/external-resources.qdoc b/src/xml/doc/src/external-resources.qdoc new file mode 100644 index 0000000000..2f0a67e553 --- /dev/null +++ b/src/xml/doc/src/external-resources.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \externalpage http://www.w3.org/TR/REC-DOM-Level-1/ + \title W3C DOM Level 1 +*/ + +/*! + \externalpage http://www.w3.org/TR/DOM-Level-2-Core/ + \title W3C DOM Level 2 +*/ diff --git a/src/xml/doc/src/qtxml.qdoc b/src/xml/doc/src/qtxml.qdoc new file mode 100644 index 0000000000..519e61a6b5 --- /dev/null +++ b/src/xml/doc/src/qtxml.qdoc @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module QtXml + \title QtXml Module + \ingroup modules + \ingroup technology-apis + + \brief The QtXml module provides a stream reader and writer for + XML documents, and C++ implementations of SAX and DOM. + + To include the definitions of the module's classes, use the + following directive: + + \snippet code/doc_src_qtxml.cpp 0 + + To link against the module, add this line to your \l qmake \c + .pro file: + + \snippet code/doc_src_qtxml.pro 1 +*/ diff --git a/src/xml/doc/src/xml-processing.qdoc b/src/xml/doc/src/xml-processing.qdoc new file mode 100644 index 0000000000..617815905e --- /dev/null +++ b/src/xml/doc/src/xml-processing.qdoc @@ -0,0 +1,613 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group xml-tools + \title XML Classes + + \brief Classes that support XML, via, for example DOM and SAX. + + These classes are relevant to XML users. + + \generatelist{related} +*/ + +/*! + \page xml-processing.html + \title XML Processing + \ingroup technology-apis + + \brief An Overview of the XML processing facilities in Qt. + + In addition to core XML support, classes for higher level querying + and manipulation of XML data are provided by the Qt XML Patterns + module. In the QtSvg module, the QSvgRenderer and QSvgGenerator + classes can read and write a subset of SVG, an XML-based file + format. Qt also provides helper functions that may be useful to + those working with XML and XHTML: see Qt::escape() and + Qt::convertFromPlainText(). + + \section1 Topics: + + \list + \li \l {Classes for XML Processing} + \li \l {An Introduction to Namespaces} + \li \l {XML Streaming} + \li \l {The SAX Interface} + \li \l {Working with the DOM Tree} + \endlist + + \section1 Classes for XML Processing + + These classes are relevant to XML users. + + \annotatedlist xml-tools +*/ + +/*! + \page xml-namespaces.html + \title An Introduction to Namespaces + \target namespaces + + \contentspage XML Processing + \nextpage XML Streaming + + Parts of the Qt XML module documentation assume that you are familiar + with XML namespaces. Here we present a brief introduction; skip to + \link #namespacesConventions Qt XML documentation conventions \endlink + if you already know this material. + + Namespaces are a concept introduced into XML to allow a more modular + design. With their help data processing software can easily resolve + naming conflicts in XML documents. + + Consider the following example: + + \snippet code/doc_src_qtxml.qdoc 6 + + Here we find three different uses of the name \e title. If you wish to + process this document you will encounter problems because each of the + \e titles should be displayed in a different manner -- even though + they have the same name. + + The solution would be to have some means of identifying the first + occurrence of \e title as the title of a book, i.e. to use the \e + title element of a book namespace to distinguish it from, for example, + the chapter title, e.g.: + \snippet code/doc_src_qtxml.qdoc 7 + + \e book in this case is a \e prefix denoting the namespace. + + Before we can apply a namespace to element or attribute names we must + declare it. + + Namespaces are URIs like \e http://www.example.com/fnord/book/. This + does not mean that data must be available at this address; the URI is + simply used to provide a unique name. + + We declare namespaces in the same way as attributes; strictly speaking + they \e are attributes. To make for example \e + http://www.example.com/fnord/ the document's default XML namespace \e + xmlns we write + + \snippet code/doc_src_qtxml.qdoc 8 + + To distinguish the \e http://www.example.com/fnord/book/ namespace from + the default, we must supply it with a prefix: + + \snippet code/doc_src_qtxml.qdoc 9 + + A namespace that is declared like this can be applied to element and + attribute names by prepending the appropriate prefix and a ":" + delimiter. We have already seen this with the \e book:title element. + + Element names without a prefix belong to the default namespace. This + rule does not apply to attributes: an attribute without a prefix does + not belong to any of the declared XML namespaces at all. Attributes + always belong to the "traditional" namespace of the element in which + they appear. A "traditional" namespace is not an XML namespace, it + simply means that all attribute names belonging to one element must be + different. Later we will see how to assign an XML namespace to an + attribute. + + Due to the fact that attributes without prefixes are not in any XML + namespace there is no collision between the attribute \e title (that + belongs to the \e author element) and for example the \e title element + within a \e chapter. + + Let's clarify this with an example: + \snippet code/doc_src_qtxml.qdoc 10 + + Within the \e document element we have two namespaces declared. The + default namespace \e http://www.example.com/fnord/ applies to the \e + book element, the \e chapter element, the appropriate \e title element + and of course to \e document itself. + + The \e book:author and \e book:title elements belong to the namespace + with the URI \e http://www.example.com/fnord/book/. + + The two \e book:author attributes \e title and \e name have no XML + namespace assigned. They are only members of the "traditional" + namespace of the element \e book:author, meaning that for example two + \e title attributes in \e book:author are forbidden. + + In the above example we circumvent the last rule by adding a \e title + attribute from the \e http://www.example.com/fnord/ namespace to \e + book:author: the \e fnord:title comes from the namespace with the + prefix \e fnord that is declared in the \e book:author element. + + Clearly the \e fnord namespace has the same namespace URI as the + default namespace. So why didn't we simply use the default namespace + we'd already declared? The answer is quite complex: + \list + \li attributes without a prefix don't belong to any XML namespace at + all, not even to the default namespace; + \li additionally omitting the prefix would lead to a \e title-title clash; + \li writing it as \e xmlns:title would declare a new namespace with the + prefix \e title instead of applying the default \e xmlns namespace. + \endlist + + With the Qt XML classes elements and attributes can be accessed in two + ways: either by refering to their qualified names consisting of the + namespace prefix and the "real" name (or \e local name) or by the + combination of local name and namespace URI. + + More information on XML namespaces can be found at + \l http://www.w3.org/TR/REC-xml-names/. + + \target namespacesConventions + \section1 Conventions Used in the Qt XML Documentation + + The following terms are used to distinguish the parts of names within + the context of namespaces: + \list + \li The \e {qualified name} + is the name as it appears in the document. (In the above example \e + book:title is a qualified name.) + \li A \e {namespace prefix} in a qualified name + is the part to the left of the ":". (\e book is the namespace prefix in + \e book:title.) + \li The \e {local part} of a name (also refered to as the \e {local + name}) appears to the right of the ":". (Thus \e title is the + local part of \e book:title.) + \li The \e {namespace URI} ("Uniform Resource Identifier") is a unique + identifier for a namespace. It looks like a URL + (e.g. \e http://www.example.com/fnord/ ) but does not require + data to be accessible by the given protocol at the named address. + \endlist + + Elements without a ":" (like \e chapter in the example) do not have a + namespace prefix. In this case the local part and the qualified name + are identical (i.e. \e chapter). + + \sa {DOM Bookmarks Example}, {SAX Bookmarks Example} +*/ + +/*! + \page xml-streaming.html + \title XML Streaming + + \previouspage An Introduction to Namespaces + \contentspage XML Processing + \nextpage The SAX Interface + + Since version 4.3, Qt provides two new classes for reading and + writing XML: QXmlStreamReader and QXmlStreamWriter. + + The QXmlStreamReader and QXmlStreamWriter are two new classes provided + in Qt 4.3 and later. A stream reader reports an XML document as a stream + of tokens. This differs from SAX as SAX applications provide handlers to + receive XML events from the parser whereas the QXmlStreamReader drives the + loop, pulling tokens from the reader when they are needed. + This pulling approach makes it possible to build recursive descent parsers, + allowing XML parsing code to be split into different methods or classes. + + QXmlStreamReader is a well-formed XML 1.0 parser that excludes external + parsed entities. Hence, data provided by the stream reader adheres to the + W3C's criteria for well-formed XML, as long as no error occurs. Otherwise, + functions such as \l{QXmlStreamReader::atEnd()}{atEnd()}, + \l{QXmlStreamReader::error()}{error()} and \l{QXmlStreamReader::hasError()} + {hasError()} can be used to check and view the errors. + + An example of QXmlStreamReader implementation would be the \c XbelReader in + \l{QXmlStream Bookmarks Example}, which is a subclass of QXmlStreamReader. + The constructor takes \a treeWidget as a parameter and the class has Xbel + specific functions: + + \snippet xml/streambookmarks/xbelreader.h 1 + + \dots + \snippet xml/streambookmarks/xbelreader.h 2 + \dots + + The \c read() function accepts a QIODevice and sets it with + \l{QXmlStreamReader::setDevice()}{setDevice()}. The + \l{QXmlStreamReader::raiseError()}{raiseError()} function is used to + display a custom error message, inidicating that the file's version + is incorrect. + + \snippet xml/streambookmarks/xbelreader.cpp 1 + + The pendent to QXmlStreamReader is QXmlStreamWriter, which provides an XML + writer with a simple streaming API. QXmlStreamWriter operates on a + QIODevice and has specialised functions for all XML tokens or events you + want to write, such as \l{QXmlStreamWriter::writeDTD()}{writeDTD()}, + \l{QXmlStreamWriter::writeCharacters()}{writeCharacters()}, + \l{QXmlStreamWriter::writeComment()}{writeComment()} and so on. + + To write XML document with QXmlStreamWriter, you start a document with the + \l{QXmlStreamWriter::writeStartDocument()}{writeStartDocument()} function + and end it with \l{QXmlStreamWriter::writeEndDocument()} + {writeEndDocument()}, which implicitly closes all remaining open tags. + Element tags are opened with \l{QXmlStreamWriter::writeStartDocument()} + {writeStartDocument()} and followed by + \l{QXmlStreamWriter::writeAttribute()}{writeAttribute()} or + \l{QXmlStreamWriter::writeAttributes()}{writeAttributes()}, + element content, and then \l{QXmlStreamWriter::writeEndDocument()} + {writeEndDocument()}. Also, \l{QXmlStreamWriter::writeEmptyElement()} + {writeEmptyElement()} can be used to write empty elements. + + Element content comprises characters, entity references or nested elements. + Content can be written with \l{QXmlStreamWriter::writeCharacters()} + {writeCharacters()}, a function that also takes care of escaping all + forbidden characters and character sequences, + \l{QXmlStreamWriter::writeEntityReference()}{writeEntityReference()}, + or subsequent calls to \l{QXmlStreamWriter::writeStartElement()} + {writeStartElement()}. + + The \c XbelWriter class from \l{QXmlStream Bookmarks Example} is a subclass + of QXmlStreamWriter. Its \c writeFile() function illustrates the core + functions of QXmlStreamWriter mentioned above: + + \snippet xml/streambookmarks/xbelwriter.cpp 1 +*/ + +/*! + \page xml-sax.html + \title The SAX interface + + \previouspage XML Streaming + \contentspage XML Processing + \nextpage Working with the DOM Tree + + SAX is an event-based standard interface for XML parsers. + The Qt interface follows the design of the SAX2 Java implementation. + Its naming scheme was adapted to fit the Qt naming conventions. + Details on SAX2 can be found at \l{http://www.saxproject.org}. + + Support for SAX2 filters and the reader factory are under + development. The Qt implementation does not include the SAX1 + compatibility classes present in the Java interface. + + \section1 Introduction to SAX2 + + The SAX2 interface is an event-driven mechanism to provide the user with + document information. An "event" in this context means something + reported by the parser, for example, it has encountered a start tag, + or an end tag, etc. + + To make it less abstract consider the following example: + \snippet code/doc_src_qtxml.qdoc 3 + + Whilst reading (a SAX2 parser is usually referred to as "reader") + the above document three events would be triggered: + \list 1 + \li A start tag occurs (\c{<quote>}). + \li Character data (i.e. text) is found, "A quotation.". + \li An end tag is parsed (\c{</quote>}). + \endlist + + Each time such an event occurs the parser reports it; you can set up + event handlers to respond to these events. + + Whilst this is a fast and simple approach to read XML documents, + manipulation is difficult because data is not stored, simply handled + and discarded serially. The \l{Working with the DOM Tree}{DOM interface} + reads in and stores the whole document in a tree structure; + this takes more memory, but makes it easier to manipulate the + document's structure. + + The Qt XML module provides an abstract class, \l QXmlReader, that + defines the interface for potential SAX2 readers. Qt includes a reader + implementation, \l QXmlSimpleReader, that is easy to adapt through + subclassing. + + The reader reports parsing events through special handler classes: + \table + \header \li Handler class \li Description + \row \li \l QXmlContentHandler + \li Reports events related to the content of a document (e.g. the start tag + or characters). + \row \li \l QXmlDTDHandler + \li Reports events related to the DTD (e.g. notation declarations). + \row \li \l QXmlErrorHandler + \li Reports errors or warnings that occurred during parsing. + \row \li \l QXmlEntityResolver + \li Reports external entities during parsing and allows users to resolve + external entities themselves instead of leaving it to the reader. + \row \li \l QXmlDeclHandler + \li Reports further DTD related events (e.g. attribute declarations). + \row \li \l QXmlLexicalHandler + \li Reports events related to the lexical structure of the + document (the beginning of the DTD, comments etc.). + \endtable + + These classes are abstract classes describing the interface. The \l + QXmlDefaultHandler class provides a "do nothing" default + implementation for all of them. Therefore users only need to overload + the QXmlDefaultHandler functions they are interested in. + + To read input XML data a special class \l QXmlInputSource is used. + + Apart from those already mentioned, the following SAX2 support classes + provide additional useful functionality: + \table + \header \li Class \li Description + \row \li \l QXmlAttributes + \li Used to pass attributes in a start element event. + \row \li \l QXmlLocator + \li Used to obtain the actual parsing position of an event. + \row \li \l QXmlNamespaceSupport + \li Used to implement namespace support for a reader. Note that + namespaces do not change the parsing behavior. They are only + reported through the handler. + \endtable + + The \l{SAX Bookmarks example} illustrates how to subclass + QXmlDefaultHandler to read an XML bookmark file (XBEL) and + how to generate XML by hand. + + \section1 SAX2 Features + + The behavior of an XML reader depends on its support for certain + optional features. For example, a reader may have the feature "report + attributes used for namespace declarations and prefixes along with + the local name of a tag". Like every other feature this has a unique + name represented by a URI: it is called + \e http://xml.org/sax/features/namespace-prefixes. + + The Qt SAX2 implementation can report whether the reader has + particular functionality using the QXmlReader::hasFeature() + function. Available features can be tested with QXmlReader::feature(), + and switched on or off using QXmlReader::setFeature(). + + Consider the example + \snippet code/doc_src_qtxml.qdoc 4 + A reader that does not support the \e + http://xml.org/sax/features/namespace-prefixes feature would report + the element name \e document but not its attributes \e xmlns:book and + \e xmlns with their values. A reader with the feature \e + http://xml.org/sax/features/namespace-prefixes reports the namespace + attributes if the \link QXmlReader::feature() feature\endlink is + switched on. + + Other features include \e http://xml.org/sax/features/namespace + (namespace processing, implies \e + http://xml.org/sax/features/namespace-prefixes) and \e + http://xml.org/sax/features/validation (the ability to report + validation errors). + + Whilst SAX2 leaves it to the user to define and implement whatever + features are required, support for \e + http://xml.org/sax/features/namespace (and thus \e + http://xml.org/sax/features/namespace-prefixes) is mandantory. + The \l QXmlSimpleReader implementation of \l QXmlReader, + supports them, and can do namespace processing. + + \l QXmlSimpleReader is not validating, so it + does not support \e http://xml.org/sax/features/validation. + + \section1 Namespace Support via Features + + As we have seen in the previous section, we can configure the + behavior of the reader when it comes to namespace + processing. This is done by setting and unsetting the + \e http://xml.org/sax/features/namespaces and + \e http://xml.org/sax/features/namespace-prefixes features. + + They influence the reporting behavior in the following way: + \list 1 + \li Namespace prefixes and local parts of elements and attributes can + be reported. + \li The qualified names of elements and attributes are reported. + \li \l QXmlContentHandler::startPrefixMapping() and \l + QXmlContentHandler::endPrefixMapping() are called by the reader. + \li Attributes that declare namespaces (i.e. the attribute \e xmlns and + attributes starting with \e{xmlns:}) are reported. + \endlist + + Consider the following element: + \snippet code/doc_src_qtxml.qdoc 5 + With \e http://xml.org/sax/features/namespace-prefixes set to true + the reader will report four attributes; but with the \e + namespace-prefixes feature set to false only three, with the \e + xmlns:fnord attribute defining a namespace being "invisible" to the + reader. + + The \e http://xml.org/sax/features/namespaces feature is responsible + for reporting local names, namespace prefixes and URIs. With \e + http://xml.org/sax/features/namespaces set to true the parser will + report \e title as the local name of the \e fnord:title attribute, \e + fnord being the namespace prefix and \e http://example.com/fnord/ as + the namespace URI. When \e http://xml.org/sax/features/namespaces is + false none of them are reported. + + In the current implementation the Qt XML classes follow the definition + that the prefix \e xmlns itself isn't associated with any namespace at all + (see \l{http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-using}). + Therefore even with \e http://xml.org/sax/features/namespaces and + \e http://xml.org/sax/features/namespace-prefixes both set to true + the reader won't return either a local name, a namespace prefix or + a namespace URI for \e xmlns:fnord. + + This might be changed in the future following the W3C suggestion + \link http://www.w3.org/2000/xmlns/ http://www.w3.org/2000/xmlns/ \endlink + to associate \e xmlns with the namespace \e http://www.w3.org/2000/xmlns. + + As the SAX2 standard suggests, \l QXmlSimpleReader defaults to having + \e http://xml.org/sax/features/namespaces set to true and + \e http://xml.org/sax/features/namespace-prefixes set to false. + When changing this behavior using \l QXmlSimpleReader::setFeature() + note that the combination of both features set to + false is illegal. + + \section2 Summary + + \l QXmlSimpleReader implements the following behavior: + + \table + \header \li (namespaces, namespace-prefixes) + \li Namespace prefix and local part + \li Qualified names + \li Prefix mapping + \li xmlns attributes + \row \li (true, false) \li Yes \li Yes* \li Yes \li No + \row \li (true, true) \li Yes \li Yes \li Yes \li Yes + \row \li (false, true) \li No* \li Yes \li No* \li Yes + \row \li (false, false) \li {4,1} Illegal + \endtable + + The behavior of the entries marked with an asterisk (*) is not specified by SAX. + + \section1 Properties + + Properties are a more general concept. They have a unique name, + represented as an URI, but their value is \c void*. Thus nearly + anything can be used as a property value. This concept involves some + danger, though: there is no means of ensuring type-safety; the user + must take care that they pass the right type. Properties are + useful if a reader supports special handler classes. + + The URIs used for features and properties often look like URLs, e.g. + \c http://xml.org/sax/features/namespace. This does not mean that the + data required is at this address. It is simply a way of defining + unique names. + + Anyone can define and use new SAX2 properties for their readers. + Property support is not mandatory. + + To set or query properties the following functions are provided: \l + QXmlReader::setProperty(), \l QXmlReader::property() and \l + QXmlReader::hasProperty(). +*/ + +/*! + \page xml-dom.tml + \title Working with the DOM Tree + \target dom + + \previouspage The SAX Interface + \contentspage XML Processing + + DOM Level 2 is a W3C Recommendation for XML interfaces that maps the + constituents of an XML document to a tree structure. The specification + of DOM Level 2 can be found at \l{http://www.w3.org/DOM/}. + + \target domIntro + \section1 Introduction to DOM + + DOM provides an interface to access and change the content and + structure of an XML file. It makes a hierarchical view of the document + (a tree view). Thus -- in contrast to the SAX2 interface -- an object + model of the document is resident in memory after parsing which makes + manipulation easy. + + All DOM nodes in the document tree are subclasses of \l QDomNode. The + document itself is represented as a \l QDomDocument object. + + Here are the available node classes and their potential child classes: + + \list + \li \l QDomDocument: Possible children are + \list + \li \l QDomElement (at most one) + \li \l QDomProcessingInstruction + \li \l QDomComment + \li \l QDomDocumentType + \endlist + \li \l QDomDocumentFragment: Possible children are + \list + \li \l QDomElement + \li \l QDomProcessingInstruction + \li \l QDomComment + \li \l QDomText + \li \l QDomCDATASection + \li \l QDomEntityReference + \endlist + \li \l QDomDocumentType: No children + \li \l QDomEntityReference: Possible children are + \list + \li \l QDomElement + \li \l QDomProcessingInstruction + \li \l QDomComment + \li \l QDomText + \li \l QDomCDATASection + \li \l QDomEntityReference + \endlist + \li \l QDomElement: Possible children are + \list + \li \l QDomElement + \li \l QDomText + \li \l QDomComment + \li \l QDomProcessingInstruction + \li \l QDomCDATASection + \li \l QDomEntityReference + \endlist + \li \l QDomAttr: Possible children are + \list + \li \l QDomText + \li \l QDomEntityReference + \endlist + \li \l QDomProcessingInstruction: No children + \li \l QDomComment: No children + \li \l QDomText: No children + \li \l QDomCDATASection: No children + \li \l QDomEntity: Possible children are + \list + \li \l QDomElement + \li \l QDomProcessingInstruction + \li \l QDomComment + \li \l QDomText + \li \l QDomCDATASection + \li \l QDomEntityReference + \endlist + \li \l QDomNotation: No children + \endlist + + With \l QDomNodeList and \l QDomNamedNodeMap two collection classes + are provided: \l QDomNodeList is a list of nodes, + and \l QDomNamedNodeMap is used to handle unordered sets of nodes + (often used for attributes). + + The \l QDomImplementation class allows the user to query features of the + DOM implementation. + + To get started please refer to the \l QDomDocument documentation. + You might also want to take a look at the \l{DOM Bookmarks example}, + which illustrates how to read and write an XML bookmark file (XBEL) + using DOM. +*/ -- cgit v1.2.3