Search Results for

Show / Hide Table of Contents

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

##### Remarks

Upon a 'get' of this property, if the text needs to be formatted (if NeedsFormat is `true`) Format(ustring, Int32, Boolean, Boolean, Boolean, Int32) 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, 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)

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.

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

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

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)

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

##### 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, Int32)

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)

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

##### 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, Int32)

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)

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

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

### Events

#### HotKeyChanged

Event invoked when the HotKey is changed.

##### Declaration

    public event Action<Key> HotKeyChanged

##### Event Type

Type | Description
--- | ---
System.Action<Key> |