ZTextEdit¶

multi line text edit¶
in focused state¶
in focused state with selection¶
in disabled state¶
in un-focused state with selection¶

ZInputBox is a multi-line text input widget. If the input text is longer than the height of the widget or wider, it supports scrolling the text so the currently edited portion of the text is visible.

The text in the text edit can come either from a internally managed instance of Tui::ZDocument or from a externally managed Tui::ZDocument instance. An externally managed document can be shared by multiple text edit widgets, in that case each widget has an independent cursor, selection and scroll position.

For details about how positions and selections work see Using cursors.

Example¶

Tui::ZTextEdit *text = new Tui::ZTextEdit(dialog->terminal()->textMetrics(), dialog);
text->setMinimumSize(10, 4);
layout->addWidget(text);

Keyboard Usage¶

Key	Result
(text input) ^(r)	Insert text at cursor position. If there is a current selection, the selected text is deleted before inserting the new text.
`Enter` ^(r)	Insert a line break. If there is a current selection, the selected text is deleted before the line break is added.
`Backspace` ^(r)	Remove one letter/character before the cursor position. If there is a current selection, the selected text is deleted instead.
`Delete` ^(r)	Remove one letter/character after the cursor position. If there is a current selection, the selected text is deleted instead.
`Ctrl+Backspace` ^(r)	Remove one word before the cursor position. If there is a current selection, the selected text is deleted instead.
`Ctrl+Delete` ^(r)	Remove one word after the cursor position. If there is a current selection, the selected text is deleted instead.
`Tab` ^(r)	Without selection inserts a tab at the current cursor position. The width and type (using \t or spaces) is configurable. With a selection indents the selected lines.
`Shift+Tab` ^(r)	With a selection dedents the selected lines.
`Insert` ^(r)	Toggle overwrite mode.
`Ctrl+C` `Ctrl+Insert`	Copies the current selection to the clipboard.
`Ctrl+V` ^(r) `Shift+Insert` ^(r)	Inserts the current clipboard content at the cursor position. If there is a current selection, the selected text is deleted before inserting the new text.
`Ctrl+X` ^(r) `Shift+Delete` ^(r)	Copies the selected text to the clipboard and removes it.
`←`	Move cursor position one letter/character to the left. ^(s)
`→`	Move cursor position one letter/character to the right. ^(s)
`↓`	Move the cursor one visual line down. ^(s)
`↑`	Move the cursor one visual line up. ^(s)
`Home`	Move cursor position to the start of the current line. ^(s)
`End`	Move cursor position to the position just after the end of the current line. ^(s)
`Ctrl+←`	Move cursor position one word to the left. ^(s)
`Ctrl+→`	Move cursor position one word to the right. ^(s)
`Ctrl+Home`	Move cursor position to the start of the text. ^(s)
`Ctrl+End`	Move cursor position to the end of the text. ^(s)
`Page Up`	Move cursor position one page up. ^(s)
`Page Down`	Move cursor position one page down. ^(s)
`Ctrl+A`	Selects the whole text.
`F4`	Toggles select mode. In select mode the selection is extended without the need to hold down `Shift`. This can be helpful with terminals that don’t report some key combinations with `Shift`.
`Ctrl+Z` ^(r)(u)	Undo the previous edit step.
`Ctrl+Y` ^(r)(u)	Redo the previous edit step.

(r) Read-only mode will disable this key.
(s) With Shift or when select mode is active, extends the selection.
(u) If isUndoRedoEnabled is set to false this key will be disabled.

Behavior¶

Text edit widgets by default accept focus, don’t have a minimum size and have a expanding vertical and horizontal layout policy. The size request of the widget is 0x0.

The user can edit the text by using the keys described in the keyboard usage section. Additionally the input box accepts text pasted into the terminal and inserts it at the cursor position. It emits signals when the cursor or scroll position changes.

Unless in detached scrolling mode, the text is always scrolled so that the cursor position is visible.

Palette¶

Palette Color	Usage
`textedit.fg`, `textedit.bg`	Body of the text edit widget (active, unfocused)
`textedit.disabled.fg`, `textedit.disabled.bg`	Body of the text edit widget (disabled)
`textedit.focused.fg`, `textedit.focused.bg`	Body of the text edit widget (active, focused)
`textedit.selected.fg`, `textedit.selected.bg`	Selected text
`textedit.linenumber.fg`, `textedit.linenumber.bg`	Line number border (active, unfocused)
`textedit.focused.linenumber.fg`, `textedit.focused.linenumber.bg`	Line number border (active, focused)

Commands¶

This widget registers the following commands if the applications calls void Tui::ZTextEdit::registerCommandNotifiers(Qt::ShortcutContext context) using the passed context.

Command	Usage
`Copy`	Copies the current selection to the clipboard.
`Cut` ^(r)	Copies the selected text to the clipboard and removes it.
`Paste` ^(r)	Inserts the current clipboard content at the cursor position. If there is a current selection, the selected text is deleted before inserting the new text.
`Undo` ^(r)(u)	Undo the previous edit step.
`Redo` ^(r)(u)	Redo the previous edit step.

(r) Read-only mode will disable this command.

(u) If isUndoRedoEnabled is set to false this command will be disabled.

ZTextEdit¶

class Tui::ZTextEdit : public Tui::ZWidget ¶

A multi line text edit widget.

Constructors

ZTextLine(const Tui::ZTextMetrics &textMetrics, Tui::ZWidget *parent = nullptr)¶

ZTextLine(const Tui::ZTextMetrics &textMetrics, Tui::ZDocument *document, Tui::ZWidget *parent = nullptr)¶

Create the ZTextEdit with the text metrics textMetrics and the given parent.

The variant taking document sets the document used to document otherwise it creates a fresh document as backing that is automatically deleted when this widget is destructed.

Functions

void setCursorPosition(Tui::ZDocumentCursor::Position position, bool extendSelection = false)¶: Sets the “position” point of the text cursor to position. If extendSelection the “anchor” point is kept, otherwise it is set to the same position.

Tui::ZDocumentCursor::Position cursorPosition() const¶: Returns the “position” point of the text cursor.

void setAnchorPosition(Tui::ZDocumentCursor::Position position)¶: Sets the “anchor” point of the text cursor to position.

Tui::ZDocumentCursor::Position anchorPosition() const¶: Returns the “anchor” point of the text cursor.

void setTextCursor(const Tui::ZDocumentCursor &cursor)¶: Sets the text cursor “anchor” and “position” point to the values from cursor and updates the vertical movement position to that of cursor.

Tui::ZDocumentCursor textCursor() const¶: Returns a copy of the editing cursor of the text edit widget.

void setSelection(Tui::ZDocumentCursor::Position anchor, Tui::ZDocumentCursor::Position position)¶: Sets the text cursor selection to start at anchor and end at position.

Tui::ZDocument *document() const¶: Returns the model Tui::ZDocument instance. Use this for more control over the document or to access additional apis to observe or edit the text in the widget.

int lineNumberBorderWidth() const¶: Returns the width in columns of the line number border. If the line number border is disabled, it returns the width it would have if enabled.

virtual int allBordersWidth() const¶

Returns the width of all enabled borders. The base class only has one border, the line number border.

Derived classes can override this function to influence the text width used for cursor movement and scrolling calculations.

void setTabStopDistance(int tab)¶

int tabStopDistance() const¶: The tab stop distance determines in what interval stops for tabs are set. These stops are used for hard tabs (\t characters) as well as for the stops when emulating tabs with spaces and for indent and dedent.

void setShowLineNumbers(bool show)¶

bool showLineNumbers() const¶: Selects if a border with line numbers is shown.

void setUseTabChar(bool tab)¶

bool useTabChar() const¶: Selects if hard tabs (\t characters) are used as tabs and for indention.

void setWordWrapMode(Tui::ZTextOption::WrapMode wrap)¶

Tui::ZTextOption::WrapMode wordWrapMode() const¶: Selects the word/line wrapping mode. If wrapping is enabled horizontal scrolling is disabled.

void setOverwriteMode(bool mode)¶

void toggleOverwriteMode()¶

bool overwriteMode() const¶: If set to true, typed text overwrites existing text. Text never overwrites line breaks. This option does not apply to text inserted by calling functions on this class or inserted by pasting.

void setSelectMode(bool mode)¶

void toggleSelectMode()¶

bool selectMode() const¶: If the select mode is active, cursor movement keys extend the selection without holding down Shift. This can be helpful with terminals that don’t report some key combinations with Shift.

void setInsertCursorStyle(Tui::CursorStyle style)¶

Tui::CursorStyle insertCursorStyle() const¶: Selects the cursor style to use when overwrite mode is not set.

void setOverwriteCursorStyle(Tui::CursorStyle style)¶

Tui::CursorStyle overwriteCursorStyle() const¶: Selects the cursor style to use when overwrite mode is set.

void setTabChangesFocus(bool enabled)¶

bool tabChangesFocus() const¶: Selects if Tab can be used to change focus (i.e. is ignored by the text edit widget) or if it is used as an edit operation.

void setReadOnly(bool readOnly)¶

bool isReadOnly() const¶: Selects if this widget is read-only. Read-only mode only applies to edits by keyboard and to commands.

void setUndoRedoEnabled(bool enabled)¶

bool isUndoRedoEnabled() const¶: Selects if undo and redo keyboard shortcuts and commands are enabled.

bool isModified() const¶

Returns true if the document displayed in this text edit widget has been modified.

See Tui::ZDocument::isModified().

void insertText(const QString &str)¶: Inserts the text str at the current cursor position. If there is a current selection, the selected text is deleted before inserting the new text.

void insertTabAt(Tui::ZDocumentCursor &cur)¶: Inserts a tab at the given cursor cursor. The width and type (using \t or spaces) is configurable using useTabChar() const and tabStopDistance() const.

void cut()¶: Copies the selected text to the clipboard and removes it.

void copy()¶: Copies the current selection to the clipboard.

void paste()¶: Inserts the current clipboard content at the cursor position. If there is a current selection, the selected text is deleted before inserting the new text.

bool canPaste()¶: Returns true if paste() is current available.

bool canCut()¶: Returns true if cut() is current available.

bool canCopy()¶: Returns true if copy() is current available.

Tui::ZDocument::UndoGroup startUndoGroup()¶

Starts an undo group.

See Undo and redo for details.

void removeSelectedText()¶: Removes the currently selected text.

void clearSelection()¶: Clears the selection without changing the contents of the document.

void selectAll()¶: Selects all text in the document.

QString selectedText() const¶: Return the selected text, if any. Otherwise returns the empty string.

bool hasSelection() const¶: Returns true if there is currently a text selection.

void undo()¶: Preforms an undo step.

void redo()¶: Performs a redo step.

void enableDetachedScrolling()¶

void disableDetachedScrolling()¶

bool isDetachedScrolling() const¶: In detached scrolling mode, the scroll position is not automatically adjusted to keep the cursor visible. Use detachedScrollUp(), detachedScrollUp() or setScrollPosition(int column, int line, int fineLine) to adjust the scroll position manually.

void detachedScrollUp()¶

void detachedScrollDown()¶: When detached scrolling is active these function allow scrolling the text up and down.

int scrollPositionLine() const¶: Returns the index of the topmost visible line.

int scrollPositionFineLine() const¶

When line wrapping is enabled, returns the number of wrapped visual lines of the topmost visible logical line that are scrolled out.

Otherwise always returns 0.

int scrollPositionColumn() const¶: Returns the number of columns the text is scrolled to the right.

void setScrollPosition(int column, int line, int fineLine)¶: Sets the current scroll position to column columns scrolled to the right, line lines scrolled down and fineLine wrapped visual lines of the topmost visible logical lines that are scrolled out.

int pageNavigationLineCount() const¶

Returns the number of visual lines that Page Up and Page Down keys move up or down.

Derived classes can override this method to change the number of lines the cursor is moved.

Tui::ZDocumentCursor findSync(const QString &subString, Tui::ZDocument::FindFlags options = Tui::ZDocument::FindFlags{})¶

Find the next occurrence of literal string subString in the document starting at the current cursor position. If the search succeeds the found text will be selected, otherwise the current selection is cleared.

This function runs synchronously, so be careful not to block the main thread for too long, by searching in long documents.

The parameter options allows selecting different behaviors for case-sensitivity, wrap around and search direction.

The function returns a cursor with the match selected if found, otherwise a cursor without a selection.

See Finding for more details.

Tui::ZDocumentCursor findSync(const QRegularExpression &regex, Tui::ZDocument::FindFlags options = Tui::ZDocument::FindFlags{})¶

Find the next occurrence of regular expression regex in the document starting at the current cursor position. If the search succeeds the found text will be selected, otherwise the current selection is cleared.

This function runs synchronously, so be careful not to block the main thread for too long, by searching in long documents.

The parameter options allows selecting different behaviors for case-sensitivity, wrap around and search direction.

The function returns a cursor with the match selected if found, otherwise a cursor without a selection. If access to details about capture groups is required use findSyncWithDetails.

See Finding for more details.

Tui::ZDocumentFindResult findSyncWithDetails(const QRegularExpression &regex, Tui::ZDocument::FindFlags options = Tui::ZDocument::FindFlags{})¶

Find the next occurrence of regular expression regex in the document starting at the current cursor position. If the search succeeds the found text will be selected, otherwise the current selection is cleared.

This function runs synchronously, so be careful not to block the main thread for too long, by searching in long documents.

The parameter options allows selecting different behaviors for case-sensitivity, wrap around and search direction.

The function returns an instance of Tui::ZDocumentFindResult with the find result. It contains a cursor with the match selected if found, otherwise a cursor without a selection. Additionally it contains the contents of the regular expression’s capture groups.

See Finding for more details.

QFuture<Tui::ZDocumentFindAsyncResult> findAsync(const QString &subString, Tui::ZDocument::FindFlags options = Tui::ZDocument::FindFlags{})¶

QFuture<Tui::ZDocumentFindAsyncResult> findAsyncWithPool(QThreadPool *pool, int priority, const QString &subString, Tui::ZDocument::FindFlags options = Tui::ZDocument::FindFlags{})¶

Find the next occurrence of literal string subString in the document starting at the current cursor position. If the search succeeds the found text will be selected, otherwise the current selection is cleared.

This function runs asynchronously and returns a future resolving to a Tui::ZDocumentFindAsyncResult instance with the find result. It contains positions for a cursor with the match selected if found, otherwise both positions are equal to signal no match was found.

The parameter options allows selecting different behaviors for case-sensitivity, wrap around and search direction.

The variant taking pool and priority, runs the search operation on the thread pool pool with the priority priority. The variant without runs the search operation on the default thread pool with default priority.

See Finding for more details.

QFuture<Tui::ZDocumentFindAsyncResult> findAsync(const QRegularExpression &regex, Tui::ZDocument::FindFlags options = Tui::ZDocument::FindFlags{})¶

QFuture<Tui::ZDocumentFindAsyncResult> findAsyncWithPool(QThreadPool *pool, int priority, const QRegularExpression &regex, Tui::ZDocument::FindFlags options = Tui::ZDocument::FindFlags{})¶

Find the next occurrence of regular expression regex in the document starting at the current cursor position. If the search succeeds the found text will be selected, otherwise the current selection is cleared.

This function runs asynchronously and returns a future resolving to a Tui::ZDocumentFindAsyncResult instance with the find result. It contains positions for a cursor with the match selected if found, otherwise both positions are equal to signal no match was found. Additionally it contains the contents of the regular expression’s capture groups.

The parameter options allows selecting different behaviors for case-sensitivity, wrap around and search direction.

The variant taking pool and priority, runs the search operation on the thread pool pool with the priority priority. The variant without runs the search operation on the default thread pool with default priority.

See Finding for more details.

void clear()¶: Reset the document used by this widget back to the empty state.

void readFrom(QIODevice *file)¶

Replaces the contents of the document used by this widget with the contents of QIODevice file.

Returns true on success, otherwise returns false.

void readFrom(QIODevice *file, Tui::ZDocumentCursor::Position initialPosition)¶

Replaces the contents of the document used by this widget with the contents of QIODevice file. It sets the initial cursor position to initialPosition.

Returns true on success, otherwise returns false.

void writeTo(QIODevice *file) const¶

Saves the contents of the document used by this widget in to the QIODevice file.

Returns true on success, otherwise returns false.

Also marks the current undo state as saved.

void setText(const QString &text)¶: Replaces the contents of the document used by this widget with the contents of the string text.

void setText(const QString &text, Tui::ZDocumentCursor::Position initialPosition)¶: Replaces the contents of the document used by this widget with the contents of the string text. It sets the initial cursor position to initialPosition.

void text() const¶

Returns the contents of the document used by this widget as a string.

In constrast to void writeTo(QIODevice *file) const this function does not mark the current undo state as saved.

void registerCommandNotifiers(Qt::ShortcutContext context)¶: Registers the commands listed in the command section using the shortcut context context.

Tui::ZDocumentCursor makeCursor()¶: Returns a newly created cursor for the backing document for this widget.

Signals

void cursorPositionChanged(int x, int utf16CodeUnit, int utf8CodeUnit, int line)¶: This signal is emitted with the current cursor position. The x value is the visual position in the line in columns, the utf16CodeUnit is position in the line in normal (utf16) code units, the utf8CodeUnit has the same information in utf8 code units as used in files and line is the line in the document.

void scrollPositionChanged(int x, int line, int fineLine)¶: This signal is emitted with the current scroll position. The value x is the amount of columns the text is scrolled to the right, line is the number of (unwrapped) lines scrolled down and fineLine is the amount of visual lines scrolled in a wrapped logical line.

void scrollRangeChanged(int x, int y)¶: This signal is emitted with the current scrolling range. The value x specifies that needed range 0 <= · < x for the x direction and the y value specifies the allowed range of lines to scroll 0 <= · < y.

void overwriteModeChanged(bool overwrite)¶: This signal is emitted when the value of overwriteMode is changed.

void modifiedChanged(bool modified)¶: This signal is emitted when the value of isModified is changed.

void selectModeChanged(bool mode)¶: This signal is emitted when the value of selectMode is changed.

Protected Functions

Tui::ZTextOption textOption() const¶: Returns the Tui::ZTextOption used for painting the text and for various calculations while editing. A derived class can override this to change the used text options. This does not influence the options used for creating the cursor.

Tui::ZTextLayout textLayoutForLine(const Tui::ZTextOption &option, int line) const¶: Returns the text layout for the line with index line and using the text option option.

Tui::ZTextLayout textLayoutForLineWithoutWrapping(int line) const¶: Returns the text layout for the line with index line and the text option returned by textOption() const but with the text wrap disabled.

const Tui::ZTextMetrics &textMetrics() const¶: Returns the text metrics used by this widget.

void adjustScrollPosition()¶: Recalculates the scroll position to ensure the cursor is visible (unless detached scrolling is active). A derived class can override this to function to change how the scrolling of the widget works.

void emitCursorPostionChanged()¶: Emits the current cursor position. A derived class can override this to change what position is reported in the cursor position changed signal.

void updateCommands()¶: Updates the active status of the registered commands of this widget. A derived class can override this to update additional commands, but it should always invoke the function in the base class.

void clearAdvancedSelection()¶: This function does nothing in the base class, but is called in various places where a selection in created. A derived class can override this, if it implements its own selection mode that need to be cleared before a selection in the base class is created. The derived class likely needs to override the keyEvent handler and re-implement movement and related key combinations to get consistent behavior.

Type aliases

This class has some convenience type aliases.