Changed the streambookmarks example to use aggregation

QXmlStreamReader and QXmlStreamWriter can be used conveniently without
subclassing, which the example now demonstrates.

Reviewed-by: mae
Reviewed-by: David Boddie

7 files changed, 89 insertions, 71 deletions

diff --git a/doc/src/examples/qxmlstreambookmarks.qdoc b/doc/src/examples/qxmlstreambookmarks.qdoc
index 26964c4..904cd6d 100644
--- a/doc/src/examples/qxmlstreambookmarks.qdoc
+++ b/doc/src/examples/qxmlstreambookmarks.qdoc
@@ -51,10 +51,10 @@
 
     \section1 XbelWriter Class Definition
 
-    The \c XbelWriter class is a subclass of QXmlStreamReader, which provides
-    an XML parser with a streaming API. \c XbelWriter also contains a private
-    instance of QTreeWidget in order to display the bookmarks according to
-    hierarchies.
+    The \c XbelWriter class contains a private instance of QXmlStreamWriter,
+    which provides an XML writer with a streaming API. \c XbelWriter also
+    has a reference to the QTreeWidget instance where the bookmark hierarchy
+    is stored.
 
     \snippet examples/xml/streambookmarks/xbelwriter.h 0
 
@@ -75,7 +75,7 @@
 
     \snippet examples/xml/streambookmarks/xbelwriter.cpp 1
 
-    The \c writeItem() function accepts a QTreeWidget object and writes it
+    The \c writeItem() function accepts a QTreeWidgetItem object and writes it
     to the stream, depending on its \c tagName, which can either be a "folder",
     "bookmark", or "separator".
 
@@ -83,9 +83,10 @@
 
     \section1 XbelReader Class Definition
 
-    The \c XbelReader class is a subclass of QXmlStreamReader, the pendent
-    class for QXmlStreamWriter. \c XbelReader contains a private instance
-    of QTreeWidget to group bookmarks according to their hierarchies.
+    The \c XbelReader contains a private instance of QXmlStreamReader, the
+    companion class to QXmlStreamWriter. \c XbelReader also contains a
+    reference to the QTreeWidget that is used to group the bookmarks according
+    to their hierarchy.
 
     \snippet examples/xml/streambookmarks/xbelreader.h 0
 
@@ -102,21 +103,26 @@
     \snippet examples/xml/streambookmarks/xbelreader.cpp 0
 
     The \c read() function accepts a QIODevice and sets it using
-    \l{QXmlStreamReader::setDevice()}{setDevice()}. The actual process
-    of reading only takes place if the file is a valid XBEL 1.0 file. 
-    Note that the XML input needs to be well-formed to be accepted by 
-    QXmlStreamReader. Otherwise, the \l{QXmlStreamReader::raiseError()}
-    {raiseError()} function is used to display an error message. Since the
-    XBEL reader is only concerned with reading XML elements, it makes
-    extensive use of the \l{QXmlStreamReader::readNextStartElement()}
+    \l{QXmlStreamReader::}{setDevice()}. The actual process of reading only
+    takes place if the file is a valid XBEL 1.0 file. Note that the XML input
+    needs to be well-formed to be accepted by QXmlStreamReader. Otherwise, the
+    \l{QXmlStreamReader::}{raiseError()} function is used to display an error
+    message. Since the XBEL reader is only concerned with reading XML elements,
+    it makes extensive use of the \l{QXmlStreamReader::}{readNextStartElement()}
     convenience function.
 
     \snippet examples/xml/streambookmarks/xbelreader.cpp 1
 
+    The \c errorString() function is used if an error occurred, in order to
+    obtain a description of the error complete with line and column number
+    information.
+
+    \snippet examples/xml/streambookmarks/xbelreader.cpp 2
+
     The \c readXBEL() function reads the name of a startElement and calls
     the appropriate function to read it, depending on whether if its a
     "folder", "bookmark" or "separator". Otherwise, it calls
-    \l{QXmlStreamReader::skipCurrentElement()}. The Q_ASSERT() macro is used
+    \l{QXmlStreamReader::}{skipCurrentElement()}. The Q_ASSERT() macro is used
     to provide a pre-condition for the function.
 
     \snippet examples/xml/streambookmarks/xbelreader.cpp 3
@@ -126,8 +132,8 @@
     \snippet examples/xml/streambookmarks/xbelreader.cpp 4
 
     The \c readSeparator() function creates a separator and sets its flags.
-    The text is set to 30 "0xB7", the HEX equivalent for period, and then
-    read using \c readElementText().
+    The text is set to 30 "0xB7", the HEX equivalent for period. The element
+    is then skipped using \l{QXmlStreamReader::}{skipCurrentElement()}.
 
     \snippet examples/xml/streambookmarks/xbelreader.cpp 5
 
diff --git a/examples/xml/streambookmarks/mainwindow.cpp b/examples/xml/streambookmarks/mainwindow.cpp
index 183143d..5aef327 100644
--- a/examples/xml/streambookmarks/mainwindow.cpp
+++ b/examples/xml/streambookmarks/mainwindow.cpp
@@ -91,10 +91,8 @@ void MainWindow::open()
     XbelReader reader(treeWidget);
     if (!reader.read(&file)) {
         QMessageBox::warning(this, tr("QXmlStream Bookmarks"),
-                             tr("Parse error in file %1 at line %2, column %3:\n%4")
+                             tr("Parse error in file %1:\n\n%2")
                              .arg(fileName)
-                             .arg(reader.lineNumber())
-                             .arg(reader.columnNumber())
                              .arg(reader.errorString()));
     } else {
         statusBar()->showMessage(tr("File loaded"), 2000);
diff --git a/examples/xml/streambookmarks/xbelreader.cpp b/examples/xml/streambookmarks/xbelreader.cpp
index 99a7f34..0770643 100644
--- a/examples/xml/streambookmarks/xbelreader.cpp
+++ b/examples/xml/streambookmarks/xbelreader.cpp
@@ -60,33 +60,43 @@ XbelReader::XbelReader(QTreeWidget *treeWidget)
 //! [1]
 bool XbelReader::read(QIODevice *device)
 {
-    setDevice(device);
+    xml.setDevice(device);
 
-    if (readNextStartElement()) {
-        if (name() == "xbel" && attributes().value("version") == "1.0")
+    if (xml.readNextStartElement()) {
+        if (xml.name() == "xbel" && xml.attributes().value("version") == "1.0")
             readXBEL();
         else
-            raiseError(QObject::tr("The file is not an XBEL version 1.0 file."));
+            xml.raiseError(QObject::tr("The file is not an XBEL version 1.0 file."));
     }
 
-    return !error();
+    return !xml.error();
 }
 //! [1]
 
+//! [2]
+QString XbelReader::errorString() const
+{
+    return QObject::tr("%1\nLine %2, column %3")
+            .arg(xml.errorString())
+            .arg(xml.lineNumber())
+            .arg(xml.columnNumber());
+}
+//! [2]
+
 //! [3]
 void XbelReader::readXBEL()
 {
-    Q_ASSERT(isStartElement() && name() == "xbel");
+    Q_ASSERT(xml.isStartElement() && xml.name() == "xbel");
 
-    while (readNextStartElement()) {
-        if (name() == "folder")
+    while (xml.readNextStartElement()) {
+        if (xml.name() == "folder")
             readFolder(0);
-        else if (name() == "bookmark")
+        else if (xml.name() == "bookmark")
             readBookmark(0);
-        else if (name() == "separator")
+        else if (xml.name() == "separator")
             readSeparator(0);
         else
-            skipCurrentElement();
+            xml.skipCurrentElement();
     }
 }
 //! [3]
@@ -94,9 +104,9 @@ void XbelReader::readXBEL()
 //! [4]
 void XbelReader::readTitle(QTreeWidgetItem *item)
 {
-    Q_ASSERT(isStartElement() && name() == "title");
+    Q_ASSERT(xml.isStartElement() && xml.name() == "title");
 
-    QString title = readElementText();
+    QString title = xml.readElementText();
     item->setText(0, title);
 }
 //! [4]
@@ -104,52 +114,52 @@ void XbelReader::readTitle(QTreeWidgetItem *item)
 //! [5]
 void XbelReader::readSeparator(QTreeWidgetItem *item)
 {
-    Q_ASSERT(isStartElement() && name() == "separator");
+    Q_ASSERT(xml.isStartElement() && xml.name() == "separator");
 
     QTreeWidgetItem *separator = createChildItem(item);
     separator->setFlags(item->flags() & ~Qt::ItemIsSelectable);
     separator->setText(0, QString(30, 0xB7));
-    skipCurrentElement();
+    xml.skipCurrentElement();
 }
 //! [5]
 
 void XbelReader::readFolder(QTreeWidgetItem *item)
 {
-    Q_ASSERT(isStartElement() && name() == "folder");
+    Q_ASSERT(xml.isStartElement() && xml.name() == "folder");
 
     QTreeWidgetItem *folder = createChildItem(item);
-    bool folded = (attributes().value("folded") != "no");
+    bool folded = (xml.attributes().value("folded") != "no");
     treeWidget->setItemExpanded(folder, !folded);
 
-    while (readNextStartElement()) {
-        if (name() == "title")
+    while (xml.readNextStartElement()) {
+        if (xml.name() == "title")
             readTitle(folder);
-        else if (name() == "folder")
+        else if (xml.name() == "folder")
             readFolder(folder);
-        else if (name() == "bookmark")
+        else if (xml.name() == "bookmark")
             readBookmark(folder);
-        else if (name() == "separator")
+        else if (xml.name() == "separator")
             readSeparator(folder);
         else
-            skipCurrentElement();
+            xml.skipCurrentElement();
     }
 }
 
 void XbelReader::readBookmark(QTreeWidgetItem *item)
 {
-    Q_ASSERT(isStartElement() && name() == "bookmark");
+    Q_ASSERT(xml.isStartElement() && xml.name() == "bookmark");
 
     QTreeWidgetItem *bookmark = createChildItem(item);
     bookmark->setFlags(bookmark->flags() | Qt::ItemIsEditable);
     bookmark->setIcon(0, bookmarkIcon);
     bookmark->setText(0, QObject::tr("Unknown title"));
-    bookmark->setText(1, attributes().value("href").toString());
+    bookmark->setText(1, xml.attributes().value("href").toString());
 
-    while (readNextStartElement()) {
-        if (name() == "title")
+    while (xml.readNextStartElement()) {
+        if (xml.name() == "title")
             readTitle(bookmark);
         else
-            skipCurrentElement();
+            xml.skipCurrentElement();
     }
 }
 
@@ -161,6 +171,6 @@ QTreeWidgetItem *XbelReader::createChildItem(QTreeWidgetItem *item)
     } else {
         childItem = new QTreeWidgetItem(treeWidget);
     }
-    childItem->setData(0, Qt::UserRole, name().toString());
+    childItem->setData(0, Qt::UserRole, xml.name().toString());
     return childItem;
 }
diff --git a/examples/xml/streambookmarks/xbelreader.h b/examples/xml/streambookmarks/xbelreader.h
index 2debadc..00d5850 100644
--- a/examples/xml/streambookmarks/xbelreader.h
+++ b/examples/xml/streambookmarks/xbelreader.h
@@ -51,7 +51,7 @@ class QTreeWidgetItem;
 QT_END_NAMESPACE
 
 //! [0]
-class XbelReader : public QXmlStreamReader
+class XbelReader
 {
 public:
 //! [1]
@@ -60,6 +60,8 @@ public:
 
     bool read(QIODevice *device);
 
+    QString errorString() const;
+
 private:
 //! [2]
     void readXBEL();
@@ -70,6 +72,7 @@ private:
 
     QTreeWidgetItem *createChildItem(QTreeWidgetItem *item);
 
+    QXmlStreamReader xml;
     QTreeWidget *treeWidget;
 //! [2]
 
diff --git a/examples/xml/streambookmarks/xbelwriter.cpp b/examples/xml/streambookmarks/xbelwriter.cpp
index 3a2862a..58757f5 100644
--- a/examples/xml/streambookmarks/xbelwriter.cpp
+++ b/examples/xml/streambookmarks/xbelwriter.cpp
@@ -47,23 +47,23 @@
 XbelWriter::XbelWriter(QTreeWidget *treeWidget)
     : treeWidget(treeWidget)
 {
-    setAutoFormatting(true);
+    xml.setAutoFormatting(true);
 }
 //! [0]
 
 //! [1]
 bool XbelWriter::writeFile(QIODevice *device)
 {
-    setDevice(device);
+    xml.setDevice(device);
 
-    writeStartDocument();
-    writeDTD("<!DOCTYPE xbel>");
-    writeStartElement("xbel");
-    writeAttribute("version", "1.0");
+    xml.writeStartDocument();
+    xml.writeDTD("<!DOCTYPE xbel>");
+    xml.writeStartElement("xbel");
+    xml.writeAttribute("version", "1.0");
     for (int i = 0; i < treeWidget->topLevelItemCount(); ++i)
         writeItem(treeWidget->topLevelItem(i));
 
-    writeEndDocument();
+    xml.writeEndDocument();
     return true;
 }
 //! [1]
@@ -74,20 +74,20 @@ void XbelWriter::writeItem(QTreeWidgetItem *item)
     QString tagName = item->data(0, Qt::UserRole).toString();
     if (tagName == "folder") {
         bool folded = !treeWidget->isItemExpanded(item);
-        writeStartElement(tagName);
-        writeAttribute("folded", folded ? "yes" : "no");
-        writeTextElement("title", item->text(0));
+        xml.writeStartElement(tagName);
+        xml.writeAttribute("folded", folded ? "yes" : "no");
+        xml.writeTextElement("title", item->text(0));
         for (int i = 0; i < item->childCount(); ++i)
             writeItem(item->child(i));
-        writeEndElement();
+        xml.writeEndElement();
     } else if (tagName == "bookmark") {
-        writeStartElement(tagName);
+        xml.writeStartElement(tagName);
         if (!item->text(1).isEmpty())
-            writeAttribute("href", item->text(1));
-        writeTextElement("title", item->text(0));
-        writeEndElement();
+            xml.writeAttribute("href", item->text(1));
+        xml.writeTextElement("title", item->text(0));
+        xml.writeEndElement();
     } else if (tagName == "separator") {
-        writeEmptyElement(tagName);
+        xml.writeEmptyElement(tagName);
     }
 }
 //! [2]
diff --git a/examples/xml/streambookmarks/xbelwriter.h b/examples/xml/streambookmarks/xbelwriter.h
index 29a8b04..b74d015 100644
--- a/examples/xml/streambookmarks/xbelwriter.h
+++ b/examples/xml/streambookmarks/xbelwriter.h
@@ -50,7 +50,7 @@ class QTreeWidgetItem;
 QT_END_NAMESPACE
 
 //! [0]
-class XbelWriter : public QXmlStreamWriter
+class XbelWriter
 {
 public:
     XbelWriter(QTreeWidget *treeWidget);
@@ -58,6 +58,7 @@ public:
 
 private:
     void writeItem(QTreeWidgetItem *item);
+    QXmlStreamWriter xml;
     QTreeWidget *treeWidget;
 };
 //! [0]
diff --git a/src/corelib/xml/qxmlstream.cpp b/src/corelib/xml/qxmlstream.cpp
index a311b99..4cd8965 100644
--- a/src/corelib/xml/qxmlstream.cpp
+++ b/src/corelib/xml/qxmlstream.cpp
@@ -313,8 +313,8 @@ QXmlStreamEntityResolver *QXmlStreamReader::entityResolver() const
   error handling described.
 
   The \l{QXmlStream Bookmarks Example} illustrates how to use the
-  recursive descent technique with a subclassed stream reader to read
-  an XML bookmark file (XBEL).
+  recursive descent technique to read an XML bookmark file (XBEL) with
+  a stream reader.
 
   \section1 Namespaces
 
@@ -2943,7 +2943,7 @@ QStringRef QXmlStreamReader::documentEncoding() const
   encodings can be enforced using setCodec().
 
   The \l{QXmlStream Bookmarks Example} illustrates how to use a
-  subclassed stream writer to write an XML bookmark file (XBEL) that
+  stream writer to write an XML bookmark file (XBEL) that
   was previously read in by a QXmlStreamReader.
 
 */