using System; using System.Collections.Generic; using System.Globalization; using System.Linq; using NStack; namespace Terminal.Gui { /// /// Text alignment enumeration, controls how text is displayed. /// public enum TextAlignment { /// /// Aligns the text to the left of the frame. /// Left, /// /// Aligns the text to the right side of the frame. /// Right, /// /// Centers the text in the frame. /// Centered, /// /// Shows the text as justified text in the frame. /// Justified } /// /// Provides text formatting capabilities for console apps. Supports, hotkeys, horizontal alignment, multille lines, and word-based line wrap. /// public class TextFormatter { List lines = new List (); ustring text; TextAlignment textAlignment; Attribute textColor = -1; bool needsFormat; Key hotKey; Size size; /// /// The text to be displayed. This text is never modified. /// public virtual ustring Text { get => text; set { text = value; if (text.RuneCount > 0 && (Size.Width == 0 || Size.Height == 0 || Size.Width != text.RuneCount)) { // Proivde a default size (width = length of longest line, height = 1) // TODO: It might makem more sense for the default to be width = length of first line? Size = new Size (TextFormatter.MaxWidth (Text, int.MaxValue), 1); } NeedsFormat = true; } } // TODO: Add Vertical Text Alignment /// /// Controls the horizontal text-alignment property. /// /// The text alignment. public TextAlignment Alignment { get => textAlignment; set { textAlignment = value; NeedsFormat = true; } } /// /// Gets or sets the size of the area the text will be constrainted to when formatted. /// public Size Size { get => size; set { size = value; NeedsFormat = true; } } /// /// The specifier character for the hotkey (e.g. '_'). Set to '\xffff' to disable hotkey support for this View instance. The default is '\xffff'. /// public Rune HotKeySpecifier { get; set; } = (Rune)0xFFFF; /// /// The position in the text of the hotkey. The hotkey will be rendered using the hot color. /// public int HotKeyPos { get => hotKeyPos; set => hotKeyPos = value; } /// /// Gets the hotkey. Will be an upper case letter or digit. /// public Key HotKey { get => hotKey; internal set => hotKey = value; } /// /// 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. /// HotKeyTagMask public uint HotKeyTagMask { get; set; } = 0x100000; /// /// Gets the formatted lines. /// /// /// /// Upon a 'get' of this property, if the text needs to be formatted (if is true) /// will be called internally. /// /// public List Lines { get { // With this check, we protect against subclasses with overrides of Text if (ustring.IsNullOrEmpty (Text)) { lines = new List (); lines.Add (ustring.Empty); NeedsFormat = false; return lines; } if (NeedsFormat) { var shown_text = text; if (FindHotKey (text, HotKeySpecifier, true, out hotKeyPos, out hotKey)) { shown_text = RemoveHotKeySpecifier (Text, hotKeyPos, HotKeySpecifier); shown_text = ReplaceHotKeyWithTag (shown_text, hotKeyPos); } if (Size.IsEmpty) { throw new InvalidOperationException ("Size must be set before accessing Lines"); } lines = Format (shown_text, Size.Width, textAlignment, Size.Height > 1); NeedsFormat = false; } return lines; } } /// /// Gets or sets whether the needs to format the text when is called. /// If it is false when Draw is called, the Draw call will be faster. /// /// /// /// This is set to true when the properties of are set. /// /// public bool NeedsFormat { get => needsFormat; set => needsFormat = value; } static ustring StripCRLF (ustring str) { var runes = str.ToRuneList (); for (int i = 0; i < runes.Count; i++) { switch (runes [i]) { case '\n': runes.RemoveAt (i); break; case '\r': if ((i + 1) < runes.Count && runes [i + 1] == '\n') { runes.RemoveAt (i); runes.RemoveAt (i + 1); i++; } else { runes.RemoveAt (i); } break; } } return ustring.Make (runes); } static ustring ReplaceCRLFWithSpace (ustring str) { var runes = str.ToRuneList (); for (int i = 0; i < runes.Count; i++) { switch (runes [i]) { case '\n': runes [i] = (Rune)' '; break; case '\r': if ((i + 1) < runes.Count && runes [i + 1] == '\n') { runes [i] = (Rune)' '; runes.RemoveAt (i + 1); i++; } else { runes [i] = (Rune)' '; } break; } } return ustring.Make (runes); ; } /// /// Formats the provided text to fit within the width provided using word wrapping. /// /// The text to word wrap /// The width to contrain the text to /// Returns a list of word wrapped lines. /// /// /// This method does not do any justification. /// /// /// This method strips Newline ('\n' and '\r\n') sequences before processing. /// /// public static List WordWrap (ustring text, int width) { if (width < 0) { throw new ArgumentOutOfRangeException ("Width cannot be negative."); } int start = 0, end; var lines = new List (); if (ustring.IsNullOrEmpty (text)) { return lines; } var runes = StripCRLF (text).ToRuneList (); while ((end = start + width) < runes.Count) { while (runes [end] != ' ' && end > start) end -= 1; if (end == start) end = start + width; lines.Add (ustring.Make (runes.GetRange (start, end - start))); start = end; if (runes[end] == ' ') { start++; } } if (start < text.RuneCount) { lines.Add (ustring.Make (runes.GetRange (start, runes.Count - start))); } return lines; } /// /// Justifies text within a specified width. /// /// The text to justify. /// If the text length is greater that width it will be clipped. /// Alignment. /// Justified and clipped text. public static ustring ClipAndJustify (ustring text, int width, TextAlignment talign) { if (width < 0) { throw new ArgumentOutOfRangeException ("Width cannot be negative."); } if (ustring.IsNullOrEmpty (text)) { return text; } var runes = text.ToRuneList (); int slen = runes.Count; if (slen > width) { return ustring.Make (runes.GetRange (0, width)); } else { if (talign == TextAlignment.Justified) { return Justify (text, width); } return text; } } /// /// 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. /// /// /// /// Character to replace whitespace and pad with. For debugging purposes. /// The justifed text. public static ustring Justify (ustring text, int width, char spaceChar = ' ') { if (width < 0) { throw new ArgumentOutOfRangeException ("Width cannot be negative."); } if (ustring.IsNullOrEmpty (text)) { return text; } var words = text.Split (ustring.Make (' ')); int textCount = words.Sum (arg => arg.RuneCount); var spaces = words.Length > 1 ? (width - textCount) / (words.Length - 1) : 0; var extras = words.Length > 1 ? (width - textCount) % words.Length : 0; var s = new System.Text.StringBuilder (); for (int w = 0; w < words.Length; w++) { var x = words [w]; s.Append (x); if (w + 1 < words.Length) for (int i = 0; i < spaces; i++) s.Append (spaceChar); if (extras > 0) { extras--; } } return ustring.Make (s.ToString ()); } static char [] whitespace = new char [] { ' ', '\t' }; private int hotKeyPos; /// /// Reformats text into lines, applying text alignment and optionally wrapping text to new lines on word boundaries. /// /// /// The width to bound the text to for word wrapping and clipping. /// Specifies how the text will be aligned horizontally. /// 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 /// A list of word wrapped lines. /// /// /// 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. /// /// public static List Format (ustring text, int width, TextAlignment talign, bool wordWrap) { if (width < 0) { throw new ArgumentOutOfRangeException ("width cannot be negative"); } List lineResult = new List (); if (ustring.IsNullOrEmpty (text) || width == 0) { lineResult.Add (ustring.Empty); return lineResult; } if (wordWrap == false) { text = ReplaceCRLFWithSpace (text); lineResult.Add (ClipAndJustify (text, width, talign)); return lineResult; } var runes = text.ToRuneList (); int runeCount = runes.Count; int lp = 0; for (int i = 0; i < runeCount; i++) { Rune c = runes [i]; if (c == '\n') { var wrappedLines = WordWrap (ustring.Make (runes.GetRange (lp, i - lp)), width); foreach (var line in wrappedLines) { lineResult.Add (ClipAndJustify (line, width, talign)); } if (wrappedLines.Count == 0) { lineResult.Add (ustring.Empty); } lp = i + 1; } } foreach (var line in WordWrap (ustring.Make (runes.GetRange (lp, runeCount - lp)), width)) { lineResult.Add (ClipAndJustify (line, width, talign)); } return lineResult; } /// /// Computes the number of lines needed to render the specified text given the width. /// /// Number of lines. /// Text, may contain newlines. /// The minimum width for the text. public static int MaxLines (ustring text, int width) { var result = TextFormatter.Format (text, width, TextAlignment.Left, true); return result.Count; } /// /// Computes the maximum width needed to render the text (single line or multple lines) given a minimum width. /// /// Max width of lines. /// Text, may contain newlines. /// The minimum width for the text. public static int MaxWidth (ustring text, int width) { var result = TextFormatter.Format (text, width, TextAlignment.Left, true); return result.Max (s => s.RuneCount); } /// /// Calculates the rectangle required to hold text, assuming no word wrapping. /// /// The x location of the rectangle /// The y location of the rectangle /// The text to measure /// public static Rect CalcRect (int x, int y, ustring text) { if (ustring.IsNullOrEmpty (text)) return new Rect (new Point (x, y), Size.Empty); int mw = 0; int ml = 1; int cols = 0; foreach (var rune in text) { if (rune == '\n') { ml++; if (cols > mw) mw = cols; cols = 0; } else { if (rune != '\r') { cols++; } } } if (cols > mw) mw = cols; return new Rect (x, y, mw, ml); } /// /// Finds the hotkey and its location in text. /// /// The text to look in. /// The hotkey specifier (e.g. '_') to look for. /// 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. /// Outputs the Rune index into text. /// Outputs the hotKey. /// true if a hotkey was found; false otherwise. public static bool FindHotKey (ustring text, Rune hotKeySpecifier, bool firstUpperCase, out int hotPos, out Key hotKey) { if (ustring.IsNullOrEmpty (text) || hotKeySpecifier == (Rune)0xFFFF) { hotPos = -1; hotKey = Key.Unknown; return false; } Rune hot_key = (Rune)0; int hot_pos = -1; // Use first hot_key char passed into 'hotKey'. // TODO: Ignore hot_key of two are provided // TODO: Do not support non-alphanumeric chars that can't be typed int i = 0; foreach (Rune c in text) { if ((char)c != 0xFFFD) { if (c == hotKeySpecifier) { hot_pos = i; } else if (hot_pos > -1) { hot_key = c; break; } } i++; } // Legacy support - use first upper case char if the specifier was not found if (hot_pos == -1 && firstUpperCase) { i = 0; foreach (Rune c in text) { if ((char)c != 0xFFFD) { if (Rune.IsUpper (c)) { hot_key = c; hot_pos = i; break; } } i++; } } if (hot_key != (Rune)0 && hot_pos != -1) { hotPos = hot_pos; if (hot_key.IsValid && char.IsLetterOrDigit ((char)hot_key)) { hotKey = (Key)char.ToUpperInvariant ((char)hot_key); return true; } } hotPos = -1; hotKey = Key.Unknown; return false; } /// /// Replaces the Rune at the index specfiied by the hotPos parameter with a tag identifying /// it as the hotkey. /// /// The text to tag the hotkey in. /// The Rune index of the hotkey in text. /// The text with the hotkey tagged. /// /// 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. /// public ustring ReplaceHotKeyWithTag (ustring text, int hotPos) { // Set the high bit var runes = text.ToRuneList (); if (Rune.IsLetterOrNumber (runes [hotPos])) { runes [hotPos] = new Rune ((uint)runes [hotPos] | HotKeyTagMask); } return ustring.Make (runes); } /// /// Removes the hotkey specifier from text. /// /// The text to manipulate. /// The hot-key specifier (e.g. '_') to look for. /// Returns the position of the hot-key in the text. -1 if not found. /// The input text with the hotkey specifier ('_') removed. public static ustring RemoveHotKeySpecifier (ustring text, int hotPos, Rune hotKeySpecifier) { if (ustring.IsNullOrEmpty (text)) { return text; } // Scan ustring start = ustring.Empty; int i = 0; foreach (Rune c in text) { if (c == hotKeySpecifier && i == hotPos) { i++; continue; } start += ustring.Make (c); i++; } return start; } /// /// Draws the text held by to using the colors specified. /// /// Specifies the screen-relative location and maximum size for drawing the text. /// The color to use for all text except the hotkey /// The color to use to draw the hotkey public void Draw (Rect bounds, Attribute normalColor, Attribute hotColor) { // With this check, we protect against subclasses with overrides of Text (like Button) if (ustring.IsNullOrEmpty (text)) { return; } Application.Driver?.SetAttribute (normalColor); // Use "Lines" to ensure a Format (don't use "lines")) for (int line = 0; line < Lines.Count; line++) { if (line > bounds.Height) continue; var runes = lines [line].ToRunes (); int x; switch (textAlignment) { case TextAlignment.Left: x = bounds.Left; break; case TextAlignment.Justified: x = bounds.Left; break; case TextAlignment.Right: x = bounds.Right - runes.Length; break; case TextAlignment.Centered: x = bounds.Left + (bounds.Width - runes.Length) / 2; break; default: throw new ArgumentOutOfRangeException (); } for (var col = bounds.Left; col < bounds.Left + bounds.Width; col++) { Application.Driver?.Move (col, bounds.Top + line); var rune = (Rune)' '; if (col >= x && col < (x + runes.Length)) { rune = runes [col - x]; } if ((rune & HotKeyTagMask) == HotKeyTagMask) { Application.Driver?.SetAttribute (hotColor); Application.Driver?.AddRune ((Rune)((uint)rune & ~HotKeyTagMask)); Application.Driver?.SetAttribute (normalColor); } else { Application.Driver?.AddRune (rune); } } } } } }