Revision control
++ // Copyright (C) 2023 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example rsslisting
++ \examplecategory {Networking}
++ \meta tag {serialization}
++ \title A minimal RSS listing application
++
++ \brief A demonstration of how to fetch and display a network resource.
++
++ This example shows how to fetch a resource the user has requested and
++ display data contained in the response, illustrated by an RSS listing
++ application. (RDF Site Summary, or Really Simple Syndication, is a standard
++ format for communicating updates to web sites. See
++ https://www.rssboard.org/rss-specification for details.) The user inferface
++ in the illustration is simple, as the focus of this example is on how to use
++ networking, but naturally a more sophisticated interface would be wanted for
++ a serious RSS reader.
++
++ The example also illustrates how to do asynchronous parsing of data as it is
++ received, preserving state in member variables so that an incremental parser
++ can consume chunks of data as they arrive over the network. Constituents of
++ the parsed content may start in one chunk of data but not be completed until
++ a later chunk, requiring the parser to retain state between calls.
++
++ \image rsslisting.png {The application fetches information from the specified URL, in this case, Qt Blog, and then parses the available XML data}
++
++ The main program is fairly minimal. It simply instantiates a \l QApplication
++ and the \c RSSListing widget, shows the latter and hands over control to the
++ former. For the sake of illustration, it gives the widget the Qt blog's URL
++ as default value for the resource to check.
++
++ \snippet rsslisting/main.cpp 0
++
++ \section1 The RSSListing class
++
++ \snippet rsslisting/rsslisting.h 0
++
++ The widget itself provides a simple user interface for specifying the URL to
++ fetch and, once available updates are displayed, controlling the downloading
++ of updated items. A \l QLineEdit provides for input of the URL, and a
++ \l QTreeWidget for display of the results once fetched.
++
++ The widget downloads and parses the RSS (a form of XML) asynchronously,
++ feeding the data to an XML reader as it arrives. This supports reading of
++ very large data sources. Because the data is streamed from the network
++ through the XML reader, there is no need to retain the full text of the XML
++ in memory. In other context, a similar approach can allow the user to
++ interrupt such incremental loading.
++
++ \section2 Construction
++
++ \snippet rsslisting/rsslisting.cpp setup
++
++ The constructor sets up the assorted components of the widget and connects
++ their various signals to the slots it shall use to handle them.
++
++ The user interface consists of a line edit, a push button, and a list view
++ widget. The line edit is used for entering the URL to fetch; the push button
++ starts the process of fetching updates. The line edit is empty by default,
++ but the constructor's caller can override that, as our \c main() has done.
++ In any case, the user can replace the default with the URL of another RSS
++ feed.
++
++ The list view shows the updated items reported in the RSS feed.
++ Double-clicking on one of these sends its URL to the user's browser or other
++ user agent using \l QDesktopServices::openUrl().
++
++ \section2 The slots
++
++ \snippet rsslisting/rsslisting.cpp slots
++
++ All slots are kept simple by delegating any hard work to private methods.
++
++ When the user completes input of a URL, either by clicking the "Fetch"
++ button or by pressing the return key in the line edit, the \c fetch() slot
++ disables the "Fetch" button and disables further editing of the line edit.
++ It clears the display of available updates and delegates to \c get() the
++ initiating of an HTTP GET request.
++
++ When data is received, the network reply triggers its \l {QNetworkReply::}
++ {readyRead()} signal, which \c get() connects to the \c consumeData()
++ slot. This checks the response got a successful status code and, if it did,
++ calls \c parseXml() to consume the data.
++
++ If the network reply gets an error, this is delivered to the \c error()
++ slot, which reports the error, clears the XML stream reader then disconnects
++ from the reply and deletes it.
++
++ On completion (whether successful or otherwise) of a network reply, the \c
++ finished() slot restores the UI to be ready to accept a new URL to fetch by
++ re-enabling the line edit and "Fetch" button.
++
++ \section2 The get() method
++
++ \snippet rsslisting/rsslisting.cpp get
++
++ The private \c get() method is used by the \c fetch() slot to initiate an
++ HTTP GET request. It first clears the XML stream reader and, if a reply is
++ currently active, disconnects and deletes it. If the URL it has been passed
++ is valid, it asks the network access manager to GET it. It connects its
++ relevant slots to signals of the resulting reply (if any) and sets up its
++ XML stream reader to read data from the reply - a network reply object is
++ also a \c QIODevice, from which data can be read.
++
++ \section2 The parseXml() method
++
++ \snippet rsslisting/rsslisting.cpp parse
++
++ When data is received, and thus made available to the XML stream reader, \c
++ parseXml() reads from the XML stream, checking for \c item elements and,
++ within them, \c title and \c link elements. It will use the \c{rss:about}
++ attribute of an \c item as URL in the Link column of the tree-view, failing
++ that the content of its \c link element; and it uses the content of the \c
++ title element in the Title column of the tree-view. As each \c item element
++ closes, its details are turned into a new row in the tree widget, with the
++ extracted title and URL in the Title and Link columns.
++
++ The variables that keep track of the parsing state - \c linkString, \c
++ titleString and \c currentTag - are member variables of the \c RSSListing
++ class, even though they are only accessed from this method, because this
++ method may be called repeatedly, as new data arrives, and one chunk of
++ received data may start an element that isn't completed until a later chunk
++ arrives. This enables the parser to operate asynchronously as the data
++ arrives, instead of having to wait until all the data has arrived.
++
++ \sa QNetworkReply, QXmlStreamReader
++ */