| 1 | # QTermWidget |
|---|
| 2 | |
|---|
| 3 | ## Overview |
|---|
| 4 | |
|---|
| 5 | A terminal emulator widget for Qt 5. |
|---|
| 6 | |
|---|
| 7 | QTermWidget is an open-source project originally based on the KDE4 Konsole application, but it took its own direction later on. |
|---|
| 8 | 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). |
|---|
| 9 | |
|---|
| 10 | It is compatible with BSD, Linux and OS X. |
|---|
| 11 | |
|---|
| 12 | This project is licensed under the terms of the [GPLv2](https://www.gnu.org/licenses/gpl-2.0.en.html) or any later version. See the LICENSE file for the full text of the license. Some files are published under compatible licenses: |
|---|
| 13 | ``` |
|---|
| 14 | Files: example/main.cpp |
|---|
| 15 | lib/TerminalCharacterDecoder.cpp |
|---|
| 16 | lib/TerminalCharacterDecoder.h |
|---|
| 17 | lib/kprocess.cpp |
|---|
| 18 | lib/kprocess.h |
|---|
| 19 | lib/kpty.cpp |
|---|
| 20 | lib/kpty.h |
|---|
| 21 | lib/kpty_p.h |
|---|
| 22 | lib/kptydevice.cpp |
|---|
| 23 | lib/kptydevice.h |
|---|
| 24 | lib/kptyprocess.cpp |
|---|
| 25 | lib/kptyprocess.h |
|---|
| 26 | lib/qtermwidget.cpp |
|---|
| 27 | lib/qtermwidget.h |
|---|
| 28 | lib/qtermwidget_interface.h |
|---|
| 29 | Copyright: Author Adriaan de Groot <groot@kde.org> |
|---|
| 30 | 2010, KDE e.V <kde-ev-board@kde.org> |
|---|
| 31 | 2002-2007, Oswald Buddenhagen <ossi@kde.org> |
|---|
| 32 | 2006-2008, Robert Knight <robertknight@gmail.com> |
|---|
| 33 | 2002, Waldo Bastian <bastian@kde.org> |
|---|
| 34 | 2008, e_k <e_k@users.sourceforge.net> |
|---|
| 35 | 2022, Francesc Martinez <info@francescmm.com> |
|---|
| 36 | License: LGPL-2+ |
|---|
| 37 | |
|---|
| 38 | Files: cmake/FindUtf8Proc.cmake |
|---|
| 39 | Copyright: 2009-2011, Kitware, Inc |
|---|
| 40 | 2009-2011, Philip Lowman <philip@yhbt.com> |
|---|
| 41 | License: BSD-3-clause |
|---|
| 42 | ``` |
|---|
| 43 | |
|---|
| 44 | ## Installation |
|---|
| 45 | |
|---|
| 46 | ### Compiling sources |
|---|
| 47 | |
|---|
| 48 | The only runtime dependency is qtbase ≥ 5.12.0. |
|---|
| 49 | Build dependencies are as follows: |
|---|
| 50 | - CMake ≥ 3.1.0 serves as the build system and therefore needs to be present to compile. |
|---|
| 51 | - The latest [lxqt-build-tools](https://github.com/lxqt/lxqt-build-tools/) is also needed for compilation. |
|---|
| 52 | - Git is needed to optionally pull latest VCS checkouts. |
|---|
| 53 | |
|---|
| 54 | 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. |
|---|
| 55 | |
|---|
| 56 | To build, run `make`. To install, run `make install` which accepts variable `DESTDIR` as usual. |
|---|
| 57 | |
|---|
| 58 | 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](.ci/build.sh) for a complete example. |
|---|
| 59 | |
|---|
| 60 | ### Binary packages |
|---|
| 61 | |
|---|
| 62 | 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. |
|---|
| 63 | Just use the distributions' package managers to search for string `qtermwidget`. |
|---|
| 64 | |
|---|
| 65 | |
|---|
| 66 | ### Translation |
|---|
| 67 | |
|---|
| 68 | Translations can be done in [LXQt-Weblate](https://translate.lxqt-project.org/projects/lxqt-desktop/qtermwidget/) |
|---|
| 69 | |
|---|
| 70 | <a href="https://translate.lxqt-project.org/projects/lxqt-desktop/qtermwidget/"> |
|---|
| 71 | <img src="https://translate.lxqt-project.org/widgets/lxqt-desktop/-/qtermwidget/multi-auto.svg" alt="Translation status" /> |
|---|
| 72 | </a> |
|---|
| 73 | |
|---|
| 74 | ## API |
|---|
| 75 | ### Public Types |
|---|
| 76 | Type | Variable |
|---|
| 77 | | ---: | :--- |
|---|
| 78 | enum | ScrollBarPosition { NoScrollBar, ScrollBarLeft, ScrollBarRight } |
|---|
| 79 | enum | KeyboardCursorShape { BlockCursor, UnderlineCursor, IBeamCursor } |
|---|
| 80 | |
|---|
| 81 | ### Properties |
|---|
| 82 | * flowControlEnabled : bool |
|---|
| 83 | * getPtySlaveFd : const int |
|---|
| 84 | * getShellPID : int |
|---|
| 85 | * getForegroundProcessId : int |
|---|
| 86 | * getTerminalFont : QFont |
|---|
| 87 | * historyLinesCount : int |
|---|
| 88 | * icon : const QString |
|---|
| 89 | * keyBindings : QString |
|---|
| 90 | * screenColumnsCount : int |
|---|
| 91 | * selectedText(bool _preserveLineBreaks_ = true) : QString |
|---|
| 92 | * sizeHint : const QSize |
|---|
| 93 | * terminalSizeHint : bool |
|---|
| 94 | * title : const QString |
|---|
| 95 | * workingDirectory : QString |
|---|
| 96 | |
|---|
| 97 | ### Public Functions |
|---|
| 98 | Type | Function |
|---|
| 99 | | ---: | :--- |
|---|
| 100 | | | QTermWidget(int _startnow_ = 1, QWidget *_parent_ = 0) |
|---|
| 101 | virtual | ~QTermWidget() |
|---|
| 102 | void | changeDir(const QString _&dir_) |
|---|
| 103 | void | getSelectionEnd(int &_row_, int &_column_) |
|---|
| 104 | void | getSelectionStart(int &_row_, int &_column_) |
|---|
| 105 | void | scrollToEnd() |
|---|
| 106 | void | sendText(QString &_text_) |
|---|
| 107 | void | setArgs(QStringList &_args_) |
|---|
| 108 | void | setAutoClose(bool _enabled_) |
|---|
| 109 | void | setColorScheme(const QString &_name_) |
|---|
| 110 | void | setEnvironment(const QStringList &_environment_) |
|---|
| 111 | void | setFlowControlEnabled(bool _enabled_) |
|---|
| 112 | void | setFlowControlWarningEnabled(bool _enabled_) |
|---|
| 113 | void | setHistorySize(int _lines_) |
|---|
| 114 | void | setKeyboardCursorShape(QTermWidget::KeyboardCursorShape _shape_) |
|---|
| 115 | void | setMonitorActivity(bool _enabled_) |
|---|
| 116 | void | setMonitorSilence(bool _enabled_) |
|---|
| 117 | void | setMotionAfterPasting(int _action_) |
|---|
| 118 | void | setScrollBarPosition(QTermWidget::ScrollBarPosition _pos_) |
|---|
| 119 | void | setSelectionEnd(int _row_, int _column_) |
|---|
| 120 | void | setSelectionStart(int _row_, int _column_) |
|---|
| 121 | void | setShellProgram(const QString &_program_) |
|---|
| 122 | void | setSilenceTimeout(int _seconds_) |
|---|
| 123 | void | setTerminalFont(QFont &_font_) |
|---|
| 124 | void | setTerminalOpacity(qreal _level_) |
|---|
| 125 | void | setTerminalSizeHint(bool _enabled_) |
|---|
| 126 | void | setTextCodec(QTextCodec *_codec_) |
|---|
| 127 | void | setWorkingDirectory(const QString &_dir_) |
|---|
| 128 | void | startShellProgram() |
|---|
| 129 | void | startTerminalTeletype() |
|---|
| 130 | QStringList | availableColorSchemes() |
|---|
| 131 | |
|---|
| 132 | ### Public Slots |
|---|
| 133 | Type | Function |
|---|
| 134 | | ---: | :--- |
|---|
| 135 | void | copyClipboard() |
|---|
| 136 | void | pasteClipboard() |
|---|
| 137 | void | pasteSelection() |
|---|
| 138 | void | zoomIn() |
|---|
| 139 | void | zoomOut() |
|---|
| 140 | void | setSize(_const QSize &_) |
|---|
| 141 | void | setKeyBindings(const QString &_kb_) |
|---|
| 142 | void | clear() |
|---|
| 143 | void | toggleShowSearchBar() |
|---|
| 144 | |
|---|
| 145 | ### Signals |
|---|
| 146 | Type | Function |
|---|
| 147 | | ---: | :--- |
|---|
| 148 | void | activity() |
|---|
| 149 | void | bell(const QString &_message_) |
|---|
| 150 | void | copyAvailable(bool) |
|---|
| 151 | void | finished() |
|---|
| 152 | void | profileChanged(const QString &_profile_) |
|---|
| 153 | void | receivedData(const QString &_text_) |
|---|
| 154 | void | sendData(const char*, int) |
|---|
| 155 | void | silence() |
|---|
| 156 | void | termGetFocus() |
|---|
| 157 | void | termKeyPressed(QKeyEvent*) |
|---|
| 158 | void | termLostFocus() |
|---|
| 159 | void | titleChanged() |
|---|
| 160 | void | urlActivated(const QUrl &, bool _fromContextMenu_) |
|---|
| 161 | |
|---|
| 162 | ### Static Public Members |
|---|
| 163 | Type | Function |
|---|
| 164 | | ---: | :--- |
|---|
| 165 | static QStringList | availableColorSchemes() |
|---|
| 166 | static QStringList | availableKeyBindings() |
|---|
| 167 | static void | addCustomColorSchemeDir(const QString &*custom_dir*) |
|---|
| 168 | |
|---|
| 169 | ### Protected Functions |
|---|
| 170 | Type | Function |
|---|
| 171 | | ---: | :--- |
|---|
| 172 | virtual void | resizeEvent(_QResizeEvent_*) |
|---|
| 173 | |
|---|
| 174 | ### Protected Slots |
|---|
| 175 | Type | Function |
|---|
| 176 | | ---: | :--- |
|---|
| 177 | void | sessionFinished() |
|---|
| 178 | void | selectionChanged(bool _textSelected_) |
|---|
| 179 | |
|---|
| 180 | ### Member Type Documentation |
|---|
| 181 | **enum QTermWidget::ScrollBarPosition**\ |
|---|
| 182 | This enum describes the location where the scroll bar is positioned in the display widget when calling QTermWidget::setScrollBarPosition(). |
|---|
| 183 | |
|---|
| 184 | Constant | Value | Description |
|---|
| 185 | | --- | :---: | --- | |
|---|
| 186 | QTermWidget::NoScrollBar | 0x0 | Do not show the scroll bar. |
|---|
| 187 | QTermWidget::ScrollBarLeft | 0x1 | Show the scroll bar on the left side of the display. |
|---|
| 188 | QTermWidget::ScrollBarRight | 0x2 | Show the scroll bar on the right side of the display. |
|---|
| 189 | |
|---|
| 190 | \ |
|---|
| 191 | **enum QTermWidget::KeyboardCursorShape**\ |
|---|
| 192 | This enum describes the available shapes for the keyboard cursor when calling QTermWidget::setKeyboardCursorShape(). |
|---|
| 193 | |
|---|
| 194 | Constant | Value | Description |
|---|
| 195 | | --- | :---: | --- | |
|---|
| 196 | QTermWidget::BlockCursor | 0x0 | A rectangular block which covers the entire area of the cursor character. |
|---|
| 197 | QTermWidget::UnderlineCursor | 0x1 | A single flat line which occupies the space at the bottom of the cursor character's area. |
|---|
| 198 | QTermWidget::IBeamCursor | 0x2 | A cursor shaped like the capital letter 'I', similar to the IBeam cursor used in Qt/KDE text editors. |
|---|
| 199 | |
|---|
| 200 | ### Property Documentation |
|---|
| 201 | **flowControlEnabled : bool**\ |
|---|
| 202 | Returns whether flow control is enabled. |
|---|
| 203 | |
|---|
| 204 | **getPtySlaveFd : const int**\ |
|---|
| 205 | Returns a pty slave file descriptor. This can be used for display and control a remote terminal. |
|---|
| 206 | |
|---|
| 207 | <!--**getShellPID : int**\--> |
|---|
| 208 | **getForegroundProcessId : int**\ |
|---|
| 209 | Returns the PID of the foreground process. This is initially the same as processId() but can change |
|---|
| 210 | as the user starts other programs inside the terminal. If there is a problem reading the foreground |
|---|
| 211 | process id, 0 will be returned. |
|---|
| 212 | |
|---|
| 213 | <!--**getTerminalFont : QFont**\--> |
|---|
| 214 | |
|---|
| 215 | **historyLinesCount : int**\ |
|---|
| 216 | Returns the number of lines in the history buffer. |
|---|
| 217 | |
|---|
| 218 | <!--**icon : const QString**\--> |
|---|
| 219 | |
|---|
| 220 | **keyBindings : QString**\ |
|---|
| 221 | Returns current key bindings. |
|---|
| 222 | |
|---|
| 223 | <!--**screenColumnsCount : int**\--> |
|---|
| 224 | |
|---|
| 225 | **selectedText(bool _preserveLineBreaks_ = true) : QString**\ |
|---|
| 226 | Returns the currently selected text. |
|---|
| 227 | |
|---|
| 228 | <!--**sizeHint : const QSize**\--> |
|---|
| 229 | <!--**terminalSizeHint : bool**\--> |
|---|
| 230 | <!--**title : const QString**\--> |
|---|
| 231 | <!--**workingDirectory : QString**\--> |
|---|
| 232 | |
|---|
| 233 | ### Member Function Documentation |
|---|
| 234 | <!--__void activity()__\--> |
|---|
| 235 | <!--__void bell(const QString &_message_)__\--> |
|---|
| 236 | |
|---|
| 237 | __void changeDir(const QString _&dir_)__\ |
|---|
| 238 | Attempt to change shell directory (Linux only). |
|---|
| 239 | |
|---|
| 240 | __void clear()__\ |
|---|
| 241 | Clear the terminal content and move to home position. |
|---|
| 242 | |
|---|
| 243 | <!--__void copyAvailable(bool)__\--> |
|---|
| 244 | |
|---|
| 245 | __void copyClipboard()__\ |
|---|
| 246 | Copy selection to clipboard. |
|---|
| 247 | |
|---|
| 248 | <!--__void finished()__\--> |
|---|
| 249 | <!--__void getSelectionEnd(int &_row_, int &_column_)__\--> |
|---|
| 250 | <!--__void getSelectionStart(int &_row_, int &_column_)__\--> |
|---|
| 251 | |
|---|
| 252 | __void pasteClipboard()__\ |
|---|
| 253 | Paste clipboard to terminal. |
|---|
| 254 | |
|---|
| 255 | __void pasteSelection()__\ |
|---|
| 256 | Paste selection to terminal. |
|---|
| 257 | |
|---|
| 258 | <!--__void profileChanged(const QString &_profile_)__\--> |
|---|
| 259 | |
|---|
| 260 | __void receivedData(const QString &_text_)__\ |
|---|
| 261 | Signals that we received new data from the process running in the terminal emulator. |
|---|
| 262 | |
|---|
| 263 | __void scrollToEnd()__\ |
|---|
| 264 | Wrapped, scroll to end of text. |
|---|
| 265 | |
|---|
| 266 | __void sendData(const char*, int)__\ |
|---|
| 267 | Emitted when emulator send data to the terminal process (redirected for external recipient). It can be used for control and display the remote terminal. |
|---|
| 268 | |
|---|
| 269 | __void sendText(QString &_text_)__\ |
|---|
| 270 | Send text to terminal. |
|---|
| 271 | |
|---|
| 272 | __void setArgs(QStringList &_args_)__\ |
|---|
| 273 | Sets the shell program arguments, default is none. |
|---|
| 274 | |
|---|
| 275 | __void setAutoClose(bool _enabled_)__\ |
|---|
| 276 | Automatically close the terminal session after the shell process exits or keep it running. |
|---|
| 277 | |
|---|
| 278 | __void setColorScheme(const QString &_name_)__\ |
|---|
| 279 | Sets the color scheme, default is white on black. |
|---|
| 280 | |
|---|
| 281 | __void setEnvironment(const QStringList &_environment_)__\ |
|---|
| 282 | Sets environment variables. |
|---|
| 283 | |
|---|
| 284 | __void setFlowControlEnabled(bool _enabled_)__\ |
|---|
| 285 | Sets whether flow control is enabled. |
|---|
| 286 | |
|---|
| 287 | __void setFlowControlWarningEnabled(bool _enabled_)__\ |
|---|
| 288 | Sets whether the flow control warning box should be shown when the flow control stop key (Ctrl+S) is pressed. |
|---|
| 289 | |
|---|
| 290 | __void setHistorySize(int _lines_)__\ |
|---|
| 291 | History size for scrolling. |
|---|
| 292 | |
|---|
| 293 | __void setKeyBindings(const QString &_kb_)__\ |
|---|
| 294 | Set named key binding for given widget. |
|---|
| 295 | |
|---|
| 296 | __void setKeyboardCursorShape(QTermWidget::KeyboardCursorShape _shape_)__\ |
|---|
| 297 | Sets the shape of the keyboard cursor. This is the cursor drawn at the position in the terminal where keyboard input will appear. |
|---|
| 298 | |
|---|
| 299 | <!--__void setMonitorActivity(bool _enabled_)__\--> |
|---|
| 300 | <!--__void setMonitorSilence(bool _enabled_)__\--> |
|---|
| 301 | <!--__void setMotionAfterPasting(int _action_)__\--> |
|---|
| 302 | |
|---|
| 303 | __void setScrollBarPosition(QTermWidget::ScrollBarPosition _pos_)__\ |
|---|
| 304 | Sets presence and position of scrollbar. |
|---|
| 305 | |
|---|
| 306 | <!--__void setSelectionEnd(int _row_, int _column_)__\--> |
|---|
| 307 | <!--__void setSelectionStart(int _row_, int _column_)__\--> |
|---|
| 308 | |
|---|
| 309 | __void setShellProgram(const QString &_program_)__\ |
|---|
| 310 | Sets the shell program, default is /bin/bash. |
|---|
| 311 | |
|---|
| 312 | <!--__void setSilenceTimeout(int _seconds_)__\--> |
|---|
| 313 | <!--__void setSize(_const QSize &_)__\--> |
|---|
| 314 | |
|---|
| 315 | __void setTerminalFont(QFont &_font_)__\ |
|---|
| 316 | 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. |
|---|
| 317 | |
|---|
| 318 | <!--__void setTerminalOpacity(qreal _level_)__\--> |
|---|
| 319 | |
|---|
| 320 | __void setTerminalSizeHint(bool _enabled_)__\ |
|---|
| 321 | Exposes TerminalDisplay::TerminalSizeHint. |
|---|
| 322 | |
|---|
| 323 | __void setTextCodec(QTextCodec *_codec_)__\ |
|---|
| 324 | Sets text codec, default is UTF-8. |
|---|
| 325 | |
|---|
| 326 | <!--__void setWorkingDirectory(const QString &_dir_)__\--> |
|---|
| 327 | <!--__void silence()__\--> |
|---|
| 328 | |
|---|
| 329 | __void startShellProgram()__\ |
|---|
| 330 | Starts shell program if it was not started in constructor. |
|---|
| 331 | |
|---|
| 332 | __void startTerminalTeletype()__\ |
|---|
| 333 | Starts terminal teletype as is and redirect data for external recipient. It can be used for display and control a remote terminal. |
|---|
| 334 | |
|---|
| 335 | <!--__void termGetFocus()__\--> |
|---|
| 336 | <!--__void termKeyPressed(QKeyEvent*)__\--> |
|---|
| 337 | <!--__void termLostFocus()__\--> |
|---|
| 338 | <!--__void titleChanged()__\--> |
|---|
| 339 | <!--__void toggleShowSearchBar()__\--> |
|---|
| 340 | <!--__void urlActivated(const QUrl &, bool _fromContextMenu_)__\--> |
|---|
| 341 | |
|---|
| 342 | __void zoomIn()__\ |
|---|
| 343 | Zooms in on the text. |
|---|
| 344 | |
|---|
| 345 | __void zoomOut()__\ |
|---|
| 346 | Zooms out in on the text. |
|---|
