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 TextFormatterProperties
Alignment
Controls the horizontal text-alignment property.
Declaration
public TextAlignment Alignment { get; set; }Property Value
| Type | Description |
|---|---|
| TextAlignment | The text alignment. |
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> |
Remarks
Upon a 'get' of this property, if the text needs to be formatted (if NeedsFormat is true)
Format(ustring, Int32, Boolean, Boolean, Boolean) will be called internally.
NeedsFormat
Gets or sets whether the TextFormatter needs to format the text when Draw(Rect, Attribute, Attribute) 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 |
Remarks
This is set to true when the properties of TextFormatter are set.
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)
Calculates the rectangle required to hold text, assuming no word wrapping.
Declaration
public static Rect CalcRect(int x, int y, ustring text)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 |
Returns
| Type | Description |
|---|---|
| Rect |
ClipAndJustify(ustring, Int32, Boolean)
Justifies text within a specified width.
Declaration
public static ustring ClipAndJustify(ustring text, int width, bool justify)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. |
Returns
| Type | Description |
|---|---|
| NStack.ustring | Justified and clipped text. |
ClipAndJustify(ustring, Int32, TextAlignment)
Justifies text within a specified width.
Declaration
public static ustring ClipAndJustify(ustring text, int width, TextAlignment talign)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. |
Returns
| Type | Description |
|---|---|
| NStack.ustring | Justified and clipped text. |
Draw(Rect, Attribute, Attribute)
Draws the text held by TextFormatter to Driver using the colors specified.
Declaration
public void Draw(Rect bounds, Attribute normalColor, Attribute hotColor)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 |
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)
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)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. |
Returns
| Type | Description |
|---|---|
| System.Collections.Generic.List<NStack.ustring> | A list of word wrapped lines. |
Remarks
An empty text string will result in one empty line.
If width is 0, a single, empty line will be returned.
If width is int.MaxValue, the text will be formatted to the maximum width possible.
Format(ustring, Int32, TextAlignment, Boolean, Boolean)
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)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. |
Returns
| Type | Description |
|---|---|
| System.Collections.Generic.List<NStack.ustring> | A list of word wrapped lines. |
Remarks
An empty text string will result in one empty line.
If width is 0, a single, empty line will be returned.
If width is int.MaxValue, the text will be formatted to the maximum width possible.
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)
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 = ' ')Parameters
| Type | Name | Description |
|---|---|---|
| NStack.ustring | text | |
| System.Int32 | width | |
| System.Char | spaceChar | Character to replace whitespace and pad with. For debugging purposes. |
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. |
Remarks
The returned string will not render correctly without first un-doing the tag. To undo the tag, search for
Runes with a bitmask of
otKeyTagMask and remove that bitmask.
WordWrap(ustring, Int32, Boolean)
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)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. |
Returns
| Type | Description |
|---|---|
| System.Collections.Generic.List<NStack.ustring> | Returns a list of word wrapped lines. |
Remarks
This method does not do any justification.
This method strips Newline ('\n' and '\r\n') sequences before processing.