Show / Hide Table of Contents

# Class TextFormatter

Provides text formatting capabilites for console apps. Supports, hotkeys, horizontal alignment, multille 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.

#### 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, TextAlignment, 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 constrainted 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 |

### Methods

#### CalcRect(Int32, Int32, ustring)

Calculates the rectangle requried 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, 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 eanbled. Regardless of the value of this parameter, `hotKeySpecifier` takes precidence.
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, TextAlignment, 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)

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

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

#### 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 justifed 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 multple lines) given a minimium 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 postion 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 specfiied 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)

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

##### Declaration

    public static List<ustring> WordWrap(ustring text, int width)

##### Parameters

Type | Name | Description
--- | --- | ---
NStack.ustring | text | The text to word wrap
System.Int32 | width | The width to contrain the text to

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