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 <[email protected]>

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()

examples/corelib/serialization/serialization.pro

@@ -5,6 +5,7 @@ SUBDIRS = \
     savegame
 
 qtHaveModule(widgets) {
+    SUBDIRS +=  streambookmarks
     qtHaveModule(network): SUBDIRS += \
                 rsslisting
 }

examples/xml/streambookmarks/CMakeLists.txt → 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)
 

examples/xml/streambookmarks/doc/src/qxmlstreambookmarks.qdoc → 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,38 +75,38 @@
     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
     "folder", "bookmark" or "separator". Otherwise, it calls
     \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

examples/xml/streambookmarks/streambookmarks.pro → 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

examples/xml/CMakeLists.txt

@@ -3,5 +3,4 @@
 
 if(TARGET Qt6::Widgets)
     qt_internal_add_example(dombookmarks)
-    qt_internal_add_example(streambookmarks)
 endif()

examples/xml/xml.pro

@@ -1,6 +1,5 @@
 TEMPLATE      = subdirs
 
 qtHaveModule(widgets) {
-    SUBDIRS +=  dombookmarks \
-                streambookmarks
+    SUBDIRS +=  dombookmarks
 }

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
 */

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

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.
 

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.
 */
 
 /*!