QDoc generates warnings for images that do not have an alternate-text associated with it. Alt-text is required for to increase accessibilty options. This patch adds alt-text to images in the Qt Network Fixes: QTBUG-135122 Pick-to: 6.8 Change-Id: I690f1d381ef5a9052e189dd1f3906243df557da0 Reviewed-by: Topi Reiniö <topi.reinio@qt.io> (cherry picked from commit ae6ba06e55dbdae98eb05069e007044bf70f45da) Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
130 lines
6.3 KiB
Plaintext
130 lines
6.3 KiB
Plaintext
// 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
|
|
*/
|