From 3dd3268ded4dd74c64d7ec726fd534375ab9f018 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=98ystein=20Heskestad?= Date: Wed, 12 Apr 2023 16:22:24 +0200 Subject: [PATCH] Revamp DOM Bookmarks example Fixes: QTBUG-111974 Pick-to: 6.5 Change-Id: Ia62eaf36f616278e49112884db8aec37e2b1dcc5 Reviewed-by: Joerg Bornemann Reviewed-by: Samuel Gaist --- .../dombookmarks/doc/src/dombookmarks.qdoc | 88 ++++++++++++++++++- examples/xml/dombookmarks/mainwindow.cpp | 10 +++ examples/xml/dombookmarks/mainwindow.h | 2 + examples/xml/dombookmarks/xbeltree.cpp | 8 ++ examples/xml/dombookmarks/xbeltree.h | 2 + src/xml/doc/src/xml-processing.qdoc | 6 +- src/xml/dom/qdom.cpp | 3 +- 7 files changed, 110 insertions(+), 9 deletions(-) diff --git a/examples/xml/dombookmarks/doc/src/dombookmarks.qdoc b/examples/xml/dombookmarks/doc/src/dombookmarks.qdoc index be9a41db1f..185ee21c77 100644 --- a/examples/xml/dombookmarks/doc/src/dombookmarks.qdoc +++ b/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. */ diff --git a/examples/xml/dombookmarks/mainwindow.cpp b/examples/xml/dombookmarks/mainwindow.cpp index 6a03a57bb0..66156a2ff1 100644 --- a/examples/xml/dombookmarks/mainwindow.cpp +++ b/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] diff --git a/examples/xml/dombookmarks/mainwindow.h b/examples/xml/dombookmarks/mainwindow.h index 55b78c8449..82e29012f2 100644 --- a/examples/xml/dombookmarks/mainwindow.h +++ b/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 diff --git a/examples/xml/dombookmarks/xbeltree.cpp b/examples/xml/dombookmarks/xbeltree.cpp index 5d2e14f198..ce6fb20a12 100644 --- a/examples/xml/dombookmarks/xbeltree.cpp +++ b/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) diff --git a/examples/xml/dombookmarks/xbeltree.h b/examples/xml/dombookmarks/xbeltree.h index d39caad51a..0788c4c8ab 100644 --- a/examples/xml/dombookmarks/xbeltree.h +++ b/examples/xml/dombookmarks/xbeltree.h @@ -8,6 +8,7 @@ #include #include +//! [0] class XbelTree : public QTreeWidget { Q_OBJECT @@ -36,5 +37,6 @@ private: QIcon folderIcon; QIcon bookmarkIcon; }; +//! [0] #endif diff --git a/src/xml/doc/src/xml-processing.qdoc b/src/xml/doc/src/xml-processing.qdoc index f1f74a68c0..ad4dadb583 100644 --- a/src/xml/doc/src/xml-processing.qdoc +++ b/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. */ diff --git a/src/xml/dom/qdom.cpp b/src/xml/dom/qdom.cpp index 5928255778..4581c7dea8 100644 --- a/src/xml/dom/qdom.cpp +++ b/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. */