VT — Virtual Text Screen Library

DOS-style text screen for FreeBASIC. Two backends: an SDL2 windowed renderer (full feature set) and a headless TTY renderer for direct terminal output (no SDL2 needed). Single include, QBasic-feel API. Target: Windows, Linux, FreeBASIC 1.10.1.

' SDL2 backend (default — full features, requires SDL2.dll):
#include once "vt/vt.bi"

' TTY backend (no SDL2, outputs to terminal — experimental):
#Define VT_TTY
#include once "vt/vt.bi"

Table of Contents

Quick Start

' Minimal hello-world program.
#include once "vt/vt.bi"

vt_title "Hello"
vt_screen VT_SCREEN_0       ' 80x25, 8x16 font

vt_color VT_YELLOW, VT_BLACK
vt_print_center 12, "Hello, World!"

vt_color VT_LIGHT_GREY, VT_BLACK
vt_print_center 14, "Press any key..."
vt_present()

vt_sleep 0   ' wait for keypress

Backends

VT selects a rendering backend at compile time via a #Define placed before the include. Without any define the SDL2 backend is used.

Backend Defines

VT_TTY — Headless Terminal Backend

The TTY backend uses ANSI escape sequences to render the cell grid directly in the calling terminal. It shares the same API as the SDL2 backend; functions that have no TTY equivalent silently return -1 or no-op.

Platform support

Functions unavailable in TTY mode

Minimal TTY example

' Compile with: fbc -d VT_TTY myprogram.bas
#Define VT_TTY
#include once "vt/vt.bi"

vt_screen VT_SCREEN_0
vt_cls()
vt_color VT_BRIGHT_GREEN
vt_locate 1, 1
vt_print "Hello from TTY!"
vt_color VT_YELLOW
vt_locate 3, 1
vt_print "Your name: "
vt_present()
Dim s As String = vt_input(20)
vt_locate 5, 1
vt_print "Got: " & s
vt_present()
vt_sleep 0
vt_shutdown()

Screen Modes

Passed as the mode argument to vt_screen.

VT_SCREEN_TILES uses the 8x8 font data scaled to 16x16 glyphs; useful for tile-based games where square cells are desirable.

Window Flags

Passed as the flags argument to vt_screen. Combine with Or.

Color Constants

Used with vt_color, vt_cls, vt_set_cell, etc. These are values of the VT_COLOR_IDX enum (0–15). OR any foreground color with VT_BLINK to enable character blinking.

' Example: blinking white text on blue:
vt_color VT_WHITE Or VT_BLINK, VT_BLUE

Key Macros

vt_inkey and vt_getkey return a packed ULong. Use these macros to extract fields from it.

' Typical usage pattern:
Dim k As ULong = vt_getkey()

Select Case VT_SCAN(k)
    Case VT_KEY_UP    : ' move up
    Case VT_KEY_DOWN  : ' move down
    Case VT_KEY_ENTER : ' confirm
    Case Else
        If VT_CHAR(k) = Asc("q") Then End
End Select

Key Scancodes

Compare these against VT_SCAN(k). Never compare them directly against the raw key value returned by vt_inkey.

Mouse Button Constants

Bitmask values returned in the btns parameter of vt_getmouse.

Copy/Paste Flags

Passed to vt_copypaste. Combinable with Or.

Miscellaneous Constants

Math Macros opt-in

Available when #define VT_USE_MATH is placed before #include once "vt/vt.bi". See the Math section for the full function reference.

Sound Constants opt-in

Available when #define VT_USE_SOUND is placed before #include once "vt/vt.bi". See the Sound section for full details.

Waveforms — passed as the wave parameter to vt_sound

Blocking mode — passed as the blocking parameter to vt_sound

Sort Constants opt-in

Available when #define VT_USE_SORT is placed before #include once "vt/vt.bi". See the Sort section for the full function reference.

TUI Constants opt-in

Available when #define VT_USE_TUI is placed before #include once "vt/vt.bi". See the TUI Widgets section for the full function reference.

Return codes — VT_TUI_RET enum

Returned by vt_tui_dialog and used as .ret values in form items.

Dialog button set flags — passed to vt_tui_dialog

Widget flags

Form item kinds — used in the vt_tui_form_item type

Form return codes — returned by vt_tui_form_handle

Menu return value extraction macros

vt_tui_menubar_handle returns group * 1000 + item_index (both 1-based) when an item is activated, or 0 while idle or after Escape closes a dropdown.

' File=group 1, Edit=group 2
' File/Open = 1002,  Edit/Copy = 2002
Select Case VT_TUI_MENU_GROUP(r)
    Case 1  ' File
        Select Case VT_TUI_MENU_ITEM(r)
            Case 1 : ' New
            Case 2 : ' Open
        End Select
    Case 2  ' Edit
        Select Case VT_TUI_MENU_ITEM(r)
            Case 1 : ' Cut
            Case 2 : ' Copy
        End Select
End Select

Initialization

• vt_screen — open / reopen the window
• vt_scrollback — allocate scrollback buffer
• vt_shutdown — explicit teardown
• vt_title — set the window title
• vt_on_close — intercept the [X] close button

vt_screen

Open or reopen the virtual text screen. Calling it again closes and reinitializes with the new settings.

Return value

vt_scrollback

Allocate (or resize, or disable) the scrollback history buffer. Must be called after vt_screen. Calling it again clears any existing history.

vt_shutdown

Explicitly tear down the VT screen and free all SDL resources. This is optional: on normal program exit, SDL cleans itself up. Use it when you need to close the window mid-program.

vt_title

Set the window title. Safe to call before or after vt_screen. Before: the title is stored and applied when the window is created. After: applied immediately to the live window.

vt_on_close

Register a callback function that is invoked when the user clicks the window [X] button. Without a callback the default behaviour is to shut down immediately and call End — the program exits with no chance to intervene. With a callback registered the library calls your function first and acts on the return value.

Callback return value

' Declare the callback with the exact signature:
Function on_close() As Byte
    ' Ask the user before closing:
    vt_color VT_BLACK, VT_LIGHT_GREY
    vt_locate 25, 1
    vt_print "  Unsaved changes!  Quit? (Y/N)" & String(48, " ")
    vt_present()

    Dim ans As String = vt_getchar("YyNn")
    If LCase(ans) = "y" Then Return 0   ' allow close

    ' Restore UI and veto:
    draw_statusbar()
    vt_present()
    Return 1
End Function

' Register after vt_screen:
vt_screen VT_SCREEN_0
vt_on_close(@on_close)

' Remove callback (restore default auto-close):
vt_on_close(0)

Display

• vt_border_color — letterbox fill colour
• vt_present — flip to screen

vt_border_color

Set the colour of the letterbox bars that appear outside the logical viewport in windowed or fullscreen-aspect modes. Default is black (0, 0, 0).

vt_present

Composite the visible page and flip it to the screen. Always renders the visible page (vis_page), which may differ from the active drawing page when using multi-page mode. You are responsible for calling this; drawing functions such as vt_print and vt_cls do not call it automatically.

Printing & Cursor

• vt_cls — clear screen
• vt_color — set active colour
• vt_locate — move cursor
• vt_print — print string
• vt_print_center — print centered
• vt_scroll_enable — enable / disable auto-scroll

vt_cls

Clear the active scroll region to spaces using the current foreground and background colours. Resets the cursor to row 1, column 1 of the scroll region. Does not call vt_present.

vt_color

Set the active foreground and/or background colour used by vt_print, vt_cls, and vt_input.

' Set only foreground, leave background unchanged:
vt_color VT_BRIGHT_GREEN

' Set both:
vt_color VT_WHITE, VT_BLUE

' Blinking foreground:
vt_color VT_RED Or VT_BLINK, VT_BLACK

vt_locate

Move the text cursor and optionally change its visibility and glyph. Coordinates are 1-based. Parameters with value -1 are left unchanged.

vt_print

Print a string at the current cursor position using the active colour. The cursor advances after each character; the display is not automatically flipped. There is no implicit newline — use VT_NEWLINE (Chr(10)) within the string for line breaks. CRLF pairs are collapsed to a single line feed.

' Position, colour, print, flip:
vt_locate 5, 1
vt_color VT_CYAN, VT_BLACK
vt_print "Line one" & VT_NEWLINE & "Line two"
vt_present()

vt_print_center

Print a string horizontally centered on the given screen row. Uses the current colour and does not call vt_present.

vt_scroll_enable

Enable or disable automatic scrolling of the scroll region. When disabled, text printed past the bottom of the scroll region stays on the last row. Scroll is enabled by default.

Cell Access

• vt_get_cell — read one character cell
• vt_set_cell — write one character cell

vt_get_cell

Read the character, foreground colour, and background colour of a single cell on the active work page. Coordinates are 1-based. Out-of-range coordinates are ignored.

vt_set_cell

Write a character cell directly on the active work page without moving the cursor. Does not call vt_present. Out-of-range coordinates are silently ignored.

Scroll Region & Scrollback

• vt_scroll — move scrollback view
• vt_screen_to_live_row — map screen row during scrollback
• vt_view_print — restrict scroll region

vt_scroll

Move the scrollback view by a number of lines. Positive values scroll toward older history; negative values scroll toward the live view. Scrollback must be enabled with vt_scrollback first. Does not call vt_present.

Return value

vt_screen_to_live_row

Translate a screen row number to the corresponding live buffer row while the scrollback view is offset. Useful when implementing click-to-locate functionality: call this before snapping back to the live view with vt_scroll(-99999).

Return value

' Click-to-locate pattern during scrollback:
Dim lr As Long = vt_screen_to_live_row(clicked_row)
If lr > 0 Then
    vt_scroll -99999   ' snap back to live
    vt_locate lr, clicked_col
End If

vt_view_print

Restrict the scroll region and print region to a range of rows (like QBasic's VIEW PRINT). Rows outside this range are unaffected by vt_cls, vt_print, and scrolling. Call with no arguments (or both -1) to reset to the full screen.

Internal Keyboard Bindings

VT intercepts certain key combinations internally before they reach your program. These bindings are hardwired into the event pump and require no setup. Which keys are active depends on the active backend and, in TTY mode, on the host environment.

Scrollback navigation

Scrollback must be enabled with vt_scrollback for these to have any effect. Any key not listed below exits scrollback and returns to the live view.

Copy / Paste

Available only in SDL2 mode when vt_copypaste has been called to enable it. These keys are never intercepted in TTY mode.

Alt+letter (TUI menubar)

Used by vt_tui_menubar_draw to open a menu group by its first letter. VT delivers these as a keyrec with VT_ALT(k) = 1 and VT_CHAR(k) set to the letter. The detection method is backend-dependent but transparent to your code:

Pages

• vt_page — set draw and display page
• vt_pcopy — copy one page to another

Pages are separate full-screen cell buffers. Multiple pages are allocated at vt_screen time via the pages argument. Page 0 (VT_VIDEO) is always the startup visible page. Up to 8 pages are supported (indices 0–7).

vt_page

Set the active drawing page and the visible display page independently. All drawing commands write to the work page; vt_present reads from the vis page. Invalid indices are silently ignored.

' Classic double-buffer setup: draw on page 1, display page 0.
vt_page 1, VT_VIDEO
' ... draw freely on page 1 ...
vt_pcopy 1, VT_VIDEO   ' push finished frame to page 0
vt_present()
' Swap back when done:
vt_page VT_VIDEO, VT_VIDEO

vt_pcopy

Copy one page buffer to another (equivalent to QBasic PCOPY). Marks the display dirty but does not call vt_present. src = dst is a no-op. Invalid indices are silently ignored.

Palette

• vt_palette — set one colour or reset all
• vt_palette_get — read all 16 colours into an array
• vt_palette_set — write all 16 colours from an array

The palette is a flat array of 48 bytes: 16 colours × 3 channels (R, G, B). Entry idx starts at byte idx * 3. The default is the CGA palette.

vt_palette

Set a single palette entry, or reset all 16 colours to CGA defaults.

' Replace colour index 4 (Red) with a custom orange:
vt_palette 4, 220, 120, 0

' Reset all 16 colours back to CGA defaults:
vt_palette

vt_palette_get

Bulk-read all 16 palette entries into a caller-supplied UByte array of at least 48 elements.

vt_palette_set

Bulk-write all 16 palette entries from a caller-supplied UByte array of 48 elements.

Screen Query

• vt_cols — screen column count
• vt_csrlin — current cursor row
• vt_pos — current cursor column
• vt_rows — screen row count

vt_cols

Returns the total number of columns in the current screen mode.

vt_csrlin

Returns the current cursor row (1-based).

vt_pos

Returns the current cursor column (1-based).

vt_rows

Returns the total number of rows in the current screen mode.

Keyboard

• vt_getchar — blocking printable character
• vt_getkey — blocking key read
• vt_inkey — non-blocking key read
• vt_input — blocking line editor
• vt_key_flush — discard pending keys
• vt_key_held — real-time key state
• vt_key_repeat — configure key repeat timing
• vt_pump — manual event drain
• vt_sleep — delay or wait for key

vt_getchar

Block until a printable character (ASCII 32–255) is pressed. If allowed is non-empty, only characters within that string are accepted; all others are discarded silently. Returns the accepted character as a one-character String.

Return value

' Accept only Y or N:
vt_print "Continue? (Y/N) "
vt_present()
Dim ans As String = UCase(vt_getchar("YyNn"))

vt_getkey

Block until any key (including non-printable and special keys) is pressed. Returns the same packed ULong format as vt_inkey; use the VT_SCAN / VT_CHAR / VT_SHIFT / VT_CTRL / VT_ALT macros to extract fields.

Return value

vt_inkey

Non-blocking key read. Returns the next key from the buffer, or 0 if no key is pending. Also pumps events, updates blink, and calls vt_present if the display is dirty (throttled to 2 ms).

Return value

' Game loop pattern:
Do
    Dim k As ULong = vt_inkey()
    If VT_SCAN(k) = VT_KEY_ESC Then Exit Do
    ' ... update and draw ...
    vt_present()
    Sleep 16, 1
Loop

vt_input

Full-featured blocking single-line text editor at the current cursor position. Supports navigation (Home, End, Left, Right), insertion, deletion (Backspace, Del), and clipboard paste when copy/paste is enabled. Returns the entered string on Enter, or an empty string on Escape.

Return value

' Prompt with pre-filled default, numeric only, detect cancel:
Dim esc As Byte
vt_locate 10, 1
vt_print "Enter amount: "
vt_present()
Dim amount As String = vt_input(8, "0", "0123456789.", @esc)
If esc Then
    vt_print "Cancelled" & VT_NEWLINE
Else
    vt_print "Got: " & amount & VT_NEWLINE
End If
vt_present()

vt_key_flush

Discard all keys currently waiting in the internal key buffer.

vt_key_held

Poll the real-time state of a key. Returns 1 if the key is physically held down at the time of the call. Useful for smooth movement in game loops where event-based repeat is not fast enough. Accepts the same VT_KEY_* scancode constants used with VT_SCAN.

Return value

' Smooth movement example:
If vt_key_held(VT_KEY_LEFT)  Then x -= 1
If vt_key_held(VT_KEY_RIGHT) Then x += 1

vt_key_repeat

Configure the timing of auto-repeat events generated when a key is held down. Default: 400 ms initial delay, 30 ms repeat rate. Set either value to 0 to disable the corresponding phase of repeat.

vt_pump

Manually drain the SDL event queue. Normally called automatically by vt_inkey, vt_present, and vt_sleep. Rarely needed directly — useful in tight loops that never call any of those. Re-entrant safe (a second call while inside returns immediately).

vt_sleep

Delay for a fixed number of milliseconds, or wait indefinitely for any keypress. Keeps the display alive (blink, present) during the wait.

Mouse

• vt_getmouse — read mouse state
• vt_mouse — enable / disable tracking
• vt_mouselock — confine cursor to window
• vt_setmouse — set cursor position / visibility

vt_getmouse

Non-blocking read of the current mouse state. All parameters are optional pointers; pass 0 to skip any field. Must enable the mouse first with vt_mouse(1). The wheel accumulator is reset to zero each time it is read. Button state uses the VT_MOUSE_BTN_* bitmask constants.

Return value

' Read position and buttons:
Dim mx As Long, my As Long, mb As Long
vt_getmouse @mx, @my, @mb

' Read wheel only:
Dim mw As Long
vt_getmouse 0, 0, 0, @mw

' Read buttons only (FreeBASIC skips defaulted pointer params):
vt_getmouse(,,@mb)

vt_mouse

Enable or disable mouse tracking entirely. Enabling hides the OS cursor, starts tracking, and snaps the character cursor to the current physical mouse position. Disabling restores the OS cursor and clears button/wheel state.

vt_mouselock

Enable or disable SDL window grab, which confines the mouse cursor to the window. Fullscreen modes enable this automatically at vt_screen time. Safe to call before or after vt_mouse(1).

vt_setmouse

Set the character cursor position and/or visibility. Coordinates are 1-based. Pass -1 to leave any field unchanged. Safe to call when the mouse is disabled; settings take effect when re-enabled.

Copy/Paste

• vt_copypaste — configure selection and clipboard mode

vt_copypaste

Configure the copy/paste and text selection system. Call after vt_screen. Clears any active selection.

' Enable both keyboard and mouse copy/paste:
vt_screen VT_SCREEN_0
vt_copypaste VT_CP_KBD Or VT_CP_MOUSE

' Disable entirely:
vt_copypaste VT_CP_DISABLED

File I/O (.vts format)

• vt_bload — load screen from .vts file
• vt_bsave — save screen to .vts file

The .vts format is a compact binary screen dump: 4-byte magic "VTBS", 4-byte cols, 4-byte rows (all little-endian Long), followed by cols × rows × 3 bytes of cell data (ch, fg, bg per cell, left-to-right, top-to-bottom). Both functions operate on the active work page.

vt_bload

Load a .vts file into the active work page. Validates the magic and screen dimensions before touching the cell buffer. Sets the display dirty on success so the next vt_present reflects the loaded content.

Return value

vt_bsave

Save the active work page to a .vts file.

Return value

Font

• vt_font_reset — restore built-in embedded font
• vt_loadfont — load a custom BMP font sheet

vt_font_reset

Restore the built-in embedded CP437 font selected by the current screen mode. Destroys any custom font loaded with vt_loadfont. Must be called after vt_screen.

Return value

vt_loadfont

Load a BMP font sheet and replace the active font texture at runtime. Uses SDL2 core only (no SDL_image). The loaded font stays active until vt_loadfont is called again, vt_font_reset is called, or vt_screen reinitializes the window.

Return value

Sheet layout detection

The layout is detected automatically from the BMP pixel dimensions relative to the current screen mode's glyph size (gw × gh):

Common mask colours:

' Load a magenta-keyed grid font sheet:
Dim r As Long = vt_loadfont("myfont.bmp", -1, -1, 255, 0, 255)
If r <> 0 Then
    vt_print "Font load failed: " & r & VT_NEWLINE
End If

Utilities

• vt_rnd — random number in a range

vt_rnd

Return a random Long in the inclusive range [lo .. hi]. Negative bounds are fully supported. If lo > hi the two values are swapped silently. Seeding the RNG with Randomize is the caller's responsibility — vt_rnd does not call it.

' Seed once at startup, then use freely:
Randomize Timer

Dim n As Long = vt_rnd(-15, 15)   ' -15 to 15
Dim d As Long = vt_rnd(1, 6)      ' die roll
Dim x As Long = vt_rnd(1, vt_cols())

Sort opt-in

Generic in-place array sorting, permutation application, and Fisher-Yates shuffle. No SDL2 required — usable with or without a VT screen open.

' Enable sort in your project:
#define VT_USE_SORT
#include once "vt/vt.bi"

• vt_sort — generic in-place array sort
• vt_sort_apply — apply a permutation index to an array
• vt_sort_shuffle — Fisher-Yates in-place shuffle

vt_sort

Sort a 1D array in-place using Shellsort. Overloaded for all numeric types (Byte, UByte, Short, UShort, Long, ULong, LongInt, ULongInt, Single, Double) and String. The compiler selects the correct overload automatically — a single call works for every supported type. Arrays with any LBound are handled correctly.

Two call forms are available: a direction constant, or a comparator callback for custom ordering.

Form 1 — direction constant

Form 2 — comparator callback

' Direction sort:
Dim nums(4) As Long = {5, 1, 4, 2, 3}
vt_sort nums(), VT_ASCENDING    ' 1 2 3 4 5
vt_sort nums(), VT_DESCENDING   ' 5 4 3 2 1

' String array, alphabetical:
Dim words(2) As String = {"cherry", "apple", "banana"}
vt_sort words(), VT_ASCENDING   ' apple banana cherry

' Custom comparator: sort strings by character count (shortest first):
Function cmp_by_length(a As String, b As String) As Long
    Return Len(a) - Len(b)
End Function

Dim tags(2) As String = {"hi", "hello", "hey"}
vt_sort tags(), @cmp_by_length  ' hi hey hello

vt_sort_apply

Apply a permutation index to a 1D array, physically rearranging its elements in-place. This is the companion function to the index-sort pattern — the standard technique for sorting tables stored as parallel arrays.

pidx() values are 0-based offsets from LBound(arr), exactly matching the index arrays built and sorted by vt_sort. The permutation index is consumed by the apply step — build a fresh index array if you need to apply the same order to additional arrays.

Overloaded for the same types as vt_sort. The pidx parameter is always Long.

The index-sort pattern (sorting a table of parallel arrays)

FreeBASIC tables are often stored as several parallel arrays of equal length — one per column. Because vt_sort operates on a single array, you cannot sort all columns at once directly. The index-sort pattern solves this in three steps without duplicating the data. It also applies naturally to ZString arrays, which vt_sort cannot overload directly.

1. Build a Long index array {0, 1, 2, …} — one entry per row.
2. Sort the index array using vt_sort with a comparator that reads the real data via the index values.
3. Either read in index order (non-destructive view) or call vt_sort_apply on every parallel array to physically rearrange them.

' Table stored as parallel arrays:
Dim Shared g_item(3) As String
Dim Shared g_qty (3) As Long
g_item(0) = "eggs"   : g_qty(0) = 5
g_item(1) = "butter" : g_qty(1) = 2
g_item(2) = "milk"   : g_qty(2) = 10
g_item(3) = "bread"  : g_qty(3) = 3

' Index comparators peek into shared arrays via the index value:
Function cmp_by_qty(a As Long, b As Long) As Long
    Return g_qty(a) - g_qty(b)
End Function

' Step 1: build index array.
Dim idx(3) As Long
Dim i As Long
For i = 0 To 3 : idx(i) = i : Next i

' Step 2: sort the index, not the data.
vt_sort idx(), @cmp_by_qty   ' idx = {1,3,0,2} = butter,bread,eggs,milk

' Step 3a: read in index order (original arrays untouched):
For i = 0 To 3
    Print g_item(idx(i)); " "; g_qty(idx(i))
Next i

' Step 3b: physically rearrange both arrays using the same index:
vt_sort_apply g_item(), idx()
vt_sort_apply g_qty(),  idx()
' g_item() and g_qty() are now in qty-ascending order.

vt_sort_shuffle

Shuffle a 1D array in-place using the Fisher-Yates algorithm, producing an unbiased uniform random permutation. Seeding the RNG with Randomize is the caller's responsibility — vt_sort_shuffle does not call it. Overloaded for the same types as vt_sort.

' Shuffle a deck of cards:
Randomize Timer
Dim deck(51) As Long
Dim i As Long
For i = 0 To 51 : deck(i) = i : Next i
vt_sort_shuffle deck()

' Shuffle a string list:
Dim names(3) As String = {"Alice", "Bob", "Carol", "Dave"}
vt_sort_shuffle names()

Math opt-in

Pure FreeBASIC math helpers. No SDL2 required — usable with or without a VT screen open. Especially useful for game logic: grid distance, line of sight, smooth movement, matrix rotation.

' Enable math in your project:
#define VT_USE_MATH
#include once "vt/vt.bi"

• vt_wrap — modular roll-over wrap
• vt_lerp — linear interpolation
• vt_approach — step toward a target without overshooting
• vt_manhattan — orthogonal grid distance
• vt_chebyshev — 8-direction king-moves distance
• vt_in_rect — point-in-rectangle test
• vt_digits — printed character count of a number
• vt_bresenham_walk — walk all cells on a straight line
• vt_los — line-of-sight check
• vt_mat_rotate_cw — rotate a 2D array 90° clockwise
• vt_mat_rotate_ccw — rotate a 2D array 90° counter-clockwise

vt_wrap

Wraps v into the inclusive range [lo .. hi] with roll-over. Unlike VT_CLAMP, hitting an edge rolls around to the opposite side. If hi − lo + 1 ≤ 0 the function returns lo.

' Menu cursor that wraps at the edges:
cursor_row = vt_wrap(cursor_row + delta, 1, num_items)

' Toroidal map: player walks off the right edge, appears on the left:
px = vt_wrap(px + 1, 0, map_width - 1)

vt_lerp

Linear interpolation between a and b. At t = 0 the result is a; at t = 1 the result is b. t is not clamped — values outside [0..1] extrapolate beyond the endpoints.

' Animated value moving from 0 to 100 over time:
Dim brightness As Double = vt_lerp(0, 100, elapsed / total)

' Blend two palette entries at the midpoint:
Dim r As Double = vt_lerp(col_a.r, col_b.r, 0.5)

vt_approach

Moves cur toward tgt by amt without overshooting. If cur = tgt it returns unchanged. amt should be positive.

' Smooth enemy movement: move one step per frame toward the player:
enemy_x = vt_approach(enemy_x, player_x, 1)
enemy_y = vt_approach(enemy_y, player_y, 1)

' Animated score counter that catches up 10 points per frame:
display_score = vt_approach(display_score, real_score, 10)

vt_manhattan

Manhattan (taxicab) distance between two grid points. Counts only orthogonal steps — no diagonals. Equivalent to Abs(x2 − x1) + Abs(y2 − y1).

' Only attack if the player is within 4 orthogonal steps:
If vt_manhattan(enemy_x, enemy_y, player_x, player_y) <= 4 Then
    attack()
End If

vt_chebyshev

Chebyshev (king-moves) distance between two grid points. Diagonal steps cost 1, the same as orthogonal — matches 8-direction movement. Equivalent to VT_MAX(Abs(x2 − x1), Abs(y2 − y1)).

' Check if a target is within melee range (1 king-move):
If vt_chebyshev(ax, ay, bx, by) = 1 Then
    melee_attack()
End If

vt_in_rect

Returns 1 if point (px, py) lies within the rectangle. The rect is half-open: [rx, rx+rw) × [ry, ry+rh) — the right and bottom edges are excluded. Returns 0 otherwise.

' Hit-test a mouse click against a button region:
Dim mcol As Long, mrow As Long, mbtns As Long
vt_getmouse @mcol, @mrow, @mbtns, 0
If (mbtns And VT_MOUSE_BTN_LEFT) AndAlso vt_in_rect(mcol, mrow, 10, 5, 20, 3) Then
    button_clicked()
End If

vt_digits

Returns the number of characters that Str(n) or Print n would produce, including the minus sign for negative numbers. Zero returns 1. Uses LongInt internally to handle the full Long range without overflow.

' Right-align a score in a fixed-width column:
Dim score As Long = 9870
Dim col As Long = 75 - vt_digits(score)  ' compute start column
vt_locate 1, col
vt_print Str(score)

vt_bresenham_walk

Walks every cell on the straight line from (x1, y1) to (x2, y2) using Bresenham's line algorithm and calls cb(x, y) for each cell in order. Both endpoints are included.

The callback is a Sub(x As Long, y As Long) — pass its address with @. Because FreeBASIC has no closures, use module-level Shared variables to give the callback access to map data or other state.

' Draw a line of ASCII dashes on the text screen:
Sub draw_dash(x As Long, y As Long)
    vt_set_cell x, y, Asc("-"), VT_WHITE, VT_BLACK
End Sub

vt_bresenham_walk 1, 1, 40, 15, @draw_dash
vt_present()

vt_los

Line-of-sight check from (x1, y1) to (x2, y2) using Bresenham's algorithm. The blocker function is called for each cell on the line and must return 1 if that cell blocks sight, 0 if clear.

The start cell is never tested — the observer is standing there. The end cell is tested — a wall blocks LOS to itself. Returns 1 if the path is clear, 0 if blocked.

Because FreeBASIC has no closures, use module-level Shared variables to give the blocker function access to your map array.

Return value

' Roguelike enemy vision check:
Dim Shared g_map(79, 49) As Byte   ' 1 = wall

Function is_wall(x As Long, y As Long) As Byte
    Return g_map(x, y)
End Function

If vt_los(enemy_x, enemy_y, player_x, player_y, @is_wall) Then
    ' enemy can see the player -- enter alert state
    alert_enemy()
End If

vt_mat_rotate_cw

Rotates a 2D Long array 90° clockwise in-place. The array must be square. LBound and UBound are used internally to detect the size automatically — no size argument is needed. Non-square arrays are silently ignored (no-op). Works with any LBound (0-based or 1-based declarations).

' Rotate a Tetris piece clockwise:
Dim piece(0 To 3, 0 To 3) As Long
' ... fill piece with 0/1 values ...
vt_mat_rotate_cw piece()   ' one 90-degree CW step

vt_mat_rotate_ccw

Rotates a 2D Long array 90° counter-clockwise in-place. Identical behaviour to vt_mat_rotate_cw but in the opposite direction.

' Four CCW rotations return the matrix to its original orientation:
vt_mat_rotate_ccw piece()
vt_mat_rotate_ccw piece()
vt_mat_rotate_ccw piece()
vt_mat_rotate_ccw piece()   ' back to start

Sound opt-in

The sound extension generates waveform samples and plays them via SDL_QueueAudio. No SDL2_mixer required — SDL2 core audio only. The audio subsystem initializes automatically on the first vt_sound call and does not require vt_screen to be open.

' Enable sound in your project:
#define VT_USE_SOUND
#include once "vt/vt.bi"

• vt_sound — generate and queue a tone
• vt_sound_wait — wait for the queue to drain
• VT_BEEP — convenience macro

vt_sound

Generate samples for a tone of the given frequency and duration and add them to the SDL audio queue. The waveform and blocking behaviour are selectable. Pass freq = 0 to stop playback and clear the queue immediately.

Return value

' Single blocking note (default):
vt_sound 440, 500

' Simple melody -- blocking, plays note-by-note:
vt_sound 262, 200
vt_sound 330, 200
vt_sound 392, 400

' Same melody queued in the background -- screen updates while it plays:
vt_sound 262, 200, VT_WAVE_SQUARE, VT_SOUND_BACKGROUND
vt_sound 330, 200, VT_WAVE_SQUARE, VT_SOUND_BACKGROUND
vt_sound 392, 400, VT_WAVE_SQUARE, VT_SOUND_BACKGROUND
vt_print "Playing..." : vt_present()
vt_sound_wait()

' Stop playback immediately:
vt_sound 0

vt_sound_wait

Block until the audio queue fully drains. This is the sync barrier for sequences queued with VT_SOUND_BACKGROUND — it lets you run code (update the screen, compute the next frame) while a melody plays, then wait for it to finish without having to calculate the total duration yourself. The window stays alive during the wait, identical to the blocking wait in vt_sound. No-op if the sound subsystem was never initialized.

VT_BEEP

Convenience macro. Plays a short 800 Hz square-wave beep, blocking. Equivalent to vt_sound(800, 200).

' Simple error beep:
VT_BEEP

Strings opt-in

Pure FreeBASIC string utilities. No SDL2 or open VT screen required — all helpers work in any FreeBASIC project. Fills gaps that FreeBASIC's built-in string handling does not cover (InStr, Mid, LTrim etc. are already available and are not duplicated here).

' Enable string helpers in your project:
#define VT_USE_STRINGS
#include once "vt/vt.bi"

• vt_str_replace — replace all occurrences of a substring
• vt_str_split — split a string into an array by delimiter
• vt_str_pad_left — right-align in a fixed-width field
• vt_str_pad_right — left-align in a fixed-width field
• vt_str_repeat — repeat a string n times
• vt_str_count — count non-overlapping occurrences
• vt_str_starts_with — prefix test
• vt_str_ends_with — suffix test
• vt_str_trim_chars — trim a custom character set from both ends
• vt_str_wordwrap — insert line breaks for word wrapping

vt_str_replace

Replace every non-overlapping occurrence of find in s with repl. Scanning always advances past the replacement so overlapping matches are not produced. Returns s unchanged if find is empty.

' Replace spaces with underscores:
Dim fname As String = vt_str_replace("hello world foo", " ", "_")
' fname = "hello_world_foo"

' Delete all occurrences:
Dim stripped As String = vt_str_replace("a--b--c", "--", "")
' stripped = "abc"

vt_str_split

Split s by delim and fill arr() with the resulting segments. The array is ReDim'd by this function; the caller only needs to declare Dim arr() As String. Returns the number of elements produced.

If delim is empty, each character of s becomes its own element. A trailing delimiter produces a final empty element (e.g. "a,b," yields three elements, the last being ""). An empty s always returns one element containing "".

Return value

' Parse a comma-separated list:
Dim parts() As String
Dim cnt As Long = vt_str_split("one,two,three", ",", parts())
' cnt = 3,  parts(0)="one"  parts(1)="two"  parts(2)="three"

For i As Long = 0 To cnt - 1
    vt_print parts(i) + !"\n"
Next i

vt_str_pad_left

Right-align s in a field of exactly length characters by padding with ch on the left. If s is already longer than length, the rightmost length characters are returned (truncation keeps the least-significant end, useful for numbers). Only the first character of ch is used; if ch is empty a space is substituted. Returns "" if length ≤ 0.

' Zero-pad a score value to 6 digits:
vt_print vt_str_pad_left(Str(score), 6, "0")   ' "001450"

' Right-align a label in a 10-char column:
vt_print "[" + vt_str_pad_left("hi", 10, " ") + "]"   ' "[        hi]"

vt_str_pad_right

Left-align s in a field of exactly length characters by padding with ch on the right. If s is already longer than length, the leftmost length characters are returned. Only the first character of ch is used; if ch is empty a space is substituted. Returns "" if length ≤ 0.

' Fixed-width label next to a zero-padded value:
vt_print vt_str_pad_right("SCORE", 10, " ") + vt_str_pad_left(Str(score), 6, "0")
' "SCORE      001450"

vt_str_repeat

Return s concatenated n times. Returns "" for n ≤ 0 or an empty s. Single-character strings use FreeBASIC's String() internally for efficiency.

' Draw a separator line:
vt_print vt_str_repeat("-=", 20) + !"\n"   ' "-=-=-=-=-= ..." (40 chars)

' Build a progress bar:
Dim bar As String = "[" + vt_str_repeat("#", filled) + vt_str_repeat(".", empty_slots) + "]"

vt_str_count

Count non-overlapping occurrences of find in s. Returns 0 if either string is empty.

Return value

' Count vowels (as single chars):
Dim n As Long = vt_str_count("banana", "a")   ' 3

' Count two-char patterns (non-overlapping):
n = vt_str_count("banana", "an")   ' 2  ("b[an][an]a")

vt_str_starts_with

Returns 1 if s begins with pfx, 0 otherwise. An empty pfx always returns 1.

' Simple command dispatch:
If vt_str_starts_with(input_line, "/quit") Then end_game = 1
If vt_str_starts_with(input_line, "/say ")  Then broadcast Mid(input_line, 6)

vt_str_ends_with

Returns 1 if s ends with sfx, 0 otherwise. An empty sfx always returns 1.

' Check file extension:
If vt_str_ends_with(filename, ".vts") Then vt_bload filename

vt_str_trim_chars

Remove any character found in the set chars from both ends of s and return the result. FreeBASIC's built-in Trim only removes spaces; this function accepts any set of characters. Returns "" if s consists entirely of characters in the set. Returns s unchanged if chars is empty.

' Strip decorative border characters:
Dim clean As String = vt_str_trim_chars("***hello***", "*")
' clean = "hello"

' Strip spaces and dots from both ends:
clean = vt_str_trim_chars("  ..hi.. ", " .")
' clean = "hi"

vt_str_wordwrap

Insert Chr(10) line breaks into s so that no line exceeds col_width characters. Words are never split — if a word is longer than col_width it occupies its own line unbroken. Existing Chr(10) and Chr(13) characters in s are preserved and reset the line-length counter; CRLF pairs are collapsed to a single Chr(10).

The return value is a plain string with embedded newlines. Pass it directly to vt_print, which handles Chr(10) natively.

' Wrap a long description inside a 30-char dialog window interior:
Dim msg As String = "This item restores your health fully and also cures poison."
vt_print vt_str_wordwrap(msg, 30)

' Label already printed on the same line -- tell the wrapper to account for it:
vt_print "Description: "
vt_print vt_str_wordwrap(msg, 40, 13)

' Use screen width automatically (requires open screen):
vt_print vt_str_wordwrap(msg)

File I/O Helpers opt-in

Fills gaps in FreeBASIC's built-in file and directory handling. Wraps Dir() from dir.bi cleanly, hiding the fbDirectory constant and the multi-call scan idiom from caller code. Functions that duplicate existing FreeBASIC built-ins without adding behaviour (MkDir, RmDir, Kill, Name) are intentionally not wrapped — use them directly.

' Enable file helpers in your project:
#define VT_USE_FILE
#include once "vt/vt.bi"

• vt_file_exists — test whether a file exists
• vt_file_isdir — test whether a path is a directory
• vt_file_copy — copy a file or directory tree
• vt_file_rmdir — remove a directory, optionally recursive
• vt_file_list — list directory contents into a String array

File Flags

Bit-flags passed to vt_file_copy, vt_file_rmdir, and vt_file_list. Combine with Or.

vt_file_exists

Returns 1 if path names an existing file, 0 if the path does not exist or is a directory. Uses Dir() directly — no vbcompat.bi required.

Return value

' Guard a bload call:
If vt_file_exists("savegame.vts") Then
    vt_bload "savegame.vts"
End If

vt_file_isdir

Returns 1 if path is an existing directory, 0 otherwise. Hides the fbDirectory constant and dir.bi dependency from caller code entirely.

Return value

' Create output folder only if it does not already exist:
If vt_file_isdir("output") = 0 Then MkDir "output"

vt_file_copy

Copy a file or a full directory tree. The function auto-detects whether src is a file or a directory — no separate call needed.

File mode: the source file is read into memory and written to the destination in a single binary I/O operation. Fails if the destination already exists unless VT_FILE_OVERWRITE is passed.

Directory mode: the full directory tree is recreated under dst. If dst does not exist it is created; if it already exists the trees are merged. Individual files that already exist in dst are silently skipped unless VT_FILE_OVERWRITE is set. All entries are collected in a single Dir() pass before anything is written, so the global scan state is never corrupted by recursion.

Return value

' Simple backup before overwriting:
vt_file_copy "config.ini", "config.bak"

' Overwrite an existing destination file:
vt_file_copy "save_new.vts", "save_slot1.vts", VT_FILE_OVERWRITE

' Copy a full directory tree:
vt_file_copy "data", "data_backup"

' Copy tree, overwrite any files that already exist in dst:
vt_file_copy "data", "data_backup", VT_FILE_OVERWRITE

' Check result:
Dim ret As Long = vt_file_copy("src.dat", "dst.dat")
If ret <> 0 Then
    vt_print "copy failed: " & ret & VT_NEWLINE
End If

vt_file_rmdir

Remove a directory. Without VT_FILE_RECURSIVE the directory must be empty — for that common case FreeBASIC's built-in RmDir is sufficient and preferred. Use vt_file_rmdir when recursive deletion of a populated directory tree is needed.

When VT_FILE_RECURSIVE is set, all files and subdirectories are collected in a single Dir() pass before anything is deleted, so the global Dir() scan state is never corrupted by recursive calls. Files are removed with Kill, subdirectories by recursing into vt_file_rmdir, then the now-empty root is removed with RmDir.

Return value

' Remove an empty temp directory (prefer plain RmDir for this):
vt_file_rmdir "tmp_empty"

' Remove a populated directory tree -- explicit opt-in required:
vt_file_rmdir "build_output", VT_FILE_RECURSIVE

vt_file_list

Scan a directory for items matching pattern and fill arr() with their bare names (no path prefix). The . and .. entries are always silently skipped. The array is ReDim'd by this function; the caller only needs to declare Dim arr() As String.

By default only files are returned. Pass VT_FILE_SHOW_DIRS to include subdirectory names alongside files, or VT_FILE_DIRS_ONLY to return only subdirectory names.

Return value

' List all .txt files in a folder:
Dim files() As String
Dim cnt As Long = vt_file_list("notes", "*.txt", files())
For i As Long = 0 To cnt - 1
    vt_print files(i) & VT_NEWLINE
Next i

' List files and subdirectories together:
cnt = vt_file_list("data", "*", files(), VT_FILE_SHOW_DIRS)

' List only subdirectories:
cnt = vt_file_list("data", "*", files(), VT_FILE_DIRS_ONLY)

' Scan current directory, include hidden files:
cnt = vt_file_list("", "*", files(), VT_FILE_SHOW_HIDDEN)

TUI Widgets opt-in

DOS-style TUI widgets: windows, dialogs, menus, forms, file picker, editor. All coordinates are 1-based column / row, matching the rest of the VT API. Enable with:

#Define VT_USE_TUI
#include once "vt/vt.bi"

VT_USE_TUI automatically pulls in VT_USE_STRINGS and VT_USE_FILE — you do not need to define them separately. All TUI functions work identically on both the SDL2 and the TTY backends.

• vt_tui_theme_default / vt_tui_theme — set the colour theme
• vt_tui_rect_fill — fill a rectangle with a character and colour
• vt_tui_hline / vt_tui_vline — CP437 separator lines
• vt_tui_window — window chrome (border + title bar)
• vt_tui_statusbar — status / hint bar row
• vt_tui_progress — horizontal progress bar
• vt_tui_mouse_in_rect — mouse hit-test helper
• vt_tui_input_field — blocking single-line text input
• vt_tui_listbox — blocking scrollable item list
• vt_tui_dialog — blocking modal dialog
• vt_tui_file_dialog — blocking file / directory picker
• vt_tui_editor — blocking multi-line editor / viewer
• vt_tui_menubar_draw / vt_tui_menubar_handle — horizontal menu bar
• vt_tui_form_draw / vt_tui_form_handle — non-blocking form widget

vt_tui_theme_default / vt_tui_theme

Set the colour theme used by all TUI widgets. All colours are CGA palette indices (0–15, see Color Constants). The theme is a single global struct — there is no per-widget override.

vt_tui_theme_default restores the built-in DOS/BIOS defaults. vt_tui_theme sets all fields in one call. Neither function requires vt_screen to have been called first.

Default values

' Restore DOS blue-scheme defaults:
vt_tui_theme_default()

' Custom dark theme:
vt_tui_theme VT_LIGHT_GREY, VT_BLACK,    _
             VT_WHITE,      VT_DARK_GREY, _
             VT_BLACK,      VT_CYAN,      _
             VT_LIGHT_GREY, VT_DARK_GREY, _
             VT_LIGHT_GREY, VT_BLACK,     _
             VT_WHITE,      VT_DARK_GREY, _
             0

vt_tui_rect_fill

Fill a 1-based rectangle with a single character and colour. This is the base drawing primitive — all other widgets use it internally to clear their area.

' Clear a region to dark grey:
vt_tui_rect_fill 1, 1, 40, 10, 32, VT_LIGHT_GREY, VT_DARK_GREY

' Solid red banner row:
vt_tui_rect_fill 1, 1, 80, 1, 32, VT_BLACK, VT_RED

vt_tui_hline / vt_tui_vline

Draw a horizontal or vertical separator line using CP437 box-drawing characters. The character is chosen automatically from the active theme's border_style: single-line style uses characters 196 (horizontal) and 179 (vertical); double-line style uses 205 and 186.

' Horizontal divider across a full 80-column screen:
vt_tui_hline 1, 13, 80, VT_DARK_GREY, VT_BLACK

' Vertical divider splitting the screen at column 40:
vt_tui_vline 40, 1, 25, VT_DARK_GREY, VT_BLACK

vt_tui_window

Draw window chrome: a border, a title bar, and optionally a close button and drop shadow. Does not save or restore the background and does not block. The window interior is filled with the theme's win_fg / win_bg colours.

' Centred window, 40 wide × 12 tall, with shadow:
Dim wx As Long = (80 - 40) \ 2 + 1
Dim wy As Long = (25 - 12) \ 2 + 1
vt_tui_window wx, wy, 40, 12, "Settings", VT_TUI_WIN_SHADOW

' With close button — detect click separately:
vt_tui_window wx, wy, 40, 12, "Settings", VT_TUI_WIN_CLOSEBTN Or VT_TUI_WIN_SHADOW
If vt_tui_mouse_in_rect(wx + 40 - 4, wy, 3, 1) Then
    ' [x] was clicked
End If

vt_tui_statusbar

Fill an entire screen row with the theme's bar_bg colour and print caption left-aligned in bar_fg. Typical use: the last row for a keyboard hint bar, or row 1 below a menu bar.

' Hint bar on the last row:
vt_tui_statusbar 25, " F1=Help  F10=Menu  Esc=Quit"

vt_tui_progress

Draw a horizontal progress bar at an arbitrary screen position. The filled portion uses the theme's title_bg colour as a solid block; the empty portion uses inp_bg. Both halves use space (32) as the character so colour alone carries the bar.

' Progress bar updating inside a loop:
For i As Long = 0 To 100
    vt_tui_progress 5, 10, 40, i, 100, VT_TUI_PROG_LABEL
    vt_present()
    vt_sleep 20
Next i

vt_tui_mouse_in_rect

Hit-test helper. Returns 1 if the current mouse position is inside the given 1-based rectangle, 0 otherwise. Returns 0 immediately if the library is not ready or the mouse is disabled. Reads the internal mouse state updated by vt_inkey — call this after polling input, not before.

Return value

' Hover detection over a custom 10-cell-wide button at row 5:
If vt_tui_mouse_in_rect(10, 5, 10, 1) Then
    ' highlight the button
End If

' Close-button detection for a window at (wx, wy) of outer width ww:
If vt_tui_mouse_in_rect(wx + ww - 4, wy, 3, 1) Then
    ' [x] hovered or clicked
End If

vt_tui_input_field

Single-line text input at an arbitrary screen position. Blocking. Draws a field of wid cells in the theme's inp_fg / inp_bg colours and lets the user edit the text. Supports buffers longer than the visible width via horizontal scrolling. The text cursor is shown during editing and its previous visibility state is restored on exit.

Return value

Key bindings

' Prompt for a filename:
Dim fname As String = vt_tui_input_field(10, 12, 30, "", 64)
If Len(fname) > 0 Then
    ' use fname
End If

' Pre-filled edit (e.g. rename dialog):
Dim newname As String = vt_tui_input_field(10, 12, 30, "oldname.txt", 64)

vt_tui_listbox

Scrollable item list. Blocking. Draws the list at the given position, handles keyboard and mouse input, and returns when the user confirms or cancels. A scrollbar is drawn automatically on the right edge when the item count exceeds the visible height.

Return value

Key and mouse bindings

' Difficulty picker:
Dim opts(2) As String
opts(0) = "Easy" : opts(1) = "Normal" : opts(2) = "Hard"

Dim picked As Long = vt_tui_listbox(20, 8, 20, 3, opts())
If picked >= 0 Then
    vt_print "Chose: " & opts(picked) & VT_NEWLINE
End If

vt_tui_dialog

Self-contained blocking modal dialog. Saves the background before drawing and restores it on close. The text is word-wrapped automatically to fit; the window grows to accommodate both the wrapped content and the button row. The dialog is centred on screen (default 60 columns wide, clamped to screen width minus 4).

Return value

Key and mouse bindings

' Quit confirmation:
If vt_tui_dialog("Quit", "Are you sure you want to quit?", VT_DLG_YESNO) = VT_RET_YES Then
    End
End If

' Mandatory choice (Escape disabled):
Dim r As Long = vt_tui_dialog("Disk Full", "Retry or abort the operation?", _
                               VT_DLG_OKCANCEL Or VT_DLG_NO_ESC)

' Simple info box:
vt_tui_dialog "Done", "File saved successfully."

vt_tui_file_dialog

Self-contained blocking file / directory picker. Saves the background before drawing and restores it on close. Centred on screen, automatically sized to fit the available area (maximum 70 columns wide).

The listing always includes subdirectories (shown with a trailing /) and a .. entry at the top whenever a parent exists. Files are matched against pattern. All returned paths use forward slashes on both Windows and Linux.

Return value

Key and mouse bindings

' Open file picker for FreeBASIC sources:
Dim path As String = vt_tui_file_dialog("Open", "./", "*.bas")
If Len(path) > 0 Then
    vt_print "Selected: " & path & VT_NEWLINE
End If

' Save-as dialog starting in a saves subfolder:
path = vt_tui_file_dialog("Save", "./saves/", "*.sav")

' Directory picker only:
path = vt_tui_file_dialog("Choose Folder", "./", "*", VT_TUI_FD_DIRSONLY)

vt_tui_editor

Multi-line text editor / viewer widget. Blocking. Text is stored and returned as a single String with Chr(10) as the line separator. The widget renders inside the given rectangle using the theme's inp_fg / inp_bg colours. Lines exceeding wid are truncated in display; no horizontal scrolling.

Return value

Key bindings

' Note editor inside a window:
Dim note As String = "First line" & Chr(10) & "Second line"
vt_tui_window 5, 3, 70, 20, "Notes  [F10=Save  Esc=Cancel]"
note = vt_tui_editor(6, 4, 68, 18, note)

' Read-only file viewer:
Dim content As String
Open "readme.txt" For Binary As #1
content = Space(LOF(1))
Get #1, , content
Close #1
vt_tui_editor 1, 1, 80, 24, content, VT_TUI_ED_READONLY

vt_tui_menubar_draw / vt_tui_menubar_handle

Horizontal menu bar. Two-function design: vt_tui_menubar_draw renders the bar passively (non-blocking, call once per frame); vt_tui_menubar_handle is non-blocking while no menu is open and blocks with its own inner event loop while a dropdown is open.

Return value (vt_tui_menubar_handle)

Opening and navigating dropdowns

' Setup arrays:
Dim groups(2) As String
groups(0) = "File" : groups(1) = "Edit" : groups(2) = "Help"

Dim items(6) As String
items(0) = "New"   : items(1) = "Open" : items(2) = "Save" : items(3) = "Quit"
items(4) = "Cut"   : items(5) = "Copy"
items(6) = "About"

Dim counts(2) As Long
counts(0) = 4 : counts(1) = 2 : counts(2) = 1

' Main loop:
Dim k As ULong
Do
    k = vt_inkey()

    vt_tui_menubar_draw 1, groups()
    Dim r As Long = vt_tui_menubar_handle(1, groups(), items(), counts(), k)
    If r <> 0 Then
        Select Case VT_TUI_MENU_GROUP(r)
            Case 1  ' File
                Select Case VT_TUI_MENU_ITEM(r)
                    Case 1 : ' New
                    Case 2 : ' Open
                    Case 3 : ' Save
                    Case 4 : End  ' Quit
                End Select
        End Select
    End If

    vt_present()
    vt_sleep 10
Loop

vt_tui_form_draw / vt_tui_form_handle

Non-blocking form widget. Two-function design: vt_tui_form_draw renders all items passively each frame; vt_tui_form_handle processes one key or mouse event and returns immediately. The caller owns the vt_tui_form_item array and loops until vt_tui_form_handle returns a value other than VT_FORM_PENDING.

vt_tui_form_item type

Declare an array of this type to define the form layout. Set .cpos and .view_off to 0 when initialising — vt_tui_form_handle manages them internally afterward.

Return value (vt_tui_form_handle)

Key and mouse bindings

' Login form: two text inputs and two buttons.
Dim fitems(3) As vt_tui_form_item

fitems(0).kind    = VT_FORM_INPUT : fitems(0).x = 16 : fitems(0).y = 8
fitems(0).wid     = 20            : fitems(0).max_len = 32

fitems(1).kind    = VT_FORM_INPUT : fitems(1).x = 16 : fitems(1).y = 10
fitems(1).wid     = 20            : fitems(1).max_len = 32

fitems(2).kind    = VT_FORM_BUTTON : fitems(2).x = 16 : fitems(2).y = 12
fitems(2).val     = " OK "         : fitems(2).ret = VT_RET_OK

fitems(3).kind    = VT_FORM_BUTTON : fitems(3).x = 23 : fitems(3).y = 12
fitems(3).val     = " Cancel "     : fitems(3).ret = VT_RET_CANCEL

Dim focused As Long = 0
Dim result  As Long = VT_FORM_PENDING
Dim k       As ULong

Do
    k = vt_inkey()
    vt_tui_window 10, 5, 42, 11, "Login"
    vt_locate 8,  5 : vt_print "Username:"
    vt_locate 10, 5 : vt_print "Password:"
    vt_tui_form_draw   fitems(), focused
    result = vt_tui_form_handle(fitems(), focused, k)
    vt_present()
    vt_sleep 10
Loop While result = VT_FORM_PENDING

If result = VT_RET_OK Then
    vt_print "User: " & fitems(0).val & VT_NEWLINE
End If

VT Virtual Text Screen Library — API Reference — v1.3.4
FreeBASIC 1.10.1 / SDL2 + TTY / Windows + Linux