/****************************************************************************
**
** 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 terminal
    \title Terminal Example
    \ingroup qtserialport-examples
    \brief Shows how to use various features of QSerialPort.

    \e Terminal  shows how to create a terminal for a simple serial interface by
    using \l{Qt Serial Port}.

    \image terminal-example.png

    This example shows the main features of the QSerialPort class, like
    configuration, I/O implementation and so forth. Also, the class
    QSerialPortInfo is invoked to display information about the serial ports
    available in the system.

    QSerialPort supports two general programming approaches:

    \list

    \li \b{The asynchronous (non-blocking) approach.} Operations are scheduled
    and performed when the control returns to Qt's event loop. QSerialPort emits
    a signal when the operation is finished. For example, QSerialPort::write()
    returns immediately. When the data is sent to the serial port,
    QSerialPort emits \l{QIODevice::bytesWritten()}{bytesWritten()}.

    \li \b{The synchronous (blocking) approach.} In non-GUI and multithreaded
    applications, the \c waitFor...() functions can be called (i.e.
    QSerialPort::waitForReadyRead()) to suspend the calling thread until the
    operation has completed.

    \endlist

    In this example, the asynchronous approach is demonstrated. The
    \l{blockingslave}{Blocking Slave} example illustrates the synchronous
    approach.

    Our example contains some GUI widgets:

    \list

    \li \c{MainWindow} (\c{terminal/mainwindow.cpp}) - is the main application
    window that contains all the working logic for the serial port programming,
    including configuration, I/O processing and so forth, while inheriting the
    QMainWindow.

    \li \c{Console} (\c{terminal/console.cpp}) - is the central widget of the
    main window, displaying the transmitted or received data. The widget is
    derived from the QPlainTextEdit class.

    \li \c{SettingsDialog} (\c{terminal/settingsdialog.cpp}) - is a dialog for
    configuring the serial port, as well as for displaying the available serial
    ports and information about them.

    \endlist

    The serial port is instantiated in the \c MainWindow
    constructor. The main widget is passed as the parent, so the object deletion
    happens automatically according to the parent and child mechanism in Qt:

    \snippet terminal/mainwindow.cpp 0
    \dots
    \snippet terminal/mainwindow.cpp 1

    The only QSerialPort signal invoked in this example is
    \l{QIODevice::}{readyRead()}, which shows that new data has been
    received and hence available:

    \dots
    \snippet terminal/mainwindow.cpp 2
    \dots
    \snippet terminal/mainwindow.cpp 3

    Clicking on the \b{Connect} button invokes the \c openSerialPort() slot:

    \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
    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
    settings have never been called then the terminal attempts to open
    the port with the default settings: 9600 8N1.

    Clicking on the \b{Disconnect} button invokes the \c closeSerialPort()
    slot:

    \snippet terminal/mainwindow.cpp 5

    In this case, handled by the closure of the serial port.

    Typing characters in the console invokes the \c writeData() slot:

    \snippet terminal/mainwindow.cpp 6

    This slot sends the characters typed in the given
    \l{terminal/console.cpp}{Console} widget to the serial port.

    When the serial port receives new data, the signal
    \l{QIODevice::}{readyRead()} is emitted, and that signal is
    connected to the \c{MainWindow::readData()} slot:

    \snippet terminal/mainwindow.cpp 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}

    \include examples-run.qdocinc
*/