From 29317b426b9ec84f4ba66e6c032f71c2a2bae091 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=98ystein=20Heskestad?= Date: Thu, 9 Mar 2023 17:01:59 +0100 Subject: [PATCH] Move streambookmarks example into corelibe/serialization The stream-based XML serialization API resides in corelib/serialization. Move the steambookmarks example there. The Qt XML documentation is updated to no longer refer to this example code directly and refer to the direct location in the example documentation instead. Task-number: QTBUG-110647 Pick-to: 6.5 Change-Id: Id36fb04a6acb7b8d1eb008f61568fe0abc221e3d Reviewed-by: Marc Mutz --- examples/corelib/serialization/CMakeLists.txt | 3 ++ .../corelib/serialization/serialization.pro | 1 + .../streambookmarks/CMakeLists.txt | 2 +- .../doc/images/xmlstreamexample-filemenu.png | Bin .../doc/images/xmlstreamexample-helpmenu.png | Bin .../images/xmlstreamexample-screenshot.png | Bin .../doc/src/qxmlstreambookmarks.qdoc | 40 +++++++++--------- .../streambookmarks/jennifer.xbel | 0 .../serialization}/streambookmarks/main.cpp | 0 .../streambookmarks/mainwindow.cpp | 0 .../streambookmarks/mainwindow.h | 0 .../streambookmarks/streambookmarks.pro | 2 +- .../streambookmarks/xbelreader.cpp | 0 .../streambookmarks/xbelreader.h | 0 .../streambookmarks/xbelwriter.cpp | 0 .../streambookmarks/xbelwriter.h | 0 examples/xml/CMakeLists.txt | 1 - examples/xml/xml.pro | 3 +- src/corelib/doc/src/qtserialization.qdoc | 9 +++- src/xml/doc/src/qtxml-index.qdoc | 6 +-- src/xml/doc/src/qtxml.qdoc | 2 +- src/xml/doc/src/xml-processing.qdoc | 39 ++++++----------- 22 files changed, 51 insertions(+), 57 deletions(-) rename examples/{xml => corelib/serialization}/streambookmarks/CMakeLists.txt (90%) rename examples/{xml => corelib/serialization}/streambookmarks/doc/images/xmlstreamexample-filemenu.png (100%) rename examples/{xml => corelib/serialization}/streambookmarks/doc/images/xmlstreamexample-helpmenu.png (100%) rename examples/{xml => corelib/serialization}/streambookmarks/doc/images/xmlstreamexample-screenshot.png (100%) rename examples/{xml => corelib/serialization}/streambookmarks/doc/src/qxmlstreambookmarks.qdoc (83%) rename examples/{xml => corelib/serialization}/streambookmarks/jennifer.xbel (100%) rename examples/{xml => corelib/serialization}/streambookmarks/main.cpp (100%) rename examples/{xml => corelib/serialization}/streambookmarks/mainwindow.cpp (100%) rename examples/{xml => corelib/serialization}/streambookmarks/mainwindow.h (100%) rename examples/{xml => corelib/serialization}/streambookmarks/streambookmarks.pro (81%) rename examples/{xml => corelib/serialization}/streambookmarks/xbelreader.cpp (100%) rename examples/{xml => corelib/serialization}/streambookmarks/xbelreader.h (100%) rename examples/{xml => corelib/serialization}/streambookmarks/xbelwriter.cpp (100%) rename examples/{xml => corelib/serialization}/streambookmarks/xbelwriter.h (100%) diff --git a/examples/corelib/serialization/CMakeLists.txt b/examples/corelib/serialization/CMakeLists.txt index 0110eb8fff..7dd5d476d1 100644 --- a/examples/corelib/serialization/CMakeLists.txt +++ b/examples/corelib/serialization/CMakeLists.txt @@ -7,3 +7,6 @@ qt_internal_add_example(savegame) if(TARGET Qt6::Network AND TARGET Qt6::Widgets) qt_internal_add_example(rsslisting) endif() +if(TARGET Qt6::Widgets) + qt_internal_add_example(streambookmarks) +endif() diff --git a/examples/corelib/serialization/serialization.pro b/examples/corelib/serialization/serialization.pro index f36b467783..9f0ced0282 100644 --- a/examples/corelib/serialization/serialization.pro +++ b/examples/corelib/serialization/serialization.pro @@ -5,6 +5,7 @@ SUBDIRS = \ savegame qtHaveModule(widgets) { + SUBDIRS += streambookmarks qtHaveModule(network): SUBDIRS += \ rsslisting } diff --git a/examples/xml/streambookmarks/CMakeLists.txt b/examples/corelib/serialization/streambookmarks/CMakeLists.txt similarity index 90% rename from examples/xml/streambookmarks/CMakeLists.txt rename to examples/corelib/serialization/streambookmarks/CMakeLists.txt index cefc30453e..1d0ab8690b 100644 --- a/examples/xml/streambookmarks/CMakeLists.txt +++ b/examples/corelib/serialization/streambookmarks/CMakeLists.txt @@ -8,7 +8,7 @@ if(NOT DEFINED INSTALL_EXAMPLESDIR) set(INSTALL_EXAMPLESDIR "examples") endif() -set(INSTALL_EXAMPLEDIR "${INSTALL_EXAMPLESDIR}/xml/streambookmarks") +set(INSTALL_EXAMPLEDIR "${INSTALL_EXAMPLESDIR}/corelib/serialization/streambookmarks") find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets) diff --git a/examples/xml/streambookmarks/doc/images/xmlstreamexample-filemenu.png b/examples/corelib/serialization/streambookmarks/doc/images/xmlstreamexample-filemenu.png similarity index 100% rename from examples/xml/streambookmarks/doc/images/xmlstreamexample-filemenu.png rename to examples/corelib/serialization/streambookmarks/doc/images/xmlstreamexample-filemenu.png diff --git a/examples/xml/streambookmarks/doc/images/xmlstreamexample-helpmenu.png b/examples/corelib/serialization/streambookmarks/doc/images/xmlstreamexample-helpmenu.png similarity index 100% rename from examples/xml/streambookmarks/doc/images/xmlstreamexample-helpmenu.png rename to examples/corelib/serialization/streambookmarks/doc/images/xmlstreamexample-helpmenu.png diff --git a/examples/xml/streambookmarks/doc/images/xmlstreamexample-screenshot.png b/examples/corelib/serialization/streambookmarks/doc/images/xmlstreamexample-screenshot.png similarity index 100% rename from examples/xml/streambookmarks/doc/images/xmlstreamexample-screenshot.png rename to examples/corelib/serialization/streambookmarks/doc/images/xmlstreamexample-screenshot.png diff --git a/examples/xml/streambookmarks/doc/src/qxmlstreambookmarks.qdoc b/examples/corelib/serialization/streambookmarks/doc/src/qxmlstreambookmarks.qdoc similarity index 83% rename from examples/xml/streambookmarks/doc/src/qxmlstreambookmarks.qdoc rename to examples/corelib/serialization/streambookmarks/doc/src/qxmlstreambookmarks.qdoc index 546962162f..a452d61c1a 100644 --- a/examples/xml/streambookmarks/doc/src/qxmlstreambookmarks.qdoc +++ b/examples/corelib/serialization/streambookmarks/doc/src/qxmlstreambookmarks.qdoc @@ -2,7 +2,7 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \example streambookmarks + \example serialization/streambookmarks \title QXmlStream Bookmarks Example \brief Demonstrates how to read and write to XBEL files. \ingroup xml-examples @@ -20,7 +20,7 @@ has a reference to the QTreeWidget instance where the bookmark hierarchy is stored. - \snippet streambookmarks/xbelwriter.h 0 + \snippet serialization/streambookmarks/xbelwriter.h 0 \section1 XbelWriter Class Implementation @@ -30,20 +30,20 @@ sections between elements, increasing readability as the data is split into several lines. - \snippet streambookmarks/xbelwriter.cpp 0 + \snippet serialization/streambookmarks/xbelwriter.cpp 0 The \c writeFile() function accepts a QIODevice object and sets it using \c setDevice(). This function then writes the document type definition(DTD), the start element, the version, and \c{treeWidget}'s top-level items. - \snippet streambookmarks/xbelwriter.cpp 1 + \snippet serialization/streambookmarks/xbelwriter.cpp 1 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". - \snippet streambookmarks/xbelwriter.cpp 2 + \snippet serialization/streambookmarks/xbelwriter.cpp 2 \section1 XbelReader Class Definition @@ -52,7 +52,7 @@ reference to the QTreeWidget that is used to group the bookmarks according to their hierarchy. - \snippet streambookmarks/xbelreader.h 0 + \snippet serialization/streambookmarks/xbelreader.h 0 \section1 XbelReader Class Implementation @@ -64,7 +64,7 @@ QStyle::SP_FileIcon correspond to standard pixmaps that follow the style of your GUI. - \snippet streambookmarks/xbelreader.cpp 0 + \snippet serialization/streambookmarks/xbelreader.cpp 0 The \c read() function accepts a QIODevice and sets it using \l{QXmlStreamReader::}{setDevice()}. The actual process of reading only @@ -75,13 +75,13 @@ it makes extensive use of the \l{QXmlStreamReader::}{readNextStartElement()} convenience function. - \snippet streambookmarks/xbelreader.cpp 1 + \snippet serialization/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 streambookmarks/xbelreader.cpp 2 + \snippet serialization/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 @@ -89,24 +89,24 @@ \l{QXmlStreamReader::}{skipCurrentElement()}. The Q_ASSERT() macro is used to provide a pre-condition for the function. - \snippet streambookmarks/xbelreader.cpp 3 + \snippet serialization/streambookmarks/xbelreader.cpp 3 The \c readTitle() function reads the bookmark's title. - \snippet streambookmarks/xbelreader.cpp 4 + \snippet serialization/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. The element is then skipped using \l{QXmlStreamReader::}{skipCurrentElement()}. - \snippet streambookmarks/xbelreader.cpp 5 + \snippet serialization/streambookmarks/xbelreader.cpp 5 \section1 MainWindow Class Definition The \c MainWindow class is a subclass of QMainWindow, with a \c File menu and a \c Help menu. - \snippet streambookmarks/mainwindow.h 0 + \snippet serialization/streambookmarks/mainwindow.h 0 \section1 MainWindow Class Implementation @@ -117,33 +117,33 @@ is used to display the message "Ready" and the window's size is fixed to 480x320 pixels. - \snippet streambookmarks/mainwindow.cpp 0 + \snippet serialization/streambookmarks/mainwindow.cpp 0 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. - \snippet streambookmarks/mainwindow.cpp 1 + \snippet serialization/streambookmarks/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. - \snippet streambookmarks/mainwindow.cpp 2 + \snippet serialization/streambookmarks/mainwindow.cpp 2 The \c about() function displays a QMessageBox with a brief description of the example. - \snippet streambookmarks/mainwindow.cpp 3 + \snippet serialization/streambookmarks/mainwindow.cpp 3 In order to implement the \c open(), \c saveAs(), \c exit(), \c about() and \c aboutQt() functions, we connect them to QAction objects and add them to the \c fileMenu and \c helpMenu. The connections are as shown below: - \snippet streambookmarks/mainwindow.cpp 5 + \snippet serialization/streambookmarks/mainwindow.cpp 5 The \c createMenus() function creates the \c fileMenu and \c helpMenu and adds the QAction objects to them in order to create the menu shown @@ -155,14 +155,14 @@ \li \inlineimage xmlstreamexample-helpmenu.png \endtable - \snippet streambookmarks/mainwindow.cpp 5 + \snippet serialization/streambookmarks/mainwindow.cpp 5 \section1 \c{main()} Function The \c main() function instantiates \c MainWindow and invokes the \c show() function. - \snippet streambookmarks/main.cpp 0 + \snippet serialization/streambookmarks/main.cpp 0 See the \l{http://pyxml.sourceforge.net/topics/xbel/} {XML Bookmark Exchange Language Resource Page} for more information diff --git a/examples/xml/streambookmarks/jennifer.xbel b/examples/corelib/serialization/streambookmarks/jennifer.xbel similarity index 100% rename from examples/xml/streambookmarks/jennifer.xbel rename to examples/corelib/serialization/streambookmarks/jennifer.xbel diff --git a/examples/xml/streambookmarks/main.cpp b/examples/corelib/serialization/streambookmarks/main.cpp similarity index 100% rename from examples/xml/streambookmarks/main.cpp rename to examples/corelib/serialization/streambookmarks/main.cpp diff --git a/examples/xml/streambookmarks/mainwindow.cpp b/examples/corelib/serialization/streambookmarks/mainwindow.cpp similarity index 100% rename from examples/xml/streambookmarks/mainwindow.cpp rename to examples/corelib/serialization/streambookmarks/mainwindow.cpp diff --git a/examples/xml/streambookmarks/mainwindow.h b/examples/corelib/serialization/streambookmarks/mainwindow.h similarity index 100% rename from examples/xml/streambookmarks/mainwindow.h rename to examples/corelib/serialization/streambookmarks/mainwindow.h diff --git a/examples/xml/streambookmarks/streambookmarks.pro b/examples/corelib/serialization/streambookmarks/streambookmarks.pro similarity index 81% rename from examples/xml/streambookmarks/streambookmarks.pro rename to examples/corelib/serialization/streambookmarks/streambookmarks.pro index 23eebdfe7d..9b067c7bba 100644 --- a/examples/xml/streambookmarks/streambookmarks.pro +++ b/examples/corelib/serialization/streambookmarks/streambookmarks.pro @@ -11,5 +11,5 @@ requires(qtConfig(filedialog)) EXAMPLE_FILES = frank.xbel jennifer.xbel # install -target.path = $$[QT_INSTALL_EXAMPLES]/xml/streambookmarks +target.path = $$[QT_INSTALL_EXAMPLES]/corelib/serialization/streambookmarks INSTALLS += target diff --git a/examples/xml/streambookmarks/xbelreader.cpp b/examples/corelib/serialization/streambookmarks/xbelreader.cpp similarity index 100% rename from examples/xml/streambookmarks/xbelreader.cpp rename to examples/corelib/serialization/streambookmarks/xbelreader.cpp diff --git a/examples/xml/streambookmarks/xbelreader.h b/examples/corelib/serialization/streambookmarks/xbelreader.h similarity index 100% rename from examples/xml/streambookmarks/xbelreader.h rename to examples/corelib/serialization/streambookmarks/xbelreader.h diff --git a/examples/xml/streambookmarks/xbelwriter.cpp b/examples/corelib/serialization/streambookmarks/xbelwriter.cpp similarity index 100% rename from examples/xml/streambookmarks/xbelwriter.cpp rename to examples/corelib/serialization/streambookmarks/xbelwriter.cpp diff --git a/examples/xml/streambookmarks/xbelwriter.h b/examples/corelib/serialization/streambookmarks/xbelwriter.h similarity index 100% rename from examples/xml/streambookmarks/xbelwriter.h rename to examples/corelib/serialization/streambookmarks/xbelwriter.h diff --git a/examples/xml/CMakeLists.txt b/examples/xml/CMakeLists.txt index d97185f647..da1dde9acb 100644 --- a/examples/xml/CMakeLists.txt +++ b/examples/xml/CMakeLists.txt @@ -3,5 +3,4 @@ if(TARGET Qt6::Widgets) qt_internal_add_example(dombookmarks) - qt_internal_add_example(streambookmarks) endif() diff --git a/examples/xml/xml.pro b/examples/xml/xml.pro index 991d5a69d2..d80d8193ed 100644 --- a/examples/xml/xml.pro +++ b/examples/xml/xml.pro @@ -1,6 +1,5 @@ TEMPLATE = subdirs qtHaveModule(widgets) { - SUBDIRS += dombookmarks \ - streambookmarks + SUBDIRS += dombookmarks } diff --git a/src/corelib/doc/src/qtserialization.qdoc b/src/corelib/doc/src/qtserialization.qdoc index 528a4aa827..14ee5e7a9c 100644 --- a/src/corelib/doc/src/qtserialization.qdoc +++ b/src/corelib/doc/src/qtserialization.qdoc @@ -109,13 +109,20 @@ \section1 Advantages of Qt XML C++ Classes + Qt provides both DOM classes and stream-based classes to read and write + XML content. + Qt provides the QDomDocument class that represents the XML document and two classes for reading and writing the XML through a simple streaming API: QXmlStreamReader and QXmlStreamWriter. + \section2 The DOM XML Classes + QDomDocument class represents the entire XML document. It is the root of the document tree and provides primary access to the document's data. + \section2 The Stream-Based XML Classes + 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 @@ -132,7 +139,7 @@ The QXmlStreamWriter is a streaming API that takes care of prefixing namespaces, when the namespaceUri is specified when writing elements or attributes. - \section1 Classes that provide serialization + \section1 Classes that Provide Serialization \annotatedlist qtserialization */ diff --git a/src/xml/doc/src/qtxml-index.qdoc b/src/xml/doc/src/qtxml-index.qdoc index d6a7defb20..7ad55350a5 100644 --- a/src/xml/doc/src/qtxml-index.qdoc +++ b/src/xml/doc/src/qtxml-index.qdoc @@ -4,11 +4,9 @@ /*! \page qtxml-index.html \title Qt XML - \brief The Qt XML module provides C++ implementations of the SAX and DOM standards for XML. + \brief The Qt XML module provides a C++ implementation of the DOM standard for XML. - - The Qt XML module provides implementations of the SAX and DOM standards for - XML. + The Qt XML module provides an implementation of the DOM standard for XML. \note Qt XML will no longer receive additional features. For reading or writing XML documents iteratively (SAX), use the QXmlStreamReader and diff --git a/src/xml/doc/src/qtxml.qdoc b/src/xml/doc/src/qtxml.qdoc index f0e2d5f9b7..76394392be 100644 --- a/src/xml/doc/src/qtxml.qdoc +++ b/src/xml/doc/src/qtxml.qdoc @@ -8,7 +8,7 @@ \qtcmakepackage Xml \qtvariable xml - \brief The Qt XML module provides C++ implementations of the SAX and DOM standards for XML. + \brief The Qt XML module provides a C++ implementation of the DOM standard for XML. The \l{Qt XML} page contains information about how to use the module. diff --git a/src/xml/doc/src/xml-processing.qdoc b/src/xml/doc/src/xml-processing.qdoc index b98749ca41..f1f74a68c0 100644 --- a/src/xml/doc/src/xml-processing.qdoc +++ b/src/xml/doc/src/xml-processing.qdoc @@ -191,7 +191,8 @@ \nextpage Working with the DOM Tree Qt provides two classes for reading and writing XML through a simple streaming - API: QXmlStreamReader and QXmlStreamWriter. + API: QXmlStreamReader and QXmlStreamWriter. These classes are located in + \l{Qt Serialization}{Qt Serialization (part of QtCore)}. A stream reader reports an XML document as a stream of tokens. This differs from SAX as SAX applications provide handlers to @@ -207,27 +208,14 @@ \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 wraps a QXmlStreamReader. - The constructor takes \a treeWidget as a parameter and the class has Xbel - specific functions: + An example of an implementation tha uses QXmlStreamReader would be the + \l{QXmlStream Bookmarks Example#xbelreader-class-definition}{XbelReader} in + \l{QXmlStream Bookmarks Example}, which wraps a QXmlStreamReader. Read the + \l{QXmlStream Bookmarks Example#xbelreader-class-implementation}{implementation} + to learn more about how to use the QXmlStreamReader class. - \snippet streambookmarks/xbelreader.h 1 - - \dots - \snippet 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 streambookmarks/xbelreader.cpp 1 - - The pendent to QXmlStreamReader is QXmlStreamWriter, which provides an XML - writer with a simple streaming API. QXmlStreamWriter operates on a + Paired with QXmlStreamReader is the QXmlStreamWriter class, which provides + an XML writer with a simple streaming API. QXmlStreamWriter operates on a QIODevice and has specialized functions for all XML tokens or events you want to write, such as \l{QXmlStreamWriter::writeDTD()}{writeDTD()}, \l{QXmlStreamWriter::writeCharacters()}{writeCharacters()}, @@ -253,11 +241,10 @@ or subsequent calls to \l{QXmlStreamWriter::writeStartElement()} {writeStartElement()}. - The \c XbelWriter class from \l{QXmlStream Bookmarks Example} wraps a - QXmlStreamWriter. Its \c writeFile() function illustrates the core - functions of QXmlStreamWriter mentioned above: - - \snippet streambookmarks/xbelwriter.cpp 1 + The \l{QXmlStream Bookmarks Example#xbelwriter-class-definition}{XbelWriter} + class from \l{QXmlStream Bookmarks Example} wraps a QXmlStreamWriter. View + the \l{QXmlStream Bookmarks Example#xbelwriter-class-implementation}{implementation} + to see how to use the QXmlStreamWriter class. */ /*!