Class TextFormatter

Provides text formatting capabilities for console apps. Supports, hotkeys, horizontal alignment, multiple lines, and word-based line wrap.

Inheritance

System.Object

TextFormatter

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: Terminal.Gui

Assembly: Terminal.Gui.dll

Syntax

public class TextFormatter

Properties

Alignment

Controls the horizontal text-alignment property.

Declaration

public TextAlignment Alignment { get; set; }

Property Value

Type	Description
TextAlignment	The text alignment.

AutoSize

Used by Text to resize the view's Bounds with the Size. Setting AutoSize to true only work if the Width and Height are null or Absolute values and doesn't work with Computed layout, to avoid breaking the Pos and Dim settings.

Declaration

public bool AutoSize { get; set; }

Property Value

Type	Description
System.Boolean

CursorPosition

Gets the cursor position from HotKey. If the HotKey is defined, the cursor will be positioned over it.

Declaration

public int CursorPosition { get; set; }

Property Value

Type	Description
System.Int32

Direction

Controls the text-direction property.

Declaration

public TextDirection Direction { get; set; }

Property Value

Type	Description
TextDirection	The text vertical alignment.

HotKey

Gets the hotkey. Will be an upper case letter or digit.

Declaration

public Key HotKey { get; }

Property Value

Type	Description
Key

HotKeyPos

The position in the text of the hotkey. The hotkey will be rendered using the hot color.

Declaration

public int HotKeyPos { get; set; }

Property Value

Type	Description
System.Int32

HotKeySpecifier

The specifier character for the hotkey (e.g. '_'). Set to '\xffff' to disable hotkey support for this View instance. The default is '\xffff'.

Declaration

public Rune HotKeySpecifier { get; set; }

Property Value

Type	Description
System.Rune

HotKeyTagMask

Specifies the mask to apply to the hotkey to tag it as the hotkey. The default value of 0x100000 causes the underlying Rune to be identified as a "private use" Unicode character.

Declaration

public uint HotKeyTagMask { get; set; }

Property Value

Type	Description
System.UInt32

Lines

Gets the formatted lines.

Declaration

public List<ustring> Lines { get; }

Property Value

Type	Description
System.Collections.Generic.List<NStack.ustring>

NeedsFormat

Gets or sets whether the TextFormatter needs to format the text when Draw(Rect, Attribute, Attribute, Rect, Boolean) is called. If it is false when Draw is called, the Draw call will be faster.

Declaration

public bool NeedsFormat { get; set; }

Property Value

Type	Description
System.Boolean

PreserveTrailingSpaces

Gets or sets a flag that determines whether Text will have trailing spaces preserved or not when WordWrap(ustring, Int32, Boolean, Int32, TextDirection) is enabled. If `true` any trailing spaces will be trimmed when either the Text property is changed or when WordWrap(ustring, Int32, Boolean, Int32, TextDirection) is set to `true`. The default is `false`.

Declaration

public bool PreserveTrailingSpaces { get; set; }

Property Value

Type	Description
System.Boolean

Size

Gets or sets the size of the area the text will be constrained to when formatted.

Declaration

public Size Size { get; set; }

Property Value

Type	Description
Size

Text

The text to be displayed. This text is never modified.

Declaration

public virtual ustring Text { get; set; }

Property Value

Type	Description
NStack.ustring

VerticalAlignment

Controls the vertical text-alignment property.

Declaration

public VerticalTextAlignment VerticalAlignment { get; set; }

Property Value

Type	Description
VerticalTextAlignment	The text vertical alignment.

Methods

CalcRect(Int32, Int32, ustring, TextDirection)

Calculates the rectangle required to hold text, assuming no word wrapping.

Declaration

public static Rect CalcRect(int x, int y, ustring text, TextDirection direction = TextDirection.LeftRight_TopBottom)

Parameters

Type	Name	Description
System.Int32	x	The x location of the rectangle
System.Int32	y	The y location of the rectangle
NStack.ustring	text	The text to measure
TextDirection	direction	The text direction.

Returns

Type	Description
Rect

ClipAndJustify(ustring, Int32, Boolean, TextDirection)

Justifies text within a specified width.

Declaration

public static ustring ClipAndJustify(ustring text, int width, bool justify, TextDirection textDirection = TextDirection.LeftRight_TopBottom)

Parameters

Type	Name	Description
NStack.ustring	text	The text to justify.
System.Int32	width	If the text length is greater that width it will be clipped.
System.Boolean	justify	Justify.
TextDirection	textDirection	The text direction.

Returns

Type	Description
NStack.ustring	Justified and clipped text.

ClipAndJustify(ustring, Int32, TextAlignment, TextDirection)

Justifies text within a specified width.

Declaration

public static ustring ClipAndJustify(ustring text, int width, TextAlignment talign, TextDirection textDirection = TextDirection.LeftRight_TopBottom)

Parameters

Type	Name	Description
NStack.ustring	text	The text to justify.
System.Int32	width	If the text length is greater that width it will be clipped.
TextAlignment	talign	Alignment.
TextDirection	textDirection	The text direction.

Returns

Type	Description
NStack.ustring	Justified and clipped text.

ClipOrPad(String, Int32)

Adds trailing whitespace or truncates text so that it fits exactly width console units. Note that some unicode characters take 2+ columns

Declaration

public static string ClipOrPad(string text, int width)

Parameters

Type	Name	Description
System.String	text
System.Int32	width

Returns

Type	Description
System.String

Draw(Rect, Attribute, Attribute, Rect, Boolean)

Draws the text held by TextFormatter to Driver using the colors specified.

Declaration

public void Draw(Rect bounds, Attribute normalColor, Attribute hotColor, Rect containerBounds = default(Rect), bool fillRemaining = true)

Parameters

Type	Name	Description
Rect	bounds	Specifies the screen-relative location and maximum size for drawing the text.
Attribute	normalColor	The color to use for all text except the hotkey
Attribute	hotColor	The color to use to draw the hotkey
Rect	containerBounds	Specifies the screen-relative location and maximum container size.
System.Boolean	fillRemaining	Determines if the bounds width will be used (default) or only the text width will be used.

FindHotKey(ustring, Rune, Boolean, out Int32, out Key)

Finds the hotkey and its location in text.

Declaration

public static bool FindHotKey(ustring text, Rune hotKeySpecifier, bool firstUpperCase, out int hotPos, out Key hotKey)

Parameters

Type	Name	Description
NStack.ustring	text	The text to look in.
System.Rune	hotKeySpecifier	The hotkey specifier (e.g. '_') to look for.
System.Boolean	firstUpperCase	If true the legacy behavior of identifying the first upper case character as the hotkey will be enabled. Regardless of the value of this parameter, hotKeySpecifier takes precedence.
System.Int32	hotPos	Outputs the Rune index into text.
Key	hotKey	Outputs the hotKey.

Returns

Type	Description
System.Boolean	true if a hotkey was found; false otherwise.

Format(ustring, Int32, Boolean, Boolean, Boolean, Int32, TextDirection)

Reformats text into lines, applying text alignment and optionally wrapping text to new lines on word boundaries.

Declaration

public static List<ustring> Format(ustring text, int width, bool justify, bool wordWrap, bool preserveTrailingSpaces = false, int tabWidth = 0, TextDirection textDirection = TextDirection.LeftRight_TopBottom)

Parameters

Type	Name	Description
NStack.ustring	text
System.Int32	width	The width to bound the text to for word wrapping and clipping.
System.Boolean	justify	Specifies whether the text should be justified.
System.Boolean	wordWrap	If true, the text will be wrapped to new lines as need. If false, forces text to fit a single line. Line breaks are converted to spaces. The text will be clipped to width
System.Boolean	preserveTrailingSpaces	If true and 'wordWrap' also true, the wrapped text will keep the trailing spaces. If false, the trailing spaces will be trimmed.
System.Int32	tabWidth	The tab width.
TextDirection	textDirection	The text direction.

Returns

Type	Description
System.Collections.Generic.List<NStack.ustring>	A list of word wrapped lines.

Format(ustring, Int32, TextAlignment, Boolean, Boolean, Int32, TextDirection)

Reformats text into lines, applying text alignment and optionally wrapping text to new lines on word boundaries.

Declaration

public static List<ustring> Format(ustring text, int width, TextAlignment talign, bool wordWrap, bool preserveTrailingSpaces = false, int tabWidth = 0, TextDirection textDirection = TextDirection.LeftRight_TopBottom)

Parameters

Type	Name	Description
NStack.ustring	text
System.Int32	width	The width to bound the text to for word wrapping and clipping.
TextAlignment	talign	Specifies how the text will be aligned horizontally.
System.Boolean	wordWrap	If true, the text will be wrapped to new lines as need. If false, forces text to fit a single line. Line breaks are converted to spaces. The text will be clipped to width
System.Boolean	preserveTrailingSpaces	If true and 'wordWrap' also true, the wrapped text will keep the trailing spaces. If false, the trailing spaces will be trimmed.
System.Int32	tabWidth	The tab width.
TextDirection	textDirection	The text direction.

Returns

Type	Description
System.Collections.Generic.List<NStack.ustring>	A list of word wrapped lines.

GetMaxColsForWidth(List<ustring>, Int32)

Gets the index position from the list based on the width.

Declaration

public static int GetMaxColsForWidth(List<ustring> lines, int width)

Parameters

Type	Name	Description
System.Collections.Generic.List<NStack.ustring>	lines	The lines.
System.Int32	width	The width.

Returns

Type	Description
System.Int32	The index of the list that fit the width.

GetMaxLengthForWidth(ustring, Int32)

Gets the index position from the text based on the width.

Declaration

public static int GetMaxLengthForWidth(ustring text, int width)

Parameters

Type	Name	Description
NStack.ustring	text	The text.
System.Int32	width	The width.

Returns

Type	Description
System.Int32	The index of the text that fit the width.

GetMaxLengthForWidth(List<Rune>, Int32)

Gets the index position from the list based on the width.

Declaration

public static int GetMaxLengthForWidth(List<Rune> runes, int width)

Parameters

Type	Name	Description
System.Collections.Generic.List<System.Rune>	runes	The runes.
System.Int32	width	The width.

Returns

Type	Description
System.Int32	The index of the list that fit the width.

GetSumMaxCharWidth(ustring, Int32, Int32)

Gets the maximum characters width from the text based on the startIndex and the length.

Declaration

public static int GetSumMaxCharWidth(ustring text, int startIndex = -1, int length = -1)

Parameters

Type	Name	Description
NStack.ustring	text	The text.
System.Int32	startIndex	The start index.
System.Int32	length	The length.

Returns

Type	Description
System.Int32	The maximum characters width.

GetSumMaxCharWidth(List<ustring>, Int32, Int32)

Gets the maximum characters width from the list based on the startIndex and the length.

Declaration

public static int GetSumMaxCharWidth(List<ustring> lines, int startIndex = -1, int length = -1)

Parameters

Type	Name	Description
System.Collections.Generic.List<NStack.ustring>	lines	The lines.
System.Int32	startIndex	The start index.
System.Int32	length	The length.

Returns

Type	Description
System.Int32	The maximum characters width.

GetTextWidth(ustring)

Gets the total width of the passed text.

Declaration

public static int GetTextWidth(ustring text)

Parameters

Type	Name	Description
NStack.ustring	text

Returns

Type	Description
System.Int32	The text width.

IsHorizontalDirection(TextDirection)

Check if it is a horizontal direction

Declaration

public static bool IsHorizontalDirection(TextDirection textDirection)

Parameters

Type	Name	Description
TextDirection	textDirection

Returns

Type	Description
System.Boolean

IsLeftToRight(TextDirection)

Check if it is Left to Right direction

Declaration

public static bool IsLeftToRight(TextDirection textDirection)

Parameters

Type	Name	Description
TextDirection	textDirection

Returns

Type	Description
System.Boolean

IsTopToBottom(TextDirection)

Check if it is Top to Bottom direction

Declaration

public static bool IsTopToBottom(TextDirection textDirection)

Parameters

Type	Name	Description
TextDirection	textDirection

Returns

Type	Description
System.Boolean

IsVerticalDirection(TextDirection)

Check if it is a vertical direction

Declaration

public static bool IsVerticalDirection(TextDirection textDirection)

Parameters

Type	Name	Description
TextDirection	textDirection

Returns

Type	Description
System.Boolean

Justify(ustring, Int32, Char, TextDirection)

Justifies the text to fill the width provided. Space will be added between words (demarked by spaces and tabs) to make the text just fit width. Spaces will not be added to the ends.

Declaration

public static ustring Justify(ustring text, int width, char spaceChar = ' ', TextDirection textDirection = TextDirection.LeftRight_TopBottom)

Parameters

Type	Name	Description
NStack.ustring	text
System.Int32	width
System.Char	spaceChar	Character to replace whitespace and pad with. For debugging purposes.
TextDirection	textDirection	The text direction.

Returns

Type	Description
NStack.ustring	The justified text.

MaxLines(ustring, Int32)

Computes the number of lines needed to render the specified text given the width.

Declaration

public static int MaxLines(ustring text, int width)

Parameters

Type	Name	Description
NStack.ustring	text	Text, may contain newlines.
System.Int32	width	The minimum width for the text.

Returns

Type	Description
System.Int32	Number of lines.

MaxWidth(ustring, Int32)

Computes the maximum width needed to render the text (single line or multiple lines) given a minimum width.

Declaration

public static int MaxWidth(ustring text, int width)

Parameters

Type	Name	Description
NStack.ustring	text	Text, may contain newlines.
System.Int32	width	The minimum width for the text.

Returns

Type	Description
System.Int32	Max width of lines.

MaxWidthLine(ustring)

Determines the line with the highest width in the text if it contains newlines.

Declaration

public static int MaxWidthLine(ustring text)

Parameters

Type	Name	Description
NStack.ustring	text	Text, may contain newlines.

Returns

Type	Description
System.Int32	The highest line width.

RemoveHotKeySpecifier(ustring, Int32, Rune)

Removes the hotkey specifier from text.

Declaration

public static ustring RemoveHotKeySpecifier(ustring text, int hotPos, Rune hotKeySpecifier)

Parameters

Type	Name	Description
NStack.ustring	text	The text to manipulate.
System.Int32	hotPos	Returns the position of the hot-key in the text. -1 if not found.
System.Rune	hotKeySpecifier	The hot-key specifier (e.g. '_') to look for.

Returns

Type	Description
NStack.ustring	The input text with the hotkey specifier ('_') removed.

ReplaceHotKeyWithTag(ustring, Int32)

Replaces the Rune at the index specified by the hotPos parameter with a tag identifying it as the hotkey.

Declaration

public ustring ReplaceHotKeyWithTag(ustring text, int hotPos)

Parameters

Type	Name	Description
NStack.ustring	text	The text to tag the hotkey in.
System.Int32	hotPos	The Rune index of the hotkey in text.

Returns

Type	Description
NStack.ustring	The text with the hotkey tagged.

SplitNewLine(ustring)

Splits all newlines in the text into a list and supports both CRLF and LF, preserving the ending newline.

Declaration

public static List<ustring> SplitNewLine(ustring text)

Parameters

Type	Name	Description
NStack.ustring	text	The text.

Returns

Type	Description
System.Collections.Generic.List<NStack.ustring>	A list of text without the newline characters.

WordWrap(ustring, Int32, Boolean, Int32, TextDirection)

Formats the provided text to fit within the width provided using word wrapping.

Declaration

public static List<ustring> WordWrap(ustring text, int width, bool preserveTrailingSpaces = false, int tabWidth = 0, TextDirection textDirection = TextDirection.LeftRight_TopBottom)

Parameters

Type	Name	Description
NStack.ustring	text	The text to word wrap
System.Int32	width	The width to contain the text to
System.Boolean	preserveTrailingSpaces	If true, the wrapped text will keep the trailing spaces. If false, the trailing spaces will be trimmed.
System.Int32	tabWidth	The tab width.
TextDirection	textDirection	The text direction.

Returns

Type	Description
System.Collections.Generic.List<NStack.ustring>	Returns a list of word wrapped lines.

Events

HotKeyChanged

Event invoked when the HotKey is changed.

Declaration

public event Action<Key> HotKeyChanged

Event Type

Type	Description
System.Action<Key>