Improve Terminal example

Extend the example to handle bytesWritten() signal. This allows to
demonstrate both async read and async write with one example.
Extend the example description to cover these changes.

Apart from that do some regular cleanups:
* Do not use Example in the name
* Update screenshot
* add Connectivity category

Fixes: QTBUG-108870
Task-number: QTBUG-108868
Pick-to: 6.5
Change-Id: I013b66189fe321773f1fd7a8dcaf98c380833d8c
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>

7 files changed, 87 insertions, 24 deletions

diff --git a/examples/serialport/doc/blockingreceiver.qdoc b/examples/serialport/doc/blockingreceiver.qdoc
index a94f7a26..d8b08a43 100644
--- a/examples/serialport/doc/blockingreceiver.qdoc
+++ b/examples/serialport/doc/blockingreceiver.qdoc
@@ -137,7 +137,7 @@
 
     \snippet blockingreceiver/receiverthread.cpp 13
 
-    \sa {Terminal Example}, {Blocking Sender Example}
+    \sa {Serial Terminal}, {Blocking Sender Example}
 
     \include examples-run.qdocinc
 */
diff --git a/examples/serialport/doc/blockingsender.qdoc b/examples/serialport/doc/blockingsender.qdoc
index 2702e184..5420dfc2 100644
--- a/examples/serialport/doc/blockingsender.qdoc
+++ b/examples/serialport/doc/blockingsender.qdoc
@@ -137,7 +137,7 @@
 
     \snippet blockingsender/senderthread.cpp 13
 
-    \sa {Terminal Example}, {Blocking Receiver Example}
+    \sa {Serial Terminal}, {Blocking Receiver Example}
 
     \include examples-run.qdocinc
 */
diff --git a/examples/serialport/doc/terminal.qdoc b/examples/serialport/doc/terminal.qdoc
index c693954a..5707a248 100644
--- a/examples/serialport/doc/terminal.qdoc
+++ b/examples/serialport/doc/terminal.qdoc
@@ -1,11 +1,13 @@
 // Copyright (C) 2011 - 2012 Denis Shienkov <denis.shienkov@gmail.com>
-// Copyright (C) 2016 The Qt Company Ltd.
+// Copyright (C) 2023 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
     \example terminal
-    \title Terminal Example
+    \title Serial Terminal
     \ingroup qtserialport-examples
+    \meta category Connectivity
+
     \brief Shows how to use various features of QSerialPort.
 
     \e Terminal  shows how to create a terminal for a simple serial interface by
@@ -63,12 +65,16 @@
     happens automatically according to the parent and child mechanism in Qt:
 
     \snippet terminal/mainwindow.cpp 0
-    \dots
     \snippet terminal/mainwindow.cpp 1
+    \dots
 
-    The only QSerialPort signal invoked in this example is
-    \l{QIODevice::}{readyRead()}, which shows that new data has been
-    received and hence available:
+    This example demonstrates the following \l QSerialPort signals:
+    \list
+        \li \l {QIODevice::}{readyRead()} - shows that new data has been
+        received and hence available
+        \li \l {QIODevice::}{bytesWritten()} - used to check that all data was
+        written successfully
+    \endlist
 
     \dots
     \snippet terminal/mainwindow.cpp 2
@@ -79,7 +85,8 @@
 
     \snippet terminal/mainwindow.cpp 4
 
-    In this slot, the settings are read from \c{SettingsDialog} and an attempt is made to open and initialize the serial
+    In this slot, the settings are read from \c{SettingsDialog} and an attempt
+    is made to open and initialize the serial
     port accordingly. If successful, the status bar displays a message that the
     opening was successful with the given configuration; otherwise, a messagebox
     is displayed with the appropriate error code and message. If the serial port
@@ -93,12 +100,30 @@
 
     In this case, handled by the closure of the serial port.
 
+    Clicking on the \b{Configure} button invokes the \c{show()} slot which
+    belongs to the \c{SettingsDialog} widget.
+
+    This method (\c{terminal/settingsdialog.cpp}) displays the \c{SettingsDialog},
+    in which the user can choose the desired serial port, see the information
+    about the selected port, and set the desired parameters of the given serial
+    port.
+
+    \section2 Writing Data
+
     Typing characters in the console invokes the \c writeData() slot:
 
     \snippet terminal/mainwindow.cpp 6
 
     This slot sends the characters typed in the given
     Console widget to the serial port - see \c terminal/console.cpp.
+    It also starts a timer to track if the write actually succeeded or not.
+    We use the \l {QIODevice::}{bytesWritten()} signal to make sure that all
+    bytes are actually written. It is connected to the
+    \c {MainWindow::handleBytesWritten()} slot:
+
+    \snippet terminal/mainwindow.cpp 9
+
+    \section2 Reading Data
 
     When the serial port receives new data, the signal
     \l{QIODevice::}{readyRead()} is emitted, and that signal is
@@ -109,14 +134,6 @@
     This slot reads the data from the serial port and displays that in the
     Console widget.
 
-    Clicking on the \b{Configure} button invokes the \c{show()} slot which
-    belongs to the \c{SettingsDialog} widget.
-
-    This method (\c{terminal/settingsdialog.cpp}) displays the \c{SettingsDialog},
-    in which the user can choose the desired serial port, see the information
-    about the selected port, and set the desired parameters of the given serial
-    port.
-
     \sa {Blocking Receiver Example}
 
     \include examples-run.qdocinc
diff --git a/examples/serialport/terminal/mainwindow.cpp b/examples/serialport/terminal/mainwindow.cpp
index 56cf998d..d8c02122 100644
--- a/examples/serialport/terminal/mainwindow.cpp
+++ b/examples/serialport/terminal/mainwindow.cpp
@@ -9,19 +9,25 @@
 
 #include <QLabel>
 #include <QMessageBox>
+#include <QTimer>
+
+#include <chrono>
+
+static constexpr std::chrono::seconds kWriteTimeout = std::chrono::seconds{5};
 
 //! [0]
 MainWindow::MainWindow(QWidget *parent) :
     QMainWindow(parent),
     m_ui(new Ui::MainWindow),
+//! [0]
     m_status(new QLabel),
     m_console(new Console),
-      m_settings(new SettingsDialog(this)),
+    m_settings(new SettingsDialog(this)),
+    m_timer(new QTimer(this)),
 //! [1]
     m_serial(new QSerialPort(this))
-//! [1]
 {
-//! [0]
+//! [1]
     m_ui->setupUi(this);
     m_console->setEnabled(false);
     setCentralWidget(m_console);
@@ -36,9 +42,12 @@ MainWindow::MainWindow(QWidget *parent) :
     initActionsConnections();
 
     connect(m_serial, &QSerialPort::errorOccurred, this, &MainWindow::handleError);
+    connect(m_timer, &QTimer::timeout, this, &MainWindow::handleWriteTimeout);
+    m_timer->setSingleShot(true);
 
 //! [2]
     connect(m_serial, &QSerialPort::readyRead, this, &MainWindow::readData);
+    connect(m_serial, &QSerialPort::bytesWritten, this, &MainWindow::handleBytesWritten);
 //! [2]
     connect(m_console, &Console::getData, this, &MainWindow::writeData);
 //! [3]
@@ -93,8 +102,8 @@ void MainWindow::closeSerialPort()
 
 void MainWindow::about()
 {
-    QMessageBox::about(this, tr("About Simple Terminal"),
-                       tr("The <b>Simple Terminal</b> example demonstrates how to "
+    QMessageBox::about(this, tr("About Serial Terminal"),
+                       tr("The <b>Serial Terminal</b> example demonstrates how to "
                           "use the Qt Serial Port module in modern GUI applications "
                           "using Qt, with a menu bar, toolbars, and a status bar."));
 }
@@ -102,7 +111,16 @@ void MainWindow::about()
 //! [6]
 void MainWindow::writeData(const QByteArray &data)
 {
-    m_serial->write(data);
+    const qint64 written = m_serial->write(data);
+    if (written == data.size()) {
+        m_bytesToWrite += written;
+        m_timer->start(kWriteTimeout);
+    } else {
+        const QString error = tr("Failed to write all data to port %1.\n"
+                                 "Error: %2").arg(m_serial->portName(),
+                                                  m_serial->errorString());
+        showWriteError(error);
+    }
 }
 //! [6]
 
@@ -124,6 +142,23 @@ void MainWindow::handleError(QSerialPort::SerialPortError error)
 }
 //! [8]
 
+//! [9]
+void MainWindow::handleBytesWritten(qint64 bytes)
+{
+    m_bytesToWrite -= bytes;
+    if (m_bytesToWrite == 0)
+        m_timer->stop();
+}
+//! [9]
+
+void MainWindow::handleWriteTimeout()
+{
+    const QString error = tr("Write operation timed out for port %1.\n"
+                             "Error: %2").arg(m_serial->portName(),
+                                              m_serial->errorString());
+    showWriteError(error);
+}
+
 void MainWindow::initActionsConnections()
 {
     connect(m_ui->actionConnect, &QAction::triggered, this, &MainWindow::openSerialPort);
@@ -139,3 +174,8 @@ void MainWindow::showStatusMessage(const QString &message)
 {
     m_status->setText(message);
 }
+
+void MainWindow::showWriteError(const QString &message)
+{
+    QMessageBox::warning(this, tr("Warning"), message);
+}
diff --git a/examples/serialport/terminal/mainwindow.h b/examples/serialport/terminal/mainwindow.h
index a0fcb62a..975f9a40 100644
--- a/examples/serialport/terminal/mainwindow.h
+++ b/examples/serialport/terminal/mainwindow.h
@@ -11,6 +11,7 @@
 QT_BEGIN_NAMESPACE
 
 class QLabel;
+class QTimer;
 
 namespace Ui {
 class MainWindow;
@@ -37,17 +38,22 @@ private slots:
     void readData();
 
     void handleError(QSerialPort::SerialPortError error);
+    void handleBytesWritten(qint64 bytes);
+    void handleWriteTimeout();
 
 private:
     void initActionsConnections();
 
 private:
     void showStatusMessage(const QString &message);
+    void showWriteError(const QString &message);
 
     Ui::MainWindow *m_ui = nullptr;
     QLabel *m_status = nullptr;
     Console *m_console = nullptr;
     SettingsDialog *m_settings = nullptr;
+    qint64 m_bytesToWrite = 0;
+    QTimer *m_timer = nullptr;
     QSerialPort *m_serial = nullptr;
 };
 
diff --git a/examples/serialport/terminal/mainwindow.ui b/examples/serialport/terminal/mainwindow.ui
index 452fdd53..be0861f3 100644
--- a/examples/serialport/terminal/mainwindow.ui
+++ b/examples/serialport/terminal/mainwindow.ui
@@ -11,7 +11,7 @@
    </rect>
   </property>
   <property name="windowTitle">
-   <string>Simple Terminal</string>
+   <string>Serial Terminal</string>
   </property>
   <widget class="QWidget" name="centralWidget">
    <layout class="QVBoxLayout" name="verticalLayout"/>
diff --git a/src/serialport/doc/images/terminal-example.png b/src/serialport/doc/images/terminal-example.png
index 9affaae1..7cdbd213 100644
--- a/src/serialport/doc/images/terminal-example.png
+++ b/src/serialport/doc/images/terminal-example.png