/****************************************************************************
**
** Copyright (C) 2011 - 2012 Denis Shienkov <denis.shienkov@gmail.com>
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://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 http://www.qt.io/terms-conditions. For further
** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.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 \e{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 \e{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 \l{terminal/mainwindow.cpp}{MainWindow} - 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 \l{terminal/console.cpp}{Console} - is the central widget of the
    main window, displaying the transmitted or received data. The widget is
    derived from the QPlainTextEdit class.

    \li \l{terminal/settingsdialog.cpp}{SettingsDialog} - 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 \l{terminal/mainwindow.cpp}{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()}{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 \l{terminal/settingsdialog.cpp}
    {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
    \l{terminal/settingsdialog.cpp}{SettingsDialog}, 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{QTcpSocket::readyRead()}{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
    \l{terminal/console.cpp}{Console} widget.

    Clicking on the \b{Configure} button invokes the \c show() slot which
    belongs to the \l{terminal/settingsdialog.cpp}{SettingsDialog}
    widget.

    This method displays the \l{terminal/settingsdialog.cpp}{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
*/