<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html> <html lang="en"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <!-- terminal.qdoc --> <title>Terminal Example | Qt Serial Port 5.12.2</title> <link rel="stylesheet" type="text/css" href="style/offline-simple.css" /> <script type="text/javascript"> document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css"); // loading style sheet breaks anchors that were jumped to before // so force jumping to anchor again setTimeout(function() { var anchor = location.hash; // need to jump to different anchor first (e.g. none) location.hash = "#"; setTimeout(function() { location.hash = anchor; }, 0); }, 0); </script> </head> <body> <div class="header" id="qtdocheader"> <div class="main"> <div class="main-rounded"> <div class="navigationbar"> <table><tr> <td >Qt 5.12</td><td ><a href="qtserialport-index.html">Qt Serial Port</a></td><td ><a href="qtserialport-examples.html">Qt Serial Port Examples</a></td><td >Terminal Example</td></tr></table><table class="buildversion"><tr> <td id="buildversion" width="100%" align="right"><a href="qtserialport-index.html">Qt 5.12.2 Reference Documentation</a></td> </tr></table> </div> </div> <div class="content"> <div class="line"> <div class="content mainContent"> <div class="sidebar"> <div class="toc"> <h3><a name="toc">Contents</a></h3> <ul> <li class="level1"><a href="#running-the-example">Running the Example</a></li> </ul> </div> <div class="sidebar-content" id="sidebar-content"></div></div> <h1 class="title">Terminal Example</h1> <span class="subtitle"></span> <!-- $$$terminal-brief --> <p>Shows how to use various features of <a href="qserialport.html">QSerialPort</a>.</p> <!-- @@@terminal --> <!-- $$$terminal-description --> <div class="descr"> <a name="details"></a> <p><i>Terminal</i> shows how to create a terminal for a simple serial interface by using <a href="qtserialport-index.html">Qt Serial Port</a>.</p> <p class="centerAlign"><img src="images/terminal-example.png" alt="" /></p><p>This example shows the main features of the <a href="qserialport.html">QSerialPort</a> class, like configuration, I/O implementation and so forth. Also, the class <a href="qserialportinfo.html">QSerialPortInfo</a> is invoked to display information about the serial ports available in the system.</p> <p><a href="qserialport.html">QSerialPort</a> supports two general programming approaches:</p> <ul> <li><i>The asynchronous (non-blocking) approach.</i> Operations are scheduled and performed when the control returns to Qt's event loop. <a href="qserialport.html">QSerialPort</a> emits a signal when the operation is finished. For example, QSerialPort::write() returns immediately. When the data is sent to the serial port, <a href="qserialport.html">QSerialPort</a> emits bytesWritten().</li> <li><i>The synchronous (blocking) approach.</i> In non-GUI and multithreaded applications, the <code>waitFor...()</code> functions can be called (i.e. <a href="qserialport.html#waitForReadyRead">QSerialPort::waitForReadyRead</a>()) to suspend the calling thread until the operation has completed.</li> </ul> <p>In this example, the asynchronous approach is demonstrated. The <a href="qtserialport-blockingslave-example.html">Blocking Slave</a> example illustrates the synchronous approach.</p> <p>Our example contains some GUI widgets:</p> <ul> <li><a href="qtserialport-terminal-mainwindow-cpp.html">MainWindow</a> - 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> <li><a href="qtserialport-terminal-console-cpp.html">Console</a> - is the central widget of the main window, displaying the transmitted or received data. The widget is derived from the QPlainTextEdit class.</li> <li><a href="qtserialport-terminal-settingsdialog-cpp.html">SettingsDialog</a> - is a dialog for configuring the serial port, as well as for displaying the available serial ports and information about them.</li> </ul> <p>The serial port is instantiated in the <a href="qtserialport-terminal-mainwindow-cpp.html">MainWindow</a> constructor. The main widget is passed as the parent, so the object deletion happens automatically according to the parent and child mechanism in Qt:</p> <pre class="cpp"> MainWindow<span class="operator">::</span>MainWindow(<span class="type">QWidget</span> <span class="operator">*</span>parent) : <span class="type">QMainWindow</span>(parent)<span class="operator">,</span> m_ui(<span class="keyword">new</span> Ui<span class="operator">::</span>MainWindow)<span class="operator">,</span> m_status(<span class="keyword">new</span> <span class="type">QLabel</span>)<span class="operator">,</span> m_console(<span class="keyword">new</span> Console)<span class="operator">,</span> m_settings(<span class="keyword">new</span> SettingsDialog)<span class="operator">,</span> m_serial(<span class="keyword">new</span> <span class="type"><a href="qserialport.html">QSerialPort</a></span>(<span class="keyword">this</span>)) { ... m_serial(<span class="keyword">new</span> <span class="type"><a href="qserialport.html">QSerialPort</a></span>(<span class="keyword">this</span>)) </pre> <p>The only <a href="qserialport.html">QSerialPort</a> signal invoked in this example is readyRead(), which shows that new data has been received and hence available:</p> <pre class="cpp"> ... connect(m_serial<span class="operator">,</span> <span class="operator">&</span><span class="type"><a href="qserialport.html">QSerialPort</a></span><span class="operator">::</span>readyRead<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> <span class="operator">&</span>MainWindow<span class="operator">::</span>readData); ... } </pre> <p>Clicking on the <b>Connect</b> button invokes the <code>openSerialPort()</code> slot:</p> <pre class="cpp"> <span class="type">void</span> MainWindow<span class="operator">::</span>openSerialPort() { <span class="keyword">const</span> SettingsDialog<span class="operator">::</span>Settings p <span class="operator">=</span> m_settings<span class="operator">-</span><span class="operator">></span>settings(); m_serial<span class="operator">-</span><span class="operator">></span>setPortName(p<span class="operator">.</span>name); m_serial<span class="operator">-</span><span class="operator">></span>setBaudRate(p<span class="operator">.</span>baudRate); m_serial<span class="operator">-</span><span class="operator">></span>setDataBits(p<span class="operator">.</span>dataBits); m_serial<span class="operator">-</span><span class="operator">></span>setParity(p<span class="operator">.</span>parity); m_serial<span class="operator">-</span><span class="operator">></span>setStopBits(p<span class="operator">.</span>stopBits); m_serial<span class="operator">-</span><span class="operator">></span>setFlowControl(p<span class="operator">.</span>flowControl); <span class="keyword">if</span> (m_serial<span class="operator">-</span><span class="operator">></span>open(<span class="type">QIODevice</span><span class="operator">::</span>ReadWrite)) { m_console<span class="operator">-</span><span class="operator">></span>setEnabled(<span class="keyword">true</span>); m_console<span class="operator">-</span><span class="operator">></span>setLocalEchoEnabled(p<span class="operator">.</span>localEchoEnabled); m_ui<span class="operator">-</span><span class="operator">></span>actionConnect<span class="operator">-</span><span class="operator">></span>setEnabled(<span class="keyword">false</span>); m_ui<span class="operator">-</span><span class="operator">></span>actionDisconnect<span class="operator">-</span><span class="operator">></span>setEnabled(<span class="keyword">true</span>); m_ui<span class="operator">-</span><span class="operator">></span>actionConfigure<span class="operator">-</span><span class="operator">></span>setEnabled(<span class="keyword">false</span>); showStatusMessage(tr(<span class="string">"Connected to %1 : %2, %3, %4, %5, %6"</span>) <span class="operator">.</span>arg(p<span class="operator">.</span>name)<span class="operator">.</span>arg(p<span class="operator">.</span>stringBaudRate)<span class="operator">.</span>arg(p<span class="operator">.</span>stringDataBits) <span class="operator">.</span>arg(p<span class="operator">.</span>stringParity)<span class="operator">.</span>arg(p<span class="operator">.</span>stringStopBits)<span class="operator">.</span>arg(p<span class="operator">.</span>stringFlowControl)); } <span class="keyword">else</span> { <span class="type">QMessageBox</span><span class="operator">::</span>critical(<span class="keyword">this</span><span class="operator">,</span> tr(<span class="string">"Error"</span>)<span class="operator">,</span> m_serial<span class="operator">-</span><span class="operator">></span>errorString()); showStatusMessage(tr(<span class="string">"Open error"</span>)); } } </pre> <p>In this slot, the settings are read from <a href="qtserialport-terminal-settingsdialog-cpp.html">SettingsDialog</a> 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 <a href="qtserialport-terminal-settingsdialog-cpp.html">SettingsDialog</a>, then the terminal attempts to open the port with the default settings: 9600 8N1.</p> <p>Clicking on the <b>Disconnect</b> button invokes the <code>closeSerialPort()</code> slot:</p> <pre class="cpp"> <span class="type">void</span> MainWindow<span class="operator">::</span>closeSerialPort() { <span class="keyword">if</span> (m_serial<span class="operator">-</span><span class="operator">></span>isOpen()) m_serial<span class="operator">-</span><span class="operator">></span>close(); m_console<span class="operator">-</span><span class="operator">></span>setEnabled(<span class="keyword">false</span>); m_ui<span class="operator">-</span><span class="operator">></span>actionConnect<span class="operator">-</span><span class="operator">></span>setEnabled(<span class="keyword">true</span>); m_ui<span class="operator">-</span><span class="operator">></span>actionDisconnect<span class="operator">-</span><span class="operator">></span>setEnabled(<span class="keyword">false</span>); m_ui<span class="operator">-</span><span class="operator">></span>actionConfigure<span class="operator">-</span><span class="operator">></span>setEnabled(<span class="keyword">true</span>); showStatusMessage(tr(<span class="string">"Disconnected"</span>)); } </pre> <p>In this case, handled by the closure of the serial port.</p> <p>Typing characters in the console invokes the <code>writeData()</code> slot:</p> <pre class="cpp"> <span class="type">void</span> MainWindow<span class="operator">::</span>writeData(<span class="keyword">const</span> <span class="type">QByteArray</span> <span class="operator">&</span>data) { m_serial<span class="operator">-</span><span class="operator">></span>write(data); } </pre> <p>This slot sends the characters typed in the given <a href="qtserialport-terminal-console-cpp.html">Console</a> widget to the serial port.</p> <p>When the serial port receives new data, the signal readyRead() is emitted, and that signal is connected to the <code>MainWindow::readData()</code> slot:</p> <pre class="cpp"> <span class="type">void</span> MainWindow<span class="operator">::</span>readData() { <span class="keyword">const</span> <span class="type">QByteArray</span> data <span class="operator">=</span> m_serial<span class="operator">-</span><span class="operator">></span>readAll(); m_console<span class="operator">-</span><span class="operator">></span>putData(data); } </pre> <p>This slot reads the data from the serial port and displays that in the <a href="qtserialport-terminal-console-cpp.html">Console</a> widget.</p> <p>Clicking on the <b>Configure</b> button invokes the <code>show()</code> slot which belongs to the <a href="qtserialport-terminal-settingsdialog-cpp.html">SettingsDialog</a> widget.</p> <p>This method displays the <a href="qtserialport-terminal-settingsdialog-cpp.html">SettingsDialog</a> 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.</p> <a name="running-the-example"></a> <h2 id="running-the-example">Running the Example</h2> <p>To run the example from Qt Creator, open the <b>Welcome</b> mode and select the example from <b>Examples</b>. For more information, visit Building and Running an Example.</p> <p>Files:</p> <ul> <li><a href="qtserialport-terminal-console-cpp.html">terminal/console.cpp</a></li> <li><a href="qtserialport-terminal-console-h.html">terminal/console.h</a></li> <li><a href="qtserialport-terminal-main-cpp.html">terminal/main.cpp</a></li> <li><a href="qtserialport-terminal-mainwindow-cpp.html">terminal/mainwindow.cpp</a></li> <li><a href="qtserialport-terminal-mainwindow-h.html">terminal/mainwindow.h</a></li> <li><a href="qtserialport-terminal-mainwindow-ui.html">terminal/mainwindow.ui</a></li> <li><a href="qtserialport-terminal-settingsdialog-cpp.html">terminal/settingsdialog.cpp</a></li> <li><a href="qtserialport-terminal-settingsdialog-h.html">terminal/settingsdialog.h</a></li> <li><a href="qtserialport-terminal-settingsdialog-ui.html">terminal/settingsdialog.ui</a></li> <li><a href="qtserialport-terminal-terminal-pro.html">terminal/terminal.pro</a></li> <li><a href="qtserialport-terminal-terminal-qrc.html">terminal/terminal.qrc</a></li> </ul> <p>Images:</p> <ul> <li><a href="images/used-in-examples/terminal/images/application-exit.png">terminal/images/application-exit.png</a></li> <li><a href="images/used-in-examples/terminal/images/clear.png">terminal/images/clear.png</a></li> <li><a href="images/used-in-examples/terminal/images/connect.png">terminal/images/connect.png</a></li> <li><a href="images/used-in-examples/terminal/images/disconnect.png">terminal/images/disconnect.png</a></li> <li><a href="images/used-in-examples/terminal/images/settings.png">terminal/images/settings.png</a></li> </ul> </div> <p><b>See also </b><a href="qtserialport-blockingslave-example.html">Blocking Slave Example</a>.</p> <!-- @@@terminal --> </div> </div> </div> </div> </div> <div class="footer"> <p> <acronym title="Copyright">©</acronym> 2019 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners.<br/> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br/> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners. </p> </div> </body> </html>