A terminal emulator widget for Qt 6.
QTermWidget is an open-source project originally based on the KDE4 Konsole application, but it took its own direction later on. The main goal of this project is to provide a Unicode-enabled, embeddable Qt widget for using as a built-in console (or terminal emulation widget).
It is compatible with BSD, Linux and OS X.
This project is licensed under the terms of the GPLv2 or any later version. See the LICENSE file for the full text of the license. Some files are published under compatible licenses:
Files: example/main.cpp
lib/TerminalCharacterDecoder.cpp
lib/TerminalCharacterDecoder.h
lib/kprocess.cpp
lib/kprocess.h
lib/kpty.cpp
lib/kpty.h
lib/kpty_p.h
lib/kptydevice.cpp
lib/kptydevice.h
lib/kptyprocess.cpp
lib/kptyprocess.h
lib/qtermwidget.cpp
lib/qtermwidget.h
lib/qtermwidget_interface.h
Copyright: Author Adriaan de Groot <[email protected]>
2010, KDE e.V <[email protected]>
2002-2007, Oswald Buddenhagen <[email protected]>
2006-2008, Robert Knight <[email protected]>
2002, Waldo Bastian <[email protected]>
2008, e_k <[email protected]>
2022, Francesc Martinez <[email protected]>
License: LGPL-2+
Files: cmake/FindUtf8Proc.cmake
Copyright: 2009-2011, Kitware, Inc
2009-2011, Philip Lowman <[email protected]>
License: BSD-3-clause
The only runtime dependency is qtbase ≥ 6.6.0. Build dependencies are as follows:
- CMake ≥ 3.16.0 serves as the build system and therefore needs to be present to compile.
- lxqt-build-tools ≥ 2.0.0 is also needed for compilation.
- Git is needed to optionally pull latest VCS checkouts.
Code configuration is handled by CMake. CMake variable CMAKE_INSTALL_PREFIX will normally have to be set to /usr, depending on the way library paths are dealt with on 64bit systems. Variables like CMAKE_INSTALL_LIBDIR may have to be set as well.
To build, run make. To install, run make install which accepts variable DESTDIR as usual.
To build PyQt bindings, build this library first, and then invoke sip-wheel in pyqt/ directory. Environment variables CXXFLAGS and LDFLAGS can be used to specify non-installed or non-standard directories for headers and shared libraries, and the built Python wheel can be installed by standard tools like pip. See the CI script for a complete example.
The library is provided by all major Linux distributions. This includes Arch Linux, Debian, Fedora, openSUSE and all of their children, given they use the same package repositories.
Just use the distributions' package managers to search for string qtermwidget.
Translations can be done in LXQt-Weblate
| Type | Variable |
|---|---|
| enum | ScrollBarPosition { NoScrollBar, ScrollBarLeft, ScrollBarRight } |
| enum | KeyboardCursorShape { BlockCursor, UnderlineCursor, IBeamCursor } |
- flowControlEnabled : bool
- getPtySlaveFd : const int
- getShellPID : int
- getForegroundProcessId : int
- getTerminalFont : QFont
- historyLinesCount : int
- icon : const QString
- keyBindings : QString
- screenColumnsCount : int
- selectedText(bool preserveLineBreaks = true) : QString
- sizeHint : const QSize
- terminalSizeHint : bool
- title : const QString
- wordCharacters : QString
- workingDirectory : QString
| Type | Function |
|---|---|
| QTermWidget(int startnow = 1, QWidget *parent = 0) | |
| virtual | ~QTermWidget() |
| void | changeDir(const QString &dir) |
| void | getSelectionEnd(int &row, int &column) |
| void | getSelectionStart(int &row, int &column) |
| void | scrollToEnd() |
| void | sendText(QString &text) |
| void | setArgs(QStringList &args) |
| void | setAutoClose(bool enabled) |
| void | setColorScheme(const QString &name) |
| void | setEnvironment(const QStringList &environment) |
| void | setFlowControlEnabled(bool enabled) |
| void | setFlowControlWarningEnabled(bool enabled) |
| void | setHistorySize(int lines) |
| void | setKeyboardCursorShape(QTermWidget::KeyboardCursorShape shape) |
| void | setMonitorActivity(bool enabled) |
| void | setMonitorSilence(bool enabled) |
| void | setMotionAfterPasting(int action) |
| void | setScrollBarPosition(QTermWidget::ScrollBarPosition pos) |
| void | setSelectionEnd(int row, int column) |
| void | setSelectionStart(int row, int column) |
| void | setShellProgram(const QString &program) |
| void | setSilenceTimeout(int seconds) |
| void | setTerminalFont(QFont &font) |
| void | setTerminalOpacity(qreal level) |
| void | setTerminalSizeHint(bool enabled) |
| void | setWorkingDirectory(const QString &dir) |
| void | startShellProgram() |
| void | startTerminalTeletype() |
| QStringList | availableColorSchemes() |
| Type | Function |
|---|---|
| void | copyClipboard() |
| void | pasteClipboard() |
| void | pasteSelection() |
| void | zoomIn() |
| void | zoomOut() |
| void | setSize(const QSize &) |
| void | setKeyBindings(const QString &kb) |
| void | clear() |
| void | toggleShowSearchBar() |
| Type | Function |
|---|---|
| void | activity() |
| void | bell(const QString &message) |
| void | copyAvailable(bool) |
| void | finished() |
| void | profileChanged(const QString &profile) |
| void | receivedData(const QString &text) |
| void | sendData(const char*, int) |
| void | silence() |
| void | termGetFocus() |
| void | termKeyPressed(QKeyEvent*) |
| void | termLostFocus() |
| void | titleChanged() |
| void | urlActivated(const QUrl &, bool fromContextMenu) |
| Type | Function |
|---|---|
| static QStringList | availableColorSchemes() |
| static QStringList | availableKeyBindings() |
| static void | addCustomColorSchemeDir(const QString &custom_dir) |
| Type | Function |
|---|---|
| virtual void | resizeEvent(QResizeEvent*) |
| Type | Function |
|---|---|
| void | sessionFinished() |
| void | selectionChanged(bool textSelected) |
enum QTermWidget::ScrollBarPosition
This enum describes the location where the scroll bar is positioned in the display widget when calling QTermWidget::setScrollBarPosition().
| Constant | Value | Description |
|---|---|---|
| QTermWidget::NoScrollBar | 0x0 | Do not show the scroll bar. |
| QTermWidget::ScrollBarLeft | 0x1 | Show the scroll bar on the left side of the display. |
| QTermWidget::ScrollBarRight | 0x2 | Show the scroll bar on the right side of the display. |
enum QTermWidget::KeyboardCursorShape
This enum describes the available shapes for the keyboard cursor when calling QTermWidget::setKeyboardCursorShape().
| Constant | Value | Description |
|---|---|---|
| QTermWidget::BlockCursor | 0x0 | A rectangular block which covers the entire area of the cursor character. |
| QTermWidget::UnderlineCursor | 0x1 | A single flat line which occupies the space at the bottom of the cursor character's area. |
| QTermWidget::IBeamCursor | 0x2 | A cursor shaped like the capital letter 'I', similar to the IBeam cursor used in Qt/KDE text editors. |
flowControlEnabled : bool
Returns whether flow control is enabled.
getPtySlaveFd : const int
Returns a pty slave file descriptor. This can be used for display and control a remote terminal.
getForegroundProcessId : int
Returns the PID of the foreground process. This is initially the same as processId() but can change
as the user starts other programs inside the terminal. If there is a problem reading the foreground
process id, 0 will be returned.
historyLinesCount : int
Returns the number of lines in the history buffer.
keyBindings : QString
Returns current key bindings.
selectedText(bool preserveLineBreaks = true) : QString
Returns the currently selected text.
wordCharacters : QString
When selecting text by word, consider these characters to be word characters in addition to
alphanumeric characters, default is :@-./_~.
void changeDir(const QString &dir)
Attempt to change shell directory (Linux only).
void clear()
Clear the terminal content and move to home position.
void copyClipboard()
Copy selection to clipboard.
void pasteClipboard()
Paste clipboard to terminal.
void pasteSelection()
Paste selection to terminal.
void receivedData(const QString &text)
Signals that we received new data from the process running in the terminal emulator.
void scrollToEnd()
Wrapped, scroll to end of text.
void sendData(const char*, int)
Emitted when emulator send data to the terminal process (redirected for external recipient). It can be used for control and display the remote terminal.
void sendText(QString &text)
Send text to terminal.
void setArgs(QStringList &args)
Sets the shell program arguments, default is none.
void setAutoClose(bool enabled)
Automatically close the terminal session after the shell process exits or keep it running.
void setColorScheme(const QString &name)
Sets the color scheme, default is white on black.
void setEnvironment(const QStringList &environment)
Sets environment variables.
void setFlowControlEnabled(bool enabled)
Sets whether flow control is enabled.
void setFlowControlWarningEnabled(bool enabled)
Sets whether the flow control warning box should be shown when the flow control stop key (Ctrl+S) is pressed.
void setHistorySize(int lines)
History size for scrolling.
void setKeyBindings(const QString &kb)
Set named key binding for given widget.
void setKeyboardCursorShape(QTermWidget::KeyboardCursorShape shape)
Sets the shape of the keyboard cursor. This is the cursor drawn at the position in the terminal where keyboard input will appear.
void setScrollBarPosition(QTermWidget::ScrollBarPosition pos)
Sets presence and position of scrollbar.
void setShellProgram(const QString &program)
Sets the shell program, default is /bin/bash.
void setTerminalFont(QFont &font)
Sets terminal font. Default is application font with family Monospace, size 10. Beware of a performance penalty and display/alignment issues when using a proportional font.
void setTerminalSizeHint(bool enabled)
Exposes TerminalDisplay::TerminalSizeHint.
void startShellProgram()
Starts shell program if it was not started in constructor.
void startTerminalTeletype()
Starts terminal teletype as is and redirect data for external recipient. It can be used for display and control a remote terminal.
void zoomIn()
Zooms in on the text.
void zoomOut()
Zooms out in on the text.