Class TextFormatter

Provides text formatting capabilities for console apps. Supports, hotkeys, horizontal alignment, multiple lines, and word-based line wrap.
Inheritance
System.Object
TextFormatter
Namespace: Terminal.Gui
Assembly: Terminal.Gui.dll
Syntax
public class TextFormatter : Object

Constructors

TextFormatter()

Declaration
public 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) 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)
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)
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)
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)

Draws the text held by TextFormatter to Driver using the colors specified.
Declaration
public void Draw(Rect bounds, Attribute normalColor, Attribute hotColor, Rect containerBounds = null)
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.

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

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.

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)
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>