diff options
Diffstat (limited to 'examples/serialport/doc')
| -rw-r--r-- | examples/serialport/doc/blockingreceiver.qdoc (renamed from examples/serialport/doc/blockingslave.qdoc) | 100 | ||||
| -rw-r--r-- | examples/serialport/doc/blockingsender.qdoc (renamed from examples/serialport/doc/blockingmaster.qdoc) | 88 | ||||
| -rw-r--r-- | examples/serialport/doc/cenumerator.qdoc | 47 | ||||
| -rw-r--r-- | examples/serialport/doc/creaderasync.qdoc | 49 | ||||
| -rw-r--r-- | examples/serialport/doc/creadersync.qdoc | 49 | ||||
| -rw-r--r-- | examples/serialport/doc/cwriterasync.qdoc | 49 | ||||
| -rw-r--r-- | examples/serialport/doc/cwritersync.qdoc | 49 | ||||
| -rw-r--r-- | examples/serialport/doc/enumerator.qdoc | 47 | ||||
| -rw-r--r-- | examples/serialport/doc/terminal.qdoc | 79 |
9 files changed, 108 insertions, 449 deletions
diff --git a/examples/serialport/doc/blockingslave.qdoc b/examples/serialport/doc/blockingreceiver.qdoc index f15f8e3..71a2084 100644 --- a/examples/serialport/doc/blockingslave.qdoc +++ b/examples/serialport/doc/blockingreceiver.qdoc @@ -1,41 +1,19 @@ -/**************************************************************************** -** -** Copyright (C) 2011 - 2012 Denis Shienkov <denis.shienkov@gmail.com> -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2011 - 2012 Denis Shienkov <denis.shienkov@gmail.com> +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \example blockingslave - \title Blocking Slave Example + \example blockingreceiver + \title Blocking Receiver \ingroup qtserialport-examples + \examplecategory Connectivity + \brief Shows how to use the synchronous API of QSerialPort in a non-GUI thread. - \e{Blocking Slave} shows how to create an application for a serial interface + \e{Blocking Receiver} shows how to create an application for a serial interface using QSerialPort's synchronous API in a non-GUI thread. - \image blockingslave-example.png + \image blockingreceiver-example.png QSerialPort supports two general programming approaches: @@ -66,55 +44,55 @@ But contrary to what many think, using threads with QThread does not necessarily add unmanageable complexity to your application. - This application is a Slave, that demonstrate the work paired with Master - application \l{Blocking Master Example}. + This application is a Receiver, that demonstrate the work paired with the + sender application \l{blockingsender}{Blocking Sender example}. - The Slave application is receives the request via serial port from - the Master application and send a response to it. + The Receiver application receives the request via serial port from + the Sender application and send a response to it. - We will start with the SlaveThread class, which handles the serial + We will start with the ReceiverThread class, which handles the serial programming code. - \snippet blockingslave/slavethread.h 0 + \snippet blockingreceiver/receiverthread.h 0 - SlaveThread is a QThread subclass that provides an API for receive requests - from Master, and it has signals for delivering responses and reporting + ReceiverThread is a QThread subclass that provides an API for receive requests + from Sender, and it has signals for delivering responses and reporting errors. - You should be call startSlave() to startup Slave application. This method - transfers to the SlaveThread desired parameters for configure and startup - the serial interface. When SlaveThread received from Master any request then + You should call startReceiver() to startup Receiver application. This method + transfers to the ReceiverThread desired parameters for configure and startup + the serial interface. When ReceiverThread received from Sender any request then emitted the request() signal. If any error occurs, the error() or timeout() signals is emitted. - It's important to notice that startSlave() is called from the main, GUI + It's important to notice that startReceiver() is called from the main, GUI thread, but the response data and other parameters will be accessed from - SlaveThread's thread. SlaveThread's data members are read and written + ReceiverThread's thread. ReceiverThread's data members are read and written from different threads concurrently, so it is advisable to use QMutex to synchronize access. - \snippet blockingslave/slavethread.cpp 2 + \snippet blockingreceiver/receiverthread.cpp 2 - The startSlave() function stores the serial port name, timeout and response + The startReceiver() function stores the serial port name, timeout and response data, and QMutexLocker locks the mutex to protect these data. We then start the thread, unless it is already running. QWaitCondition::wakeOne() will be discussed later. - \snippet blockingslave/slavethread.cpp 4 - \snippet blockingslave/slavethread.cpp 5 + \snippet blockingreceiver/receiverthread.cpp 4 + \snippet blockingreceiver/receiverthread.cpp 5 In the run() function, start by acquiring the mutex lock, fetch the serial port name, timeout and response data from the member data, and then - release the lock again. Under no circumstance should the method \c startSlave() + release the lock again. Under no circumstance should the method \c startReceiver() be called simultaneously with a process fetching these data. QString is reentrant but not thread-safe, and it is not recommended to read the serial port name - from one startup, call and timeout or response data of another. SlaveThread + from one startup, call and timeout or response data of another. ReceiverThread can only handle one startup at a time. The QSerialPort object we construct on stack into run() function before loop enter: - \snippet blockingslave/slavethread.cpp 6 + \snippet blockingreceiver/receiverthread.cpp 6 This allows us once to create an object, while running loop, and also means that all the methods of the object will be executed in the context of the @@ -123,24 +101,24 @@ In the loop, check whether the name of the serial port for the current startup has changed or not. If it has, re-open and reconfigure the serial port. - \snippet blockingslave/slavethread.cpp 7 + \snippet blockingreceiver/receiverthread.cpp 7 The loop will continue waiting for request data: - \snippet blockingslave/slavethread.cpp 8 + \snippet blockingreceiver/receiverthread.cpp 8 \warning The method waitForReadyRead() should be used before each read() call for the blocking approach, because it processes all the I/O routines instead of Qt event-loop. - The timeout() signal is emitted if error occurs when reading data. + The timeout() signal is emitted if an error occurs when reading data. - \snippet blockingslave/slavethread.cpp 9 + \snippet blockingreceiver/receiverthread.cpp 9 After a successful read, try to send a response and wait for completion of the transfer: - \snippet blockingslave/slavethread.cpp 10 + \snippet blockingreceiver/receiverthread.cpp 10 \warning The method waitForBytesWritten() should be used after each write() call for the blocking approach, because it processes all the I/O routines @@ -148,20 +126,20 @@ The timeout() signal is emitted if an error occurs when writing data. - \snippet blockingslave/slavethread.cpp 11 + \snippet blockingreceiver/receiverthread.cpp 11 After a successful writing is emitted, request() signal containing the - data received from the Master application: + data received from the Sender application: - \snippet blockingslave/slavethread.cpp 12 + \snippet blockingreceiver/receiverthread.cpp 12 Next, the thread switches to reading the current parameters for the serial interface, because they can already have been updated, and run the loop from the beginning. - \snippet blockingslave/slavethread.cpp 13 + \snippet blockingreceiver/receiverthread.cpp 13 - \sa {Terminal Example}, {Blocking Master Example} + \sa {Serial Terminal}, {Blocking Sender} \include examples-run.qdocinc */ diff --git a/examples/serialport/doc/blockingmaster.qdoc b/examples/serialport/doc/blockingsender.qdoc index d3f7e4e..db28b72 100644 --- a/examples/serialport/doc/blockingmaster.qdoc +++ b/examples/serialport/doc/blockingsender.qdoc @@ -1,42 +1,20 @@ -/**************************************************************************** -** -** Copyright (C) 2011 - 2012 Denis Shienkov <denis.shienkov@gmail.com> -** Copyright (C) 2012 - 2013 Laszlo Papp <lpapp@kde.org> -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2011 - 2012 Denis Shienkov <denis.shienkov@gmail.com> +// Copyright (C) 2012 - 2013 Laszlo Papp <lpapp@kde.org> +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! - \example blockingmaster - \title Blocking Master Example + \example blockingsender + \title Blocking Sender \ingroup qtserialport-examples + \examplecategory Connectivity + \brief Shows how to use the synchronous API of QSerialPort in a worker thread. - \e{Blocking Master} shows how to create an application for a serial + \e{Blocking Sender} shows how to create an application for a serial interface using the synchronous API of QSerialPort in a worker thread. - \image blockingmaster-example.png + \image blockingsender-example.png QSerialPort supports two programming alternatives: @@ -65,35 +43,35 @@ should only be used in non-GUI threads to keep the user interface responsive. - This application is the master which demonstrates the work paired with the slave - application \l{blockingslave}{Blocking Slave Example}. + This application is the sender which demonstrates the work paired with the + receiver application \l{blockingreceiver}{Blocking Receiver example}. - The master application initiates the transfer request via the serial port to - the slave application and waits for response. + The sender application initiates the transfer request via the serial port to + the receiver application and waits for response. - \snippet blockingmaster/masterthread.h 0 + \snippet blockingsender/senderthread.h 0 - MasterThread is a QThread subclass that provides API for scheduling - requests to the slave. This class provides signals for responding and + SenderThread is a QThread subclass that provides API for scheduling + requests to the receiver. This class provides signals for responding and reporting errors. The transaction() method can be called to start up the - new master transaction with the desired request. The result is provided by + new sender transaction with the desired request. The result is provided by the response() signal. In case of any issues, the error() or timeout() signal is emitted. Note, the transaction() method is called in the main thread, but the - request is provided in the MasterThread thread. The MasterThread + request is provided in the SenderThread thread. The SenderThread data members are read and written concurrently in different threads, thus the QMutex class is used to synchronize the access. - \snippet blockingmaster/masterthread.cpp 2 + \snippet blockingsender/senderthread.cpp 2 The transaction() method stores the serial port name, timeout and request data. The mutex can be locked with QMutexLocker to protect this data. The thread can be started then, unless it is already running. The \l{QWaitCondition::wakeOne()}{wakeOne()} method is discussed later. - \snippet blockingmaster/masterthread.cpp 4 - \snippet blockingmaster/masterthread.cpp 5 + \snippet blockingsender/senderthread.cpp 4 + \snippet blockingsender/senderthread.cpp 5 In the run() function, the first is to lock the QMutex object, then fetch the serial port name, timeout and request data by using the member data. Having @@ -103,13 +81,13 @@ simultaneously with a process fetching the data. Note, while the QString class is reentrant, it is not thread-safe. Thereby, it is not recommended to read the serial port name in a request thread, and timeout or request data - in another thread. The MasterThread class can only handle one request at a + in another thread. The SenderThread class can only handle one request at a time. The QSerialPort object is constructed on stack in the run() method before entering the loop: - \snippet blockingmaster/masterthread.cpp 6 + \snippet blockingsender/senderthread.cpp 6 This makes it possible to create an object while running the loop. It also means that all the object methods are executed in the scope of the run() @@ -119,12 +97,12 @@ current transaction has changed. If this has changed, the serial port is reopened and then reconfigured. - \snippet blockingmaster/masterthread.cpp 7 + \snippet blockingsender/senderthread.cpp 7 The loop will continue to request data, write to the serial port and wait until all data is transferred. - \snippet blockingmaster/masterthread.cpp 8 + \snippet blockingsender/senderthread.cpp 8 \warning As for the blocking transfer, the \l{QSerialPort::waitForBytesWritten()}{waitForBytesWritten()} method should be @@ -134,12 +112,12 @@ The timeout() signal is emitted if a timeout error occurs when transferring data. - \snippet blockingmaster/masterthread.cpp 9 + \snippet blockingsender/senderthread.cpp 9 There is a waiting period for response after a successful request, and then it is read again. - \snippet blockingmaster/masterthread.cpp 10 + \snippet blockingsender/senderthread.cpp 10 \warning As for the blocking alternative, the \l{QSerialPort::waitForReadyRead()}{waitForReadyRead()} method should be @@ -148,20 +126,20 @@ The timeout() signal is emitted if a timeout error occurs when receiving data. - \snippet blockingmaster/masterthread.cpp 11 + \snippet blockingsender/senderthread.cpp 11 When a transaction has been completed successfully, the response() signal contains - the data received from the slave application: + the data received from the receiver application: - \snippet blockingmaster/masterthread.cpp 12 + \snippet blockingsender/senderthread.cpp 12 Afterwards, the thread goes to sleep until the next transaction appears. The thread reads the new data after waking up by using the members and runs the loop from the beginning. - \snippet blockingmaster/masterthread.cpp 13 + \snippet blockingsender/senderthread.cpp 13 - \sa {Terminal Example}, {Blocking Slave Example} + \sa {Serial Terminal}, {Blocking Receiver} \include examples-run.qdocinc */ diff --git a/examples/serialport/doc/cenumerator.qdoc b/examples/serialport/doc/cenumerator.qdoc deleted file mode 100644 index 1b1d6dc..0000000 --- a/examples/serialport/doc/cenumerator.qdoc +++ /dev/null @@ -1,47 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Laszlo Papp <lpapp@kde.org> -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example cenumerator - \title Command Line Enumerator Example - \ingroup qtserialport-examples - \brief Shows how to get information about serial devices in a system. - - \e{Command Line Enumerator} shows how to use the class QSerialPortInfo for - getting information about serial devices that are present in the system. - - \image cenumerator-example.png - - This command line example displays information about serial ports in a - console, provided by the class QSerialPortInfo. - - For getting information about the available ports, use the static method - \l{QSerialPortInfo::availablePorts()}{availablePorts()}. - - \include examples-run.qdocinc -*/ diff --git a/examples/serialport/doc/creaderasync.qdoc b/examples/serialport/doc/creaderasync.qdoc deleted file mode 100644 index fdcbc24..0000000 --- a/examples/serialport/doc/creaderasync.qdoc +++ /dev/null @@ -1,49 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2013 Laszlo Papp <lpapp@kde.org> -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example creaderasync - \title Command Line Reader Async Example - \ingroup qtserialport-examples - \brief Shows how to receive data asynchronously over serial port. - - \e{Command Line Reader Async} shows how to use the QSerialPort class for - receiving data asynchronously over the selected serial port with the desired - settings. - - \image creaderasync-example.png - - This command line reader async example receives data asynchronously over the - selected serial port in a console, provided by the QSerialPort class. - - For receiving data synchronously over the selected serial port, use the - \l{QSerialPort::read()}{read()} or \l{QSerialPort::readAll()}{readAll()} - methods, and \l{QIODevice::readyRead()}{readyRead()} signal. - - \include examples-run.qdocinc -*/ diff --git a/examples/serialport/doc/creadersync.qdoc b/examples/serialport/doc/creadersync.qdoc deleted file mode 100644 index cb4c79a..0000000 --- a/examples/serialport/doc/creadersync.qdoc +++ /dev/null @@ -1,49 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2013 Laszlo Papp <lpapp@kde.org> -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example creadersync - \title Command Line Reader Sync Example - \ingroup qtserialport-examples - \brief Shows how to receive data synchronously over serial port. - - \e{Command Line Reader Sync} shows how to use the QSerialPort class - for receiving data synchronously over the selected serial port with the - desired settings. - - \image creadersync-example.png - - This command line reader sync example receives data synchronously over the - selected serial port in a console, provided by the QSerialPort class. - - For receiving data synchronously over the selected serial port, use the - \l{QSerialPort::read()}{read()} or \l{QSerialPort::readAll()}{readAll()}, - and \l{QIODevice::waitForReadyRead()}{waitForReadyRead()} methods. - - \include examples-run.qdocinc -*/ diff --git a/examples/serialport/doc/cwriterasync.qdoc b/examples/serialport/doc/cwriterasync.qdoc deleted file mode 100644 index 30d77c8..0000000 --- a/examples/serialport/doc/cwriterasync.qdoc +++ /dev/null @@ -1,49 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2013 Laszlo Papp <lpapp@kde.org> -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example cwriterasync - \title Command Line Writer Async Example - \ingroup qtserialport-examples - \brief Shows how to send data asynchronously over serial port. - - \e{Command Line Writer Async} shows how to use the QSerialPort class for - sending data asynchronously over the selected serial port with the desired - settings. - - \image cwriterasync-example.png - - This command line writer async example sends data asynchronously over the - selected serial port in a console, provided by the QSerialPort class. - - For sending data asynchronously over the selected serial port, use the - \l{QIODevice::write()}{write()} method and - \l{QIODevice::bytesWritten()}{bytesWritten()} signal. - - \include examples-run.qdocinc -*/ diff --git a/examples/serialport/doc/cwritersync.qdoc b/examples/serialport/doc/cwritersync.qdoc deleted file mode 100644 index b46a508..0000000 --- a/examples/serialport/doc/cwritersync.qdoc +++ /dev/null @@ -1,49 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2013 Laszlo Papp <lpapp@kde.org> -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example cwritersync - \title Command Line Writer Sync Example - \ingroup qtserialport-examples - \brief Shows how to send data synchronously over serial port. - - \e{Command Line Writer Sync} shows how to use the QSerialPort class for - sending data synchronously over the selected serial port with the desired - settings. - - \image cwritersync-example.png - - This command line writer sync example sends data synchronously over the - selected serial port in a console, provided by the QSerialPort class. - - For sending data synchronously over the selected serial port, use the - \l{QIODevice::write()}{write()} and - \l{QIODevice::waitForBytesWritten()}{waitForBytesWritten()} methods. - - \include examples-run.qdocinc -*/ diff --git a/examples/serialport/doc/enumerator.qdoc b/examples/serialport/doc/enumerator.qdoc deleted file mode 100644 index 1a5fce5..0000000 --- a/examples/serialport/doc/enumerator.qdoc +++ /dev/null @@ -1,47 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 - 2012 Denis Shienkov <denis.shienkov@gmail.com> -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example enumerator - \title Enumerator Example - \ingroup qtserialport-examples - \brief Shows how to display information about serial devices in a system. - - \e Enumerator shows how to use the class QSerialPortInfo for - getting information about serial devices that are present in the system. - - \image enumerator-example.png - - This GUI example displays information about serial ports in a widget, - provided by the class QSerialPortInfo. - - For getting information about the available ports, use the static method - \l{QSerialPortInfo::availablePorts()}{availablePorts()}. - - \include examples-run.qdocinc -*/ diff --git a/examples/serialport/doc/terminal.qdoc b/examples/serialport/doc/terminal.qdoc index 0215677..c90a3c0 100644 --- a/examples/serialport/doc/terminal.qdoc +++ b/examples/serialport/doc/terminal.qdoc @@ -1,35 +1,13 @@ -/**************************************************************************** -** -** Copyright (C) 2011 - 2012 Denis Shienkov <denis.shienkov@gmail.com> -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2011 - 2012 Denis Shienkov <denis.shienkov@gmail.com> +// 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 + \examplecategory Connectivity + \brief Shows how to use various features of QSerialPort. \e Terminal shows how to create a terminal for a simple serial interface by @@ -60,7 +38,7 @@ \endlist In this example, the asynchronous approach is demonstrated. The - \l{blockingslave}{Blocking Slave} example illustrates the synchronous + \l{blockingreceiver}{Blocking Receiver} example illustrates the synchronous approach. Our example contains some GUI widgets: @@ -87,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 @@ -103,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 @@ -117,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 @@ -133,15 +134,7 @@ 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 Slave Example} + \sa {Blocking Receiver} \include examples-run.qdocinc */ |