ZTerminal¶

ZTerminal represents a connection to a terminal and the terminal scoped state for Tui Widgets.

The terminal connection can be to the terminal the application was run from, an internal offscreen terminal or a terminal specified by the application.

Startup¶

As soon as the message loop runs after creating an instance of ZTerminal, terminal auto detection is started. Also the terminal is setup for operations with Tui Widgets. If a main widget is set when the terminal detection finishes, a terminal change event is delivered to all widgets in the main widgets’ widget tree.

If the terminal detection yields that the terminal is likely not compatible with Tui Widgets the program is terminated by a call to QCoreApplication::quit unless ForceIncompatibleTerminals or incompatibleTerminalDetected() was used.

If terminal auto detection takes too long a message is printed to the terminal. The application can override this message using setAutoDetectTimeoutMessage() or disable it using DisableAutoDetectTimeoutMessage.

Options¶

Most constructors of ZTerminal take an options parameter that allows customizing the terminal’s behavior.

Some of these options only apply to terminals connected directly through a kernel device.

using Tui::ZTerminal::Options = QFlags<Tui::ZTerminal::Option>¶

enum Tui::ZTerminal::Option¶

enumerator AllowInterrupt¶

Don’t disable kernel interpretation of interrupt character for SIGINT (often Ctrl+C).

Normally interpretation of the interrupt character is disabled so it is usable as normal key combination in the application. When this flag is included in a terminal’s options the handling will be left at the setting that was active when starting the terminal connection and likely a SIGINT is delivered when pressing that key.

By default SIGINT will trigger an unclean termination of the application process.

This option is only available for terminals connected directly through a kernel device that is acting as the controlling terminal of the process

enumerator AllowSuspend¶

Don’t disable kernel interpretation of suspend character for SIGTSTP (often Ctrl+Z).

Normally interpretation of the suspend character is disabled so it is usable as normal key combination in the application. When this flag is included in a terminal’s options the handling will be left at the setting that was active when starting the terminal connection and likely a SIGTSTP is delivered when pressing that key.

By default SIGTSTP will trigger the application suspending into the background. The terminal will be restored to the state before the terminal was connected and the application stopped.

When the application is resumed back into the foreground (e.g. by using fg in the shell) the terminal will be reconfigured for usage with ZTerminal and the application resumes when passing through the event loop the next time.

This option is only available for terminals connected directly through a kernel device that is acting as the controlling terminal of the process

enumerator AllowQuit¶

Don’t disable kernel interpretation of quit character for SIGQUIT (often Ctrl+\).

Normally interpretation of the quit character is disabled so it is usable as normal key combination in the application. When this flag is included in a terminal’s options the handling will be left at the setting that was active when starting the terminal connection and likely a SIGQUIT is delivered when pressing that key.

By default SIGQUIT will trigger a unclean termination of the application process.

This option is only available for terminals connected directly through a kernel device that is acting as the controlling terminal of the process

enumerator DisableAutoResize¶

By default ZTerminal reacts to the signal SIGWINCH from the kernel by adjusting the internal representation of the terminal to the new size. If this option is included in the terminal’s options the internal state will not be adjusted.

This option is only available for terminals connected directly through a kernel device and acting as the controlling terminal of the process.

enumerator DisableAlternativeScreen¶

By default ZTerminal switches the terminal to the alternate screen if supported. This means that the application will not overwrite the contents of the terminal and the terminal view will be restored after the instance is destroyed.

If this option is included in the terminal’s options then the terminal will not switch to the alternate screen and the last output of the application will be preserved in the terminal.

enumerator DisableAutoDetectTimeoutMessage¶

By default ZTerminal displays a message if the terminal auto detection takes longer than 10 seconds. See setAutoDetectTimeoutMessage(const QString &message) for details about setting that message.

If this option is included in the terminal’s options then that message will not be generated.

enumerator ForceIncompatibleTerminals¶

If the terminal autodetection result is that the terminal is not compatible with ZTerminal then by default, it will not proceed to initialize the terminal any further. Further by default the application will be terminated with a message. The termination can be prevented by connecting to the signal incompatibleTerminalDetected().

If this option is included in the terminal’s options then this check will be skipped and ZTerminal will try to use the terminal anyway.

enumerator DisableTaggedPaste¶

By default ZTerminal will setup supported terminals to generate Tui::ZPasteEvent events when the user pastes text from the clipboard instead of generating key events.

If this option is included in the terminal’s options then the terminal is left for paste events at the setting it was when the connection was started. Usually this means that pasted text will be received as key events.

enumerator DebugDisableBufferedIo¶: By default ZTerminal uses internal buffering for terminal output and flushes the output buffer after doing a refresh. This option allows disabling this buffering when debugging problems in the low level output handling.

enumerator ConservativeTrueColorOutput¶

By default ZTerminal will send RGB terminal colors used by the application to the terminal as RGB colors when the terminal is likely to support those colors.

If this option is included in the terminal’s options then RGB colors are converted to indexed colors for some terminals where the auto detection did not yield a certain result for RGB color support.

If none of the AllowInterrupt, AllowSuspend and AllowQuit options are active the terminal might be switched into an advanced keyboard mode that supports additional key combinations or keys.

Terminal connection options¶

Default terminal¶

The default constructor and the constructor that only takes an options parameter connect to the terminal the application was run from. It uses the first file descriptor that is a terminal searching stdin, stdout, stderr and the process’ controlling terminal. If no such terminal is found the application is terminated by calling QCoreApplication::quit. The application can avoid termination by using isDefaultTerminalAvailable() to avoid constructing a ZTerminal instance when no terminal is available.

Terminal from file descriptor¶

Using the constructor that takes FileDescriptor as parameter the application can connect the ZTerminal instance to a terminal represented by the given file descriptor. The application has to ensure that the file descriptor actually is a terminal (isatty(3)) and is both readable and writable.

Offscreen terminal¶

Using the constructor that takes OffScreen as parameter the application can create a ZTerminal instance that is not connected to an actual terminal, but instead does not display anything.

This can be useful for example for testing or as null instance when an application that should be runnable without a terminal does not have access to an actual terminal.

Custom terminal connection¶

Using the constructor that takes TerminalConnection as parameter the application can create a ZTerminal instance that uses methods of TerminalConnection and an instance of an application supplied class derived from TerminalConnectionDelegate for all terminal communication.

This can be useful to connect to terminals that are not directly reachable via a kernel terminal device, such as internally implemented ssh connections or other custom transports.

Shutdown¶

The destructor of the terminal instance will restore the terminal to its configuration before ZTerminal started using the terminal. Additionally ZTerminal installs signal handlers to restore the terminal if the application crashes.

If on the other hand the application is using the default terminal connection and the terminal gets disconnected, the application is terminated by calling QCoreApplication::quit, unless the application connects to the terminalConnectionLost() signal.

Main Widget¶

When used with widgets, a terminal instance has one main widget. It can be set by using setMainWidget(ZWidget *w). This main widget is the root of the widget tree that will be connected to the terminal.

When the main widget is initially connected to the terminal (after terminal auto detection and setup) it and all widgets in its widget tree will receive a terminal changed event. After receiving that event the widgets can be used through the terminal connection.

The keyboard focus is a terminal scoped property. But to ease preparing the widget tree before actually connecting it to the terminal when the main widget is set, the newly attached widget tree is scanned for the widget with the most recent call to OtherFocusReason) which is both enabled and visible to take focus.

If a widget is set as main widget of the terminal, its size will be set to the size of the terminal (or its minimum size if that is larger) when the terminal size changes. The main widget will always be placed in the top left corner of the terminal and the position part of the widget’s geometry is ignored.

Viewport¶

If the terminal size is smaller than the minimum size indicated by the main widget, ZTerminal will switch into viewport mode. In viewport mode the application is rendered to a buffer that is larger than the actual terminal size and the terminal will view a selectable part of that buffer.

The minimum size used for this is determined by taking the larger value (in each dimension) of the sizes returned by QSize Tui::ZWidget::minimumSize() const and virtual QSize Tui::ZWidget::minimumSizeHint() const. Some root widgets (like Tui::ZRoot) allow dynamically expanding the minimum size to be large enough to display specially marked windows.

If the viewport mode is active, ZTerminal will display the text “F6 Scroll” in the lower left corner of the terminal. Pressing F6 will switch to viewport scroll mode with the text “←↑→↓ ESC” in the lower left corner. In viewport scroll mode, the part of the application that is visible in the terminal can be adjusted using the arrow keys. Pressing F6 again will send an F6 event to the application and pressing ESC will return to the view port mode. Any other key will be ignored.

Terminal information¶

Certain information about the terminal connected to a ZTerminal instance is available with calling functions on it.

The size of the connected terminal is available from width() const and height() const.

When working with text it is often required to calculate the space used by a string when displayed. Calculations of the used space use a Tui::ZTextMetrics instance. Such an instance is either available from a Tui::ZPainter instance or from the terminal instance using textMetrics() const.

In addition sometimes it is useful to query if the connected terminal has certain capabilities using hasCapability(ZSymbol cap) const.

Configuration¶

Some configuration of the terminal can be changed by methods on the terminal instance.

Terminals usually have a title that is displayed somewhere in the terminal user interface. The functions setTitle(const QString &title) and setIconTitle(const QString &title) can be used to set this text when supported.

Capabilities¶

Terminals can have different capabilities. Some capabilities can be queried after auto detection is completed.

Currently the only queryable capability is extendedCharset. This capability is active for all terminals that are not known to have a severely restricted character set. An example is the linux system terminal that is restricted to 256 or at most 512 characters in the active font.

Behavior¶

If widget tree does not handle Ctrl+L the terminal will handle it by calling forceRepaint() as most TUI applications allow using Ctrl+L to force refresh the terminal if another application or some bug has left the terminal in a garbled state.

On terminal resize (when Tui::ZTerminal::Option::DisableAutoResize is not in effect) the terminal calls forceRepaint() to make sure the resize operation does not result in garbled output.

If the viewport mode is active, F6 followed by arrow keys can be used to move the viewport. See Viewport for behavior details of this mode.

Introspection¶

Sometimes it is desired to read back the actually produced output from the ZTerminal instance. For example for testing of widget or infrastructure code.

For this purpose the functions grabCurrentImage() const, grabCursorColor() const, grabCursorPosition() const, grabCursorStyle() const and grabCursorVisibility() const can be used.

It is possible to get notified after each render cycle by connecting to the afterRendering() signal.

Observing application state¶

Through the ZTerminal instance it is possible to observe events in the running application.

As keyboard focus is a terminal scoped state, the signal focusChanged() can be used to observe the focus moving from one widget to another widget.

The state of resolution if multi key shortcuts can be observed via callbacks registered using ZPendingKeySequenceCallbacks &callbacks).

And the progression through rendering cycles of the application can be monitored using the signals afterRendering() and beforeRendering().

Standalone usage¶

It is also possible (but unusual) to use a ZTerminal instance without widgets. In this case painter() can be used to directly paint on the buffer of the ZTerminal instance and flush this buffer to the connected terminal by using updateOutput() or updateOutputForceFullRepaint().

When not using widgets the cursor attributes, that are usually configured by functions in ZWidget, can be set using setCursorColor(int cursorColorR, int cursorColorG, int cursorColorB), setCursorPosition(QPoint cursorPosition) and setCursorStyle(CursorStyle style).

Pause / Unpause operation¶

It is possible to pause usage of the terminal by a ZTerminal instance by calling pauseOperation(). This restores the terminal mode to the state before ZTerminal started using the terminal and enables using the terminal for running other applications that access the terminal.

If the application wants to return to using the terminal with ZTerminal it should call unpauseOperation().

Layout infrastructure¶

The ZTerminal instance also acts as a central point for coordination of layout updates. Usually applications use the layout infrastructure through interfaces in Tui::ZWidget and Tui::ZLayout (and for testing in Tui::ZTest).

By default, layout work is deferred using the event loop to reduce costly relayout cycles. Tui::ZWidget and Tui::ZLayout register widgets to be relayouted in the next cycle by calling maybeRequestLayout(ZWidget *w) or requestLayout(ZWidget *w).

The function isLayoutPending() const can be used to observe if a layout cycle is pending.

While normally it is sufficient to let ZTerminal schedule the next layout cycle, an application can force running a pending layout cycle immediately by calling doLayout(). When calling this function care should be taken to call it only from code that cannot be itself be triggered by a layout cycle to avoid recursion.

Components that need to cache information scoped to a layout cycle can use currentLayoutGeneration() to get a value that changes for each layout cycle to manage cache invalidation.

ZTerminal¶

class Tui::ZTerminal : public QObject ¶

This class is neither copyable nor movable. It does not define comparison operators.

Constructors

ZTerminal(QObject *parent = nullptr)
ZTerminal(Options options, QObject *parent = nullptr)
ZTerminal(FileDescriptor fd, Options options, QObject *parent = nullptr)
ZTerminal(const OffScreen& offscreen, QObject *parent = nullptr)
ZTerminal(TerminalConnection *connection, Options options, QObject *parent = nullptr)

Functions

QString ZTerminal::autoDetectTimeoutMessage() const
int currentLayoutGeneration()
void dispatchKeyboardEvent(ZKeyEvent &translated)
void dispatchPasteEvent(ZPasteEvent &translated)
void doLayout()
ZWidget *focusWidget() const
void forceRepaint()
ZImage grabCurrentImage() const
std::tuple<int, int, int> grabCursorColor() const
QPoint grabCursorPosition() const
CursorStyle grabCursorStyle() const
bool grabCursorVisibility() const
bool hasCapability(ZSymbol cap) const
int height() const
QString iconTitle() const
ZWidget *keyboardGrabber() const
bool isLayoutPending() const
ZWidget *mainWidget() const
void maybeRequestLayout(ZWidget *w)
ZPainter painter()
bool isPaused() const
void pauseOperation()
void registerPendingKeySequenceCallbacks(const Tui::ZPendingKeySequenceCallbacks &callbacks)
void requestLayout(ZWidget *w)
void resize(int width, int height)
void setAutoDetectTimeoutMessage(const QString &message)
void setCursorColor(int cursorColorR, int cursorColorG, int cursorColorB)
void setCursorPosition(QPoint cursorPosition)
void setCursorStyle(CursorStyle style)
void setIconTitle(const QString &title)
void setMainWidget(ZWidget *w)
void setTitle(const QString &title)
ZTextMetrics textMetrics() const
QString title() const
void unpauseOperation()
void update()
void updateOutput()
void updateOutputForceFullRepaint()
int width() const

Protected Functions

std::unique_ptr<Tui::ZKeyEvent> translateKeyEvent(const Tui::ZTerminalNativeEvent &nativeEvent)

Static Functions

bool isDefaultTerminalAvailable()

Signals

afterRendering()
beforeRendering()
focusChanged()
incompatibleTerminalDetected()
terminalConnectionLost()

Members¶

ZTerminal(QObject *parent = nullptr)¶

Construct an instance connected to the terminal the application was started from.

This forwards to ZTerminal(Options options, QObject *parent = nullptr) with options set to empty.

ZTerminal(Tui::ZTerminal::Options options, QObject *parent = nullptr)¶

Construct an instance connected to the terminal the application was started from.

The instance uses parent as parent. The parent is only used for Qt style automatic deletion and may be nullptr.

See Startup for details on terminal instance startup and Options for details on the supported options.

ZTerminal(FileDescriptor fd, Options options, QObject *parent = nullptr)¶

Construct an instance connected to the terminal specifed in fd. The file descriptor must be opened for reading and writing and must be a kernel terminal device (see isatty(3), e.g. tty or pty).

The class does not take ownership of the file descriptor contained in fd. The application has to ensure that the file descriptor contained in fd is kept open for at least as long as the instance using it exists.

The instance uses parent as parent. The parent is only used for Qt style automatic deletion and may be nullptr.

See Startup for details on terminal instance startup and Options for details on the supported options.

ZTerminal(const OffScreen &offscreen, QObject *parent = nullptr)¶

Construct an instance not connected to a external terminal at all.

Terminal auto detection is skipped. Terminal capabilities will be taken from offscreen.

The instance uses parent as parent. The parent is only used for Qt style automatic deletion and may be nullptr.

ZTerminal(TerminalConnection *connection, Options options, QObject *parent = nullptr)¶

Construct an instance that communicates with the terminal using virtual functions in the delegate passed in using connection and the void Tui::ZTerminal::TerminalConnection::terminalInput(const char *data, int length) function.

Parts of the configuration are taken from the initial settings in connection and from terminal auto detection running over the connection.

ZTerminal does not take ownership of the connection instance. The application has to ensure that the connection instance is kept valid for at least as long as the instance using it exists.

The instance uses parent as parent. The parent is only used for Qt style automatic deletion and may be nullptr.

See Startup for details on terminal instance startup and Options for details on the supported options.

void afterRendering()¶

This signal is emitted after each repaint cycle but before sending the rendered output to the terminal.

This signal is suitable to introspect the rendering result or do last minute modifiations.

void setAutoDetectTimeoutMessage(const QString &message)¶

QString autoDetectTimeoutMessage() const¶

The auto detect timeout message is send to the terminal when autodetection takes a long time.

Auto detection is not automatically aborted after this message is send. Instead the user needs to press a key to terminate auto detection.

void beforeRendering()¶

This signal is emitted just before rendering and layout.

This signal can be used to update display state right before a render cycle is done, when there is not suitable signal or event to trigger updateing.

static bool isDefaultTerminalAvailable()¶: Returns true if connecting to the default terminal is possible. Returns false if the application does not have a terminal connected as standard I/O and does not have a controlling terminal.

bool hasCapability(ZSymbol cap) const¶

Queries if the capability cap is set.

See Capabilities for details and possible values for cap.

int currentLayoutGeneration()¶: The returned value can be used for cache invalidation when caching layout state during a layout cycle.

void setCursorColor(int cursorColorR, int cursorColorG, int cursorColorB)¶

Prefer using void Tui::ZWidget::setCursorColor(int r, int b, int g).

Set the cursor color if the terminal supports cursor color.

Usage of this function and a main widget will interfere. Use this for standalone usage or possibly in code connected to the afterRendering() signal.

void setCursorPosition(QPoint cursorPosition)¶

Prefer using void Tui::ZWidget::showCursor(QPoint position) or void Tui::ZPainter::setCursor(int x, int y).

Set the cursor position.

The special position QPoint{-1, -1} hides the cursor.

Usage of this function and a main widget will interfere. Use this for standalone usage or possibly in code connected to the afterRendering() signal.

void setCursorStyle(CursorStyle style)¶

Prefer using void Tui::ZWidget::setCursorStyle(CursorStyle style).

Set the shape/style of the cursor. See Tui::CursorStyle for possible values.

Usage of this function and a main widget will interfere. Use this for standalone usage or possibly in code connected to the afterRendering() signal.

void dispatchKeyboardEvent(ZKeyEvent &translated)¶

For testing prefer using Tui::ZTest::sendText or Tui::ZTest::sendKey instead.

The function allows injecting a artifical Tui::ZKeyEvent into the application as if it had been send by the terminal.

void dispatchPasteEvent(ZPasteEvent &translated)¶

For testing prefer using Tui::ZTest::sendPaste instead.

The function allows injecting a artifical Tui::ZPasteEvent into the application as if it had been send by the terminal.

void doLayout()¶: Force immediate execution of a pending layout cycle. If no layout cycle is pending this function has no effect.

void focusChanged()¶: This signal is emitted whenever the keyboard focus changes or is lost. The newly focused widget can be retrieved by calling ZWidget *focusWidget() const

ZWidget *focusWidget() const¶: Returns the widget which currently has the keyboard focus or nullptr if no widget has focus.

void forceRepaint()¶: Force a immediate repaint cycle and do a full (non incremental) update of the terminal with rendered result.

ZImage grabCurrentImage() const¶

This introspection function returns the currently buffered ZTerminal side terminal contents.

The application should not call this function while paint events are processed because the returned image might change in future versions.

If the result of the rendering cycle is needed this function can be called from code connected to the afterRendering() signal.

std::tuple<int, int, int> grabCursorColor() const¶: This introspection function returns the current cursor color in the order { red, green, blue}.

QPoint grabCursorPosition() const¶: This introspection function returns the current cursor position.

CursorStyle grabCursorStyle() const¶: This introspection function returns the current cursor style.

bool grabCursorVisibility() const¶: This introspection function returns the current visibility of the cursor.

int height() const¶

This function return the current height of the terminal as seen by ZTerminal.

If Tui::ZTerminal::Option::DisableAutoResize is not in effect the height should match the actual terminal height unless the application has overridden the height using resize(int width, int height). If the terminal connection does not propagate size changes the height might be outdated.

If Tui::ZTerminal::Option::DisableAutoResize is in effect the height returned is either the initial size of the terminal or the height of the last call to resize(int width, int height).

void setTitle(const QString &title)¶

QString title() const¶

void setIconTitle(const QString &title)¶

QString iconTitle() const¶

Most terminals display a title in some place. These functions allow managing the title. The title will only be used on terminals that are capable to restore the previous title on clean up.

Some terminals actually manage 2 titles. The icon title is usually shown for iconified form of the terminal window and in window choosers / taskbars. The normal title is usually shown for the currently active terminal in the window title.

void incompatibleTerminalDetected()¶

This signal is emitted when a incompatible terminal is detected.

If Tui::ZTerminal::Option::ForceIncompatibleTerminals is not in effect and this signal is not connected ZTerminal will output an error message and the application will be terminated using QCoreApplication::quit. If the signal is connected the terminal will still not be initialized but the application is free to handle the problem in another way like displaying a custom error message or proceeding without using Tui Widgets.

If Tui::ZTerminal::Option::ForceIncompatibleTerminals is in effect even incomaptible terminals are initialized on a best effort basis and the signal will be emitted after setup of the terminal completes.

ZWidget *keyboardGrabber() const¶

Returns the current widget that has grabbed the keyboard if any.

Widgets can grab the keyboard using void Tui::ZWidget::grabKeyboard().

void setMainWidget(ZWidget *w)¶

ZWidget *mainWidget() const¶

The main window is the root of the widget tree connected to this ZTerminal instance.

For details see Main Widget.

If a new main widget is set, various widget related state in the ZTerminal instance is cleared (e.g. focus, keyboard grab, pending layouting).

The geometry of the main widget overwritten by the terminal size in most cases. The size of the main widget can be influenced by setting the widget’s minimum size. The position of the widget’s geometry is ignored and the widget is always placed in the top-left corner of the terminal.

ZPainter painter()¶

Returns a painter that allows modifying the the ZTerminal side terminal buffer directly.

Usage of this function and a main widget will interfere. Use this for standalone usage or possibly in code connected to the afterRendering() signal.

bool isPaused() const¶

void pauseOperation()¶

void unpauseOperation()¶

These functions manage pausing terminal operation. It is safe to call these functions repeatedly, but calls are not counted so for example one call to unpauseOperation will undo the effect of multiple calls to pauseOperation.

See Pause / Unpause operation for details.

void registerPendingKeySequenceCallbacks(const Tui::ZPendingKeySequenceCallbacks &callbacks)¶

The ZPendingKeySequenceCallbacks allows monitoring in progress multi step shortcuts.

See Tui::ZPendingKeySequenceCallbacks for details.

bool isLayoutPending() const¶

void requestLayout(ZWidget *w)¶

void maybeRequestLayout(ZWidget *w)¶: These functions can be used to manage layout cycles. They are mostly used by Tui::ZLayout, but could be used to in implementations of other layout systems too.

void resize(int width, int height)¶: Clears and resizes the ZTerminal side terminal buffer. The ZTerminal side terminal buffer should be sized to match the size of the actual terminal and many parts of Tui Widgets assume that this holds true.

void terminalConnectionLost()¶

This signal is emitted if the connection to the default terminal or a terminal connected through ZTerminal(FileDescriptor fd, Options options, QObject *parent = nullptr) is lost.

After this signal is emitted ZTerminal will no longer be able to do any updates or receive input from the formerly connected terminal.

If the signal is not connected ZTerminal will terminate the application using QCoreApplication::quit instead.

ZTextMetrics textMetrics() const¶

Returns a ZTextMetrics instance that describes how text is assigned to cells in the connected terminal.

The result should only be used after auto detection is completed.

void update()¶

Request an rendering cycle to be done soon. The update will be processed using an event with low priority or a timer.

Nested Types¶

struct Tui::ZTerminal::FileDescriptor¶

This struct is a wrapper for type safe passing of a file descriptor.

explicit FileDescriptor(int fd)¶: Construct an instance with fd as file descriptor. The class does not take ownership of fd. The application has to ensure that fd is kept open for at least as long as a Tui::ZTerminal instance using it exists.

struct Tui::ZTerminal::OffScreen¶

This class is copyable and assignable.

This class is used to configure details of the offscreen mode of Tui::ZTerminal.

OffScreen(int width, int height)¶: Construct offscreen configuration with requested width width and requested height height.

OffScreen withCapability(ZSymbol capability)¶

Returns a modified OffScreen object that requests that capability be enabled in the terminal instance.

Unknown capabilities are ignored.

See Capabilities for possible capabilities.

OffScreen withoutCapability(ZSymbol capability)¶

Returns a modified OffScreen object that requests that capability be disabled in the terminal instance.

Unknown capabilities are ignored.

See Capabilities for possible capabilities.

struct Tui::ZTerminal::TerminalConnection¶

This class represents an application defined connection to a terminal.

The application need to setup the class using void setDelegate(TerminalConnectionDelegate *delegate), void setBackspaceIsX08(bool val) and void setSize(int width, int height) before passing the instance to the Tui::ZTerminal constructor.

After connnecting a Tui::ZTerminal instance the application must supply terminal input by calling void terminalInput(const char *data, int length) and may change the terminal size by calling void setSize(int width, int height).

The application has to ensure that the instance is kept valid for at least as long as the terminal instance using it exists. One instance of this class can not be used with multiple terminal instances at the same time.

void terminalInput(const char *data, int length)¶

The application uses this function to transmit terminal input to the terminal instance connected to this instance.

It is an error to call this method while this instance is not connected to a terminal instance.

The input of length length is passed in the data parameter.

void setDelegate(TerminalConnectionDelegate *delegate)¶

The application must use this function to set an delegate object delegate for the terminal connection before connecting the instance to a terminal instance.

It is an error to connect this instance to a terminal instance without having set a valid delegate.

void setBackspaceIsX08(bool val)¶

Set how the backspace key is send by the terminal. if val is true, the terminal is expected to send a 0x08 character for backspace. if val is false, the terminal is expected to send a 0x7f character for backspace.

If the terminal connection originates from a kernel terminal device val should be the true if the terminal is setup with termios.c_cc[VERASE] == 0x08.

The application should call this function before connecting the instance to a terminal instance, changes after connecting the terminal are ignored.

void setSize(int width, int height)¶

Set the terminal size to width width and height height.

The application should call this function before connecting the instance to a terminal instance and for each terminal size change after the initial call.

class Tui::ZTerminal::TerminalConnectionDelegate¶

This class acts as a delegate class for an application definied connection to a terminal.

The application has to implement a derived class that implements all pure virtual functions for communication to the terminal.

void write(const char *data, int length)¶

The terminal instance calls this function to write length bytes starting at data to the terminal.

The delegate must either send these bytes to the terminal or buffer them for later delivery.

void flush()¶

The terminal instance calls this function when the bytes send via void write(const char *data, int length) have to be delivered to the terminal.

It will be called when all terminal output for a given refresh or action is completed.

void restoreSequenceUpdated(const char *data, int len)¶

The terminal instance calls this function whenever the sequence of bytes that need to be output to the terminal on unclean connection shutdown are changed.

The delegate should save the length bytes starting at data for this purpose.

If possible the delegate should arrange for these bytes to be send to the terminal even if the process shuts down uncleanly. For example in a client/server setup where a client forwards a terminal connection and the server is running the Tui Widgets application is would be good to move the restore sequence to the client.

If the terminal instance is destroyed cleanly (i.e. the destructor of ZTerminal is run) this sequence should not be sent to the terminal, as the clean shutdown already handles this.

void deinit(bool awaitingResponse)¶

The terminal instance calls this function on clean shutdown.

if awaitingResponse is set the terminal will likely still send replies to query sequences sent by the ZTerminal instance. The delegate might try catch these replies by reading and discarding all terminal input for a limited time.

void pause()¶: The terminal instance calls this function whenever void Tui::ZTerminal::pauseOperation() is called.

void unpause()¶: The terminal instance calls this function whenever void Tui::ZTerminal::unpauseOperation() is called.

ZTerminal¶

Startup¶

Options¶

Terminal connection options¶

Default terminal¶

Terminal from file descriptor¶

Offscreen terminal¶

Custom terminal connection¶

Shutdown¶

Main Widget¶

Viewport¶

Terminal information¶

Configuration¶

Capabilities¶

Behavior¶

Introspection¶

Observing application state¶

Standalone usage¶

Pause / Unpause operation¶

Layout infrastructure¶

ZTerminal¶

Members¶

Nested Types¶

Tui Widgets

Navigation

Related Topics