summaryrefslogtreecommitdiff
path: root/examples/doc/terminal.qdoc
blob: d5ce209bc93dbbb268399df364403fce981cb899 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
/****************************************************************************
**
** Copyright (C) 2011 - 2012 Denis Shienkov <denis.shienkov@gmail.com>
** Contact: http://www.qt-project.org/legal
**
** 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 Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/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

    The Terminal example shows how to create a terminal for a simple serial
    interface by using Qt Serial Port.

    \image terminal-example.png Screenshot of the Terminal example

    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{QSerialPort::bytesWritten()}{bytesWritten()}.

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

    \endlist

    In this example, the asynchronous approach is demonstrated. The
    \l{examples/blockingterminal}{Blocking Simple Terminal} example
    illustrates the synchronous approach.

    Our example contains some GUI widgets:

    \list

    \li \l{examples/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{examples/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{examples/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{examples/terminal/mainwindow.cpp}{MainWindow}
    constructor. The main widget is passed as the parent, so the object deletion
    happens automatically according to the 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
    QSerialPort::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{examples/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{examples/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{examples/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{examples/terminal/console.cpp}{Console} widget.

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

    This method displays the \l{examples/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 Simple Terminal Example}
*/