# 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.

  using Position = Tui::ZDocumentCursor::Position
  using FindFlag = Tui::ZDocument::FindFlag
  using FindFlags = Tui::ZDocument::FindFlags