ZDocument¶

ZDocument is a model class to store multi-line text for usage with multi-line text edit widgets, like ZTextEdit.

The document class itself mostly serves read access. Most modifications are done using the Tui::ZDocumentCursor class.

The current contents of the document can be accessed line by line. Also this class serves to enable functions on the document as a whole, like load/save and undo/redo.

The document may only be accessed from its associated thread, but a Tui::ZDocumentSnapshot can be created from a document that allows access, to a frozen state of the document, from any thread. This can be useful to implement time intensive operations on the document (like syntax highlighting) without blocking the main thread.

When loading a document that consistently uses CRLF (\r\n) line endings (traditional on MSDOS and Windows) the CR (\r) will be removed from all lines and can later be added back on saving.

Text documents are expected to normally end in a line break. If the document does not, then the newlineAfterLastLineMissing() const property is set and no final newline will be generated when saving the document.

Cursors and line markers¶

It is often needed to track a certain position in the document, even if the contents before that position changes in length. For this Tui::ZDocumentCursor and Tui::ZDocumentLineMarker can be used. Instances of these classes are updated accordingly to the edits happening before them in the document.

In contrast Tui::ZDocumentCursor::Position is a simple value of a fixed position that is not updated on changes.

The cursor is also the primary means of modification to the document. See Using cursors for details.

Cursors and line markers are also updated on undo and redo.

Change tracking¶

Each change of the document’s contents changes revision() const. The revision of the document does not change back to an old value on undo. The revision is not changed when line user-data is set or modified.

Each line also has a revision that is changed whenever the line is changed. The line revision returns to a previous value on undo and redo. It is not changed when line user-data is set or modified.

For changes to the document the signal contentsChanged() is emitted asynchronously. That means the signal is emitted after changes have happened in a future event loop iteration. Thus the part of the application that performs edits can be sure the receivers of the signal do not interfere with the editing.

Additional signals are emitted when the modification status (i.e. if the current undo step is the initial one or was explicitly marked as saved) changes.

Changes to cursor (cursorChanged(const Tui::ZDocumentCursor *cursor)) and line marker (lineMarkerChanged(const Tui::ZDocumentLineMarker *marker)) positions also trigger signals.

Line user-data¶

It is often useful for an application to store additional information associated with a line. This could for example be cached syntax highlighting information or generally additional information.

To facilitate this, the document allows saving an additional object with each line, by using setLineUserData.

Setting it or changes to it do not trigger change signals or increment the document or line revisions. The user is responsible for thread safe usage of this object, when using snapshots with other threads than the document’s thread.

Currently the user-data is also affected by undo and redo, but this might change in the future.

Undo and redo¶

The document class supports undo and redo operations.

The document’s modified state is tracked according to the current undo step. When the document is saved the application is responsible to call markUndoStateAsSaved() to update the undo step that is considered to be unmodified.

When inserting text in the document, multiple insert operations are merged to avoid too fine grained undo steps. If the inserted text contains a space, tab or line break or if the insert is performed at a different position the merging is prevented. The application can suppress merging by calling clearCollapseUndoStep().

If one logical action of the user is composed of multiple changes to the document, an undo group can merge all changes into one undo step. An undo group is started with startUndoGroup and is active until explicitly closed or until the returned group object is destroyed.

An application can keep itself informed, if currently an undo or redo operation is available, by connecting to the undoAvailable(bool available) and redoAvailable(bool available) signals.

Finding¶

The document offers functions to search for literal text or regular expression matches in the document.

These functions are offered in a synchronous and asynchronous variants.

The start position of a search is passed in by using a cursor.

For forward search, the next match for a given starting cursor is a match which starting point is greater than the maximum of the starting cursor’s “anchor” and “position” point.

For backward search, the next match for a given starting cursor is a match that ends before the maximum of the starting cursor’s “anchor” and “position” point and does not intersect with the last character of the selection (if a selection is active).

By using Tui::ZDocument::FindFlags the application can specify how the search is performed. By default the search is case insensitive, runs forward and does not wrap. If wrapping is enabled by FindFlags::FindWrap, if no result is found by searching in the specified direction the search will be repeated from the other end of the document till to the starting position of the search.
If case senstive search is requested by FindFlags::FindCaseSensitively a match will be required to be exact, otherwise a match using Qt::CaseInSensitive or QRegularExpression::PatternOption::CaseInsensitiveOption will be performed.
A backward search is requested by FindFlags::FindBackward.

Using cursors¶

A cursor represents a position in the document or a selection between two positions. It has functions to navigate in the document and alter its contents.

Points in the document are between characters (or more precisely between clusters of code points) in the document. The position is expressed in the number of code-units before the character/cluster and the line number. Zero code-units into a line designates the position before the first character/cluster in the line and the position after the last character/cluster is designated by the total count of code-units in the line (i.e. the result of Tui::ZDocument::lineCodeUnits(line)) Movement and the vertical position of the layouted text are calculated using the Tui::ZTextLayout class. When creating the cursor, the application has to supply a function to create a Tui::ZTextLayout for a given line with the configuration applied that the cursor should use.

Tui::ZDocumentCursor cursor{&doc, [textMetrics, &doc](int line, bool wrappingAllowed) {
        Tui::ZTextLayout lay(textMetrics, doc.line(line));
        // <your custom configuration here>
        lay.doLayout(65000);
        return lay;
    }
};

The movement is then determined by Tui::ZTextLayout::nextCursorPosition(…) and Tui::ZTextLayout::previousCursorPosition(…).

The selection spans between two points called “anchor” and “position”. If both points are equal the cursor has no selection. If they differ the text between the two positions is selected. The order of the two points is significant when the navigation functions of the cursor are used. The navigation always moves the “position”. If the navigation functions are used to extend the selection, the “anchor” point is not changed. Otherwise the “anchor” point is reset to the “position” point after the navigation. If, after a navigation while extending the selection, the “anchor” point and the “position” point are equal, the cursor does not have a active selection.

If the cursor has a active selection, then inserting will replace the selected range in the document. With an active selection, the delete functions (except deleteLine()) will remove the selected text instead of their specific function.

In addition to the “anchor” and “position” points that determine the position and selection of the cursor, there is a additional vertical movement position. The vertical movement position is not in code-units as the points, but in columns and is used when the “position” point of the cursor is moved up or down using moveUp or moveDown. This allows a user to navigate across lines or within wrapped lines visually and preserves the vertical position when navigating over short lines.

The “position” point will always stay inside the bounds of the line in the document, while the vertical movement position can be right of the end of the line.

The vertical movement position is updated when setting a new position with setPosition(…) and when using horizontal navigation functions. It can also be set explicitly.

ZDocument¶

class Tui::ZDocument : public QObject ¶

Constructors

ZDocument(QObject *parent = nullptr)¶: Constructs an empty document, with parent as its parent in the QObject system.

Functions

void reset()¶

Reset the document back to the empty state.

This function triggers change signals.

bool writeTo(QIODevice *file, bool crLfMode = false) const¶

Write the document’s contents to the QIODevice file.

If crLfMode is true, line breaks will use the CRLF (\r\n) line ending convention. To keep the same line ending convention as the originally loaded file, pass the return value from bool Tui::ZDocument::crLfMode() const here.

If bool newlineAfterLastLineMissing() const is not set, an trailing line break will be added to the file.

Returns true on success, otherwise returns false.

bool readFrom(QIODevice *file)¶

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

Reset the document and read new data from the QIODevice file.

Sets the crLfMode property to true, if the file consistently uses the CRLF (\r\n) line ending convention. Pass this value as crLfMode into writeTo to keep the same line ending convention as the loaded file when saving.

The variant taking a initialPosition sets the initial cursor position to initialPosition in the initial undo step.

The variant taking a initialPositionCursor sets the initial cursor position also in the cursor passed as initialPositionCursor. The passed pointer may be nullptr.

Returns true on success, otherwise returns false.

void text(bool crLfMode = false) const¶

Return the document’s contents as a string.

If crLfMode is true, line breaks will use the CRLF (\r\n) line ending convention. To keep the same line ending convention as the originally input string or file, pass the return value from bool Tui::ZDocument::crLfMode() const here.

If bool newlineAfterLastLineMissing() const is not set, an trailing line break will be added to the returned string.

void setText(const QString &text)¶

void setText(const QString &text, Tui::ZDocumentCursor::Position initialPosition, Tui::ZDocumentCursor *initialPositionCursor)¶

Reset the document and read new data from the QString text.

Sets the crLfMode property to true, if the input string consistently uses the CRLF (\r\n) line ending convention. Pass this value as crLfMode into text or writeTo to keep the same line ending convention as the input string when retrieving the contents.

The variant taking a initialPosition sets the initial cursor position to initialPosition in the initial undo step.

The variant taking a initialPositionCursor sets the initial cursor position also in the cursor passed as initialPositionCursor. The passed pointer may be nullptr.

void setCrLfMode(bool crLf)¶

bool crLfMode() const¶: This property contains the line ending convention used when loading this documents. If it is false, lines are terminated using LF (\n). If it is true, lines are terminated using CRLF (\r\n).

int lineCount() const¶: Returns the number of lines in the document.

QString line(int line) const¶

Returns the text contents of the line with index line in the document.

The value of line must be 0 <= line < lineCount() to avoid undefined behavior.

int lineCodeUnits(int line) const¶

Returns the length in code-units of the line with index line in the document.

The value of line must be 0 <= line < lineCount() to avoid undefined behavior.

unsigned lineRevision(int line) const¶

Return the revision of the line with index line in the document.

See Change tracking for more details.

The value of line must be 0 <= line < lineCount() to avoid undefined behavior.

void setLineUserData(int line, std::shared_ptr<Tui::ZDocumentLineUserData> userData)¶

Set the user-data pointer of the line with index line in the document to userData.

This function does not change the line’s or document’s revision and does not trigger change signals. It also does not create a new undo step.

The value of line must be 0 <= line < lineCount() to avoid undefined behavior.

std::shared_ptr<Tui::ZDocumentLineUserData> lineUserData(int line) const¶

Return the user-data pointer of the line with index line in the document.

The value of line must be 0 <= line < lineCount() to avoid undefined behavior.

Tui::ZDocumentSnapshot snapshot() const¶

Returns a snapshot of the document.

This snapshot can be safely accessed from other threads and captures the current contents of the document. It will not change when further edits are applied to the document.

The application is responsible to ensure that multi-threaded access to the user-data pointer contained in the snapshot is safe.

unsigned revision() const¶

Returns the current document revision.

See Change tracking for more details.

bool isModified() const¶

Returns if the document is currently modified.

That is, it returns true if the current undo step is not marked as the currently saved undo step.

See Undo and redo for more details.

void setNewlineAfterLastLineMissing(bool value)¶

bool newlineAfterLastLineMissing() const¶

This property describes if the document is missing the conventional final line break of a text document.

If it is false the final line break is implicitly added when saving the document.

QString filename() const¶

void setFilename(const QString &filename)¶: This property contains the file name of the document. It is for informational purposes only and is not used in implementation of this class. It is up to the application, if and how this property is maintained.

void clearCollapseUndoStep()¶

Prevent the next operation to be merged with the current undo step.

See Undo and redo for more details.

void sortLines(int first, int last, Tui::ZDocumentCursor *cursorForUndoStep)¶: Sort the lines from first to last (exclusive) of the document.

void moveLine(int from, int to, Tui::ZDocumentCursor *cursorForUndoStep)¶

Move the line with index from to the position to.

The line in index from will end up on index to after the operation.

Example:

Given a document with the following lines:

red
green
blue
white

If we now call moveLine(1, 2, …), the result will be:

red
blue
green
white

The value of from and to must both be 0 <= · < lineCount() to avoid undefined behavior.

void debugConsistencyCheck(const Tui::ZDocumentCursor *exclude = nullptr) const¶

Perform a consistency check for debugging. Excludes the cursor exclude from the consistency check if set to a non-null value.

This function aborts the program is a problem is found.

void undo(Tui::ZDocumentCursor *cursor)¶

Preforms an undo step.

The cursor cursor is moved to the position of the cursor, that created the undo step, before the modification. The passed pointer must not be nullptr.

If isUndoAvailable() const is false this does nothing.

See Undo and redo for more details.

void redo(Tui::ZDocumentCursor *cursor)¶

Performs a redo step. That is, it counteracts a previous undo if no editing has happened in-between.

The cursor cursor is moved to the position of the cursor, that created the undo step, after the modification. The passed pointer must not be nullptr.

If isRedoAvailable() const is false this does nothing.

See Undo and redo for more details.

bool isUndoAvailable() const¶: Returns true if undo can be called.

bool isRedoAvailable() const¶: Returns true if redo can be called.

UndoGroup startUndoGroup(Tui::ZDocumentCursor *cursor)¶

Starts an undo group and returns the undo group’s activation object.

The position of cursor cursor before and after the modification is saved in the undo step. The passed pointer must not be nullptr.

Undo groups can not be nested and are closed when the activation object (or its moved to objects) are destroyed or the undo group is explicitly closed.

See Undo and redo for more details.

void markUndoStateAsSaved()¶

Marks the current undo step as saved.

After calling this function bool isModified() const will return false until the next modification is made (or undo/redo is called).

It also prevents merging of the current undo step with a newly created undo step on future changes.

See Undo and redo for more details.

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

Find the next occurrence of literal string subString in the document starting with start.

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, const Tui::ZDocumentCursor &start, Tui::ZDocument::FindFlags options = FindFlags{}) const¶

Find the next occurrence of regular expression regex in the document starting with start.

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, const Tui::ZDocumentCursor &start, Tui::ZDocument::FindFlags options = FindFlags{}) const¶

Find the next occurrence of regular expression regex in the document starting with start.

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, const Tui::ZDocumentCursor &start, Tui::ZDocument::FindFlags options = FindFlags{}) const¶

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

Find the next occurrence of literal string subString in the document starting with start.

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, const Tui::ZDocumentCursor &start, Tui::ZDocument::FindFlags options = FindFlags{}) const¶

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

Find the next occurrence of regular expression regex in the document starting with start.

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.

Signals

void modificationChanged(bool changed)¶

This signal informs the application of the current modification state of the document.

See Undo and redo for more details.

void redoAvailable(bool available)¶

This signal informs the application if the redo operation is currently available.

See Undo and redo for more details.

void undoAvailable(bool available)¶

This signal informs the application if the undo operation is currently available.

See Undo and redo for more details.

void contentsChanged()¶

This signal is emitted asynchronously when the contents of the document was changed.

See Change tracking for more details.

void cursorChanged(const Tui::ZDocumentCursor *cursor)¶

This signal is emitted asynchronously when the position of the cursor cursor has changed.

This signal is emitted for direct position changes as well as for changes caused by modifications before the cursor position or caused by undo or redo.

See Change tracking for more details.

void lineMarkerChanged(const Tui::ZDocumentLineMarker *marker)¶

This signal is emitted asynchronously when the position of the line marker marker has changed.

This signal is emitted for direct position changes as well as for changes caused by modifications before the line marker position or caused by undo or redo.

See Change tracking for more details.

void crLfModeChanged(bool crLf)¶: This signal is emitted when the crLfMode property changes. crLf contains the new value of the property.

Nested Types

using FindFlags = QFlags<Tui::ZDocument::FindFlag>¶

enum FindFlag¶

Flags used to select find behavior in Tui::ZDocument.

enumerator FindBackward¶: Search backwords from the starting cursor.

enumerator FindCaseSensitively¶

Search case sensitive.

If this flag is used, a match will be required to be exact, otherwise a match using Qt::CaseInSensitive or QRegularExpression::PatternOption::CaseInsensitiveOption will performed.

enumerator FindWrap¶: If no match was found, wrap around once and continue searching.

class UndoGroup¶

This class is only move constructable and move assignable. It is not directly user constructable.

Activate an undo group by calling Tui::ZDocument::startUndoGroup

The undo group is closed as soon as the instance (or the moved to instance) is destructed, or it is manually closed.

void closeGroup()¶: Manually close the undo group.

class Tui::ZDocumentCursor¶

A cursor is the primary means of modification for a Tui::ZDocument.

This class is copy constructable and copy assignable.

See Using cursors for more details.

Constructors

explicit ZDocumentCursor(Tui::ZDocument *doc, std::function<Tui::ZTextLayout(int line, bool wrappingAllowed)> createTextLayout)¶

Construct a new cursor.

The cursor needs a layouting function for navigating the document. This function is passed as createTextLayout and must return a layouted Tui::ZTextLayout instance for the line passed as line. If the application supports line wrapping of the document, it should use the current line wrapping setting when the function is called with wrappingAllowed set to true.

Functions

void insertText(const QString &text)¶

Insert the text text at the current cursor location.

If the cursor has a selection, it will be replaced by the text text.

Both cursor points will be set to the end of the inserted text.

void overwriteText(const QString &text, int clusterCount = 1)¶

Insert the text text at the current cursor location, overwriting up to clusterCount characters/clusters.

If text is empty this function does nothing.

If the cursor has a selection, it will be replaced by the text text and clusterCount is ignored.

Otherwise removes up to clusterCount characters/clusters following the current position on the current line. First clusterCount is reduced by the amount of \n characters found in text, then it is reduced to at most the count of remaining characters/clusters in the current line. Then the text is inserted.

It should be called with textMetrics.sizeInClusters(text) as clusterCount. When done so and without a selection, calling it with each character/cluster one at a time and calling it with the same characters all at once will yield the same result.

Both cursor points will be set to the end of the inserted text.

void removeSelectedText()¶

If the cursor has a selection, it will be removed.

The cursor will be placed before the start of the selection, after removing the selection.

void clearSelection()¶: Clears the selection. That is moves the “anchor” point to the “position” point without changing the contents of the document.

QString selectedText() const¶: If the cursor has a selection, returns the currently selected text, otherwise returns an empty string.

void deleteCharacter()¶

If the cursor does not have a selection, removes the character/cluster to the right of the cursor. Otherwise it removes the selection.

If the cursor started on the end of a line, it removes the line break and joins the current line with the next line.

void deletePreviousCharacter()¶

If the cursor does not have a selection, removes the character/cluster to the left of the cursor. Otherwise it removes the selection.

If the cursor started on the start of a line, it removes the line break and joins the current line with the previous line.

void deleteWord()¶

If the cursor does not have a selection, removes the word to the right of the cursor. Otherwise it removes the selection.

If the cursor started on the end of a line, it removes the line break and joins the current line with the next line.

The precise amount of removed text is determined by the Tui::ZTextLayout::nextCursorPosition() function using CursorMode::SkipWords.

void deletePreviousWord()¶

If the cursor does not have a selection, removes the word to the left of the cursor. Otherwise it removes the selection.

If the cursor started on the start of a line, it removes the line break and joins the current line with the previous line.

The precise amount of removed text is determined by the Tui::ZTextLayout::previousCursorPosition() function using CursorMode::SkipWords.

void deleteLine()¶

Deletes the whole line that the “position” point is on.

The cursor will no longer have a selection active after this function is called.

void moveCharacterLeft(bool extendSelection = false)¶

Moves the “position” point of the cursor one character/cluster to the left. If the cursor started on the start of a line, it moves the cursor to the end of the previous line.

If extendSelection is true then the “anchor” point of the cursor is not moved, otherwise the “anchor” point is set to the new “position” point of the cursor. Even if the cursor does not move, if extendSelection is false the cursor will no longer have a selection active after this function is called.

void moveCharacterRight(bool extendSelection = false)¶

Moves the “position” point of the cursor one character/cluster to the right. If the cursor started on the end of a line, it moves the cursor to the start of the next line.

If extendSelection is true then the “anchor” point of the cursor is not moved, otherwise the “anchor” point is set to the new “position” point of the cursor. Even if the cursor does not move, if extendSelection is false the cursor will no longer have a selection active after this function is called.

void moveWordLeft(bool extendSelection = false)¶

Moves the “position” point of the cursor one word to the left. If the cursor started on the start of a line, it moves the cursor to the end of the previous line.

The precise movement is determined by the Tui::ZTextLayout::previousCursorPosition() function using CursorMode::SkipWords.

If extendSelection is true then the “anchor” point of the cursor is not moved, otherwise the “anchor” point is set to the new “position” point of the cursor. Even if the cursor does not move, if extendSelection is false the cursor will no longer have a selection active after this function is called.

void moveWordRight(bool extendSelection = false)¶

Moves the “position” point of the cursor one word to the right. If the cursor started on the end of a line, it moves the cursor to the start of the next line.

The precise movement is determined by the Tui::ZTextLayout::nextCursorPosition() function using CursorMode::SkipWords.

If extendSelection is true then the “anchor” point of the cursor is not moved, otherwise the “anchor” point is set to the new “position” point of the cursor. Even if the cursor does not move, if extendSelection is false the cursor will no longer have a selection active after this function is called.

void moveUp(bool extendSelection = false)¶

Moves the cursor up.

When word wrapping is active the cursor navigates based on the wrapped lines. Thus moving up on a wrapped line moves the “position” point of the cursor closer to the start of the line.

If the cursor is already on the first line, it moves to the start of the first line.

The position in the line the moved cursor is placed on is determined based on the layouted positions, using the current value of int verticalMovementColumn() const. If that vertical position is inside the line the cursor will be placed there, otherwise it is placed at the right most position in the line.

If extendSelection is true then the “anchor” point of the cursor is not moved, otherwise the “anchor” point is set to the new “position” point of the cursor. Even if the cursor does not move, if extendSelection is false the cursor will no longer have a selection active after this function is called.

void moveDown(bool extendSelection = false)¶

Moves the cursor down.

When word wrapping is active the cursor navigates based on the wrapped lines. Thus moving down on a wrapped line moves the “position” point of the cursor closer to the end of the line.

If the cursor is already on the last line, it moves to the end of the last line.

The position in the line the moved cursor is placed on is determined based on the layouted positions, using the current value of int verticalMovementColumn() const. If that vertical position is inside the line the cursor will be placed there, otherwise it is placed at the right most position in the line.

If extendSelection is true then the “anchor” point of the cursor is not moved, otherwise the “anchor” point is set to the new “position” point of the cursor. Even if the cursor does not move, if extendSelection is false the cursor will no longer have a selection active after this function is called.

void moveToStartOfLine(bool extendSelection = false)¶

Moves the “position” point of the cursor to the start of the current line. This function ignores line wrapping.

If extendSelection is true then the “anchor” point of the cursor is not moved, otherwise the “anchor” point is set to the new “position” point of the cursor. Even if the cursor does not move, if extendSelection is false the cursor will no longer have a selection active after this function is called.

void moveToStartIndentedText(bool extendSelection = false)¶

Moves the “position” point of the cursor to the start of the non whitespace text on the current line. The cursor is placed before the first non space and not tab character, or if no such character exists at the end of the line. This function ignores line wrapping.

If extendSelection is true then the “anchor” point of the cursor is not moved, otherwise the “anchor” point is set to the new “position” point of the cursor. Even if the cursor does not move, if extendSelection is false the cursor will no longer have a selection active after this function is called.

void moveToEndOfLine(bool extendSelection = false)¶

Moves the “position” point of the cursor to the end of the current line. This function ignores line wrapping.

If extendSelection is true then the “anchor” point of the cursor is not moved, otherwise the “anchor” point is set to the new “position” point of the cursor. Even if the cursor does not move, if extendSelection is false the cursor will no longer have a selection active after this function is called.

void moveToStartOfDocument(bool extendSelection = false)¶

Moves the “position” point of the cursor to the start of the first line of the document.

If extendSelection is true then the “anchor” point of the cursor is not moved, otherwise the “anchor” point is set to the new “position” point of the cursor. Even if the cursor does not move, if extendSelection is false the cursor will no longer have a selection active after this function is called.

void moveToEndOfDocument(bool extendSelection = false)¶

Moves the “position” point of the cursor to the end of the last line of the document.

If extendSelection is true then the “anchor” point of the cursor is not moved, otherwise the “anchor” point is set to the new “position” point of the cursor. Even if the cursor does not move, if extendSelection is false the cursor will no longer have a selection active after this function is called.

Position position() const¶: Returns the current “position” point of the cursor.

void setPosition(Position pos, bool extendSelection = false)¶

Sets the “position” point of the cursor to pos.

If pos points into a cluster of characters or inside a multi-code-unit code-point, the position at the nearest cluster boundary after pos will be used.

If extendSelection is true then the “anchor” point of the cursor is not moved, otherwise the “anchor” point is set to the new “position” point of the cursor. Even if the cursor does not move, if extendSelection is false the cursor will no longer have a selection active after this function is called.

Updates the vertical movement position of the cursor.

void setPositionPreservingVerticalMovementColumn(Position pos, bool extendSelection = false)¶

Sets the “position” point of the cursor to pos.

If pos points into a cluster of characters or inside a multi-code-unit code-point, the position at the nearest cluster boundary after pos will be used.

If extendSelection is true then the “anchor” point of the cursor is not moved, otherwise the “anchor” point is set to the new “position” point of the cursor. Even if the cursor does not move, if extendSelection is false the cursor will no longer have a selection active after this function is called.

Furthermore if the “anchor” and “position” points are equal after this call the cursor will no longer have a selection active after this function is called.

Does not update the vertical movement position of the cursor.

Position anchor() const¶: Returns the current “anchor” point of the cursor.

void setAnchorPosition(Position pos)¶

Sets the “anchor” point of the cursor to pos.

If pos points into a cluster of characters or inside a multi-code-unit code-point, the position at the nearest cluster boundary after pos will be used.

If the “anchor” and “position” points are equal after this call, the cursor will no longer have a selection active after this function is called. Otherwise the characters in the document from the “anchor” point to the “position” point will be selected.

int verticalMovementColumn() const¶

void setVerticalMovementColumn(int column)¶

The vertical movement position is used by void moveUp(bool extendSelection = false) and void moveDown(bool extendSelection = false) to determine the new position of the cursor in a (possibly wrapped) line.

The vertical movement position of the cursor, is not in code-units as the “anchor” or “position” points of the cursor, but in visual columns.

Vertical movement uses an independent visual position to allow moving the cursor across shorter lines without loosing the vertical position, so that moving to a longer line remembers the starting point of the up or down movement.

The vertical movement position is reset to the position of the cursor when calling void setPosition(Position pos, bool extendSelection = false) and when the cursor is moved with function that is not moveUp or moveDown.

Position selectionStartPos() const¶: If the cursor has an active selection, returns the minimum of the “anchor” and “position” points of the cursor. Otherwise return the current cursor position.

Position selectionEndPos() const¶: If the cursor has an active selection, returns the maximum of the “anchor” and “position” points of the cursor. Otherwise return the current cursor position.

void selectAll()¶

Selects the whole content of the document.

It sets the “anchor” point of the cursor to the beginning of the document and the “position” point of the cursor after the last character of the document.

bool hasSelection() const¶

Returns true if the document has an active selection.

That is, if the “anchor” and “position” points are different.

bool atStart() const¶: Returns true of the cursor position is at the start of the document.

bool atEnd() const¶: Returns true if the cursor position is at the end of the document, that is after the last character of the last line.

bool atLineStart() const¶: Returns true if the cursor position is at the start of a line.

bool atLineEnd() const¶: Returns true if the cursor position is at the end of a line, that is after the last character of the line.

void debugConsistencyCheck() const¶

Perform a consistency check for debugging.

This function aborts the program is a problem is found.

Nested Types

class Position¶

Holds a point in a document as line index and code unit index inside that line.

The position is before the character specified by the line and code unit index.

This class is copy and move constructable and assignable. It has a default constructor that sets the line and code unit indices to zero. The position is comparable and implements operators for equality and comparison.

int codeUnit¶: The code unit before which this position instance points.

int line¶: The line the position instance points to.

class Tui::ZDocumentLineUserData¶

ZDocumentLineUserData is used as base class for line user-data stored by Tui::ZDocument.

See Line user-data for more details.

This class is copy and move constructable and assignable. It has a default constructor.

class Tui::ZDocumentFindAsyncResult¶

Contains the results of an asynchronous find operation on Tui::ZDocument.

This class is copy constructable and copy assignable. It has a default constructor but is usually obtained by calling one of the async find methods on Tui::ZDocument.

Tui::ZDocumentCursor::Position anchor() const¶

Returns the start position of the match.

If the position is equal to the position returned by Position cursor() const then the search did not match, otherwise this position is the start of the match.

Setting a cursor with both positions will yield a cursor with the match selected.

If unsigned revision() const does not match the document’s revision the search result might be outdated.

Tui::ZDocumentCursor::Position cursor() const¶

Returns the position after the end of the match.

If the position is equal to the position returned by Position anchor() const then the search did not match, otherwise this position is after the end of the match.

Setting a cursor with both positions will yield a cursor with the match selected.

If unsigned revision() const does not match the document’s revision the search result might be outdated.

unsigned revision() const¶: Returns the revision of the snapshot of the document used for the find operation.

int regexLastCapturedIndex() const¶

Returns the last (highest) index valid to pass in to QString regexCapture(int index) const.

This is only meaningful when this is a result of a regular expression match, otherwise it will be -1.

See https://doc.qt.io/qt-5/qregularexpressionmatch.html#lastCapturedIndex

QString regexCapture(int index) const¶

Returns the captured string of capture group index.

This is only meaningful when this is a result of a regular expression match.

See https://doc.qt.io/qt-5/qregularexpressionmatch.html#captured

QString regexCapture(const QString &name) const¶

Returns the captured string of named capture group name.

This is only meaningful when this is a result of a regular expression match.

See https://doc.qt.io/qt-5/qregularexpressionmatch.html#captured-1

class Tui::ZDocumentFindResult¶

Contains the results of a synchronous regular expression find operation on Tui::ZDocument.

This class is copy constructable and copy assignable. An instance is usually obtained by calling Tui::ZDocument::findSyncWithDetails(…).

Tui::ZDocumentCursor cursor() const¶

Returns the cursor for the match.

The cursor has the match selected if found, otherwise the cursor does not have a selection.

int regexLastCapturedIndex() const¶

Returns the last (highest) index valid to pass in to QString regexCapture(int index) const.

See https://doc.qt.io/qt-5/qregularexpressionmatch.html#lastCapturedIndex

QString regexCapture(int index) const¶

Returns the captured string of capture group index.

See https://doc.qt.io/qt-5/qregularexpressionmatch.html#captured

QString regexCapture(const QString &name) const¶

Returns the captured string of named capture group name.

See https://doc.qt.io/qt-5/qregularexpressionmatch.html#captured-1

class Tui::ZDocumentLineMarker¶

A line marker marks a line in a Tui::ZDocument.

When lines before it are added or removed, it is automatically adjusted to point to the original line.

This class is copy constructable and copy assignable.

Constructors

explicit ZDocumentLineMarker(Tui::ZDocument *doc)¶: Construct an instance initialized to the first line of document doc.

explicit ZDocumentLineMarker(Tui::ZDocument *doc, int line)¶: Construct an instance initialized to the line with index line of document doc.

Functions

int line() const¶: Return the line index of the line tracked by this line marker.

void setLine(int line)¶: Sets the line tracked by this line marker to the line with index line.

class Tui::ZDocumentSnapshot¶

A thread-safe snapshot of a Tui::ZDocument.

This class is copy constructable and copy assignable. It is default constructable but instances are usually obtained from Tui::ZDocumentSnapshot Tui::ZDocument::snapshot() const.

int lineCount() const¶: Returns the number of lines in the snapshot.

QString line(int line) const¶

Returns the text contents of the line with index line in the snapshot.

The value of line must be 0 <= line < lineCount() to avoid undefined behavior.

int lineCodeUnits(int line) const¶

Returns the length in code-units of the line with index line in the snapshot.

The value of line must be 0 <= line < lineCount() to avoid undefined behavior.

unsigned lineRevision(int line) const¶

Return the revision of the line with index line in the snapshot.

The value of line must be 0 <= line < lineCount() to avoid undefined behavior.

std::shared_ptr<Tui::ZDocumentLineUserData> lineUserData(int line) const¶

Return the user-data pointer of the line with index line in the snapshot.

The value of line must be 0 <= line < lineCount() to avoid undefined behavior.

unsigned revision() const¶: Returns the revision of the document that was used to create this snapshot.

bool isUpToDate() const¶: Returns false if the revision of the document, this snapshot was created from, has changed since the snapshot was created.

ZDocument¶

Cursors and line markers¶

Change tracking¶

Line user-data¶

Undo and redo¶

Finding¶

Using cursors¶

ZDocument¶

Tui Widgets

Navigation

Related Topics