ZTextLayout

ZTextLayout allows outputting text with features not directly supported by the text output functions in Tui::ZPainter and also allows mapping from visual coordinates to text position and adjusting text positions by letter/cluster or words. It supports using different color and attributes for part of the text, line breaks, line wrapping and more.

It is a low level class and is intended for use in widgets that render text manually.

The most basic usage is to construct the class using the terminal’s or painter’s text metrics together with the text to display and then calling void Tui::ZTextLayout::doLayout(int width).

After the layouting is done, the other instance methods can be used to display the text and to query information from the layout.

Displaying the text can be done with draw passing it the position and the base text style.

class Tui::ZTextLayout

This class is copyable. It does not define comparison operators.

Layouts and paints text. Also allows to query information about the layout of the text.

Constructors

ZTextLayout(Tui::ZTextMetrics metrics)

Construct a text layout using metrics as text metrics.

When using this constructor, the text must be set using void setText(const QString &text) and the text must be layouted before the layout can be used to draw the text or query layout details.

ZTextLayout(Tui::ZTextMetrics metrics, const QString &text)

Construct a text layout using metrics as text metrics and text as the initial text.

When using this constructor, the text must be layouted before the layout can be used to draw the text or query layout details.

Enums

enum CursorMode

enumerator SkipCharacters

Adjust cursor position by letters/clusters.

enumerator SkipWords

Adjust cursor postion by words.

enum Edge

enumerator Leading

Use the start of the cluster.

enumerator Trailing

Use the end of the cluster.

Functions

QString text() const

void setText(const QString &text)

The text that is to be layouted.

When the text is changed, it must be layouted again before using any functions to draw using the layout or to query layout details.

const Tui::ZTextOption &textOption() const

void setTextOption(const Tui::ZTextOption &option)

The text option describes various details on how the text should be layouted.

See Tui::ZTextOption for details.

When the text option is changed the text must to be layouted again before using any functions to draw using the layout or to query layout details.

void doLayout(int width)

Layouts the text using width as layout width.

This function creates as many lines as needed to display the text using width width. Lines are created at position (x, y) = (0, line number) where line number increments for each new line.

After calling this function, functions to draw using the layout or to query layout details can be used.

When using this function do not call void beginLayout() or void endLayout() manually.

void beginLayout()

Begins manual layout of the text.

After calling this function the application can create and layout lines using Tui::ZTextLineRef createLine().

After all lines are created and layouted the application must call void endLayout().

void endLayout()

Must be called when using manual layout after layouting all lines.

Tui::ZTextLineRef createLine()

Creates a new line to be layouted when using manual layout.

If all text to layout is already layouted, no further lines will be added and a invalid Tui::ZTextLineRef is returned.

Following the call to this function the application code should call void Tui::ZTextLineRef::setLineWidth(int width) to trigger layouting the line.

In addition to layouting the line, the line should be assigned a relative position using void Tui::ZTextLineRef::setPosition(const QPoint &pos)

void draw(Tui::ZPainter painter, const QPoint &pos, Tui::ZTextStyle style, const Tui::ZTextStyle *formattingChars = nullptr, const QVector<Tui::ZFormatRange> &ranges = QVector<Tui::ZFormatRange>()) const

Draws the whole text layout at position pos using the painter painter.

It uses style for text not covered by a item in ranges and formattingChars for formating characters not covered by a item in ranges (if enabled in the options).

If nullptr is passed as formattingChars, it defaults to style.

The last format range in ranges that matches a part of the text is used to format that text.

void showCursor(Tui::ZPainter painter, const QPoint &pos, int cursorPosition) const

Show the terminal cursor at visual position that corresponds to cursor position cursorPosition in the layouted text.

This is intended for calling after calling draw using the same pos.

QRect boundingRect() const

After layout, returns the smallest rectangle that contains all the layouted text.

int lineCount() const

After layout, returns the number of lines created from the text.

int maximumWidth() const

After layout, returns the maxium of the width of all lines.

The width does not contain the x offset of the lines.

Tui::ZTextLineRef lineAt(int i) const

After layout, returns the the i-th line of the layouted text.

If i is out of range returns a invalid Tui::ZTextLineRef.

Tui::ZTextLineRef lineForTextPosition(int pos) const

After layout, returns the line that contains the character at position pos (in code units) in the layout’s text.

If pos is the position after the last code point in the layout’s text it returns the last line.

If pos is out of range returns a invalid Tui::ZTextLineRef.

int previousCursorPosition(int oldPos, Tui::ZTextLayout::CursorMode mode = SkipCharacters) const

After layout, returns the previous cursor position in code units relative to oldPos.

When mode is CursorMode::SkipCharacters the cursor position will be one letter/cluster before oldPos (or 0 no previous position exists).

When mode is CursorMode::SkipWords the cursor position will be one word before oldPos (or 0 no previous position exists).

int nextCursorPosition(int oldPos, Tui::ZTextLayout::CursorMode mode = SkipCharacters) const

After layout, returns the next cursor position in code units relative to oldPos.

When mode is CursorMode::SkipCharacters the cursor position will be one letter/cluster after oldPos (or the position after the last code point in the text if no next position exists).

When mode is CursorMode::SkipWords the cursor position will be one word after oldPos (or the position after the last code point in the text if no next position exists).

bool isValidCursorPosition(int pos) const

After layout, returns true iff the position pos (in code units) is a valid cursor position in the current text.

A cursor position is valid if it is neither negative nor greater than the text lenght and it falls on a cluster boundary.

class Tui::ZTextLineRef

This class is copyable. It does not define comparison operators.

This class represents a reference to a line in a Tui::ZTextLayout. It can be used to render a line of the layout or query information about the line.

bool isValid() const

Returns true when the instance references a line. Otherwise returns false. Invalid instances are used to represent either that no line exists or that no new line can be created because all the text in the text layout is already layouted.

void draw(Tui::ZPainter painter, const QPoint &pos, Tui::ZTextStyle color, Tui::ZTextStyle formattingChars, const QVector<Tui::ZFormatRange> &ranges = QVector<Tui::ZFormatRange>()) const

Draws the current line using the painter painter. The line is drawn using its relative position in the layout plus the position pos. That is when drawing all lines each draw call usually uses the same pos as the other draw calls.

It uses style for text not covered by a item in ranges and formattingChars for formating characters not covered by a item in ranges (if enabled in the options).

The last format range in ranges that matches a part of the text is used to format that text.

int cursorToX(int *cursorPos, Tui::ZTextLayout::Edge edge) const

int cursorToX(int cursorPos, Tui::ZTextLayout::Edge edge) const

Translate the cursor position cursorPos to the relative x position in the current line.

If the cursor position in not on the current line it is adjusted to the nearest position that is on the line. if the cursor position is not a valid cursor position the position is adjusted to the nearest valid cursor position before the given position.

In the variant taking cursorPos as pointer the pointed to value will be updated to the cursor postion used for the x position calculation.

If edge is ZTextLayout::Leading the return is the position at the start of the cluster. If edge is ZTextLayout::Trailing the return is the position after the cluster. If the cursor points to the \n that terminates the line the trailing edge is the same as the leading edge, because the line break character does not take any space in the layout.

int xToCursor(int x) const

Translates a relative x position to the corresponding cursor position (in code units).

The returned cursor position is the nearest cursor position for the given x. For single cell clusters the position will be before the cluster.

The combination xToCursor(cursorToX(cursor, Tui::ZTextLayout::Edge::Leading)) returns cursor again for valid cursor positions on the current line.

void setPosition(const QPoint &pos)

QPoint position() const

The position of a line is the relative position in the layout of the line.

int x() const

Return the x part of the relative position of the line.

int y() const

Return the y part of the relative position of the line.

int width() const

Return the width of the line.

int height() const

Always return 1.

QRect rect() const

Returns QRect(position(), QSize{width(), height()}).

int lineNumber() const

Returns the number of this line in its text layout.

See also: Tui::ZTextLineRef Tui::ZTextLayout::lineAt(int i) const

int textStart() const

Return the start position in the layout’s text of this line in code units.

int textLength() const

Return the length of text from the layout’s text covered by this line in code units.

void setLineWidth(int width)

Triggers layout of a line with remaining text of the text layout.