Revamp DOM Bookmarks example

Fixes: QTBUG-111974
Pick-to: 6.5
Change-Id: Ia62eaf36f616278e49112884db8aec37e2b1dcc5
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
Reviewed-by: Samuel Gaist <samuel.gaist@idiap.ch>

examples/xml/dombookmarks/doc/src/dombookmarks.qdoc

@@ -3,16 +3,96 @@
 
 /*!
     \example dombookmarks
-    \title DOM Bookmarks Example
+    \title DOM Bookmarks Application
     \ingroup xml-examples
+    \meta category {Input/Output}
+    \meta tag {xml}
     \brief Provides a reader for XML Bookmark Exchange Language files.
 
-    The DOM Bookmarks example provides a reader for XML Bookmark Exchange Language (XBEL)
-    files that uses Qt's DOM-based XML API to read and parse the files. The SAX Bookmarks
-    example provides an alternative way to read this type of file.
+    The DOM Bookmarks Application provides a reader for XML Bookmark Exchange
+    Language (XBEL) files that uses Qt's DOM-based XML API to read and parse
+    the files. The {QXmlStream Bookmarks Example} provides an alternative
+    way to read this type of file.
 
     \image dombookmarks-example.png
 
+    \section1 The XbelTree Class Definition
+
+    The XbelTree class has functions for reading and writing to the filesystem.
+    It inherits from the QTreeWidget class, contains the model for the
+    dispalying of the bookmarks, and allows it to be edited.
+
+    \snippet dombookmarks/xbeltree.h 0
+
+    \section1 The XbelTree Class Implementation
+
+    The \c XbelTree constructor accepts a QWidget within which it is placed.
+    The \c folderIcon is set to QIcon::Normal mode where the pixmap is only
+    displayed when the user is not interacting with the icon. The
+    QStyle::SP_DirClosedIcon, QStyle::SP_DirOpenIcon, and QStyle::SP_FileIcon
+    correspond to standard pixmaps that follow the style of your GUI.
+
+    \snippet dombookmarks/xbeltree.cpp 0
+
+    The \c read() function opens the given QIODevice using
+    QDomDocument::setContent. If it succeeds  opening the file and the top
+    level headers are verified, the contents of the class is cleared before
+    the file contents is parsed by iterating all the top level XML nodes and
+    calling \c parseFolderElement() on each of them.
+
+    \snippet dombookmarks/xbeltree.cpp 1
+
+    The \c parseFolderElement() function handles the different element types
+    and calls itself recursively if the element is a subfolder.
+
+    \snippet dombookmarks/xbeltree.cpp 3
+
+    The \c write() function saves the domDocument to the given QIODevice using
+    QDomDocument::save.
+
+    \snippet dombookmarks/xbeltree.cpp 2
+
+    \section1 The MainWindow Class Definition
+
+    The \c MainWindow class is a subclass of QMainWindow, with a
+    \c File menu and a \c Help menu.
+
+    \snippet dombookmarks/mainwindow.h 0
+
+    \section1 The MainWindow Class Implementation
+
+    The \c MainWindow constructor instantiates the member XbelTree object,
+    and sets its header with a QStringList object, \c labels.
+    The constructor also invokes \c createMenus() to set up the menus.
+    The \c statusBar() is used to display the message "Ready".
+
+    \snippet dombookmarks/mainwindow.cpp 0
+
+    The \c createMenus() function poulates the menus and sets keyboard
+    shortcuts.
+
+    \snippet dombookmarks/mainwindow.cpp 4
+
+    The \c open() function enables the user to open an XBEL file using
+    QFileDialog::getOpenFileName(). A warning message is displayed along
+    with the \c fileName and \c errorString if the file cannot be read or
+    if there is a parse error. If it succeeds it calls \c XbelTree::read().
+
+    \snippet dombookmarks/mainwindow.cpp 1
+
+    The \c saveAs() function displays a QFileDialog, prompting the user for
+    a \c fileName using QFileDialog::getSaveFileName(). Similar to the
+    \c open() function, this function also displays a warning message if
+    the file cannot be written to. IF this succeeds it calls \c
+    XbelTree::write().
+
+    \snippet dombookmarks/mainwindow.cpp 2
+
+    The \c about() function displays a QMessageBox with a brief description
+    of the example.
+
+    \snippet dombookmarks/mainwindow.cpp 3
+
     See the \l{http://pyxml.sourceforge.net/topics/xbel/}{XML Bookmark Exchange Language
     Resource Page} for more information about XBEL files.
 */

examples/xml/dombookmarks/mainwindow.cpp

@@ -6,6 +6,7 @@
 #include "mainwindow.h"
 #include "xbeltree.h"
 
+//! [0]
 MainWindow::MainWindow()
 {
     xbelTree = new XbelTree;
@@ -19,7 +20,9 @@ MainWindow::MainWindow()
     const QSize availableSize = screen()->availableGeometry().size();
     resize(availableSize.width() / 2, availableSize.height() / 3);
 }
+//! [0]
 
+//! [1]
 void MainWindow::open()
 {
     QString fileName =
@@ -41,7 +44,9 @@ void MainWindow::open()
     if (xbelTree->read(&file))
         statusBar()->showMessage(tr("File loaded"), 2000);
 }
+//! [1]
 
+//! [2]
 void MainWindow::saveAs()
 {
     QString fileName =
@@ -63,7 +68,9 @@ void MainWindow::saveAs()
     if (xbelTree->write(&file))
         statusBar()->showMessage(tr("File saved"), 2000);
 }
+//! [2]
 
+//! [3]
 void MainWindow::about()
 {
    QMessageBox::about(this, tr("About DOM Bookmarks"),
@@ -71,7 +78,9 @@ void MainWindow::about()
                          "use Qt's DOM classes to read and write XML "
                          "documents."));
 }
+//! [3]
 
+//! [4]
 void MainWindow::createMenus()
 {
     QMenu *fileMenu = menuBar()->addMenu(tr("&File"));
@@ -90,3 +99,4 @@ void MainWindow::createMenus()
     helpMenu->addAction(tr("&About"), this, &MainWindow::about);
     helpMenu->addAction(tr("About &Qt"), qApp, &QCoreApplication::quit);
 }
+//! [4]

examples/xml/dombookmarks/mainwindow.h

@@ -8,6 +8,7 @@
 
 class XbelTree;
 
+//! [0]
 class MainWindow : public QMainWindow
 {
     Q_OBJECT
@@ -25,5 +26,6 @@ private:
 
     XbelTree *xbelTree;
 };
+//! [0]
 
 #endif

examples/xml/dombookmarks/xbeltree.cpp

@@ -17,6 +17,7 @@ static inline QString versionAttribute() { return QStringLiteral("version"); }
 static inline QString hrefAttribute() { return QStringLiteral("href"); }
 static inline QString foldedAttribute() { return QStringLiteral("folded"); }
 
+//! [0]
 XbelTree::XbelTree(QWidget *parent)
     : QTreeWidget(parent)
 {
@@ -32,6 +33,7 @@ XbelTree::XbelTree(QWidget *parent)
                          QIcon::Normal, QIcon::On);
     bookmarkIcon.addPixmap(style()->standardPixmap(QStyle::SP_FileIcon));
 }
+//! [0]
 
 #if !defined(QT_NO_CONTEXTMENU) && !defined(QT_NO_CLIPBOARD)
 void XbelTree::contextMenuEvent(QContextMenuEvent *event)
@@ -51,6 +53,7 @@ void XbelTree::contextMenuEvent(QContextMenuEvent *event)
 }
 #endif // !QT_NO_CONTEXTMENU && !QT_NO_CLIPBOARD
 
+//! [1]
 bool XbelTree::read(QIODevice *device)
 {
     QDomDocument::ParseResult result =
@@ -91,7 +94,9 @@ bool XbelTree::read(QIODevice *device)
 
     return true;
 }
+//! [1]
 
+//! [2]
 bool XbelTree::write(QIODevice *device) const
 {
     const int IndentSize = 4;
@@ -100,6 +105,7 @@ bool XbelTree::write(QIODevice *device) const
     domDocument.save(out, IndentSize);
     return true;
 }
+//! [2]
 
 void XbelTree::updateDomElement(const QTreeWidgetItem *item, int column)
 {
@@ -120,6 +126,7 @@ void XbelTree::updateDomElement(const QTreeWidgetItem *item, int column)
     }
 }
 
+//! [3]
 void XbelTree::parseFolderElement(const QDomElement &element,
                                   QTreeWidgetItem *parentItem)
 {
@@ -159,6 +166,7 @@ void XbelTree::parseFolderElement(const QDomElement &element,
         child = child.nextSiblingElement();
     }
 }
+//! [3]
 
 QTreeWidgetItem *XbelTree::createItem(const QDomElement &element,
                                       QTreeWidgetItem *parentItem)

examples/xml/dombookmarks/xbeltree.h

@@ -8,6 +8,7 @@
 #include <QIcon>
 #include <QTreeWidget>
 
+//! [0]
 class XbelTree : public QTreeWidget
 {
     Q_OBJECT
@@ -36,5 +37,6 @@ private:
     QIcon folderIcon;
     QIcon bookmarkIcon;
 };
+//! [0]
 
 #endif

src/xml/doc/src/xml-processing.qdoc

@@ -7,7 +7,7 @@
 
     \brief Classes that support XML.
 
-    These classes are relevant to XML users.
+    These classes are relevant to \l{XML Processing}{XML} users.
 
     \generatelist{related}
 */
@@ -180,7 +180,7 @@
     namespace prefix. In this case the local part and the qualified name
     are identical (i.e. \e chapter).
 
-    \sa {DOM Bookmarks Example}
+    \sa {DOM Bookmarks Application}
 */
 
 /*!
@@ -339,7 +339,7 @@
     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},
+    You might also want to take a look at the \l{DOM Bookmarks Application},
     which illustrates how to read and write an XML bookmark file (XBEL)
     using DOM.
 */

src/xml/dom/qdom.cpp

@@ -6018,10 +6018,9 @@ void QDomDocumentPrivate::saveDocument(QTextStream& s, const int indent, QDomNod
     \l{http://www.w3.org/TR/DOM-Level-2-Core/}{Level 2 Core}
     Specifications.
 
-    \sa {DOM Bookmarks Example}, {Simple DOM Model Example}
+    \sa {DOM Bookmarks Application}, {Simple DOM Model Example}
 */
 
-
 /*!
     Constructs an empty document.
 */