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: 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 --- 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 +++++++++++--------------------- 4 files changed, 24 insertions(+), 32 deletions(-) (limited to 'src') 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. */ /*! -- cgit v1.2.1