summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorCasper van Donderen <casper.vandonderen@nokia.com>2012-04-21 09:17:40 +0200
committerQt by Nokia <qt-info@nokia.com>2012-04-23 09:45:24 +0200
commit8d9cb38a66e01356bd41d24e5e3b8b206065f941 (patch)
treeb6ee4ada3a01431070a63b76a70f9e9e19272b58 /src
parent628963636521cb3853169ba278f7773b3f8c4abd (diff)
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 <jerome.pasion@nokia.com>
Diffstat (limited to 'src')
-rw-r--r--src/xml/doc/qtxml.qdocconf92
-rw-r--r--src/xml/doc/snippets/code/doc_src_qtxml.cpp43
-rw-r--r--src/xml/doc/snippets/code/doc_src_qtxml.pro43
-rw-r--r--src/xml/doc/snippets/code/doc_src_qtxml.qdoc102
-rw-r--r--src/xml/doc/snippets/code/src_xml_dom_qdom.cpp218
-rw-r--r--src/xml/doc/snippets/code/src_xml_sax_qxml.cpp43
-rw-r--r--src/xml/doc/snippets/rsslisting/handler.cpp182
-rw-r--r--src/xml/doc/snippets/rsslisting/rsslisting.cpp251
-rw-r--r--src/xml/doc/snippets/simpleparse/main.cpp87
-rw-r--r--src/xml/doc/src/external-resources.qdoc36
-rw-r--r--src/xml/doc/src/qtxml.qdoc46
-rw-r--r--src/xml/doc/src/xml-processing.qdoc613
-rw-r--r--src/xml/dom/qdom.cpp214
-rw-r--r--src/xml/sax/qxml.cpp25
14 files changed, 1885 insertions, 110 deletions
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 = \
+ " <link rel=\"stylesheet\" type=\"text/css\" href=\"style/offline.css\" />\n"
+
+HTML.endheader = \
+ "</head>\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 <QtXml>
+//! [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]
+<quote>A quotation.</quote>
+//! [3]
+
+
+//! [4]
+<document xmlns:book = 'http://example.com/fnord/book/'
+ xmlns = 'http://example.com/fnord/' >
+//! [4]
+
+
+//! [5]
+<author xmlns:fnord = 'http://example.com/fnord/'
+ title="Ms"
+ fnord:title="Goddess"
+ name="Eris Kallisti"/>
+//! [5]
+
+
+//! [6]
+<document>
+<book>
+ <title>Practical XML</title>
+ <author title="Ms" name="Eris Kallisti"/>
+ <chapter>
+ <title>A Namespace Called fnord</title>
+ </chapter>
+</book>
+</document>
+//! [6]
+
+
+//! [7]
+<book:title>Practical XML</book:title>
+//! [7]
+
+
+//! [8]
+xmlns="http://example.com/fnord/"
+//! [8]
+
+
+//! [9]
+xmlns:book="http://example.com/fnord/book/"
+//! [9]
+
+
+//! [10]
+<document xmlns:book = 'http://example.com/fnord/book/'
+ xmlns = 'http://example.com/fnord/' >
+<book>
+ <book:title>Practical XML</book:title>
+ <book:author xmlns:fnord = 'http://example.com/fnord/'
+ title="Ms"
+ fnord:title="Goddess"
+ name="Eris Kallisti"/>
+ <chapter>
+ <title>A Namespace Called fnord</title>
+ </chapter>
+</book>
+</document>
+//! [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]
+<body>
+<h1>Heading</h1>
+<p>Hello <b>you</b></p>
+</body>
+//! [4]
+
+
+//! [5]
+<h1>Heading</h1>
+<p>The text...</p>
+<h2>Next heading</h2>
+//! [5]
+
+
+//! [6]
+<h1>Heading</h1>
+<p>The text...</p>
+<h2>Next heading</h2>
+//! [6]
+
+
+//! [7]
+<link href="http://qt.nokia.com" color="red" />
+//! [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]
+<img src="myimg.png">
+//! [12]
+
+
+//! [13]
+<h1>Hello <b>Qt</b> <![CDATA[<xml is cool>]]></h1>
+//! [13]
+
+
+//! [14]
+Hello Qt <xml is cool>
+//! [14]
+
+
+//! [15]
+<!-- this is a comment -->
+//! [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 <title> 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.
+*/
diff --git a/src/xml/dom/qdom.cpp b/src/xml/dom/qdom.cpp
index 23a9db8e3a..0a6ec9542e 100644
--- a/src/xml/dom/qdom.cpp
+++ b/src/xml/dom/qdom.cpp
@@ -1081,7 +1081,7 @@ bool QDomImplementation::isNull()
the data.
\value ReturnNullNode The factory function should return a null node.
- \sa setInvalidDataPolicy() invalidDataPolicy()
+ \sa setInvalidDataPolicy(), invalidDataPolicy()
*/
/*!
@@ -1094,7 +1094,7 @@ bool QDomImplementation::isNull()
\value EncodingFromDocument The encoding is fetched from the document.
\value EncodingFromTextStream The encoding is fetched from the QTextStream.
- See also the overload of the save() function that takes an EncodingPolicy.
+ \sa QDomNode::save()
*/
/*!
@@ -1104,7 +1104,7 @@ bool QDomImplementation::isNull()
Returns the invalid data policy, which specifies what should be done when
a factory function in QDomDocument is passed invalid data.
- \sa setInvalidDataPolicy() InvalidDataPolicy
+ \sa setInvalidDataPolicy(), InvalidDataPolicy
*/
QDomImplementation::InvalidDataPolicy QDomImplementation::invalidDataPolicy()
@@ -1122,9 +1122,9 @@ QDomImplementation::InvalidDataPolicy QDomImplementation::invalidDataPolicy()
The \a policy is set for all instances of QDomDocument which already
exist and which will be created in the future.
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 0
+ \snippet code/src_xml_dom_qdom.cpp 0
- \sa invalidDataPolicy() InvalidDataPolicy
+ \sa invalidDataPolicy(), InvalidDataPolicy
*/
void QDomImplementation::setInvalidDataPolicy(InvalidDataPolicy policy)
@@ -1294,7 +1294,7 @@ int QDomNodeListPrivate::length() const
For a more general introduction of the DOM implementation see the
QDomDocument documentation.
- \sa QDomNode::childNodes() QDomDocument::elementsByTagName()
+ \sa QDomNode::childNodes(), QDomDocument::elementsByTagName()
*/
/*!
@@ -1991,11 +1991,12 @@ void QDomNodePrivate::setLocation(int lineNumber, int columnNumber)
The following example looks for the first element in an XML document and
prints the names of all the elements that are its direct children.
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 1
+
+ \snippet code/src_xml_dom_qdom.cpp 1
For further information about the Document Object Model see
- \l{http://www.w3.org/TR/REC-DOM-Level-1/}{Level 1} and
- \l{http://www.w3.org/TR/DOM-Level-2-Core/}{Level 2 Core}.
+ \l{W3C DOM Level 1}{Level 1} and
+ \l{W3C DOM Level 2}{Level 2 Core}.
For a more general introduction of the DOM implementation see the
QDomDocument documentation.
*/
@@ -2057,13 +2058,13 @@ QDomNode& QDomNode::operator=(const QDomNode &n)
structure in QDomDocument. The test for equality checks if the two
references point to the same underlying node. For example:
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 2
+ \snippet code/src_xml_dom_qdom.cpp 2
The two nodes (QDomElement is a QDomNode subclass) both refer to
the document's root element, and \c {element1 == element2} will
return true. On the other hand:
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 3
+ \snippet code/src_xml_dom_qdom.cpp 3
Even though both nodes are empty elements carrying the same name,
\c {element3 == element4} will return false because they refer to
@@ -2147,7 +2148,7 @@ QString QDomNode::nodeName() const
All the other subclasses do not have a node value and will return
an empty string.
- \sa setNodeValue() nodeName()
+ \sa setNodeValue(), nodeName()
*/
QString QDomNode::nodeValue() const
{
@@ -2192,8 +2193,8 @@ void QDomNode::setNodeValue(const QString& v)
Returns the type of the node.
\sa toAttr(), toCDATASection(), toDocumentFragment(),
- toDocument() toDocumentType(), toElement(), toEntityReference(),
- toText(), toEntity() toNotation(), toProcessingInstruction(),
+ toDocument(), toDocumentType(), toElement(), toEntityReference(),
+ toText(), toEntity(), toNotation(), toProcessingInstruction(),
toCharacterData(), toComment()
*/
QDomNode::NodeType QDomNode::nodeType() const
@@ -2220,7 +2221,9 @@ QDomNode QDomNode::parentNode() const
Most often you will call this function on a QDomElement object.
For example, if the XML document looks like this:
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 4
+
+ \snippet code/src_xml_dom_qdom.cpp 4
+
Then the list of child nodes for the "body"-element will contain
the node created by the &lt;h1&gt; tag and the node created by the
&lt;p&gt; tag.
@@ -2228,7 +2231,7 @@ QDomNode QDomNode::parentNode() const
The nodes in the list are not copied; so changing the nodes in the
list will also change the children of this node.
- \sa firstChild() lastChild()
+ \sa firstChild(), lastChild()
*/
QDomNodeList QDomNode::childNodes() const
{
@@ -2242,7 +2245,7 @@ QDomNodeList QDomNode::childNodes() const
\link isNull() null node\endlink is returned. Changing the
returned node will also change the node in the document tree.
- \sa lastChild() childNodes()
+ \sa lastChild(), childNodes()
*/
QDomNode QDomNode::firstChild() const
{
@@ -2256,7 +2259,7 @@ QDomNode QDomNode::firstChild() const
\link isNull() null node\endlink is returned. Changing the
returned node will also change the node in the document tree.
- \sa firstChild() childNodes()
+ \sa firstChild(), childNodes()
*/
QDomNode QDomNode::lastChild() const
{
@@ -2270,7 +2273,9 @@ QDomNode QDomNode::lastChild() const
returned node will also change the node in the document tree.
For example, if you have XML like this:
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 5
+
+ \snippet code/src_xml_dom_qdom.cpp 5
+
and this QDomNode represents the &lt;p&gt; tag, previousSibling()
will return the node representing the &lt;h1&gt; tag.
@@ -2288,7 +2293,9 @@ QDomNode QDomNode::previousSibling() const
returned node will also change the node in the document tree.
If you have XML like this:
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 6
+
+ \snippet code/src_xml_dom_qdom.cpp 6
+
and this QDomNode represents the <p> tag, nextSibling() will
return the node representing the <h2> tag.
@@ -2378,8 +2385,8 @@ bool QDomNode::isSupported(const QString& feature, const QString& version) const
namespaces. A namespace URI must be specified at creation time and
cannot be changed later.
- \sa prefix() localName() QDomDocument::createElementNS()
- QDomDocument::createAttributeNS()
+ \sa prefix(), localName(), QDomDocument::createElementNS(),
+ QDomDocument::createAttributeNS()
*/
QString QDomNode::namespaceURI() const
{
@@ -2406,8 +2413,9 @@ QString QDomNode::namespaceURI() const
an empty string; but it might be an empty string if the name does
not have a prefix.
- \sa setPrefix() localName() namespaceURI()
- QDomDocument::createElementNS() QDomDocument::createAttributeNS()
+ \sa setPrefix(), localName(), namespaceURI(),
+ QDomDocument::createElementNS(),
+ QDomDocument::createAttributeNS()
*/
QString QDomNode::prefix() const
{
@@ -2426,8 +2434,9 @@ QString QDomNode::prefix() const
namespaces. A namespace prefix must have be specified at creation
time; it is not possible to add a namespace prefix afterwards.
- \sa prefix() localName() namespaceURI()
- QDomDocument::createElementNS() QDomDocument::createAttributeNS()
+ \sa prefix(), localName(), namespaceURI(),
+ QDomDocument::createElementNS(),
+ QDomDocument::createAttributeNS()
*/
void QDomNode::setPrefix(const QString& pre)
{
@@ -2446,8 +2455,8 @@ void QDomNode::setPrefix(const QString& pre)
namespaces. A namespace must have been specified at creation time;
it is not possible to add a namespace afterwards.
- \sa prefix() namespaceURI() QDomDocument::createElementNS()
- QDomDocument::createAttributeNS()
+ \sa prefix(), namespaceURI(), QDomDocument::createElementNS(),
+ QDomDocument::createAttributeNS()
*/
QString QDomNode::localName() const
{
@@ -2488,7 +2497,7 @@ bool QDomNode::hasAttributes() const
The DOM specification disallow inserting attribute nodes, but due
to historical reasons QDom accept them nevertheless.
- \sa insertAfter() replaceChild() removeChild() appendChild()
+ \sa insertAfter(), replaceChild(), removeChild(), appendChild()
*/
QDomNode QDomNode::insertBefore(const QDomNode& newChild, const QDomNode& refChild)
{
@@ -2517,7 +2526,7 @@ QDomNode QDomNode::insertBefore(const QDomNode& newChild, const QDomNode& refChi
The DOM specification disallow inserting attribute nodes, but due
to historical reasons QDom accept them nevertheless.
- \sa insertBefore() replaceChild() removeChild() appendChild()
+ \sa insertBefore(), replaceChild(), removeChild(), appendChild()
*/
QDomNode QDomNode::insertAfter(const QDomNode& newChild, const QDomNode& refChild)
{
@@ -2540,7 +2549,7 @@ QDomNode QDomNode::insertAfter(const QDomNode& newChild, const QDomNode& refChil
Returns a new reference to \a oldChild on success or a \link
isNull() null node\endlink an failure.
- \sa insertBefore() insertAfter() removeChild() appendChild()
+ \sa insertBefore(), insertAfter(), removeChild(), appendChild()
*/
QDomNode QDomNode::replaceChild(const QDomNode& newChild, const QDomNode& oldChild)
{
@@ -2556,7 +2565,7 @@ QDomNode QDomNode::replaceChild(const QDomNode& newChild, const QDomNode& oldChi
Returns a new reference to \a oldChild on success or a \link
isNull() null node\endlink on failure.
- \sa insertBefore() insertAfter() replaceChild() appendChild()
+ \sa insertBefore(), insertAfter(), replaceChild(), appendChild()
*/
QDomNode QDomNode::removeChild(const QDomNode& oldChild)
{
@@ -2593,7 +2602,7 @@ QDomNode QDomNode::removeChild(const QDomNode& oldChild)
The DOM specification disallow inserting attribute nodes, but for
historical reasons, QDom accepts them anyway.
- \sa insertBefore() insertAfter() replaceChild() removeChild()
+ \sa insertBefore(), insertAfter(), replaceChild(), removeChild()
*/
QDomNode QDomNode::appendChild(const QDomNode& newChild)
{
@@ -2655,14 +2664,14 @@ QDomNode QDomNode::namedItem(const QString& name) const
/*!
Writes the XML representation of the node and all its children to
- the stream \a str. This function uses \a indent as the amount of
+ the stream \a stream. This function uses \a indent as the amount of
space to indent the node.
If the document contains invalid XML characters or characters that cannot be
encoded in the given encoding, the result and behavior is undefined.
If \a encodingPolicy is QDomNode::EncodingFromDocument and this node is a
- document node, the encoding of text stream \a str's encoding is set by
+ document node, the encoding of text stream \a stream's encoding is set by
treating a processing instruction by name "xml" as an XML declaration, if
one exists, and otherwise defaults to UTF-8. XML declarations are not
processing instructions, but this behavior exists for historical
@@ -2671,7 +2680,7 @@ QDomNode QDomNode::namedItem(const QString& name) const
If \a encodingPolicy is EncodingFromTextStream and this node is a document node, this
function behaves as save(QTextStream &str, int indent) with the exception that the encoding
- specified in the text stream \a str is used.
+ specified in the text stream \a stream is used.
If the document contains invalid XML characters or characters that cannot be
encoded in the given encoding, the result and behavior is undefined.
@@ -2917,7 +2926,7 @@ bool QDomNode::isComment() const
otherwise returns the first child element. Returns a null element if no
such child exists.
- \sa lastChildElement() previousSiblingElement() nextSiblingElement()
+ \sa lastChildElement(), previousSiblingElement(), nextSiblingElement()
*/
QDomElement QDomNode::firstChildElement(const QString &tagName) const
@@ -2937,7 +2946,7 @@ QDomElement QDomNode::firstChildElement(const QString &tagName) const
otherwise returns the last child element. Returns a null element if no
such child exists.
- \sa firstChildElement() previousSiblingElement() nextSiblingElement()
+ \sa firstChildElement(), previousSiblingElement(), nextSiblingElement()
*/
QDomElement QDomNode::lastChildElement(const QString &tagName) const
@@ -2957,7 +2966,7 @@ QDomElement QDomNode::lastChildElement(const QString &tagName) const
is non-empty; otherwise returns any next sibling element.
Returns a null element if no such sibling exists.
- \sa firstChildElement() previousSiblingElement() lastChildElement()
+ \sa firstChildElement(), previousSiblingElement(), lastChildElement()
*/
QDomElement QDomNode::nextSiblingElement(const QString &tagName) const
@@ -3283,7 +3292,7 @@ QDomNamedNodeMap::~QDomNamedNodeMap()
QDomNode::isNull() null node\endlink is returned. A node's name is
the name returned by QDomNode::nodeName().
- \sa setNamedItem() namedItemNS()
+ \sa setNamedItem(), namedItemNS()
*/
QDomNode QDomNamedNodeMap::namedItem(const QString& name) const
{
@@ -3300,7 +3309,7 @@ QDomNode QDomNamedNodeMap::namedItem(const QString& name) const
If the new node replaces an existing node, i.e. the map contains a
node with the same name, the replaced node is returned.
- \sa namedItem() removeNamedItem() setNamedItemNS()
+ \sa namedItem(), removeNamedItem(), setNamedItemNS()
*/
QDomNode QDomNamedNodeMap::setNamedItem(const QDomNode& newNode)
{
@@ -3316,7 +3325,7 @@ QDomNode QDomNamedNodeMap::setNamedItem(const QDomNode& newNode)
QDomNode::isNull() null node\endlink if the map did not contain a
node called \a name.
- \sa setNamedItem() namedItem() removeNamedItemNS()
+ \sa setNamedItem(), namedItem(), removeNamedItemNS()
*/
QDomNode QDomNamedNodeMap::removeNamedItem(const QString& name)
{
@@ -3347,7 +3356,7 @@ QDomNode QDomNamedNodeMap::item(int index) const
If the map does not contain such a node, a \link
QDomNode::isNull() null node\endlink is returned.
- \sa setNamedItemNS() namedItem()
+ \sa setNamedItemNS(), namedItem()
*/
QDomNode QDomNamedNodeMap::namedItemNS(const QString& nsURI, const QString& localName) const
{
@@ -3362,7 +3371,7 @@ QDomNode QDomNamedNodeMap::namedItemNS(const QString& nsURI, const QString& loca
it is replaced by \a newNode. If the new node replaces an existing
node, the replaced node is returned.
- \sa namedItemNS() removeNamedItemNS() setNamedItem()
+ \sa namedItemNS(), removeNamedItemNS(), setNamedItem()
*/
QDomNode QDomNamedNodeMap::setNamedItemNS(const QDomNode& newNode)
{
@@ -3380,7 +3389,7 @@ QDomNode QDomNamedNodeMap::setNamedItemNS(const QDomNode& newNode)
node with the local name \a localName and the namespace URI \a
nsURI.
- \sa setNamedItemNS() namedItemNS() removeNamedItem()
+ \sa setNamedItemNS(), namedItemNS(), removeNamedItem()
*/
QDomNode QDomNamedNodeMap::removeNamedItemNS(const QString& nsURI, const QString& localName)
{
@@ -3707,7 +3716,7 @@ QDomNamedNodeMap QDomDocumentType::notations() const
Returns the public identifier of the external DTD subset or
an empty string if there is no public identifier.
- \sa systemId() internalSubset() QDomImplementation::createDocumentType()
+ \sa systemId(), internalSubset(), QDomImplementation::createDocumentType()
*/
QString QDomDocumentType::publicId() const
{
@@ -3720,7 +3729,7 @@ QString QDomDocumentType::publicId() const
Returns the system identifier of the external DTD subset or
an empty string if there is no system identifier.
- \sa publicId() internalSubset() QDomImplementation::createDocumentType()
+ \sa publicId(), internalSubset(), QDomImplementation::createDocumentType()
*/
QString QDomDocumentType::systemId() const
{
@@ -3733,7 +3742,7 @@ QString QDomDocumentType::systemId() const
Returns the internal subset of the document type or an empty
string if there is no internal subset.
- \sa publicId() systemId()
+ \sa publicId(), systemId()
*/
QString QDomDocumentType::internalSubset() const
{
@@ -3753,7 +3762,7 @@ QString QDomDocumentType::internalSubset() const
Returns \c DocumentTypeNode.
- \sa isDocumentType() QDomNode::toDocumentType()
+ \sa isDocumentType(), QDomNode::toDocumentType()
*/
#undef IMPL
@@ -3855,7 +3864,7 @@ QDomDocumentFragment& QDomDocumentFragment::operator= (const QDomDocumentFragmen
Returns \c DocumentFragment.
- \sa isDocumentFragment() QDomNode::toDocumentFragment()
+ \sa isDocumentFragment(), QDomNode::toDocumentFragment()
*/
/**************************************************************
@@ -3945,7 +3954,7 @@ void QDomCharacterDataPrivate::appendData(const QString& arg)
The node type of the node containing this character data is
returned by nodeType().
- \sa QDomText QDomComment QDomCDATASection
+ \sa QDomText, QDomComment, QDomCDATASection
*/
/*!
@@ -4250,11 +4259,11 @@ void QDomAttrPrivate::save(QTextStream& s, int, int) const
For example, the following piece of XML produces an element with
no children, but two attributes:
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 7
+ \snippet code/src_xml_dom_qdom.cpp 7
You can access the attributes of an element with code like this:
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 8
+ \snippet code/src_xml_dom_qdom.cpp 8
This example also shows that changing an attribute received from
an element changes the attribute of the element. If you do not
@@ -4350,7 +4359,7 @@ QDomElement QDomAttr::ownerElement() const
Returns the value of the attribute or an empty string if the
attribute has not been specified.
- \sa specified() setValue()
+ \sa specified(), setValue()
*/
QString QDomAttr::value() const
{
@@ -4664,12 +4673,16 @@ void QDomElementPrivate::save(QTextStream& s, int depth, int indent) const
removeAttributeNS().
If you want to access the text of a node use text(), e.g.
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 9
+
+ \snippet code/src_xml_dom_qdom.cpp 9
+
The text() function operates recursively to find the text (since
not all elements contain text). If you want to find all the text
in all of a node's children, iterate over the children looking for
QDomText nodes, e.g.
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 10
+
+ \snippet code/src_xml_dom_qdom.cpp 10
+
Note that we attempt to convert each node to a text node and use
text() rather than using firstChild().toText().data() or
n.toText().data() directly on the node, because the node may not
@@ -4682,11 +4695,12 @@ void QDomElementPrivate::save(QTextStream& s, int depth, int indent) const
To browse the elements of a dom document use firstChildElement(), lastChildElement(),
nextSiblingElement() and previousSiblingElement(). For example, to iterate over all
child elements called "entry" in a root element called "database", you can use:
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 11
+
+ \snippet code/src_xml_dom_qdom.cpp 11
For further information about the Document Object Model see
- \l{http://www.w3.org/TR/REC-DOM-Level-1/}{Level 1} and
- \l{http://www.w3.org/TR/DOM-Level-2-Core/}{Level 2 Core}.
+ \l{W3C DOM Level 1}{Level 1} and
+ \l{W3C DOM Level 2}{Level 2 Core}.
For a more general introduction of the DOM implementation see the
QDomDocument documentation.
*/
@@ -4749,7 +4763,7 @@ void QDomElement::setTagName(const QString& name)
/*!
Returns the tag name of this element. For an XML element like this:
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 12
+ \snippet code/src_xml_dom_qdom.cpp 12
the tagname would return "img".
@@ -4766,7 +4780,7 @@ QString QDomElement::tagName() const
/*!
Returns a QDomNamedNodeMap containing all this element's attributes.
- \sa attribute() setAttribute() attributeNode() setAttributeNode()
+ \sa attribute(), setAttribute(), attributeNode(), setAttributeNode()
*/
QDomNamedNodeMap QDomElement::attributes() const
{
@@ -4779,7 +4793,7 @@ QDomNamedNodeMap QDomElement::attributes() const
Returns the attribute called \a name. If the attribute does not
exist \a defValue is returned.
- \sa setAttribute() attributeNode() setAttributeNode() attributeNS()
+ \sa setAttribute(), attributeNode(), setAttributeNode(), attributeNS()
*/
QString QDomElement::attribute(const QString& name, const QString& defValue) const
{
@@ -4793,7 +4807,7 @@ QString QDomElement::attribute(const QString& name, const QString& defValue) con
attribute with the same name exists, its value is replaced by \a
value.
- \sa attribute() setAttributeNode() setAttributeNS()
+ \sa attribute(), setAttributeNode(), setAttributeNS()
*/
void QDomElement::setAttribute(const QString& name, const QString& value)
{
@@ -4880,7 +4894,7 @@ void QDomElement::setAttribute(const QString& name, double value)
/*!
Removes the attribute called name \a name from this element.
- \sa setAttribute() attribute() removeAttributeNS()
+ \sa setAttribute(), attribute(), removeAttributeNS()
*/
void QDomElement::removeAttribute(const QString& name)
{
@@ -4891,10 +4905,10 @@ void QDomElement::removeAttribute(const QString& name)
/*!
Returns the QDomAttr object that corresponds to the attribute
- called \a name. If no such attribute exists a \link
- QDomNode::isNull() null attribute\endlink is returned.
+ called \a name. If no such attribute exists a
+ \l{QDomNode::isNull()}{null attribute} is returned.
- \sa setAttributeNode() attribute() setAttribute() attributeNodeNS()
+ \sa setAttributeNode(), attribute(), setAttribute(), attributeNodeNS()
*/
QDomAttr QDomElement::attributeNode(const QString& name)
{
@@ -4908,10 +4922,10 @@ QDomAttr QDomElement::attributeNode(const QString& name)
If the element has another attribute that has the same name as \a
newAttr, this function replaces that attribute and returns it;
- otherwise the function returns a \link QDomNode::isNull() null
- attribute\endlink.
+ otherwise the function returns a
+ \l{QDomNode::isNull()}{null attribute}.
- \sa attributeNode() setAttribute() setAttributeNodeNS()
+ \sa attributeNode(), setAttribute(), setAttributeNodeNS()
*/
QDomAttr QDomElement::setAttributeNode(const QDomAttr& newAttr)
{
@@ -4923,7 +4937,7 @@ QDomAttr QDomElement::setAttributeNode(const QDomAttr& newAttr)
/*!
Removes the attribute \a oldAttr from the element and returns it.
- \sa attributeNode() setAttributeNode()
+ \sa attributeNode(), setAttributeNode()
*/
QDomAttr QDomElement::removeAttributeNode(const QDomAttr& oldAttr)
{
@@ -4939,7 +4953,7 @@ QDomAttr QDomElement::removeAttributeNode(const QDomAttr& oldAttr)
elements in the returned list is the order they are encountered
during the preorder traversal.
- \sa elementsByTagNameNS() QDomDocument::elementsByTagName()
+ \sa elementsByTagNameNS(), QDomDocument::elementsByTagName()
*/
QDomNodeList QDomElement::elementsByTagName(const QString& tagname) const
{
@@ -4970,7 +4984,7 @@ bool QDomElement::hasAttribute(const QString& name) const
namespace URI \a nsURI. If the attribute does not exist \a
defValue is returned.
- \sa setAttributeNS() attributeNodeNS() setAttributeNodeNS() attribute()
+ \sa setAttributeNS(), attributeNodeNS(), setAttributeNodeNS(), attribute()
*/
QString QDomElement::attributeNS(const QString nsURI, const QString& localName, const QString& defValue) const
{
@@ -4989,7 +5003,7 @@ QString QDomElement::attributeNS(const QString nsURI, const QString& localName,
Although \a qName is the qualified name, the local name is used to
decide if an existing attribute's value should be replaced.
- \sa attributeNS() setAttributeNodeNS() setAttribute()
+ \sa attributeNS(), setAttributeNodeNS(), setAttribute()
*/
void QDomElement::setAttributeNS(const QString nsURI, const QString& qName, const QString& value)
{
@@ -5050,7 +5064,7 @@ void QDomElement::setAttributeNS(const QString nsURI, const QString& qName, doub
Removes the attribute with the local name \a localName and the
namespace URI \a nsURI from this element.
- \sa setAttributeNS() attributeNS() removeAttribute()
+ \sa setAttributeNS(), attributeNS(), removeAttribute()
*/
void QDomElement::removeAttributeNS(const QString& nsURI, const QString& localName)
{
@@ -5068,7 +5082,7 @@ void QDomElement::removeAttributeNS(const QString& nsURI, const QString& localNa
If no such attribute exists a \l{QDomNode::isNull()}{null
attribute} is returned.
- \sa setAttributeNode() attribute() setAttribute()
+ \sa setAttributeNode(), attribute(), setAttribute()
*/
QDomAttr QDomElement::attributeNodeNS(const QString& nsURI, const QString& localName)
{
@@ -5085,7 +5099,7 @@ QDomAttr QDomElement::attributeNodeNS(const QString& nsURI, const QString& local
attribute and returns it; otherwise the function returns a \link
QDomNode::isNull() null attribute\endlink.
- \sa attributeNodeNS() setAttributeNS() setAttributeNode()
+ \sa attributeNodeNS(), setAttributeNS(), setAttributeNode()
*/
QDomAttr QDomElement::setAttributeNodeNS(const QDomAttr& newAttr)
{
@@ -5101,7 +5115,7 @@ QDomAttr QDomElement::setAttributeNodeNS(const QDomAttr& newAttr)
as its root. The order of the elements in the returned list is the
order they are encountered during the preorder traversal.
- \sa elementsByTagName() QDomDocument::elementsByTagNameNS()
+ \sa elementsByTagName(), QDomDocument::elementsByTagNameNS()
*/
QDomNodeList QDomElement::elementsByTagNameNS(const QString& nsURI, const QString& localName) const
{
@@ -5124,12 +5138,12 @@ bool QDomElement::hasAttributeNS(const QString& nsURI, const QString& localName)
Returns the element's text or an empty string.
Example:
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 13
+ \snippet code/src_xml_dom_qdom.cpp 13
The function text() of the QDomElement for the \c{<h1>} tag,
will return the following text:
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 14
+ \snippet code/src_xml_dom_qdom.cpp 14
Comments are ignored by this function. It only evaluates QDomText
and QDomCDATASection objects.
@@ -5335,12 +5349,14 @@ void QDomCommentPrivate::save(QTextStream& s, int depth, int indent) const
\ingroup xml-tools
A comment in the parsed XML such as this:
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 15
+
+ \snippet code/src_xml_dom_qdom.cpp 15
+
is represented by QDomComment objects in the parsed Dom tree.
For further information about the Document Object Model see
- \l{http://www.w3.org/TR/REC-DOM-Level-1/} and
- \l{http://www.w3.org/TR/DOM-Level-2-Core/}.
+ \l{W3C DOM Level 1}{Level 1} and
+ \l{W3C DOM Level 2}{Level 2 Core}.
For a more general introduction of the DOM implementation see the
QDomDocument documentation.
*/
@@ -6102,7 +6118,7 @@ QString QDomProcessingInstruction::target() const
/*!
Returns the content of this processing instruction.
- \sa setData() target()
+ \sa setData(), target()
*/
QString QDomProcessingInstruction::data() const
{
@@ -6554,13 +6570,15 @@ void QDomDocumentPrivate::saveDocument(QTextStream& s, const int indent, QDomNod
tag with elementsByTagName() or with elementsByTagNameNS().
The QDom classes are typically used as follows:
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 16
+
+ \snippet code/src_xml_dom_qdom.cpp 16
Once \c doc and \c elem go out of scope, the whole internal tree
representing the XML document is deleted.
To create a document using DOM use code like this:
- \snippet doc/src/snippets/code/src_xml_dom_qdom.cpp 17
+
+ \snippet code/src_xml_dom_qdom.cpp 17
For further information about the Document Object Model see
the Document Object Model (DOM)
@@ -6705,8 +6723,8 @@ bool QDomDocument::setContent(const QString& text, bool namespaceProcessing, QSt
\li Any unparsed entity reference is replaced with an empty string.
\endlist
- \sa QDomNode::namespaceURI() QDomNode::localName()
- QDomNode::prefix() QString::isNull() QString::isEmpty()
+ \sa QDomNode::namespaceURI(), QDomNode::localName(),
+ QDomNode::prefix(), QString::isNull(), QString::isEmpty()
*/
bool QDomDocument::setContent(const QByteArray &data, bool namespaceProcessing, QString *errorMsg, int *errorLine, int *errorColumn)
{
@@ -6881,7 +6899,7 @@ QDomElement QDomDocument::documentElement() const
If \a tagName is not a valid XML name, the behavior of this function is governed
by QDomImplementation::InvalidDataPolicy.
- \sa createElementNS() QDomNode::appendChild() QDomNode::insertBefore()
+ \sa createElementNS(), QDomNode::appendChild(), QDomNode::insertBefore(),
QDomNode::insertAfter()
*/
QDomElement QDomDocument::createElement(const QString& tagName)
@@ -6911,7 +6929,7 @@ QDomDocumentFragment QDomDocument::createDocumentFragment()
data of an XML document (even in the form of character references), the
behavior of this function is governed by QDomImplementation::InvalidDataPolicy.
- \sa QDomNode::appendChild() QDomNode::insertBefore() QDomNode::insertAfter()
+ \sa QDomNode::appendChild(), QDomNode::insertBefore(), QDomNode::insertAfter()
*/
QDomText QDomDocument::createTextNode(const QString& value)
{
@@ -6927,7 +6945,7 @@ QDomText QDomDocument::createTextNode(const QString& value)
If \a value contains characters which cannot be stored in an XML comment,
the behavior of this function is governed by QDomImplementation::InvalidDataPolicy.
- \sa QDomNode::appendChild() QDomNode::insertBefore() QDomNode::insertAfter()
+ \sa QDomNode::appendChild(), QDomNode::insertBefore(), QDomNode::insertAfter()
*/
QDomComment QDomDocument::createComment(const QString& value)
{
@@ -6944,7 +6962,7 @@ QDomComment QDomDocument::createComment(const QString& value)
the behavior of this function is governed by
QDomImplementation::InvalidDataPolicy.
- \sa QDomNode::appendChild() QDomNode::insertBefore() QDomNode::insertAfter()
+ \sa QDomNode::appendChild(), QDomNode::insertBefore(), QDomNode::insertAfter()
*/
QDomCDATASection QDomDocument::createCDATASection(const QString& value)
{
@@ -6963,7 +6981,7 @@ QDomCDATASection QDomDocument::createCDATASection(const QString& value)
appear in a processing instruction, the behavior of this function is governed by
QDomImplementation::InvalidDataPolicy.
- \sa QDomNode::appendChild() QDomNode::insertBefore() QDomNode::insertAfter()
+ \sa QDomNode::appendChild(), QDomNode::insertBefore(), QDomNode::insertAfter()
*/
QDomProcessingInstruction QDomDocument::createProcessingInstruction(const QString& target,
const QString& data)
@@ -6997,7 +7015,7 @@ QDomAttr QDomDocument::createAttribute(const QString& name)
If \a name is not a valid XML name, the behavior of this function is governed by
QDomImplementation::InvalidDataPolicy.
- \sa QDomNode::appendChild() QDomNode::insertBefore() QDomNode::insertAfter()
+ \sa QDomNode::appendChild(), QDomNode::insertBefore(), QDomNode::insertAfter()
*/
QDomEntityReference QDomDocument::createEntityReference(const QString& name)
{
@@ -7012,7 +7030,7 @@ QDomEntityReference QDomDocument::createEntityReference(const QString& name)
the order they are encountered in a preorder traversal of the
element tree.
- \sa elementsByTagNameNS() QDomElement::elementsByTagName()
+ \sa elementsByTagNameNS(), QDomElement::elementsByTagName()
*/
QDomNodeList QDomDocument::elementsByTagName(const QString& tagname) const
{
@@ -7081,8 +7099,8 @@ QDomNodeList QDomDocument::elementsByTagName(const QString& tagname) const
\li The text is copied to the new node.
\endtable
- \sa QDomElement::setAttribute() QDomNode::insertBefore()
- QDomNode::insertAfter() QDomNode::replaceChild() QDomNode::removeChild()
+ \sa QDomElement::setAttribute(), QDomNode::insertBefore(),
+ QDomNode::insertAfter(), QDomNode::replaceChild(), QDomNode::removeChild(),
QDomNode::appendChild()
*/
QDomNode QDomDocument::importNode(const QDomNode& importedNode, bool deep)
@@ -7136,7 +7154,7 @@ QDomAttr QDomDocument::createAttributeNS(const QString& nsURI, const QString& qN
\a nsURI. The order of the node list is the order they are
encountered in a preorder traversal of the element tree.
- \sa elementsByTagName() QDomElement::elementsByTagNameNS()
+ \sa elementsByTagName(), QDomElement::elementsByTagNameNS()
*/
QDomNodeList QDomDocument::elementsByTagNameNS(const QString& nsURI, const QString& localName)
{
diff --git a/src/xml/sax/qxml.cpp b/src/xml/sax/qxml.cpp
index a5c206dc27..616ceeb042 100644
--- a/src/xml/sax/qxml.cpp
+++ b/src/xml/sax/qxml.cpp
@@ -1208,7 +1208,7 @@ void QXmlAttributes::clear()
\a uri and the local name is \a localPart. The value of the
attribute is \a value.
- \sa qName() uri() localName() value()
+ \sa qName(), uri(), localName(), value()
*/
void QXmlAttributes::append(const QString &qName, const QString &uri, const QString &localPart, const QString &value)
{
@@ -1266,7 +1266,7 @@ void QXmlAttributes::append(const QString &qName, const QString &uri, const QStr
raw XML file. The benefit of using the QXmlInputClass in such
cases is that it tries to use the correct encoding.
- \sa QXmlReader QXmlSimpleReader
+ \sa QXmlReader, QXmlSimpleReader
*/
// the following two are guaranteed not to be a character
@@ -1315,7 +1315,7 @@ QXmlInputSource::QXmlInputSource()
is 0 or it is not possible to read from the device, the input
source will contain no data.
- \sa setData() fetchData() QIODevice
+ \sa setData(), fetchData(), QIODevice
*/
QXmlInputSource::QXmlInputSource(QIODevice *dev)
{
@@ -1353,7 +1353,8 @@ supplied input is well-formed. Therefore, when reimplementing
this function, it is important to ensure that this behavior is
duplicated.
-\sa reset() fetchData() QXmlSimpleReader::parse() QXmlSimpleReader::parseContinue()
+\sa reset(), fetchData(), QXmlSimpleReader::parse(),
+ QXmlSimpleReader::parseContinue()
*/
QChar QXmlInputSource::next()
{
@@ -1400,7 +1401,7 @@ void QXmlInputSource::reset()
Returns the data the input source contains or an empty string if the
input source does not contain any data.
- \sa setData() QXmlInputSource() fetchData()
+ \sa setData(), QXmlInputSource(), fetchData()
*/
QString QXmlInputSource::data() const
{
@@ -1456,7 +1457,7 @@ void QXmlInputSource::setData(const QByteArray& dat)
You don't normally need to use this function if you use next().
- \sa data() next() QXmlInputSource()
+ \sa data(), next(), QXmlInputSource()
*/
void QXmlInputSource::fetchData()
@@ -2364,13 +2365,13 @@ events are reported.
it we can use the same handler for both of the following
reader functions:
- \snippet doc/src/snippets/xml/rsslisting/rsslisting.cpp 0
+ \snippet rsslisting/rsslisting.cpp 0
Since the reader will inform the handler of parsing errors, it is
necessary to reimplement QXmlErrorHandler::fatalError() if, for
example, we want to stop parsing when such an error occurs:
- \snippet doc/src/snippets/xml/rsslisting/handler.cpp 0
+ \snippet rsslisting/handler.cpp 0
The above function returns false, which tells the reader to stop
parsing. To continue to use the same reader,
@@ -3007,7 +3008,7 @@ void QXmlSimpleReaderPrivate::initIncrementalParsing()
create a reader, and define an input source to be used by the
reader:
- \snippet doc/src/snippets/xml/simpleparse/main.cpp 0
+ \snippet simpleparse/main.cpp 0
A handler lets us perform actions when the reader encounters
certain types of content, or if errors in the input are found. The
@@ -3016,7 +3017,7 @@ void QXmlSimpleReaderPrivate::initIncrementalParsing()
handler by subclassing QXmlDefaultHandler, and use this to handle
both error and content events:
- \snippet doc/src/snippets/xml/simpleparse/main.cpp 1
+ \snippet simpleparse/main.cpp 1
If you don't set at least the content and error handlers, the
parser will fall back on its default behavior---and will do
@@ -3026,7 +3027,7 @@ void QXmlSimpleReaderPrivate::initIncrementalParsing()
single pass using the parse() function with an argument that
specifies the input source:
- \snippet doc/src/snippets/xml/simpleparse/main.cpp 2
+ \snippet simpleparse/main.cpp 2
If you can't parse the entire input in one go (for example, it is
huge, or is being delivered over a network connection), data can
@@ -3041,7 +3042,7 @@ void QXmlSimpleReaderPrivate::initIncrementalParsing()
Aspects of the parsing behavior can be adapted using setFeature()
and setProperty().
- \snippet doc/src/snippets/code/src_xml_sax_qxml.cpp 0
+ \snippet code/src_xml_sax_qxml.cpp 0
QXmlSimpleReader is not reentrant. If you want to use the class
in threaded code, lock the code using QXmlSimpleReader with a