mConsoleStyle module

Builds the escape sequences that change colours and text styles, move the cursor, clear the screen and set the window title, and shortens, aligns, wraps and cleans text.

Each function returns a String and writes nothing: the program passes the string to WriteTo or another output member. A sequence acts only when the console processes virtual-terminal sequences, which EnableVirtualTerminal turns on; in a console without that mode the characters of the sequence appear as text. The module needs no console and no cConsole object, so its functions also run in a program that has none.

The functions are written with the name of the module, as in mConsoleStyle.Bold. A function that takes no arguments is called with or without parentheses.

Dim s As String

s = mConsoleStyle.Colored("Hi", mConsoleStyle.FgRed)
Debug.Print Replace(s, Chr$(27), "<ESC>")
s = mConsoleStyle.ColoredRGB("Hi", 255, 128, 0, 0, 0, 64)
Debug.Print Replace(s, Chr$(27), "<ESC>")
Debug.Print Replace(mConsoleStyle.CursorPosition(5, 10), Chr$(27), "<ESC>")
' Output:
' <ESC>[31mHi<ESC>[0m
' <ESC>[38;2;255;128;0m<ESC>[48;2;0;0;64mHi<ESC>[0m
' <ESC>[5;10H

Known problems in version 0.0.0.0
Cursor movement
Clearing
Text styles
Colours
Scrolling
Window and screen
Styled text
Text helpers
Characters
See Also

The sequences of the first sections start with ESC [, the control sequence introducer, written below as CSI; ESC is the character with code 27. The text styles and colours stay in force until another sequence changes them, so a program ends a coloured text with Reset.

Dim con As New cConsole

If con.EnableVirtualTerminal() Then
    con.WriteLine mConsoleStyle.Bold & "Title" & mConsoleStyle.Reset
    con.WriteLine mConsoleStyle.Colored("Warning", mConsoleStyle.FgYellow)
    con.WriteTo mConsoleStyle.CursorUp(1) & mConsoleStyle.ClearLine()
End If
con.Restore

Known problems in version 0.0.0.0

RepeatStr repeats the first character of its string, not the string.
StripAnsi ends a sequence only at one of eight letters, so it also removes the text after the sequences that end in another letter, such as the one made by CursorHide.

Cursor movement

Cursor functions

Function	Returns	Moves
CursorUp ( [ n ] )	CSI n `A`	up n lines
CursorDown ( [ n ] )	CSI n `B`	down n lines
CursorForward ( [ n ] )	CSI n `C`	right n columns
CursorBack ( [ n ] )	CSI n `D`	left n columns
CursorNextLine ( [ n ] )	CSI n `E`	to the start of the line n lines down
CursorPrevLine ( [ n ] )	CSI n `F`	to the start of the line n lines up
CursorColumn ( n )	CSI n `G`	to column n of the current line
CursorPosition ( row , col )	CSI row `;` col `H`	to the row and the column
CursorSave	CSI `s`	saves the position of the cursor
CursorRestore	CSI `u`	goes to the saved position
CursorHide	CSI `?25l`	hides the cursor
CursorShow	CSI `?25h`	shows the cursor

n, row and col are Long values. n of the first six functions is optional and defaults to 1; CursorColumn has no default. The numbers of these sequences are counted from 1, whereas SetCursorPosition of cConsole counts from 0, takes the column first, and works on the screen buffer, not the window. CursorPosition takes the row first, as the sequence does. The value is written as it is: a negative number or 0 is not checked.

Clearing

ClearScreen, ClearLine

Syntax: ClearScreen ( [ mode ] ) As String

Syntax: ClearLine ( [ mode ] ) As String

mode: optional A Long. The default is 2. For ClearScreen: 0 clears from the cursor to the end of the screen, 1 from the start to the cursor, 2 the whole screen, and 3 the whole screen and the scrolled-off lines. For ClearLine: 0 clears from the cursor to the end of the line, 1 from the start of the line to the cursor, 2 the whole line.

ClearScreen returns CSI mode J and ClearLine returns CSI mode K. They differ from Clear and ClearLine of cConsole, which fill the screen buffer with the tracked colours through the console functions; the sequences clear with the colours that are in force. Whether a console honours mode 3 depends on the console.

Text styles

Style functions

Function	Returns	Effect
Reset	CSI `0m`	ends every colour and style
Bold	CSI `1m`	bold, or brighter colour
Dim_	CSI `2m`	dim text
Italic	CSI `3m`	italic
Underline	CSI `4m`	underlined text
Blink	CSI `5m`	blinking text
Reverse	CSI `7m`	swaps the text and background colours
Hidden	CSI `8m`	hidden text
Strikethrough	CSI `9m`	struck-through text

The function for dim text is called Dim_ because Dim is a keyword of the language. Which of these styles a console draws depends on the console: a console may show bold as a brighter colour, or ignore blinking and italics.

Colours

Colour functions

The 16 colours of the escape sequences. The foreground sequence ends in m and begins CSI; the number is the code in the table.

Colour	Foreground function	Code	Background function	Code
Black	FgBlack	30	BgBlack	40
Red	FgRed	31	BgRed	41
Green	FgGreen	32	BgGreen	42
Yellow	FgYellow	33	BgYellow	43
Blue	FgBlue	34	BgBlue	44
Magenta	FgMagenta	35	BgMagenta	45
Cyan	FgCyan	36	BgCyan	46
White	FgWhite	37	BgWhite	47
Default	FgDefault	39	BgDefault	49
Bright black	FgBrightBlack	90	BgBrightBlack	100
Bright red	FgBrightRed	91	BgBrightRed	101
Bright green	FgBrightGreen	92	BgBrightGreen	102
Bright yellow	FgBrightYellow	93	BgBrightYellow	103
Bright blue	FgBrightBlue	94	BgBrightBlue	104
Bright magenta	FgBrightMagenta	95	BgBrightMagenta	105
Bright cyan	FgBrightCyan	96	BgBrightCyan	106
Bright white	FgBrightWhite	97	BgBrightWhite	107

None of these functions has parameters. The order of the colours is that of the ANSI standard, not that of ConsoleColor, whose numbers are those of the Windows console attributes: ANSI red is 1 where ConsoleColor.DarkRed is 4. A program that uses both has to map the colours itself.

Fg256, Bg256, FgRGB, BgRGB

Syntax: Fg256 ( colorIndex ) As String

Syntax: Bg256 ( colorIndex ) As String

Syntax: FgRGB ( r , g , b ) As String

Syntax: BgRGB ( r , g , b ) As String

colorIndex: required A Long, 0 to 255, an index of the 256-colour palette of the console.
r, g, b: required Long values, 0 to 255, the red, green and blue parts of a 24-bit colour.

Fg256 returns CSI 38;5; colorIndex m and Bg256 CSI 48;5; colorIndex m. FgRGB returns CSI 38;2; r ; g ; b m and BgRGB CSI 48;2; r ; g ; b m. The numbers are written as given and not checked. A console that has no 256-colour or true-colour mode shows the nearest colour or ignores the sequence.

Scrolling

ScrollUp, ScrollDown

Syntax: ScrollUp ( [ n ] ) As String

Syntax: ScrollDown ( [ n ] ) As String

n: optional A Long, the number of lines. The default is 1.

ScrollUp returns CSI n S, which scrolls the text up, and ScrollDown returns CSI n T, which scrolls it down.

Window and screen

SetTitle

Returns the sequence that sets the title of the window.

Syntax: SetTitle ( title ) As String

title: required A String.

Returns ESC ] 0 ; title and the bell character (code 7). The title of the console window can also be set with the Title property of cConsole, which calls a Windows function and does not need the virtual-terminal mode.

AltScreenOn, AltScreenOff

Syntax: AltScreenOn As String

Syntax: AltScreenOff As String

AltScreenOn returns CSI ?1049h, which switches to the alternate screen buffer, a second screen that leaves the text of the main one intact; AltScreenOff returns CSI ?1049l, which switches back. The full-screen mode of cConsole does not use the alternate buffer. In a console with virtual-terminal processing on, AltScreenOn shows an empty screen, the text written afterwards goes to it, and AltScreenOff brings back the earlier text. A program that wants its picture to vanish when it ends writes AltScreenOn first and AltScreenOff last.

Hyperlink

Returns the sequence for a text that links to a web address.

Syntax: Hyperlink ( url , text ) As String

url: required A String, the address.
text: required A String, the visible text.

Returns ESC ] 8 ; ; url and the bell character, then text, then ESC ] 8 ; ; and the bell character. A console that supports this operating system command (OSC 8) shows text as a link; another console shows text only, or the characters of the sequence.

Styled text

Styled

Wraps text in a style and ends the style after it.

Syntax: Styled ( text , style ) As String

text: required A String.
style: required A String, the sequences to put before the text, such as mConsoleStyle.Bold & mConsoleStyle.FgCyan.

Returns style, text and Reset.

Colored

Wraps text in a foreground colour, and optionally a background colour, and ends them after it.

Syntax: Colored ( text , fgColor [ , bgColor ] ) As String

text: required A String.
fgColor: required A String, a foreground sequence such as mConsoleStyle.FgRed.
bgColor: optional A String, a background sequence. The default is an empty string, which leaves the background alone.

Returns fgColor, bgColor, text and Reset. The function does not check that the two strings are colour sequences; any strings are joined.

ColoredRGB

Wraps text in a true-colour foreground, and optionally a true-colour background.

Syntax: ColoredRGB ( text , fgR , fgG , fgB [ , bgR [ , bgG [ , bgB ] ] ] ) As String

text: required A String.
fgR, fgG, fgB: required Long values, 0 to 255, the foreground colour.
bgR, bgG, bgB: optional Long values, 0 to 255, the background colour. They default to -1. The background is used only when all three are 0 or more.

Returns FgRGB, the background sequence when all three background values are given, text, and Reset.

Text helpers

These functions count characters with Len, so they are correct for text that holds no escape sequences and no characters that the console draws double width. StripAnsi removes the sequences from a text first.

CenterText

Pads text to a width, with the text in the middle.

Syntax: CenterText ( text , width [ , fillChar ] ) As String

text: required A String.
width: required A Long, the length of the result.
fillChar: optional A String whose first character is used to pad. The default is a space.

Returns a string width characters long. The padding on the left is (width - Len(text)) \ 2 characters, and the rest goes to the right, so an odd amount of padding gives the extra character to the right. Text that is as long as width or longer is cut to width characters.

LeftAlign

Pads text on the right to a width.

Syntax: LeftAlign ( text , width [ , fillChar ] ) As String

Parameters as for CenterText. Text that is as long as width or longer is cut to width characters.

RightAlign

Pads text on the left to a width.

Syntax: RightAlign ( text , width [ , fillChar ] ) As String

Parameters as for CenterText. Text that is as long as width or longer is cut to its first width characters, not its last.

RepeatStr

Intended to repeat a string a number of times.

Syntax: RepeatStr ( s , count ) As String

s: required A String.
count: required A Long. A value of 0 or less returns an empty string.

The function is implemented with String$(count, s), which repeats only the first character of s. RepeatStr("ab", 3) therefore returns aaa, and not ababab. For a one-character s the result is as expected. To repeat a longer string, build it with a loop or with Replace(Space$(count), " ", s).

StripAnsi

Removes escape sequences from text.

Syntax: StripAnsi ( text ) As String

text: required A String.

The function drops every character from an ESC character up to and including the next letter among m, H, J, K, A, B, C and D, and returns the rest. That covers the colour and style sequences (they end in m) and the cursor positioning and clearing sequences of this module that end in one of those letters. A sequence that ends in another letter, such as l of CursorHide and h of CursorShow, s and u of the save and restore, S and T of the scroll functions, E, F and G of the line functions, ?1049h of AltScreenOn, or the bell character that ends SetTitle and Hyperlink, is not recognised: the function goes on dropping characters until it meets one of the eight letters, so some of the text that follows is lost too.

Debug.Print mConsoleStyle.StripAnsi(mConsoleStyle.Colored("Hello", mConsoleStyle.FgRed))
Debug.Print mConsoleStyle.StripAnsi(mConsoleStyle.CursorHide & "Hello")
Debug.Print mConsoleStyle.RepeatStr("ab", 3)
' Output:
' Hello
' ello
' aaa

The second line shows the loss: the sequence of CursorHide ends in l, so the function skips on to the H of Hello.

Truncate

Shortens text to a length, with a mark at the end.

Syntax: Truncate ( text , maxLen [ , ellipsis ] ) As String

text: required A String.
maxLen: required A Long, the longest result.
ellipsis: optional A String, the mark that shows the text was cut. The default is three periods.

Returns text when it is no longer than maxLen. Otherwise it returns the first maxLen - Len(ellipsis) characters of text followed by ellipsis; when maxLen is not larger than the length of ellipsis, it returns the first maxLen characters of ellipsis.

WordWrap

Breaks text into lines of at most a width, at spaces.

Syntax: WordWrap ( text , width ) As String

text: required A String.
width: required A Long, the longest line in characters.

Splits text at the space characters and joins the words into lines, with a line feed (code 10) between lines. A word that is longer than width is not broken; it is put on a line of its own. Other characters, such as line breaks inside text, count as part of a word.

Dim lines() As String
Dim i As Long

lines = Split(mConsoleStyle.WordWrap("one two three four", 9), vbLf)
For i = 0 To UBound(lines)
    Debug.Print "[" & mConsoleStyle.CenterText(lines(i), 9) & "]"
Next
' Output:
' [ one two ]
' [  three  ]
' [  four   ]

Characters

The module holds String constants for drawing text with characters that are not on the keyboard. Each is one character, and is written with the name of the module, as in mConsoleStyle.BOX_HORIZONTAL. The font of the console has to contain the character; otherwise the console draws a substitute.

Box-drawing characters

Single line		Double line
BOX_HORIZONTAL	U+2500	BOX_D_HORIZONTAL	U+2550
BOX_VERTICAL	U+2502	BOX_D_VERTICAL	U+2551
BOX_TOP_LEFT	U+250C	BOX_D_TOP_LEFT	U+2554
BOX_TOP_RIGHT	U+2510	BOX_D_TOP_RIGHT	U+2557
BOX_BOTTOM_LEFT	U+2514	BOX_D_BOTTOM_LEFT	U+255A
BOX_BOTTOM_RIGHT	U+2518	BOX_D_BOTTOM_RIGHT	U+255D
BOX_T_LEFT	U+251C	BOX_D_T_LEFT	U+2560
BOX_T_RIGHT	U+2524	BOX_D_T_RIGHT	U+2563
BOX_T_TOP	U+252C	BOX_D_T_TOP	U+2566
BOX_T_BOTTOM	U+2534	BOX_D_T_BOTTOM	U+2569
BOX_CROSS	U+253C	BOX_D_CROSS	U+256C

Block, progress and arrow characters

Constant	Code point	Constant	Code point
BLOCK_FULL	U+2588	ARROW_UP	U+2191
BLOCK_UPPER_HALF	U+2580	ARROW_DOWN	U+2193
BLOCK_LOWER_HALF	U+2584	ARROW_LEFT	U+2190
BLOCK_LEFT_HALF	U+258C	ARROW_RIGHT	U+2192
BLOCK_RIGHT_HALF	U+2590	ARROW_UP_DOWN	U+2195
BLOCK_LIGHT	U+2591	ARROW_LEFT_RIGHT	U+2194
BLOCK_MEDIUM	U+2592	PROGRESS_FILLED	U+2588
BLOCK_DARK	U+2593	PROGRESS_EMPTY	U+2591

Symbol characters

Constant	Code point	Constant	Code point
CHECK_MARK	U+2713	SQUARE	U+25A0
CROSS_MARK	U+2717	SQUARE_EMPTY	U+25A1
BULLET	U+2022	STAR	U+2605
DIAMOND	U+25C6	STAR_EMPTY	U+2606
CIRCLE	U+25CF	CIRCLE_EMPTY	U+25CB