# Welcome!

DVX (DOS Visual eXecutive) is a graphical user interface environment for DOS, designed for 486-class hardware and above. This help file covers the system architecture, the core libdvx API, the widget toolkit, and the platform abstraction layer.

## What Is libdvx?

libdvx is the heart of DVX -- a DXE3 library that provides:

- A VESA VBE 2.0+ video backend (LFB only, no bank switching).
- Optimised 2D drawing primitives (rectangle fill, bevels, text, bitmap blits, cursors).
- A dirty-rectangle compositor that minimises LFB traffic.
- A window manager with Motif-style chrome, drag/resize, menus, and scrollbars.
- A retained-mode widget toolkit with automatic layout.
- Modal dialog helpers, an INI preferences system, a DXE resource system, and per-app memory tracking.

Applications written in C link against libdvx (and the widget DXEs they need) to build native DVX programs. Applications written in DVX BASIC compile to bytecode that runs on top of libdvx via the form runtime.

## Target Audience

This document is aimed at developers writing native C code for DVX:

- System-level contributors maintaining libdvx itself.
- Widget authors writing new .wgt DXE modules.
- Application authors writing .app DXE modules.
- Tool authors (e.g. the BASIC compiler/runtime) that sit on top of libdvx.

All examples and signatures assume the DJGPP cross-compiler toolchain.

## What's Covered

- Architecture -- Five-layer model, display pipeline, event model, build system.
- API Reference -- Every public function, struct, enum, and constant documented with parameters and return values.

Use the table of contents on the left to navigate. The API reference is organised by header file; each function has a one-line summary, parameter table, and (where useful) a working example.

## Conventions

- Types end in a capital T (e.g. WindowT, DisplayT, BlitOpsT).
- Enum types end in a capital E (e.g. ColorIdE, WallpaperModeE, ScrollbarOrientE).
- Public functions use camelCase and prefixes that identify the subsystem: dvx* (application), wm* (window manager), wgt* (widget), prefs* (preferences), draw* / rect* (drawing), dirtyList* / flush* (compositor), video* / packColor / setClipRect (video), platform* (platform layer).
- Constants use SCREAMING_SNAKE_CASE (e.g. HIT_CONTENT, MB_OK, CURSOR_ARROW).
- Every header uses stdint.h types (int32_t, uint8_t) and stdbool.h types (bool).

## Getting Started

If you're new to DVX, read these topics in order:

- Architecture Overview -- The big picture, five-layer model, and the design philosophy.
- Display Pipeline -- How the backbuffer, dirty list, and compositor work together.
- Event Model -- How input becomes window/widget callbacks.
- Widget System -- The retained-mode toolkit layered on the window manager.
- DXE Module System -- How apps and widgets are loaded dynamically.

Then dip into the API Reference to find specific functions. The public entry point for any application is dvxInit / dvxRun in dvxApp.h.

## License

DVX is distributed under the MIT License (see the copyright notice at the top of every source file). Third-party code (stb_image, stb_ds, stb_image_write in thirdparty/) is used under its own permissive license.

# DVX Architecture Overview

DOS Visual eXecutive -- A Windowing GUI for DJGPP/DPMI

DVX (DOS Visual eXecutive) is a complete windowing GUI compositor targeting DJGPP/DPMI on DOS. It provides overlapping windows with Motif-style chrome, a retained-mode widget toolkit, cooperative multitasking of DXE-loaded applications, and a dirty-rectangle compositor optimized for 486/Pentium hardware.

## Key Design Constraints

- VESA VBE 2.0+ LFB only -- no bank switching. If the hardware cannot provide a linear framebuffer, initialization fails.
- 486 baseline -- all hot paths are written to be fast on a 486, with Pentium-specific paths where the gain is significant.
- Single-tasking cooperative model -- applications yield the CPU via tsYield(); there is no preemptive scheduler.
- A single emulator is the trusted reference platform for testing; any bugs observed there are treated as DVX bugs.
- No external font or cursor files -- all bitmaps are compiled in as static const data.

The runtime environment consists of a bootstrap loader (dvx.exe) that loads core DXE libraries, widget plugins, and the shell, which in turn loads and manages DXE application modules.

## Contents

Five-Layer Architecture

Display Pipeline

Window System

Widget System

Modal Dialogs

Resource System

Preferences System

Per-App Memory Tracking

DXE Module System

Event Model

Font System

Color System

Platform Layer

Build System

# Five-Layer Architecture

DVX is organized into five layers, each implemented as a single .h/.c pair. Every header includes dvxTypes.h (the shared type definitions) to avoid circular dependencies. The layers are strictly stacked: each layer depends only on the layers below it.

     Applications (DXE .app modules)
     ==================================================
     |                                                |
     |  +------------------------------------------+  |
     |  |  Layer 5: dvxApp  (Application API)      |  |  dvxApp.h / dvxApp.c
     |  |  Event loop, window creation, public API  |  |
     |  +------------------------------------------+  |
     |  |  Layer 4: dvxWm   (Window Manager)       |  |  dvxWm.h / dvxWm.c
     |  |  Window stack, chrome, drag, resize      |  |
     |  +------------------------------------------+  |
     |  |  Layer 3: dvxComp  (Compositor)          |  |  dvxComp.h / dvxComp.c
     |  |  Dirty rect tracking, merge, LFB flush   |  |
     |  +------------------------------------------+  |
     |  |  Layer 2: dvxDraw  (Drawing Primitives)  |  |  dvxDraw.h / dvxDraw.c
     |  |  Rects, bevels, text, blits, cursors     |  |
     |  +------------------------------------------+  |
     |  |  Layer 1: dvxVideo (Video Backend)       |  |  dvxVideo.h / dvxVideo.c
     |  |  VESA VBE, LFB mapping, pixel format     |  |
     |  +------------------------------------------+  |
     |                                                |
     |  +------------------------------------------+  |
     |  |  Platform Layer (dvxPlat.h)              |  |  dvxPlatformDos.c
     |  |  OS-specific: video, input, asm spans    |  |
     |  +------------------------------------------+  |
     |                                                |
     |  +------------------------------------------+  |
     |  |  Shared Types (dvxTypes.h)               |  |
     |  |  DisplayT, WindowT, RectT, ColorSchemeT  |  |
     |  +------------------------------------------+  |
     ==================================================

## Layer Summary

      Layer               Header         Responsibility
      -----               ------         --------------
      1 - Video           dvxVideo.h     VESA VBE mode negotiation, LFB mapping via DPMI, backbuffer allocation, packColor() (RGB to native pixel format), display-wide clip rectangle.
      2 - Draw            dvxDraw.h      All 2D drawing: rectFill, rectCopy, drawBevel, drawText/drawTextN, drawMaskedBitmap (cursor), drawTermRow (batch terminal row). Stateless beyond clip rect. Dispatches hot inner loops through BlitOpsT function pointers.
      3 - Compositor      dvxComp.h      Dirty rectangle tracking (dirtyListAdd), pairwise merge of overlapping rects (dirtyListMerge), and flushRect to copy dirty regions from backBuf to LFB.
      4 - Window Manager  dvxWm.h        Window lifecycle, Z-order stack, chrome drawing (title bars, bevels, close/minimize/maximize gadgets), hit testing, drag/resize, menu bars, scrollbars, system menu, keyboard move/resize, minimized icon bar.
      5 - Application     dvxApp.h       Public API aggregating all layers into AppContextT. Provides dvxInit/dvxShutdown, dvxRun/dvxUpdate, window creation helpers, image loading, clipboard, accelerator tables, theme management, wallpaper, video mode switching, screenshot capture.

# Display Pipeline

The double-buffer strategy is the single most important performance decision in DVX. All drawing goes to a system RAM backbuffer (DisplayT.backBuf); only dirty rectangles are flushed to the linear framebuffer (DisplayT.lfb) in video memory.

This matters because writes to video memory over the PCI bus are 10-50x slower than writes to main RAM on 486/Pentium hardware for random-access patterns.

## Per-Frame Compositing Pipeline

      1. Input poll (mouse, keyboard)
             |
      2. Event dispatch (focus window callbacks)
             |
      3. Layers call dirtyListAdd() for changed regions
             |
      4. dirtyListMerge() consolidates overlapping rects
             |
      5. For each merged dirty rect:
         a. Clip and redraw desktop background (or wallpaper)
         b. For each window (back-to-front, painter's algorithm):
            - wmDrawChrome()   -- frame, title bar, gadgets, menu bar
            - wmDrawContent()  -- blit per-window content buffer
            - wmDrawScrollbars()
         c. Draw minimized window icons
         d. Draw popup menus / tooltips (overlay pass)
         e. Draw software mouse cursor
             |
      6. flushRect() -- copy each dirty rect from backBuf to LFB
             |
      7. Yield (platformYield)

## Key Data Structures

DisplayT -- Central display context: width, height, pitch, pixel format, LFB pointer, backbuffer pointer, palette, clip rectangle. Passed by pointer through every layer -- no globals.

BlitOpsT -- Vtable of span fill/copy function pointers resolved at init time for the active pixel depth. On DOS these dispatch to hand-written rep stosl / rep movsd asm inner loops.

DirtyListT -- Fixed-capacity dynamic array of RectT. Linear scanning for merge candidates is cache-friendly at typical sizes (under 128 rects). If the list fills up, the compositor merges aggressively or falls back to full-screen repaint.

## Why This Works on a 486

- A full 640x480x32bpp frame is 1.2 MB -- far too much to flush every frame over a slow PCI bus.
- A typical dirty region during normal interaction (typing, menu open) is a few KB.
- Merging overlapping dirty rects into larger rects reduces per-rect overhead and improves bus utilization.
- Per-window content buffers persist across frames, so windows don't repaint on expose -- only when their own content changes.

# Window System

## WindowT Structure

Each WindowT is the central object of the window manager. Key fields:

      Field Group                              Purpose
      -----------                              -------
      Geometry (x, y, w, h)                   Outer frame rectangle (including chrome).
      Content area (contentX/Y/W/H)           Computed from frame minus chrome. Where application content lives.
      Content buffer (contentBuf, contentPitch) Per-window backbuffer in native pixel format. Persists across frames.
      Chrome state (menuBar, vScroll, hScroll) Optional menu bar and scrollbars. Affect content area computation.
      Widget tree (widgetRoot)                 Root of the retained-mode widget tree (NULL if using raw callbacks).
      Callbacks                                onPaint, onKey, onKeyUp, onMouse, onResize, onClose, onMenu, onScroll, onFocus, onBlur, onCursorQuery.

## Window Stack (Z-Order)

WindowStackT is an array of WindowT* ordered front-to-back: index count-1 is the topmost window. This allows:

- Back-to-front iteration for painting (painter's algorithm).
- Front-to-back iteration for hit testing (first hit wins).
- Reordering by pointer swap (no copying of large WindowT structs).

Only one drag/resize/scroll operation can be active system-wide at a time (single mouse), so that state lives on the stack, not on individual windows.

## Chrome Layout

      +-------------------------------------------+
      |  4px outer border (raised bevel)          |
      |  +-------------------------------------+  |
      |  | [X] Title Bar Text     [_] [^] [X]  |  |  20px title height
      |  +-------------------------------------+  |
      |  | 2px inner border                    |  |
      |  +-------------------------------------+  |
      |  | Menu Bar (optional, 20px)           |  |
      |  +-------------------------------------+  |
      |  |                                     |  |
      |  |          Content Area               |  |
      |  |                                     |  |
      |  |                               |  S  |  |  S = vertical scrollbar
      |  |                               |  B  |  |      (16px wide)
      |  +-------------------------------------+  |
      |  |  Horizontal Scrollbar (optional)    |  |  16px tall
      |  +-------------------------------------+  |
      |  4px outer border                         |
      +-------------------------------------------+

Chrome constants are compile-time defines:

      CHROME_BORDER_WIDTH   = 4px
      CHROME_TITLE_HEIGHT   = 20px
      CHROME_INNER_BORDER   = 2px
      CHROME_MENU_HEIGHT    = 20px
      SCROLLBAR_WIDTH       = 16px

## Hit Test Regions

wmHitTest() iterates the stack front-to-back and returns a hit-part identifier: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, HIT_RESIZE, HIT_MENU, HIT_VSCROLL, HIT_HSCROLL, HIT_MINIMIZE, HIT_MAXIMIZE. Resize edge detection returns a bitmask of RESIZE_LEFT, RESIZE_RIGHT, RESIZE_TOP, RESIZE_BOTTOM (corners combine two edges).

## Menu System

Menus use fixed-size inline char buffers for labels (MAX_MENU_LABEL = 32, no heap strings). Both menus per bar and items per menu are stored in dynamic arrays that grow on demand. Supports cascading submenus via MenuItemT.subMenu pointer. Item types: normal, checkbox, radio. Separators are non-interactive items. The popup state (PopupStateT) tracks a stack of parent frames for cascading submenu nesting.

## Minimized Windows

Minimized windows display as 64x64 icons at the bottom of the screen with beveled borders, similar to a classic desktop icon bar. Icons show a scaled-down preview of the window's content buffer, refreshed one per frame in a round-robin fashion to amortize the scaling cost.

# Widget System

The widget system (dvxWgt.h) is a retained-mode toolkit layered on top of the window manager. Widgets form a tree rooted at a per-window VBox container.

## WidgetT Base Structure

Every widget shares the same WidgetT struct. The type field is a runtime-assigned integer ID. The wclass pointer references the widget's WidgetClassT vtable. Widget-specific private data is stored in w->data (opaque void*).

Tree linkage: parent, firstChild, lastChild, nextSibling. No prevSibling -- this halves pointer overhead and removal is still O(n) for typical tree depths of 5-10.

## Layout Engine

Two-pass flexbox-like algorithm:

- Bottom-up (calcMinSize) -- compute minimum sizes for every widget, starting from leaves.
- Top-down (layout) -- allocate space within available bounds, distributing extra space according to weight values (0 = fixed, 100 = normal stretch).

Size hints use a tagged encoding: the top 2 bits of an int32_t select the unit (pixels, character widths, or percentage of parent), the low 30 bits hold the value. Macros: wgtPixels(v), wgtChars(v), wgtPercent(v).

## Widget Class Dispatch (WidgetClassT)

Each widget type provides a WidgetClassT with a handlers[] array indexed by stable method IDs. Method IDs are never reordered or reused -- new methods append at the end. This provides ABI-stable dispatch so that widget DXEs compiled against an older DVX version continue to work.

Methods include: PAINT, PAINT_OVERLAY, CALC_MIN_SIZE, LAYOUT, ON_MOUSE, ON_KEY, ON_ACCEL_ACTIVATE, DESTROY, GET_TEXT, SET_TEXT, POLL, and more (21 defined, room for 32).

### Class Flags

      Flag                    Meaning
      ----                    -------
      WCLASS_FOCUSABLE        Can receive keyboard focus (Tab navigation)
      WCLASS_HORIZ_CONTAINER  Lays out children horizontally (HBox)
      WCLASS_PAINTS_CHILDREN  Widget handles child rendering itself
      WCLASS_SCROLLABLE       Accepts mouse wheel events
      WCLASS_SCROLL_CONTAINER ScrollPane -- scrolling viewport
      WCLASS_NEEDS_POLL       Needs periodic polling (e.g. AnsiTerm comms)
      WCLASS_SWALLOWS_TAB     Tab key goes to widget, not focus navigation
      WCLASS_PRESS_RELEASE    Click = press + release (buttons)

## Available Widget Types

Each widget is a separate .wgt DXE module. 29 widget types are included:

      Widget                  Description
      ------                  -----------
      Box (VBox/HBox)         Vertical and horizontal layout containers
      Button                  Clickable push button with label
      Canvas                  Raw drawing surface for custom painting
      Checkbox                Boolean toggle with checkmark
      ComboBox                Text input with dropdown list
      DataCtrl                Data-bound control for database operations
      DbGrid                  Database grid (tabular data display)
      Dropdown                Dropdown selection list
      Image                   Static image display
      ImageButton             Button with bitmap icon
      Label                   Static text label
      ListBox                 Scrollable selection list
      ListView                Multi-column list with headers and sorting
      ProgressBar             Determinate progress indicator
      Radio                   Radio button (mutual exclusion group)
      ScrollPane              Scrollable viewport container
      Separator               Visual divider line
      Slider                  Value selection via draggable thumb
      Spacer                  Empty space for layout
      Spinner                 Numeric input with up/down arrows
      Splitter                Resizable split pane
      StatusBar               Window status bar with sections
      TabControl              Tabbed page container
      Terminal (AnsiTerm)     ANSI terminal emulator widget
      TextInput               Single-line text entry field
      Timer                   Periodic timer events
      Toolbar                 Toolbar with icon buttons
      TreeView                Hierarchical tree display
      WrapBox                 Flow layout (wrapping horizontal container)

## Widget API Registry

Each widget DXE registers a small API struct under a name during wgtRegister(). Callers retrieve it via wgtGetApi("button") and cast to the widget-specific API type. Per-widget headers provide typed accessors so callers avoid manual casts. Adding a new widget requires zero changes to the core.

## Widget Interface Descriptors (WgtIfaceT)

Each widget can register an interface descriptor that describes its BASIC-facing properties, methods, and events. These descriptors are used by the form runtime and IDE for generic dispatch and property panel enumeration. Properties have typed getters/setters (WGT_IFACE_STRING, WGT_IFACE_INT, WGT_IFACE_BOOL, WGT_IFACE_ENUM).

# Modal Dialogs (dvxDlg.h)

Pre-built modal dialog boxes block the caller and run their own event loop via dvxUpdate() until the user dismisses them. Each dialog sets ctx->modalWindow to prevent input from reaching other windows while open.

## Dialog Types

      Function              Purpose
      --------              -------
      dvxMessageBox         Generic message box with button/icon flags (MB_OK, MB_YESNO, MB_ICONERROR, etc.)
      dvxErrorBox           Shortcut for MB_OK + MB_ICONERROR
      dvxInfoBox            Shortcut for MB_OK + MB_ICONINFO
      dvxFileDialog         File open/save dialog with directory navigation and filter dropdown
      dvxInputBox           Single-line text input with OK/Cancel
      dvxIntInputBox        Integer input with spinner, clamp range, and step
      dvxChoiceDialog       List selection with OK/Cancel
      dvxPromptSave         Canonical "Save changes?" Yes/No/Cancel dialog

## Flag Encoding

dvxMessageBox flags split into two nibbles: button configuration (low) and icon type (high). This matches the Win16 MessageBox() convention so OR'd flags read naturally:

    dvxMessageBox(ctx, "Confirm", "Delete file?", MB_YESNO | MB_ICONQUESTION);

Return values are ID_OK / ID_CANCEL / ID_YES / ID_NO / ID_RETRY.

# Resource System (dvxRes.h)

Resources are appended to DXE3 files (.app, .wgt, .lib) after the normal DXE content. The DXE loader never reads past the DXE header, so the appended data is invisible to dlopen. Every DXE can carry its own icons, text strings, and binary data without separate resource files.

## On-Disk Layout

    [DXE3 content]           -- untouched, loaded by dlopen
    [resource data entries]  -- sequential, variable length
    [resource directory]     -- fixed-size entries (48 bytes each)
    [footer]                 -- magic + directory offset + count (16 bytes)

Readers start from the end: seek to EOF - sizeof(footer), verify the magic (DVX_RES_MAGIC = "DVXR"), then seek to the directory. Entries are sorted at open time so lookups are O(log n) via bsearch.

## Types

      Type ID           Value   Payload
      -------           -----   -------
      DVX_RES_ICON      1       Image data (BMP or PNG, typically 16x16 or 32x32 icons)
      DVX_RES_TEXT      2       Null-terminated string (localisable UI text, author, copyright)
      DVX_RES_BINARY    3       Arbitrary data (app-specific)

## Runtime API

      Function           Description
      --------           -----------
      dvxResOpen         Open a handle by reading the footer and directory
      dvxResRead         Look up a resource by name and read its data into a malloc'd buffer
      dvxResFind         Look up a resource's directory entry (no data copy)
      dvxResClose        Release the handle
      dvxResAppend       Append a new resource to a DXE file
      dvxResRemove       Remove a resource by name

The dvxApp.h wrappers (dvxResLoadIcon, dvxResLoadText, dvxResLoadData) combine open + read + close for the common case.

# Preferences System (dvxPrefs.h)

Handle-based API over classic INI files. Multiple files can be open at once. Each prefsLoad / prefsCreate returns a PrefsHandleT opaque pointer passed to subsequent calls and freed with prefsClose. The system INI lives at DVX_INI_PATH = "CONFIG\\DVX.INI".

## Usage Pattern

    PrefsHandleT *h = prefsLoad(DVX_INI_PATH);
    int32_t  w      = prefsGetInt(h, "video", "width", 640);
    bool     sound  = prefsGetBool(h, "audio", "enable", true);
    const char *bg  = prefsGetString(h, "desktop", "wallpaper", "");

    prefsSetInt(h, "video", "width", 800);
    prefsSave(h);
    prefsClose(h);

Boolean getters recognise "true"/"yes"/"1" and "false"/"no"/"0" (case-insensitive). If the file does not exist, prefsLoad still returns a valid empty handle with the path captured so prefsSave can write a new file.

# Per-App Memory Tracking (dvxMem.h)

All allocations route through dvxMalloc/dvxFree wrappers that prepend a 16-byte header recording the owning app ID and allocation size. The Task Manager displays per-app memory usage, and leaks are detected at app termination.

## Transparent Interception

DXE code does NOT need to include dvxMem.h. The DXE export table maps malloc / free / calloc / realloc / strdup to the dvxXxx wrappers, so standard C code is tracked automatically.

Explicit use (e.g. in the Task Manager) can include dvxMem.h to call:

      Function               Purpose
      --------               -------
      dvxMemGetAppUsage      Query current bytes allocated for an app
      dvxMemResetApp         Free every tracked allocation charged to an app

The dvxMemAppIdPtr pointer is set by the shell to &ctx->currentAppId so the allocator always knows which app to charge.

# DXE Module System

DVX uses DJGPP's DXE3 (Dynamic eXtension) format for all loadable modules. DXE3 supports RTLD_GLOBAL symbol sharing -- symbols exported by one module are visible to all subsequently loaded modules. This is critical: widget DXEs call core API functions (e.g. rectFill, wgtInvalidate) that are exported by the core library DXE.

## Module Types

      Extension  Directory   Purpose                                             Examples
      ---------  ---------   -------                                             --------
      .lib       LIBS/       Core libraries loaded first. Provide infrastructure APIs.  libtasks.lib, libdvx.lib, dvxshell.lib
      .wgt       WIDGETS/    Widget type plugins. Each exports wgtRegister().    button.wgt, listview.wgt, terminal.wgt
      .app       APPS/*/     Application modules. Each exports appDescriptor and appMain(). Loaded on demand by the shell.  progman.app, notepad.app, cpanel.app

## Boot Sequence

      dvx.exe (loader)
         |
         +-- Enter VGA mode 13h, display splash screen with progress bar
         |
         +-- Scan LIBS/ for *.lib, WIDGETS/ for *.wgt
         |
         +-- Read .dep files for each module (dependency base names)
         |
         +-- Topological sort: load modules in dependency order
         |     - dlopen() with RTLD_GLOBAL
         |     - Each .wgt that exports wgtRegister() has it called
         |
         +-- Find and call shellMain() (exported by dvxshell.lib)
               |
               +-- dvxInit() -- video mode, input, font, colors, cursors
               |
               +-- Load desktop app (progman.app)
               |
               +-- Main loop:
                     dvxUpdate() -> tsYield() -> shellReapApps()

## Application Lifecycle

Two kinds of DXE apps:

### Callback-only (hasMainLoop = false)

appMain() creates windows, registers callbacks, and returns. The app lives through GUI callbacks driven by the shell's main loop. Lifecycle ends when the last window is closed. No extra task stack needed -- simpler and cheaper.

### Main-loop (hasMainLoop = true)

A dedicated cooperative task is created. appMain() runs in that task with its own loop, calling tsYield() to share CPU. Needed for apps with continuous work (terminal emulators, games). Lifecycle ends when appMain() returns.

## Crash Recovery

The platform layer installs signal handlers for SIGSEGV, SIGFPE, SIGILL. On crash, the handler logs platform-specific diagnostics (register dump on DJGPP), then longjmps back to the shell's main loop. The crashed app is killed; other apps and the shell survive. This provides Windows 3.1-style fault tolerance.

## Per-App Memory Tracking

All allocations route through dvxMalloc/dvxFree wrappers that prepend a 16-byte header recording the owning app ID and allocation size. The Task Manager displays per-app memory usage, and leaks are detected at app termination.

# Event Model

DVX uses a cooperative polling model. The main loop (dvxRun / dvxUpdate) runs this cycle each frame:

- Poll mouse -- platformMousePoll() returns position and button bitmask. Compare with previous frame for press/release edge detection.
- Poll keyboard -- platformKeyboardRead() returns ASCII + scancode. Non-blocking; returns false if buffer is empty.
- Dispatch to focused window -- the event loop fires window callbacks (onKey, onMouse, etc.) on the focused window. If the window has a widget tree, the widget system's installed handlers dispatch to individual widgets.
- Compositor pass -- merge dirty rects, composite, flush to LFB.
- Yield -- platformYield() or idle callback.

## Event Dispatch Chain

      Mouse/Keyboard Input
           |
      Global handlers (Ctrl+Esc, modal filter)
           |
      Accelerator table check (focused window)
           |
      Window callback (onMouse / onKey)
           |
      [If widget tree installed:]
           |
      widgetOnMouse / widgetOnKey
           |
      Widget hit test (widgetHitTest)
           |
      wclsOnMouse / wclsOnKey (vtable dispatch)
           |
      Universal callbacks (onClick, onChange, etc.)

## Accelerator Tables

Per-window accelerator tables map key + modifier combinations to command IDs. The runtime normalizes key/modifier at registration time (uppercase key, strip shift from modifiers) so matching at dispatch time is two integer comparisons per entry. Matched accelerators fire the window's onMenu callback with the command ID, unifying the menu and hotkey code paths.

## Mouse Cursor

Software-rendered cursor using the classic AND/XOR mask approach. Seven cursor shapes are compiled in: arrow, horizontal resize, vertical resize, NW-SE diagonal resize, NE-SW diagonal resize, busy (hourglass), and crosshair. The cursor is painted into the backbuffer on top of the composited frame and the affected region is flushed to the LFB each frame.

## Double-Click Detection

Timestamp-based: two clicks on the same target (title bar, minimized icon, close gadget) within the configurable double-click interval trigger the double-click action. Separate tracking for each target type.

# Font System

DVX uses fixed-width 8-pixel-wide bitmap fonts only. One size is provided: 8x16, matching the standard VGA ROM font and CP437 encoding (256 glyphs).

## BitmapFontT

      typedef struct {
          int32_t        charWidth;    // fixed width per glyph (always 8)
          int32_t        charHeight;   // 16
          int32_t        firstChar;    // typically 0
          int32_t        numChars;     // typically 256
          const uint8_t *glyphData;    // packed 1bpp, charHeight bytes per glyph
      } BitmapFontT;

Design rationale:

- Character positions are pure multiplication (x = col * 8).
- Glyph lookup is a single array index.
- Each scanline of a glyph is exactly one byte (1bpp at 8 pixels wide).
- No glyph-width tables, kerning, or per-character positioning needed.
- 8-pixel width aligns with byte boundaries -- no bit shifting in per-scanline rendering.

## Text Rendering Functions

drawChar() -- Renders a single character. Supports opaque (background fill) and transparent modes.

drawTextN() -- Optimized batch rendering for a known character count. Clips once for the entire run, fills background in a single rectFill, then overlays glyph foreground pixels. Significantly faster than per-character rendering for long runs.

drawTermRow() -- Renders an 80-column terminal row in a single pass, with per-cell foreground/background from a 16-color palette, blink attribute support, and cursor rendering. Exists because per-character terminal rendering is unacceptably slow on target hardware.

drawTextAccel() -- Renders text with & accelerator markers. The character after & is underlined to indicate the keyboard shortcut.

## Performance Optimization

AppContextT stores a fixed-point 16.16 reciprocal of font.charHeight (charHeightRecip) so that dividing by charHeight (for pixel-to-row conversion in terminal/text widgets) becomes a multiply+shift instead of an integer divide, which costs 40+ cycles on a 486.

# Color System

## Pixel Format

PixelFormatT describes the active VESA mode's pixel encoding. Populated once from the VBE mode info block. Stores shift, mask, and bit count for each channel so packColor() can convert RGB to native format with shift-and-mask arithmetic -- no per-pixel computation.

Supported depths:

      Depth    Bytes/Pixel  Notes
      -----    -----------  -----
      8 bpp    1            Palette mode. Nearest-index via 6x6x6 color cube + grey ramp.
      15 bpp   2            5-5-5 RGB (1 bit unused).
      16 bpp   2            5-6-5 RGB.
      32 bpp   4            8-8-8 RGB (8 bits unused).

## ColorSchemeT -- Theming

All 20 UI colors are pre-packed into display pixel format at init time. Every color is a uint32_t that can be written directly to the framebuffer with zero per-pixel conversion. The scheme must be regenerated on video mode change, but mode changes require re-init anyway.

Color roles mirror classic Motif/Windows 3.x conventions:

- desktop -- desktop background
- windowFace, windowHighlight, windowShadow -- window chrome bevel triplet
- activeTitleBg/Fg, inactiveTitleBg/Fg -- focused vs. unfocused title bar
- contentBg/Fg -- window content area
- menuBg/Fg, menuHighlightBg/Fg -- menus
- buttonFace -- button background
- scrollbarBg/Fg/Trough -- scrollbar components
- cursorFg/Bg -- mouse cursor colors

Source RGB values are kept in AppContextT.colorRgb[] for theme save/load. Themes are stored as INI files with a [colors] section. The API provides dvxLoadTheme(), dvxSaveTheme(), dvxSetColor(), and dvxResetColorScheme().

## Bevel Styles

Bevels are the defining visual element of the Motif aesthetic. Convenience macros create bevel style descriptors by swapping highlight and shadow colors:

      BEVEL_RAISED(colorScheme, borderWidth)       -- raised 3D look
      BEVEL_SUNKEN(colorScheme, face, borderWidth) -- sunken/inset look
      BEVEL_TROUGH(colorScheme)                    -- 1px scrollbar trough
      BEVEL_SB_BUTTON(colorScheme)                 -- scrollbar button

# Platform Layer

All OS-specific and CPU-specific code is isolated behind platform/dvxPlat.h. To port DVX, implement a new dvxPlatformXxx.c against this header.

## Implementations

      File                Target        Details
      ----                ------        -------
      dvxPlatformDos.c    DJGPP/DPMI    Real VESA VBE, INT 33h mouse, INT 16h keyboard, rep movsd/rep stosl asm spans, DPMI physical memory mapping for LFB, INT 9 hook for key-up, CuteMouse Wheel API.

## Abstraction Areas

### Video

platformVideoInit() -- mode probe and framebuffer setup. platformVideoShutdown() -- restore previous mode. platformVideoEnumModes() -- enumerate available modes.

### Framebuffer Flush

platformFlushRect() -- copy dirty rect from backBuf to LFB. On DOS, each scanline uses rep movsd for near-optimal aligned 32-bit writes over the PCI bus.

### Optimized Memory Spans

Six functions: platformSpanFill8/16/32() and platformSpanCopy8/16/32(). Called once per scanline of every rectangle fill, blit, and text draw. On DOS these use inline assembly for critical inner loops.

### Mouse Input

Polling model. platformMousePoll() returns position and button bitmask. Wheel support via CuteMouse API.

### Keyboard Input

platformKeyboardRead() -- non-blocking key read. platformKeyUpRead() -- key release detection (requires INT 9 hook on DOS). platformAltScanToChar() -- scancode-to-ASCII lookup for Alt+key combinations.

### Crash Recovery

platformInstallCrashHandler() -- signal handlers + longjmp for fault tolerance.

### DXE Support

platformRegisterDxeExports() -- register C runtime and platform symbols for DXE resolution. platformRegisterSymOverrides() -- register function pointer overrides for module loader.

# Build System

## Cross-Compilation

DVX is cross-compiled from Linux using a DJGPP cross-compiler (i586-pc-msdosdjgpp-gcc). The top-level Makefile orchestrates building all subsystems in dependency order.

      make               -- build everything
      ./mkcd.sh          -- build + create ISO for the target emulator

## Build Targets

      all: core tasks loader texthelp listhelp tools widgets shell taskmgr serial sql apps

      Target     Output                    Description
      ------     ------                    -----------
      core       bin/libs/libdvx.lib       GUI core library (draw, comp, wm, app, widget infrastructure)
      tasks      bin/libs/libtasks.lib     Cooperative task switcher
      loader     bin/dvx.exe               Bootstrap loader (the DOS executable)
      widgets    bin/widgets/*.wgt         29 widget type plugins
      shell      bin/libs/dvxshell.lib     DVX Shell (app management, desktop)
      taskmgr    bin/libs/taskmgr.lib      Task Manager (loaded as a separate DXE)
      texthelp   shared library            Shared text editing helpers (clipboard, word boundaries)
      listhelp   shared library            Shared dropdown/list helpers
      apps       bin/apps/*/*.app          Application modules (progman, notepad, clock, etc.)
      tools      bin/dvxres                Resource compiler (runs on Linux, builds resource sections into DXEs)
      serial     serial DXE libs           UART driver, HDLC packets, security, seclink
      sql        SQL DXE lib               SQLite integration

## DXE3 Build Process

Each DXE module is compiled to an object file with GCC, then linked with dxe3gen:

      # Compile
      i586-pc-msdosdjgpp-gcc -O2 -march=i486 -mtune=i586 -c -o widget.o widget.c

      # Link as DXE (exports all non-static symbols)
      dxe3gen -o widget.wgt -U widget.o

      # Optionally append resources
      dvxres build widget.wgt widget.res

The -E flag specifies exported symbols (prefixed with underscore per DJGPP convention). -U marks unresolved symbols as OK (they'll be resolved at load time from previously loaded DXEs).

## Deployment (mkcd.sh)

- Runs make all.
- Verifies critical outputs exist (dvx.exe, libtasks.lib, libdvx.lib, dvxshell.lib).
- Counts widget modules.
- Creates an ISO 9660 image from bin/ using mkisofs: -iso-level 1 (strict 8.3 filenames for DOS), -J (Joliet extensions for long names), -V DVX (volume label).
- Places the ISO at the target emulator's CD-ROM mount path.

## Compiler Flags

      -O2                  Optimization level 2
      -march=i486          486 instruction set baseline
      -mtune=i586          Optimize scheduling for Pentium
      -Wall -Wextra        Full warnings

## Directory Layout

      dvxgui/
      +-- core/              Core library sources (dvxVideo, dvxDraw, dvxComp, dvxWm, dvxApp, widget infra)
      |   +-- platform/      Platform abstraction (dvxPlat.h, dvxPlatformDos.c, dvxPlatformUtil.c)
      |   +-- thirdparty/    stb_image, stb_ds, stb_image_write
      +-- loader/            Bootstrap loader (dvx.exe)
      +-- tasks/             Cooperative task switcher (libtasks.lib)
      +-- shell/             DVX Shell (dvxshell.lib)
      +-- widgets/           Widget DXE modules (*.wgt), each in its own subdirectory
      |   +-- box/           VBox/HBox layout containers
      |   +-- button/        Push button
      |   +-- textInput/     Text entry field
      |   +-- listView/      Multi-column list
      |   +-- ...            (29 widget types total)
      +-- texthelp/          Shared text editing helpers
      +-- listhelp/          Shared dropdown/list helpers
      +-- apps/              Application DXE modules (*.app)
      |   +-- progman/       Program Manager (desktop)
      |   +-- notepad/       Text editor
      |   +-- cpanel/        Control Panel
      |   +-- imgview/       Image viewer
      |   +-- clock/         Clock
      |   +-- dvxdemo/       Demo / showcase app
      |   +-- dvxbasic/      DVX BASIC compiler and VM
      +-- tools/             Build tools (dvxres resource compiler)
      +-- rs232/             ISR-driven UART driver
      +-- packet/            HDLC framing, CRC-16, sliding window
      +-- security/          DH key exchange, XTEA cipher, DRBG RNG
      +-- seclink/           Encrypted channel wrapper
      +-- serial/            Combined serial stack DXE
      +-- proxy/             Linux proxy (emulator <-> secLink <-> telnet)
      +-- sql/               SQLite integration
      +-- bin/               Build output (dvx.exe, libs/, widgets/, apps/, config/)
      +-- obj/               Intermediate object files
      +-- docs/              Documentation

# DVX GUI API Reference

DOS Visual eXecutive -- Complete public API documentation covering every public function, type, and constant in the libdvx headers.

The DVX GUI is built as a five-layer architecture. Each layer is defined in its own header file. Additional headers cover dialogs, resources, preferences, memory tracking, the platform abstraction, and the widget system.

## Headers

- dvxTypes.h -- Shared type definitions and constants
- dvxCur.h -- Embedded mouse cursor bitmaps
- dvxFont.h -- Embedded 8x16 CP437 bitmap font
- dvxPal.h -- 8-bit mode 256-color palette
- dvxVideo.h -- Layer 1: VESA VBE video backend
- dvxDraw.h -- Layer 2: 2D drawing primitives
- dvxComp.h -- Layer 3: Dirty rectangle compositor
- dvxWm.h -- Layer 4: Window manager
- dvxApp.h -- Layer 5: Application API
- dvxDlg.h -- Modal dialog boxes
- dvxRes.h -- DXE-embedded resource system
- dvxPrefs.h -- INI preferences system
- dvxMem.h -- Per-app memory tracking
- dvxWgt.h -- Widget system public API
- dvxWgtP.h -- Widget plugin API
- platform/dvxPlat.h -- Platform abstraction layer

dvxTypes.h -- Shared Type Definitions

dvxCur.h -- Cursor Definitions

dvxFont.h -- Bitmap Font Data

dvxPal.h -- 8-bit Palette

dvxVideo.h -- Layer 1: Video Backend

dvxDraw.h -- Layer 2: Drawing Primitives

dvxComp.h -- Layer 3: Compositor

dvxWm.h -- Layer 4: Window Manager

dvxApp.h -- Layer 5: Application API

dvxDlg.h -- Modal Dialogs

dvxRes.h -- Resource System

dvxPrefs.h -- Preferences

dvxMem.h -- Memory Tracking

dvxWgt.h -- Widget System

dvxWgtP.h -- Widget Plugin API

platform/dvxPlat.h -- Platform Layer

# dvxTypes.h -- Shared Type Definitions

Central type definitions shared across all five layers of the DVX GUI stack. Every header includes this file. Contains no function definitions -- only structs, enums, typedefs, and compile-time constants.

## Core Structures

### PixelFormatT

Describes the pixel encoding for the active VESA video mode. Populated once at startup from the VBE mode info block, then treated as read-only.

      Field                                        Description
      -----                                        -----------
      int32_t bitsPerPixel                         8, 15, 16, or 32
      int32_t bytesPerPixel                        1, 2, 2, or 4
      uint32_t redMask, greenMask, blueMask        Bitmasks for each color channel
      int32_t redShift, greenShift, blueShift      Bit position of each color field
      int32_t redBits, greenBits, blueBits         Number of bits per channel

### DisplayT

Single display context passed by pointer through every layer. All drawing targets the backBuf; only dirty rects are flushed to lfb.

      Field                                  Description
      -----                                  -----------
      int32_t width, height                  Screen dimensions in pixels
      int32_t pitch                          Bytes per scanline
      PixelFormatT format                    Active pixel format
      uint8_t *lfb                           Mapped linear framebuffer (VESA LFB)
      uint8_t *backBuf                       System RAM backbuffer
      uint8_t *palette                       768 bytes for 8-bit mode, NULL otherwise
      int32_t clipX, clipY, clipW, clipH     Current clip rectangle

### RectT

Rectangle in origin + extent form. Used throughout the compositor, window manager, and widget layout engine.

      Field              Description
      -----              -----------
      int32_t x, y       Top-left corner
      int32_t w, h       Width and height

### BlitOpsT

Vtable for hot-path span operations. Resolved at init time based on pixel depth. On DOS, these dispatch to hand-written asm (rep stosl / rep movsd).

      Field                    Description
      -----                    -----------
      SpanFillFnT spanFill     Fill a horizontal span with a solid color
      SpanCopyFnT spanCopy     Copy a horizontal span between buffers
      int32_t bytesPerPixel    Bytes per pixel for the active mode
      int32_t pitch            Bytes per scanline

### BevelStyleT

Bevel drawing parameters. Swapping highlight/shadow flips raised vs. sunken appearance.

      Field                  Description
      -----                  -----------
      uint32_t highlight     Lighter color (top/left edges)
      uint32_t shadow        Darker color (bottom/right edges)
      uint32_t face          Interior fill color (0 = no fill)
      int32_t width          Border thickness in pixels (typically 2)

### BitmapFontT

Fixed-width 8-pixel-wide bitmap font descriptor. One size provided: 8x16 (standard VGA ROM font, CP437 encoding).

      Field                          Description
      -----                          -----------
      int32_t charWidth              Fixed width per glyph (always 8)
      int32_t charHeight             Glyph height (16 in the bundled font)
      int32_t firstChar              ASCII code of first glyph (typically 0)
      int32_t numChars               Number of glyphs (typically 256)
      const uint8_t *glyphData       Packed 1bpp data, charHeight bytes per glyph

### ColorSchemeT

All UI colors pre-packed into display pixel format at init time. Theme support is achieved by swapping this struct.

      Field                                              Description
      -----                                              -----------
      uint32_t desktop                                   Desktop background color
      uint32_t windowFace                                Window body / chrome face
      uint32_t windowHighlight                           Bevel highlight (top/left edge)
      uint32_t windowShadow                              Bevel shadow (bottom/right edge)
      uint32_t activeTitleBg, activeTitleFg              Focused window title bar
      uint32_t inactiveTitleBg, inactiveTitleFg          Unfocused window title bar
      uint32_t contentBg, contentFg                      Window content area default colors
      uint32_t menuBg, menuFg                            Menu bar and popup background/text
      uint32_t menuHighlightBg, menuHighlightFg          Menu item highlight
      uint32_t buttonFace                                Button face color
      uint32_t scrollbarBg, scrollbarFg, scrollbarTrough Scrollbar element colors
      uint32_t cursorFg, cursorBg                        Mouse cursor colors

### ColorIdE

Enum for addressing individual colors in ColorSchemeT. Order matches struct field order.

Values: ColorDesktopE, ColorWindowFaceE, ColorWindowHighlightE, ColorWindowShadowE, ColorActiveTitleBgE, ColorActiveTitleFgE, ColorInactiveTitleBgE, ColorInactiveTitleFgE, ColorContentBgE, ColorContentFgE, ColorMenuBgE, ColorMenuFgE, ColorMenuHighlightBgE, ColorMenuHighlightFgE, ColorButtonFaceE, ColorScrollbarBgE, ColorScrollbarFgE, ColorScrollbarTroughE, ColorCursorFgE, ColorCursorBgE, ColorCountE.

### DirtyListT

Fixed-capacity list of dirty rectangles. Dynamic array, grows on demand.

      Field              Description
      -----              -----------
      RectT *rects       Dynamic array of dirty rectangles
      int32_t count      Current number of dirty rects
      int32_t cap        Allocated capacity

### WindowT

Central window object. Each window owns a persistent content backbuffer and receives events through callback function pointers.

      Field                                                          Description
      -----                                                          -----------
      int32_t id                                                     Unique window identifier
      int32_t appId                                                  Shell app ID (0 = shell itself)
      int32_t x, y, w, h                                            Outer frame position and dimensions
      int32_t contentX, contentY, contentW, contentH                 Content area inset from frame
      char title[MAX_TITLE_LEN]                                      Window title text (max 128 chars)
      bool visible, focused, minimized, maximized, resizable, modal  Window state flags
      bool iconNeedsRefresh                                          true when contentBuf changed (for minimized icon refresh)
      uint8_t paintNeeded                                            PAINT_NONE / PAINT_PARTIAL / PAINT_FULL
      int32_t maxW, maxH                                             Maximum dimensions
      int32_t preMaxX, preMaxY, preMaxW, preMaxH                    Saved geometry before maximize
      uint8_t *contentBuf                                            Per-window content backbuffer
      int32_t contentPitch                                           Content buffer bytes per row
      uint8_t *iconData                                              Icon pixel data, NULL if none
      int32_t iconW, iconH, iconPitch                                Icon image dimensions and pitch
      MenuBarT *menuBar                                              Menu bar (NULL if no menus)
      ScrollbarT *vScroll, *hScroll                                  Scrollbars (NULL if not present)
      struct WidgetT *widgetRoot                                     Widget tree root (NULL if none)
      MenuT *contextMenu                                             Right-click context menu
      AccelTableT *accelTable                                        Keyboard accelerator table
      void *userData                                                 Application-defined data pointer

Callbacks:

      Callback                                                     Description
      --------                                                     -----------
      onPaint(WindowT *win, RectT *dirtyArea)                              Content repaint requested
      onKey(WindowT *win, int32_t key, int32_t mod)                        Key press
      onKeyUp(WindowT *win, int32_t scancode, int32_t mod)                 Key release
      onMouse(WindowT *win, int32_t x, int32_t y, int32_t buttons)         Mouse event (content-relative)
      onResize(WindowT *win, int32_t newW, int32_t newH)                   Window resized
      onClose(WindowT *win)                                                Close requested
      onMenu(WindowT *win, int32_t menuId)                                 Menu item or accelerator activated
      onScroll(WindowT *win, ScrollbarOrientE orient, int32_t value)       Scrollbar value changed
      int32_t onCursorQuery(WindowT *win, int32_t x, int32_t y)            Return CURSOR_* for hit position
      onFocus(WindowT *win)                                                Window gained focus
      onBlur(WindowT *win)                                                 Window lost focus

### WindowStackT

Z-ordered window stack (front-to-back: index count-1 is topmost). Owns system-wide drag/resize/scroll interaction state.

      Field                                              Description
      -----                                              -----------
      WindowT **windows                                  Dynamic array of window pointers
      int32_t count, cap                                 Current count and allocated capacity
      int32_t focusedIdx                                 Stack index of focused window
      int32_t dragWindow, dragOffX, dragOffY             Active drag state
      int32_t dragStartX, dragStartY                     Mouse position at drag begin (for deadzone)
      bool dragActive                                    True once mouse moved past deadzone
      int32_t resizeWindow, resizeEdge                   Active resize state
      int32_t scrollWindow, scrollOrient, scrollDragOff  Active scroll drag state

### MenuT / MenuItemT / MenuBarT

Menu system types. Fixed-size label buffers (MAX_MENU_LABEL = 32). Cascading submenus supported via MenuItemT.subMenu pointer.

      Field                            Description
      -----                            -----------
      MenuItemT.label                  Item text (supports & accelerator markers)
      MenuItemT.id                     Application-defined command ID
      MenuItemT.type                   MenuItemNormalE, MenuItemCheckE, or MenuItemRadioE
      MenuItemT.separator              true = horizontal divider line
      MenuItemT.enabled, checked       Item state
      MenuItemT.accelKey               Lowercase accelerator character (0 = none)
      MenuItemT.subMenu                Child menu for cascading (NULL if leaf)
      MenuT.label                      Menu bar label (e.g. "File")
      MenuT.items                      Dynamic array of MenuItemT
      MenuT.itemCount, itemCap         Current count and allocated capacity
      MenuT.barX, barW                 Computed position/width on the menu bar
      MenuT.accelKey                   Lowercase accelerator character (0 = none)
      MenuBarT.menus                   Dynamic array of MenuT
      MenuBarT.menuCount, menuCap      Current count and allocated capacity
      MenuBarT.activeIdx               Open popup index (-1 = none)
      MenuBarT.positionsDirty          True when barX/barW need recomputation

### ScrollbarT

Window-level scrollbar state. Managed by the WM layer, drawn after content.

      Field                        Description
      -----                        -----------
      ScrollbarOrientE orient      ScrollbarVerticalE or ScrollbarHorizontalE
      int32_t min, max             Scroll range
      int32_t value                Current position
      int32_t pageSize             Visible portion (for proportional thumb sizing)
      int32_t x, y, length         Computed screen position and track length

### AccelTableT / AccelEntryT

Per-window keyboard accelerator table. Entries are matched against keystrokes in the event loop and fire onMenu(cmdId) on match.

      Field                      Description
      -----                      -----------
      AccelEntryT.key            ASCII character or KEY_Fxx constant
      AccelEntryT.modifiers      Bitmask of ACCEL_CTRL, ACCEL_SHIFT, ACCEL_ALT
      AccelEntryT.cmdId          Command ID passed to onMenu
      AccelEntryT.normKey        Pre-normalized key (uppercased) for fast matching
      AccelEntryT.normMods       Pre-masked modifiers (CTRL|ALT only) for fast matching
      AccelTableT.entries        Dynamic array of AccelEntryT
      AccelTableT.count, cap     Current count and allocated capacity

### VideoModeInfoT

Describes an available video mode (enumerated at init).

      Field            Description
      -----            -----------
      int32_t w, h     Resolution
      int32_t bpp      Bits per pixel

### CursorT

Software-rendered 16x16 cursor using AND/XOR mask encoding.

      Field                          Description
      -----                          -----------
      int32_t width, height          Cursor dimensions (always 16x16)
      int32_t hotX, hotY             Hot spot coordinates
      const uint16_t *andMask        AND mask (0 = draw pixel, 1 = transparent)
      const uint16_t *xorData        XOR data (0 = black, 1 = white where AND = 0)

## Bevel Convenience Macros

      Macro                      Description
      -----                      -----------
      BEVEL_RAISED(cs, bw)       Raised bevel style from ColorSchemeT ptr and border width
      BEVEL_SUNKEN(cs, face, bw) Sunken bevel style with explicit face color
      BEVEL_TROUGH(cs)           1px sunken trough (for scrollbar tracks)
      BEVEL_SB_BUTTON(cs)        1px raised scrollbar button

## Chrome Constants

      Define                  Value   Description
      ------                  -----   -----------
      CHROME_BORDER_WIDTH     4       Outer frame border width
      CHROME_TITLE_HEIGHT     20      Title bar height
      CHROME_TITLE_PAD        4       Title text padding
      CHROME_INNER_BORDER     2       Inner chrome border
      CHROME_MENU_HEIGHT      20      Menu bar height
      CHROME_TOTAL_TOP        26      Total inset from top of frame to content
      CHROME_TOTAL_SIDE       6       Total inset from side of frame to content
      CHROME_TOTAL_BOTTOM     6       Total inset from bottom of frame to content

## Hit Test Constants

      Define          Value   Description
      ------          -----   -----------
      HIT_CONTENT     0       Content area
      HIT_TITLE       1       Title bar
      HIT_CLOSE       2       Close gadget
      HIT_RESIZE      3       Resize border
      HIT_MENU        4       Menu bar
      HIT_VSCROLL     5       Vertical scrollbar
      HIT_HSCROLL     6       Horizontal scrollbar
      HIT_MINIMIZE    7       Minimize gadget
      HIT_MAXIMIZE    8       Maximize gadget
      HIT_NONE        -1      No window hit (desktop)

## Mouse Button Flags

      Define          Value   Description
      ------          -----   -----------
      MOUSE_LEFT      1       Left mouse button
      MOUSE_RIGHT     2       Right mouse button
      MOUSE_MIDDLE    4       Middle mouse button

## Accelerator Modifier Flags

      Define          Value   Description
      ------          -----   -----------
      ACCEL_SHIFT     0x03    Shift key (matches BIOS shift state bits)
      ACCEL_CTRL      0x04    Ctrl key
      ACCEL_ALT       0x08    Alt key

## Extended Key Codes

      Define                  Description
      ------                  -----------
      KEY_F1 .. KEY_F12       Function keys (scancode | 0x100)
      KEY_INSERT              Insert key
      KEY_DELETE              Delete key
      KEY_HOME                Home key
      KEY_END                 End key
      KEY_PGUP                Page Up key
      KEY_PGDN                Page Down key

## Resize Edge Flags

      Define          Value   Description
      ------          -----   -----------
      RESIZE_NONE     0       No resize edge
      RESIZE_LEFT     1       Left edge
      RESIZE_RIGHT    2       Right edge
      RESIZE_TOP      4       Top edge
      RESIZE_BOTTOM   8       Bottom edge (combinable via OR for corners)

## Utility Macros

      Macro           Description
      -----           -----------
      DVX_MIN(a, b)   Return the smaller of two values
      DVX_MAX(a, b)   Return the larger of two values

# dvxCur.h -- Cursor Definitions

Embedded 16x16 mouse cursor bitmaps compiled as static const data. No external cursor files. Uses the standard AND/XOR mask encoding from the IBM VGA hardware cursor spec. The AND mask selects transparency (1 = transparent, 0 = opaque) and the XOR data selects black vs. white for opaque pixels.

## Cursor Shape IDs

      Define                      Value   Description
      ------                      -----   -----------
      CURSOR_ARROW                0       Standard arrow (hot spot at tip)
      CURSOR_RESIZE_H             1       Horizontal resize (left/right arrows)
      CURSOR_RESIZE_V             2       Vertical resize (up/down arrows)
      CURSOR_RESIZE_DIAG_NWSE     3       NW-SE diagonal resize
      CURSOR_RESIZE_DIAG_NESW     4       NE-SW diagonal resize
      CURSOR_BUSY                 5       Hourglass (wait)
      CURSOR_CROSSHAIR            6       Crosshair for placement
      CURSOR_COUNT                7       Total number of cursor shapes

## Data

### dvxCursors[CURSOR_COUNT]

Static const array of CursorT structs, indexed by CURSOR_xxx constants. Each entry includes the AND mask, XOR data (both as 16-element uint16_t arrays), dimensions (16x16), and hot spot coordinates.

### dvxCursor

Legacy alias for backward compatibility with code that predates multi-cursor support. Equivalent to dvxCursors[CURSOR_ARROW].

# dvxFont.h -- Embedded Bitmap Font Data

Raw glyph bitmaps for the standard 8x16 VGA ROM font covering the full IBM Code Page 437 character set (256 glyphs). Compiled in as a static const array, avoiding a real-mode INT 10h call at startup.

Glyph format: 1 bit per pixel, 8 pixels wide, MSB = leftmost pixel. Each glyph occupies 16 consecutive bytes (one byte per scanline). The 8-pixel width means per-scanline rendering never needs bit shifting across byte boundaries.

CP437 covers:

- 0-31 -- Smiley, card suits, arrows, notes (classic extended ASCII glyphs)
- 32-126 -- Printable ASCII
- 127 -- House glyph
- 128-175 -- Accented Latin letters, currency, fractions
- 176-223 -- Box-drawing characters (essential for chrome gadgets)
- 224-254 -- Greek letters, math symbols, super/subscripts
- 255 -- Non-breaking space

## Data

### font8x16

Static const uint8_t array of 256 * 16 = 4096 bytes containing the packed 1bpp glyph bitmaps, in ASCII code order.

### dvxFont8x16

Static const BitmapFontT struct describing the 8x16 font, ready to pass to drawText/drawTextN/drawChar. Use this as the default font for all text rendering.

## Constants

      Define              Value   Description
      ------              -----   -----------
      FONT_CHAR_WIDTH     8       Fixed glyph width in pixels (defined in dvxTypes.h)

# dvxPal.h -- 256-Color Palette for 8-bit Mode

Defines the 256-color VGA/VESA palette used in 8-bit video modes. Layout:

      Range     Purpose
      -----     -------
      0-215     6x6x6 color cube -- uniformly distributed RGB (6 levels per channel: 0, 51, 102, 153, 204, 255). Index = r*36 + g*6 + b.
      216-231   16-step grey ramp for smooth gradients
      232-239   Dedicated UI chrome colors (highlight, shadow, title bar, desktop)
      240-255   Reserved (black)

The cube layout enables O(1) color lookup: snapping an RGB triplet to the nearest cube vertex is integer division by 51. The grey ramp and chrome slots hold colors that need exact values not available in the cube.

## Chrome Color Indices

      Define                     Value   Description
      ------                     -----   -----------
      PAL_CHROME_HIGHLIGHT       232     White (bevel highlight)
      PAL_CHROME_SHADOW          233     Dark grey (bevel shadow)
      PAL_CHROME_ACTIVE_BG       234     Navy (focused title bar)
      PAL_CHROME_INACTIVE_BG     235     Grey (unfocused title bar)
      PAL_CHROME_DESKTOP         236     Steel blue (desktop)
      PAL_CHROME_SELECTION       237     Navy (selection highlight)
      PAL_CHROME_TEXT            238     Black (text)
      PAL_CHROME_WHITE           239     Bright white

## Inline Functions

### dvxGeneratePalette

    static inline void dvxGeneratePalette(uint8_t *pal);

Populate a 768-byte (256 * 3) RGB buffer with the default DVX 8-bit palette. Called once at init in 8-bit mode to program the DAC.

      Parameter   Description
      ---------   -----------
      pal         Output RGB buffer (768 bytes)

### dvxNearestPalEntry

    static inline uint8_t dvxNearestPalEntry(const uint8_t *pal, uint8_t r, uint8_t g, uint8_t b);

Find the nearest palette entry for an RGB color using minimum Euclidean distance. Two-phase: snap to color cube vertex (O(1)), then scan grey ramp and chrome entries (216-239) for a closer match. Called by packColor() in 8-bit mode.

      Parameter   Description
      ---------   -----------
      pal         Active 768-byte RGB palette
      r, g, b     Color components (0-255)

Returns: Palette index (0-239) of the nearest match.

# dvxVideo.h -- Layer 1: VESA VBE Video Backend

The lowest layer. Responsible for VESA VBE mode negotiation, LFB mapping via DPMI, system RAM backbuffer allocation, pixel format discovery, and color packing. LFB-only design: bank switching is deliberately unsupported.

## videoInit

    int32_t videoInit(DisplayT *d, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);

Probe VBE for a mode matching the requested resolution and depth, enable it, map the LFB into DPMI linear address space, and allocate a system RAM backbuffer. preferredBpp is a hint; the closest available depth is used if an exact match is not found.

      Parameter        Description
      ---------        -----------
      d                Display context to initialize
      requestedW/H     Desired screen resolution
      preferredBpp     Preferred bits per pixel (8, 15, 16, or 32)

Returns: 0 on success, negative on failure.

## videoShutdown

    void videoShutdown(DisplayT *d);

Restore VGA text mode (mode 3), unmap the LFB, and free the backbuffer. Safe to call even if videoInit() failed.

      Parameter   Description
      ---------   -----------
      d           Display context to shut down

## packColor

    uint32_t packColor(const DisplayT *d, uint8_t r, uint8_t g, uint8_t b);

Pack an RGB triplet into the display's native pixel format. For direct-color modes (15/16/32 bpp), returns a packed pixel value using shift/mask fields. For 8-bit mode, returns the nearest palette index via Euclidean distance in RGB space.

      Parameter   Description
      ---------   -----------
      d           Display context (provides pixel format)
      r, g, b     Color components (0-255)

Returns: Native pixel value suitable for direct framebuffer write.

## unpackColor

    void unpackColor(const DisplayT *d, uint32_t color, uint8_t *r, uint8_t *g, uint8_t *b);

Reverse of packColor -- decode a native pixel value to 8-bit RGB components. For direct-color modes, reverses the shift/mask arithmetic. For 8-bit mode, looks up the palette entry at the given index.

      Parameter   Description
      ---------   -----------
      d           Display context
      color       Packed native pixel value
      r, g, b     Output: color components (0-255)

## setClipRect

    void setClipRect(DisplayT *d, int32_t x, int32_t y, int32_t w, int32_t h);

Set the clip rectangle on the display. All subsequent draw operations clip to this rectangle. The caller must save and restore the clip rect around scoped operations.

      Parameter   Description
      ---------   -----------
      d           Display context
      x, y, w, h Clip rectangle in screen coordinates

## resetClipRect

    void resetClipRect(DisplayT *d);

Reset the clip rectangle to the full display dimensions.

      Parameter   Description
      ---------   -----------
      d           Display context

# dvxDraw.h -- Layer 2: Drawing Primitives

All 2D drawing operations: rectangle fills, bitmap blits, text rendering, bevels, lines, and cursor rendering. Every function draws into the display's backbuffer and clips to the current clip rectangle. This layer is stateless beyond the clip rect on DisplayT.

## drawInit

    void drawInit(BlitOpsT *ops, const DisplayT *d);

Populate a BlitOpsT with the correct span functions for the display's pixel depth. Must be called once after videoInit().

      Parameter   Description
      ---------   -----------
      ops         BlitOpsT to populate
      d           Initialized display context

## rectFill

    void rectFill(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);

Fill a rectangle with a solid color. Clips to the display clip rect. Workhorse for backgrounds, window fills, and clear operations.

      Parameter   Description
      ---------   -----------
      d           Display context
      ops         Blit operations vtable
      x, y, w, h Rectangle to fill
      color       Packed pixel color

## rectCopy

    void rectCopy(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h);

Copy a rectangle from an arbitrary source buffer into the backbuffer. Used to blit per-window content buffers during compositing.

      Parameter     Description
      ---------     -----------
      d             Display context
      ops           Blit operations vtable
      dstX, dstY    Destination position in backbuffer
      srcBuf        Source pixel buffer
      srcPitch      Source buffer bytes per row
      srcX, srcY    Origin within source buffer
      w, h          Rectangle dimensions to copy

## rectCopyGrayscale

    void rectCopyGrayscale(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h);

Copy a rectangle with grayscale conversion. Each pixel's RGB is converted to luminance (0.299R + 0.587G + 0.114B) for a disabled/grayed appearance.

      Parameter       Description
      ---------       -----------
      d               Display context
      ops             Blit operations vtable
      dstX, dstY      Destination position
      srcBuf, srcPitch Source buffer and pitch
      srcX, srcY      Source origin
      w, h            Rectangle dimensions

## rectCopyTransparent

    void rectCopyTransparent(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h, uint32_t keyColor);

Copy with color-key transparency. Pixels matching keyColor are skipped, letting the destination show through. Used to draw image buttons and icons with transparent backgrounds.

      Parameter        Description
      ---------        -----------
      d                Display context
      ops              Blit operations vtable
      dstX, dstY       Destination position
      srcBuf, srcPitch Source buffer and pitch
      srcX, srcY       Source origin
      w, h             Rectangle dimensions
      keyColor         Packed color treated as transparent

## drawBevel

    void drawBevel(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const BevelStyleT *style);

Draw a beveled frame. Top/left edges in highlight color, bottom/right in shadow. Interior filled with face color if non-zero.

      Parameter   Description
      ---------   -----------
      d           Display context
      ops         Blit operations vtable
      x, y, w, h Outer bevel rectangle
      style       Bevel colors and width

## drawChar

    int32_t drawChar(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, char ch, uint32_t fg, uint32_t bg, bool opaque);

Draw a single character glyph. When opaque is true, the background fills the entire cell; when false, only foreground pixels are drawn (transparent background).

      Parameter   Description
      ---------   -----------
      d           Display context
      ops         Blit operations vtable
      font        Bitmap font
      x, y        Character position
      ch          Character to draw
      fg, bg      Foreground and background packed colors
      opaque      true = fill background, false = transparent

Returns: Advance width (always charWidth).

## drawText

    void drawText(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque);

Draw a null-terminated string. Calls drawChar per character.

      Parameter   Description
      ---------   -----------
      d           Display context
      ops         Blit operations vtable
      font        Bitmap font
      x, y        Start position
      text        Null-terminated string
      fg, bg      Foreground and background packed colors
      opaque      true = fill background, false = transparent

## drawTextN

    void drawTextN(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, int32_t count, uint32_t fg, uint32_t bg, bool opaque);

Optimized batch text rendering for a known character count. Computes clip bounds once, fills background in a single rectFill, then overlays glyph foreground pixels. Significantly faster than per-character drawChar for long runs (terminal rows, list items).

      Parameter   Description
      ---------   -----------
      d           Display context
      ops         Blit operations vtable
      font        Bitmap font
      x, y        Start position
      text        Character buffer (not required to be null-terminated)
      count       Number of characters to render
      fg, bg      Foreground and background packed colors
      opaque      true = fill background, false = transparent

## textWidth

    int32_t textWidth(const BitmapFontT *font, const char *text);

Return the pixel width of a null-terminated string (strlen(text) * charWidth).

      Parameter   Description
      ---------   -----------
      font        Bitmap font
      text        Null-terminated string

Returns: Width in pixels.

## accelParse

    char accelParse(const char *text);

Scan text for an & prefix and return the following character as a lowercase accelerator key. "&File" returns 'f', "E&xit" returns 'x'.

      Parameter   Description
      ---------   -----------
      text        Text with optional & accelerator marker

Returns: Lowercase accelerator character, or 0 if none.

## drawTextAccel

    void drawTextAccel(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque);

Draw text with & accelerator markers. The character after & is drawn underlined to indicate the keyboard shortcut. && produces a literal &. Used for menu items and button labels.

      Parameter   Description
      ---------   -----------
      d           Display context
      ops         Blit operations vtable
      font        Bitmap font
      x, y        Start position
      text        Text with & markers
      fg, bg      Foreground and background packed colors
      opaque      true = fill background, false = transparent

## textWidthAccel

    int32_t textWidthAccel(const BitmapFontT *font, const char *text);

Measure text width excluding & markers (so "&File" measures as 4 chars).

      Parameter   Description
      ---------   -----------
      font        Bitmap font
      text        Text with optional & markers

Returns: Width in pixels.

## drawMaskedBitmap

    void drawMaskedBitmap(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const uint16_t *andMask, const uint16_t *xorData, uint32_t fgColor, uint32_t bgColor);

Draw a 1-bit AND/XOR masked bitmap. Used for software-rendered mouse cursors.

      Parameter       Description
      ---------       -----------
      d               Display context
      ops             Blit operations vtable
      x, y            Screen position
      w, h            Bitmap dimensions
      andMask         AND transparency mask (one uint16_t per row)
      xorData         XOR color data
      fgColor, bgColor Cursor foreground and background packed colors

## drawTermRow

    void drawTermRow(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, int32_t cols, const uint8_t *lineData, const uint32_t *palette, bool blinkVisible, int32_t cursorCol);

Render an entire row of terminal character cells (ch/attr byte pairs) in a single pass. Colors looked up from a 16-color palette. Attribute bit 7 controls blink.

      Parameter       Description
      ---------       -----------
      d               Display context
      ops             Blit operations vtable
      font            Bitmap font
      x, y            Row start position
      cols            Number of columns
      lineData        Packed ch/attr byte pairs (2 bytes per cell)
      palette         16-entry packed color palette
      blinkVisible    false = hide blinking characters
      cursorCol       Column for inverted text cursor (-1 = none)

## drawFocusRect

    void drawFocusRect(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);

Draw a 1px dotted rectangle (alternating pixels). Used for keyboard focus indicators, matching the Windows 3.x focus rectangle convention.

      Parameter   Description
      ---------   -----------
      d           Display context
      ops         Blit operations vtable
      x, y, w, h Focus rectangle bounds
      color       Dot color (packed)

## drawHLine

    void drawHLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, uint32_t color);

Draw a horizontal line (1px tall).

      Parameter   Description
      ---------   -----------
      d           Display context
      ops         Blit operations vtable
      x, y        Start position
      w           Width in pixels
      color       Packed pixel color

## drawVLine

    void drawVLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t h, uint32_t color);

Draw a vertical line (1px wide).

      Parameter   Description
      ---------   -----------
      d           Display context
      ops         Blit operations vtable
      x, y        Start position
      h           Height in pixels
      color       Packed pixel color

# dvxComp.h -- Layer 3: Dirty Rectangle Compositor

Tracks changed screen regions and ensures only dirty regions are redrawn and flushed to video memory. The compositing pipeline: mark dirty, merge overlapping rects, redraw desktop + windows (back-to-front, painter's algorithm), flush to LFB.

## dirtyListInit

    void dirtyListInit(DirtyListT *dl);

Zero the dirty rect count. Called at the start of each frame.

      Parameter   Description
      ---------   -----------
      dl          Dirty list to initialize

## dirtyListAdd

    void dirtyListAdd(DirtyListT *dl, int32_t x, int32_t y, int32_t w, int32_t h);

Enqueue a dirty rectangle. Grows dynamically; triggers merge at a soft capacity limit.

      Parameter   Description
      ---------   -----------
      dl          Dirty list
      x, y, w, h Dirty rectangle in screen coordinates

## dirtyListMerge

    void dirtyListMerge(DirtyListT *dl);

Consolidate the dirty list by merging overlapping and adjacent rects. Uses iterative pairwise merge: if combining two rects does not increase total area beyond a threshold, they are merged. Reduces compositor passes and LFB flush operations.

      Parameter   Description
      ---------   -----------
      dl          Dirty list to merge

## dirtyListClear

    void dirtyListClear(DirtyListT *dl);

Reset the dirty list to empty (sets count to 0).

      Parameter   Description
      ---------   -----------
      dl          Dirty list to clear

## flushRect

    void flushRect(DisplayT *d, const RectT *r);

Copy a rectangle from the system RAM backbuffer to the LFB (video memory). This is the only place the real framebuffer is written. Uses platform-specific fast copy (rep movsd on DOS) for each scanline.

      Parameter   Description
      ---------   -----------
      d           Display context
      r           Rectangle to flush

## rectIntersect

    bool rectIntersect(const RectT *a, const RectT *b, RectT *result);

Compute the intersection of two rectangles.

      Parameter   Description
      ---------   -----------
      a, b        Input rectangles
      result      Output: intersection rectangle (valid only when return is true)

Returns: true if the rectangles overlap, false if disjoint.

# dvxWm.h -- Layer 4: Window Manager

Manages the window lifecycle, Z-order stack, chrome drawing, hit testing, and interactive operations (drag, resize, scroll). The WM owns window geometry and chrome; content is owned by the application via callbacks or the widget system.

## Initialization

### wmInit

    void wmInit(WindowStackT *stack);

Zero the window stack. Must be called before any other WM function.

      Parameter   Description
      ---------   -----------
      stack       Window stack to initialize

## Window Lifecycle

### wmCreateWindow

    WindowT *wmCreateWindow(WindowStackT *stack, DisplayT *d, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);

Allocate a new window, initialize its geometry and content buffer, and push it to the top of the Z-order stack. Returns with all callbacks NULL; the caller should set onPaint/onKey/etc. before the next event loop iteration.

      Parameter   Description
      ---------   -----------
      stack       Window stack
      d           Display context
      title       Window title text
      x, y        Initial position
      w, h        Initial outer frame dimensions
      resizable   true = allow user resize

Returns: Pointer to new WindowT, or NULL on failure.

### wmDestroyWindow

    void wmDestroyWindow(WindowStackT *stack, WindowT *win);

Free the window's content buffer and all attached resources (menu bar, scrollbars, widget tree), remove it from the stack, and dirty the vacated region.

      Parameter   Description
      ---------   -----------
      stack       Window stack
      win         Window to destroy

## Z-Order and Focus

### wmRaiseWindow

    void wmRaiseWindow(WindowStackT *stack, DirtyListT *dl, int32_t idx);

Move window at stack index idx to the top of the Z-order. Dirties both old and new top positions so overlapping windows get repainted.

      Parameter   Description
      ---------   -----------
      stack       Window stack
      dl          Dirty list for repaint marking
      idx         Stack index of window to raise

### wmSetFocus

    void wmSetFocus(WindowStackT *stack, DirtyListT *dl, int32_t idx);

Transfer keyboard focus to the window at stack index idx. Unfocuses the previously focused window and dirties both title bars.

      Parameter   Description
      ---------   -----------
      stack       Window stack
      dl          Dirty list
      idx         Stack index of window to focus

## Geometry

### wmUpdateContentRect

    void wmUpdateContentRect(WindowT *win);

Recompute contentX/Y/W/H from the window's outer frame dimensions, accounting for chrome borders, title bar, menu bar, and scrollbars. Must be called after any change to frame size or chrome configuration.

      Parameter   Description
      ---------   -----------
      win         Window to update

### wmReallocContentBuf

    int32_t wmReallocContentBuf(WindowT *win, const DisplayT *d);

Reallocate the per-window content backbuffer to match current contentW/H. Old buffer contents are lost; caller should trigger a full repaint via onPaint afterward.

      Parameter   Description
      ---------   -----------
      win         Window to reallocate
      d           Display context (for bytes-per-pixel)

Returns: 0 on success, -1 on allocation failure.

### wmMinWindowSize

    void wmMinWindowSize(const WindowT *win, int32_t *minW, int32_t *minH);

Get the minimum window size. Accounts for chrome, gadgets, and menu bar.

      Parameter    Description
      ---------    -----------
      win          Window
      minW, minH   Output: minimum width and height

## Menu Bar

### wmAddMenuBar

    MenuBarT *wmAddMenuBar(WindowT *win);

Allocate and attach a menu bar to a window. Adjusts content area to make room (CHROME_MENU_HEIGHT pixels). One menu bar per window.

      Parameter   Description
      ---------   -----------
      win         Window to add menu bar to

Returns: Pointer to the new MenuBarT.

### wmDestroyMenuBar

    void wmDestroyMenuBar(WindowT *win, const DisplayT *d);

Free the menu bar and reclaim the content area. The content buffer is reallocated to fit the grown content area.

      Parameter   Description
      ---------   -----------
      win         Window to remove menu bar from
      d           Display context; pass NULL only during window teardown

### wmAddMenu

    MenuT *wmAddMenu(MenuBarT *bar, const char *label);

Append a dropdown menu to the menu bar. The label supports & accelerator markers (e.g. "&File").

      Parameter   Description
      ---------   -----------
      bar         Menu bar
      label       Menu label text

Returns: Pointer to the new MenuT to populate with items.

### wmAddMenuItem

    void wmAddMenuItem(MenuT *menu, const char *label, int32_t id);

Append a clickable item to a menu. The id is passed to the window's onMenu callback when selected.

      Parameter   Description
      ---------   -----------
      menu        Menu to append to
      label       Item label (supports & markers)
      id          Application-defined command ID

### wmAddMenuCheckItem

    void wmAddMenuCheckItem(MenuT *menu, const char *label, int32_t id, bool checked);

Add a checkbox-style menu item. Check state toggles on click; rendered with a checkmark glyph.

      Parameter   Description
      ---------   -----------
      menu        Menu to append to
      label       Item label
      id          Command ID
      checked     Initial checked state

### wmAddMenuRadioItem

    void wmAddMenuRadioItem(MenuT *menu, const char *label, int32_t id, bool checked);

Add a radio-style menu item. Radio groups are defined implicitly by consecutive radio items; selecting one unchecks the others in the group.

      Parameter   Description
      ---------   -----------
      menu        Menu to append to
      label       Item label
      id          Command ID
      checked     Initial checked state

### wmAddMenuSeparator

    void wmAddMenuSeparator(MenuT *menu);

Insert a horizontal separator line. Separators are not interactive.

      Parameter   Description
      ---------   -----------
      menu        Menu to append separator to

### wmRemoveMenuItem

    bool wmRemoveMenuItem(MenuT *menu, int32_t id);

Remove a menu item by command ID. Searches the menu's items array and shifts remaining items down to close the gap.

      Parameter   Description
      ---------   -----------
      menu        Menu to remove item from
      id          Command ID to remove

Returns: true if a matching item was found and removed.

### wmClearMenuItems

    void wmClearMenuItems(MenuT *menu);

Remove all items from a menu while preserving the menu itself on the menu bar. Use when rebuilding a menu's contents dynamically (e.g. a recent-files submenu).

      Parameter   Description
      ---------   -----------
      menu        Menu to empty

### wmMenuItemIsChecked

    bool wmMenuItemIsChecked(MenuBarT *bar, int32_t id);

Query the checked state of a menu item by command ID. Searches all menus in the bar.

      Parameter   Description
      ---------   -----------
      bar         Menu bar
      id          Command ID to query

Returns: true if checked.

### wmMenuItemSetChecked

    void wmMenuItemSetChecked(MenuBarT *bar, int32_t id, bool checked);

Set the checked state of a menu item by command ID. For radio items, setting checked=true also unchecks other radio items in the same group.

      Parameter   Description
      ---------   -----------
      bar         Menu bar
      id          Command ID
      checked     New checked state

### wmMenuItemSetEnabled

    void wmMenuItemSetEnabled(MenuBarT *bar, int32_t id, bool enabled);

Enable or disable a menu item by command ID.

      Parameter   Description
      ---------   -----------
      bar         Menu bar
      id          Command ID
      enabled     true = enabled, false = grayed out

### wmAddSubMenu

    MenuT *wmAddSubMenu(MenuT *parentMenu, const char *label);

Create a cascading submenu attached to a parent menu. The child MenuT is heap-allocated and freed when the parent window is destroyed.

      Parameter    Description
      ---------    -----------
      parentMenu   Parent menu to attach submenu to
      label        Submenu label text

Returns: Pointer to the child MenuT, or NULL on allocation failure.

### wmCreateMenu

    MenuT *wmCreateMenu(void);

Allocate a heap-resident MenuT for use as a context menu (right-click). Unlike menu bar menus, context menus are standalone allocations. Free with wmFreeMenu().

Returns: Pointer to the new MenuT.

### wmFreeMenu

    void wmFreeMenu(MenuT *menu);

Free a standalone menu allocated with wmCreateMenu(). Also frees any heap-allocated submenu children recursively.

      Parameter   Description
      ---------   -----------
      menu        Menu to free

## Scrollbars

### wmAddVScrollbar

    ScrollbarT *wmAddVScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize);

Attach a vertical scrollbar to the right edge of the window's content area. Shrinks contentW by SCROLLBAR_WIDTH pixels.

      Parameter   Description
      ---------   -----------
      win         Window
      min, max    Scroll value range
      pageSize    Visible portion (controls thumb size)

Returns: Pointer to the new ScrollbarT.

### wmAddHScrollbar

    ScrollbarT *wmAddHScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize);

Attach a horizontal scrollbar to the bottom edge. Shrinks contentH by SCROLLBAR_WIDTH pixels.

      Parameter   Description
      ---------   -----------
      win         Window
      min, max    Scroll value range
      pageSize    Visible portion

Returns: Pointer to the new ScrollbarT.

## Drawing

### wmDrawChrome

    void wmDrawChrome(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo);

Draw the window frame: outer bevel, title bar with text, close/minimize/maximize gadgets, and menu bar if present. Drawing is clipped to the intersection with clipTo.

      Parameter   Description
      ---------   -----------
      d           Display context
      ops         Blit operations vtable
      font        Bitmap font for title text
      colors      Color scheme
      win         Window to draw chrome for
      clipTo      Dirty rectangle to clip drawing to

### wmDrawContent

    void wmDrawContent(DisplayT *d, const BlitOpsT *ops, WindowT *win, const RectT *clipTo);

Blit the window's content backbuffer into the display backbuffer, clipped to the dirty rect. Pure copy operation (no drawing).

      Parameter   Description
      ---------   -----------
      d           Display context
      ops         Blit operations vtable
      win         Window
      clipTo      Dirty rectangle

### wmDrawScrollbars

    void wmDrawScrollbars(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo);

Draw scrollbars (track, arrows, proportional thumb) for a window. Drawn after content so scrollbars overlay the content area edge.

      Parameter   Description
      ---------   -----------
      d           Display context
      ops         Blit operations vtable
      colors      Color scheme
      win         Window
      clipTo      Dirty rectangle

### wmDrawMinimizedIcons

    void wmDrawMinimizedIcons(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, const WindowStackT *stack, const RectT *clipTo);

Draw icons for all minimized windows along the bottom of the screen. Each icon shows a scaled preview of the window's content with a beveled border.

      Parameter   Description
      ---------   -----------
      d           Display context
      ops         Blit operations vtable
      colors      Color scheme
      stack       Window stack
      clipTo      Dirty rectangle

### wmDrawVScrollbarAt

    void wmDrawVScrollbarAt(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t x, int32_t y, int32_t h, int32_t scrollPos, int32_t visibleItems, int32_t totalItems);

Draw a standalone vertical scrollbar at the given screen coordinates, without a ScrollbarT struct. Used by popup lists (dropdown, combobox) that need a scrollbar inline within a popup overlay. Thumb size and position are computed from scrollPos / visibleItems / totalItems.

      Parameter       Description
      ---------       -----------
      d               Display context
      ops             Blit operations vtable
      colors          Color scheme
      x, y            Screen position (top of scrollbar)
      h               Track height in pixels
      scrollPos       Current top visible item index
      visibleItems    Visible item count (for thumb size)
      totalItems      Total item count

## Hit Testing

### wmHitTest

    int32_t wmHitTest(const WindowStackT *stack, int32_t mx, int32_t my, int32_t *hitPart);

Determine which window and chrome region is under the given screen coordinates. Iterates front-to-back (highest Z first) so the topmost window wins.

      Parameter   Description
      ---------   -----------
      stack       Window stack
      mx, my      Screen coordinates
      hitPart     Output: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, etc.

Returns: Stack index of hit window, or -1 for desktop.

### wmResizeEdgeHit

    int32_t wmResizeEdgeHit(const WindowT *win, int32_t mx, int32_t my);

Determine which edge(s) of a window's border zone are targeted for resize.

      Parameter   Description
      ---------   -----------
      win         Window
      mx, my      Screen coordinates

Returns: Bitmask of RESIZE_LEFT / RESIZE_RIGHT / RESIZE_TOP / RESIZE_BOTTOM.

### wmMinimizedIconHit

    int32_t wmMinimizedIconHit(const WindowStackT *stack, const DisplayT *d, int32_t mx, int32_t my);

Hit-test minimized icons at the bottom of the screen.

      Parameter   Description
      ---------   -----------
      stack       Window stack
      d           Display context
      mx, my      Screen coordinates

Returns: Stack index of the minimized window, or -1.

## Drag and Resize

### wmDragBegin

    void wmDragBegin(WindowStackT *stack, int32_t idx, int32_t mouseX, int32_t mouseY);

Begin a window drag operation. Records the mouse offset from the window origin.

      Parameter     Description
      ---------     -----------
      stack         Window stack
      idx           Stack index of window to drag
      mouseX/Y      Current mouse position

### wmDragMove

    void wmDragMove(WindowStackT *stack, DirtyListT *dl, int32_t mouseX, int32_t mouseY, int32_t screenW, int32_t screenH);

Update window position during an active drag. Dirties both old and new positions.

      Parameter      Description
      ---------      -----------
      stack          Window stack
      dl             Dirty list
      mouseX/Y       Current mouse position
      screenW/H      Screen dimensions (for clamping)

### wmDragEnd

    void wmDragEnd(WindowStackT *stack);

End the current drag operation. Clears dragWindow state.

      Parameter   Description
      ---------   -----------
      stack       Window stack

### wmResizeBegin

    void wmResizeBegin(WindowStackT *stack, int32_t idx, int32_t edge, int32_t mouseX, int32_t mouseY);

Begin a window resize operation. Records which edge(s) are being dragged.

      Parameter   Description
      ---------   -----------
      stack       Window stack
      idx         Stack index
      edge        Bitmask of RESIZE_xxx flags
      mouseX/Y    Current mouse position

### wmResizeMove

    void wmResizeMove(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, int32_t *mouseX, int32_t *mouseY);

Update window dimensions during an active resize. Enforces MIN_WINDOW_W/H and maxW/maxH constraints. Reallocates content buffer and calls onResize if size changed. mouseX/mouseY are in/out: clamped on return for cursor warping.

      Parameter   Description
      ---------   -----------
      stack       Window stack
      dl          Dirty list
      d           Display context
      mouseX/Y    In/out: mouse position (clamped on return)

### wmResizeEnd

    void wmResizeEnd(WindowStackT *stack);

End the current resize operation. Clears resizeWindow state.

      Parameter   Description
      ---------   -----------
      stack       Window stack

## Scrollbar Interaction

### wmScrollbarClick

    void wmScrollbarClick(WindowStackT *stack, DirtyListT *dl, int32_t idx, ScrollbarOrientE orient, int32_t mx, int32_t my);

Handle an initial click on a scrollbar. Determines what was hit (arrows, trough, or thumb) and either adjusts the value immediately or begins a thumb drag.

      Parameter   Description
      ---------   -----------
      stack       Window stack
      dl          Dirty list
      idx         Stack index of window
      orient      ScrollbarVerticalE or ScrollbarHorizontalE
      mx, my      Click screen coordinates

### wmScrollbarDrag

    void wmScrollbarDrag(WindowStackT *stack, DirtyListT *dl, int32_t mx, int32_t my);

Update the scroll value during an active thumb drag. Maps mouse position along the track to a proportional scroll value.

      Parameter   Description
      ---------   -----------
      stack       Window stack
      dl          Dirty list
      mx, my      Current mouse position

### wmScrollbarEnd

    void wmScrollbarEnd(WindowStackT *stack);

End an active scrollbar thumb drag.

      Parameter   Description
      ---------   -----------
      stack       Window stack

## Minimize / Maximize / Restore

### wmMaximize

    void wmMaximize(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);

Maximize a window. Saves current geometry, then expands to screen or maxW/maxH bounds.

      Parameter   Description
      ---------   -----------
      stack       Window stack
      dl          Dirty list
      d           Display context
      win         Window to maximize

### wmMinimize

    void wmMinimize(WindowStackT *stack, DirtyListT *dl, WindowT *win);

Minimize a window. Hides the window and shows an icon at the bottom of the screen.

      Parameter   Description
      ---------   -----------
      stack       Window stack
      dl          Dirty list
      win         Window to minimize

### wmRestore

    void wmRestore(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);

Restore a maximized window to its pre-maximize geometry.

      Parameter   Description
      ---------   -----------
      stack       Window stack
      dl          Dirty list
      d           Display context
      win         Maximized window to restore

### wmRestoreMinimized

    void wmRestoreMinimized(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);

Restore a minimized window (show it again and remove the icon).

      Parameter   Description
      ---------   -----------
      stack       Window stack
      dl          Dirty list
      d           Display context
      win         Minimized window to restore

## Minimized Icon Layout

### wmMinimizedIconPos

    void wmMinimizedIconPos(const DisplayT *d, int32_t index, int32_t *x, int32_t *y);

Compute the screen position of a minimized icon by ordinal index. Icons wrap into rows from bottom to top when the screen fills up.

      Parameter   Description
      ---------   -----------
      d           Display context
      index       Ordinal index of the minimized icon
      x, y        Output: screen position

### wmMinimizedIconRect

    void wmMinimizedIconRect(const WindowStackT *stack, const DisplayT *d, int32_t *y, int32_t *h);

Compute the screen rect covering all minimized icon rows. Used to dirty the icon area when windows are minimized or restored.

      Parameter   Description
      ---------   -----------
      stack       Window stack
      d           Display context
      y, h        Output: vertical extent of icon area

## Miscellaneous

### wmSetTitle

    void wmSetTitle(WindowT *win, DirtyListT *dl, const char *title);

Set the window title and dirty the title bar for repaint.

      Parameter   Description
      ---------   -----------
      win         Window
      dl          Dirty list
      title       New title text

### wmSetIcon

    int32_t wmSetIcon(WindowT *win, const char *path, const DisplayT *d);

Load an icon image for a window from a file. Converts to display pixel format.

      Parameter   Description
      ---------   -----------
      win         Window
      path        Image file path
      d           Display context

Returns: 0 on success, -1 on failure.

# dvxApp.h -- Layer 5: Application API

The topmost layer and the public-facing API. Aggregates all lower layers into a single AppContextT. Applications interact exclusively through dvx*() functions and window callbacks. The event loop follows a cooperative model: poll, dispatch, composite, yield.

## AppContextT

Single monolithic context that owns all GUI state. Contains the display, window stack, dirty list, blit ops, font, color scheme, popup state, cursor state, mouse/keyboard state, tooltip state, wallpaper buffer, video mode list, and various configuration fields. Allocated on the caller's stack or statically.

## Initialization and Shutdown

### dvxInit

    int32_t dvxInit(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);

Initialize the entire GUI stack: video mode, input devices, font, color scheme, cursor shapes, and internal state. Single entry point for starting a DVX application.

      Parameter        Description
      ---------        -----------
      ctx              Application context to initialize
      requestedW/H     Desired screen resolution
      preferredBpp     Preferred bits per pixel

Returns: 0 on success, negative on failure.

### dvxShutdown

    void dvxShutdown(AppContextT *ctx);

Tear down the GUI stack in reverse order: destroy all windows, restore text mode, release input devices. Safe to call after a failed dvxInit().

      Parameter   Description
      ---------   -----------
      ctx         Application context

### dvxChangeVideoMode

    int32_t dvxChangeVideoMode(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);

Switch to a new video mode live. Reallocates the backbuffer, all window content buffers, repacks colors, rescales wallpaper, and repositions off-screen windows.

      Parameter        Description
      ---------        -----------
      ctx              Application context
      requestedW/H     New resolution
      preferredBpp     New bits per pixel

Returns: 0 on success, -1 on failure (old mode restored).

## Event Loop

### dvxRun

    void dvxRun(AppContextT *ctx);

Enter the main event loop. Polls input, dispatches events, composites dirty regions, and yields on each iteration. Returns when ctx->running becomes false.

      Parameter   Description
      ---------   -----------
      ctx         Application context

### dvxUpdate

    bool dvxUpdate(AppContextT *ctx);

Process exactly one frame of the event loop. For applications that integrate the GUI into their own main loop (e.g. polling serial ports between frames).

      Parameter   Description
      ---------   -----------
      ctx         Application context

Returns: false when the GUI wants to exit.

### dvxQuit

    void dvxQuit(AppContextT *ctx);

Request exit from the main event loop (sets ctx->running = false).

      Parameter   Description
      ---------   -----------
      ctx         Application context

## Window Management

### dvxCreateWindow

    WindowT *dvxCreateWindow(AppContextT *ctx, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);

Create a window at an explicit screen position. The window is raised to the top, focused, and its entire region is dirtied.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      title       Window title
      x, y        Screen position
      w, h        Outer frame dimensions
      resizable   true = allow user resize

Returns: Pointer to new WindowT.

### dvxCreateWindowCentered

    WindowT *dvxCreateWindowCentered(AppContextT *ctx, const char *title, int32_t w, int32_t h, bool resizable);

Convenience wrapper that centers the window on screen.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      title       Window title
      w, h        Outer frame dimensions
      resizable   true = allow user resize

Returns: Pointer to new WindowT.

### dvxDestroyWindow

    void dvxDestroyWindow(AppContextT *ctx, WindowT *win);

Destroy a window, free all its resources, and dirty its former region.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window to destroy

### dvxRaiseWindow

    void dvxRaiseWindow(AppContextT *ctx, WindowT *win);

Raise a window to the top of the Z-order and give it focus.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window to raise

### dvxFitWindow

    void dvxFitWindow(AppContextT *ctx, WindowT *win);

Resize a window to exactly fit its widget tree's computed minimum size (plus chrome). Used for dialog boxes and fixed-layout windows.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window to fit

### dvxFitWindowW

    void dvxFitWindowW(AppContextT *ctx, WindowT *win);

Resize window width only to fit widget tree's minimum width (plus chrome).

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window to fit

### dvxFitWindowH

    void dvxFitWindowH(AppContextT *ctx, WindowT *win);

Resize window height only to fit widget tree's minimum height (plus chrome).

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window to fit

### dvxResizeWindow

    void dvxResizeWindow(AppContextT *ctx, WindowT *win, int32_t newW, int32_t newH);

Programmatically resize a window to the specified outer dimensions.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window to resize
      newW, newH  New outer frame dimensions

### dvxMinimizeWindow

    void dvxMinimizeWindow(AppContextT *ctx, WindowT *win);

Minimize a window (show as icon at bottom of screen).

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window to minimize

### dvxMaximizeWindow

    void dvxMaximizeWindow(AppContextT *ctx, WindowT *win);

Maximize a window (expand to fill screen or maxW/maxH).

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window to maximize

### dvxHideWindow

    void dvxHideWindow(AppContextT *ctx, WindowT *win);

Hide a window without destroying it. Marks the exposed region dirty.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window to hide

### dvxShowWindow

    void dvxShowWindow(AppContextT *ctx, WindowT *win);

Show a previously hidden window. Marks its region dirty for repaint.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window to show

## Invalidation

### dvxInvalidateRect

    void dvxInvalidateRect(AppContextT *ctx, WindowT *win, int32_t x, int32_t y, int32_t w, int32_t h);

Mark a sub-region of a window's content area as needing repaint. Coordinates are relative to the content area, not the screen. Triggers onPaint during the next composite pass.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window
      x, y, w, h Dirty rectangle in content-relative coordinates

### dvxInvalidateWindow

    void dvxInvalidateWindow(AppContextT *ctx, WindowT *win);

Mark the entire window content area as dirty.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window to invalidate

## Window Properties

### dvxSetTitle

    void dvxSetTitle(AppContextT *ctx, WindowT *win, const char *title);

Set a window's title text and dirty the title bar.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window
      title       New title text

### dvxSetWindowIcon

    int32_t dvxSetWindowIcon(AppContextT *ctx, WindowT *win, const char *path);

Load an icon for a window from an image file.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window
      path        Image file path

Returns: 0 on success, -1 on failure.

### dvxSetBusy

    void dvxSetBusy(AppContextT *ctx, bool busy);

Set or clear busy state. While busy, the hourglass cursor is shown and input is blocked.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      busy        true = show hourglass, false = normal

## Accessors

### dvxGetFont

    const BitmapFontT *dvxGetFont(const AppContextT *ctx);

Get a pointer to the default font.

      Parameter   Description
      ---------   -----------
      ctx         Application context

Returns: Pointer to the active BitmapFontT.

### dvxGetColors

    const ColorSchemeT *dvxGetColors(const AppContextT *ctx);

Get a pointer to the current color scheme.

      Parameter   Description
      ---------   -----------
      ctx         Application context

Returns: Pointer to the active ColorSchemeT.

### dvxGetDisplay

    DisplayT *dvxGetDisplay(AppContextT *ctx);

Get a pointer to the display context.

      Parameter   Description
      ---------   -----------
      ctx         Application context

Returns: Pointer to the DisplayT.

### dvxGetBlitOps

    const BlitOpsT *dvxGetBlitOps(const AppContextT *ctx);

Get a pointer to the blit operations vtable.

      Parameter   Description
      ---------   -----------
      ctx         Application context

Returns: Pointer to the active BlitOpsT.

### dvxGetVideoModes

    const VideoModeInfoT *dvxGetVideoModes(const AppContextT *ctx, int32_t *count);

Return the list of available video modes enumerated at init time.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      count       Output: number of mode entries

Returns: Pointer to the VideoModeInfoT array.

## Color Scheme

### dvxSetColor

    void dvxSetColor(AppContextT *ctx, ColorIdE id, uint8_t r, uint8_t g, uint8_t b);

Set a single color by ID. Repacks to native pixel format and invalidates the entire screen.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      id          Color ID (ColorIdE)
      r, g, b     RGB values (0-255)

### dvxGetColor

    void dvxGetColor(const AppContextT *ctx, ColorIdE id, uint8_t *r, uint8_t *g, uint8_t *b);

Get a color's RGB values by ID.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      id          Color ID (ColorIdE)
      r, g, b     Output: RGB values

### dvxApplyColorScheme

    void dvxApplyColorScheme(AppContextT *ctx);

Apply all colors from ctx->colorRgb[] at once (repack + full repaint).

      Parameter   Description
      ---------   -----------
      ctx         Application context

### dvxResetColorScheme

    void dvxResetColorScheme(AppContextT *ctx);

Reset all colors to the built-in defaults and repaint.

      Parameter   Description
      ---------   -----------
      ctx         Application context

### dvxLoadTheme

    bool dvxLoadTheme(AppContextT *ctx, const char *filename);

Load a theme file (INI format with [colors] section) and apply it.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      filename    Path to theme INI file

Returns: true on success.

### dvxSaveTheme

    bool dvxSaveTheme(const AppContextT *ctx, const char *filename);

Save the current color scheme to a theme file.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      filename    Output file path

Returns: true on success.

### dvxColorName

    const char *dvxColorName(ColorIdE id);

Return the INI key name for a color ID (e.g. "desktop", "windowFace").

      Parameter   Description
      ---------   -----------
      id          Color ID

Returns: Static string.

### dvxColorLabel

    const char *dvxColorLabel(ColorIdE id);

Return a human-readable display label (e.g. "Desktop", "Cursor Color").

      Parameter   Description
      ---------   -----------
      id          Color ID

Returns: Static string.

## Wallpaper

### dvxSetWallpaper

    bool dvxSetWallpaper(AppContextT *ctx, const char *path);

Load and apply a wallpaper image using the current wallpaperMode (stretch/tile/center). Pass NULL to clear the wallpaper.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      path        Image file path, or NULL to clear

Returns: true on success.

### dvxSetWallpaperMode

    void dvxSetWallpaperMode(AppContextT *ctx, WallpaperModeE mode);

Change the wallpaper display mode and re-render. No effect if no wallpaper is loaded.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      mode        WallpaperStretchE, WallpaperTileE, or WallpaperCenterE

## Mouse Configuration

### dvxSetMouseConfig

    void dvxSetMouseConfig(AppContextT *ctx, int32_t wheelDir, int32_t dblClickMs, int32_t accelThreshold, int32_t mickeyRatio, int32_t wheelStep);

Configure mouse behavior. Updates the in-memory AppContextT fields and programs any INT 33h settings that need driver-side adjustment.

      Parameter        Description
      ---------        -----------
      ctx              Application context
      wheelDir         1 = normal, -1 = reversed
      dblClickMs       Double-click speed in milliseconds (e.g. 500)
      accelThreshold   Double-speed threshold in mickeys/sec (0 = don't change)
      mickeyRatio      Mickeys per 8 pixels (0 = don't change, 8 = default speed)
      wheelStep        Lines to scroll per wheel notch (1-10, default 3)

## Accelerators

### dvxCreateAccelTable

    AccelTableT *dvxCreateAccelTable(void);

Allocate a new accelerator table. Attach to a window via win->accelTable.

Returns: Pointer to new AccelTableT.

### dvxFreeAccelTable

    void dvxFreeAccelTable(AccelTableT *table);

Free an accelerator table and its entries.

      Parameter   Description
      ---------   -----------
      table       Table to free

### dvxAddAccel

    void dvxAddAccel(AccelTableT *table, int32_t key, int32_t modifiers, int32_t cmdId);

Register a keyboard shortcut. On match, fires the window's onMenu callback with cmdId.

      Parameter   Description
      ---------   -----------
      table       Accelerator table
      key         ASCII character or KEY_Fxx constant
      modifiers   Bitmask of ACCEL_CTRL / ACCEL_SHIFT / ACCEL_ALT
      cmdId       Command ID passed to onMenu

## Window Arrangement

### dvxCascadeWindows

    void dvxCascadeWindows(AppContextT *ctx);

Cascade all visible, non-minimized windows. Each is offset diagonally by the title bar height.

      Parameter   Description
      ---------   -----------
      ctx         Application context

### dvxTileWindows

    void dvxTileWindows(AppContextT *ctx);

Arrange visible windows in an NxM grid filling the screen.

      Parameter   Description
      ---------   -----------
      ctx         Application context

### dvxTileWindowsH

    void dvxTileWindowsH(AppContextT *ctx);

Tile windows horizontally (side by side, equal width, full height).

      Parameter   Description
      ---------   -----------
      ctx         Application context

### dvxTileWindowsV

    void dvxTileWindowsV(AppContextT *ctx);

Tile windows vertically (stacked, full width, equal height).

      Parameter   Description
      ---------   -----------
      ctx         Application context

## Image I/O

### dvxLoadImage

    uint8_t *dvxLoadImage(const AppContextT *ctx, const char *path, int32_t *outW, int32_t *outH, int32_t *outPitch);

Load an image file (BMP, PNG, JPEG, GIF) and convert to the display's native pixel format. Caller must free with dvxFreeImage().

      Parameter     Description
      ---------     -----------
      ctx           Application context
      path          Image file path
      outW, outH    Output: image dimensions
      outPitch      Output: row pitch in bytes

Returns: Pixel buffer, or NULL on failure.

### dvxLoadImageFromMemory

    uint8_t *dvxLoadImageFromMemory(const AppContextT *ctx, const uint8_t *data, int32_t dataLen, int32_t *outW, int32_t *outH, int32_t *outPitch);

Load an image from a memory buffer (typically resource data). Same output format as dvxLoadImage(). Caller must free with dvxFreeImage().

      Parameter     Description
      ---------     -----------
      ctx           Application context
      data          Image data buffer
      dataLen       Buffer size in bytes
      outW, outH    Output: image dimensions
      outPitch      Output: row pitch in bytes

Returns: Pixel buffer, or NULL on failure.

### dvxLoadImageAlpha

    uint8_t *dvxLoadImageAlpha(const AppContextT *ctx, const uint8_t *data, int32_t dataLen, int32_t *outW, int32_t *outH, int32_t *outPitch, bool *outHasAlpha, uint32_t *outKeyColor);

Load an image from memory with alpha transparency. Pixels with alpha < 128 are replaced with a packed magenta key color. If any transparent pixels are found, *outHasAlpha is set to true and *outKeyColor receives the packed key color for use with rectCopyTransparent. Caller must free with dvxFreeImage.

      Parameter     Description
      ---------     -----------
      ctx           Application context
      data          Image data buffer
      dataLen       Buffer size in bytes
      outW, outH    Output: image dimensions
      outPitch      Output: row pitch
      outHasAlpha   Output: true if any transparent pixels found
      outKeyColor   Output: packed key color (valid when outHasAlpha is true)

Returns: Pixel buffer, or NULL on failure.

### dvxFreeImage

    void dvxFreeImage(uint8_t *data);

Free a pixel buffer returned by dvxLoadImage() or dvxLoadImageFromMemory().

      Parameter   Description
      ---------   -----------
      data        Buffer to free

### dvxImageInfo

    bool dvxImageInfo(const char *path, int32_t *outW, int32_t *outH);

Query image dimensions without decoding the full file.

      Parameter     Description
      ---------     -----------
      path          Image file path
      outW, outH    Output: image dimensions

Returns: true on success.

### dvxSaveImage

    int32_t dvxSaveImage(const AppContextT *ctx, const uint8_t *data, int32_t w, int32_t h, int32_t pitch, const char *path);

Save native-format pixel data to a PNG file.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      data        Pixel data in display native format
      w, h        Image dimensions
      pitch       Row pitch in bytes
      path        Output file path

Returns: 0 on success, -1 on failure.

## Screenshots

### dvxScreenshot

    int32_t dvxScreenshot(AppContextT *ctx, const char *path);

Save the entire screen (backbuffer contents) to a PNG file. Converts from native pixel format to RGB.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      path        Output PNG file path

Returns: 0 on success, -1 on failure.

### dvxWindowScreenshot

    int32_t dvxWindowScreenshot(AppContextT *ctx, WindowT *win, const char *path);

Save a window's content to a PNG file.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window
      path        Output PNG file path

Returns: 0 on success, -1 on failure.

## Clipboard

### dvxClipboardCopy

    void dvxClipboardCopy(const char *text, int32_t len);

Copy text to the process-wide clipboard buffer. Simple static buffer (not inter-process).

      Parameter   Description
      ---------   -----------
      text        Text to copy
      len         Length in bytes

### dvxClipboardGet

    const char *dvxClipboardGet(int32_t *outLen);

Retrieve the current clipboard contents. Returns a pointer to the internal buffer (valid until the next dvxClipboardCopy), or NULL if empty.

      Parameter   Description
      ---------   -----------
      outLen      Output: length of clipboard text

Returns: Clipboard text, or NULL.

## Resource Loading

### dvxResLoadIcon

    uint8_t *dvxResLoadIcon(AppContextT *ctx, const char *dxePath, const char *resName, int32_t *outW, int32_t *outH, int32_t *outPitch);

Load an icon/image resource from a DXE file and decode to native pixel format. Caller must free with dvxFreeImage().

      Parameter     Description
      ---------     -----------
      ctx           Application context
      dxePath       Path to DXE file
      resName       Resource name within the DXE
      outW, outH    Output: image dimensions
      outPitch      Output: row pitch

Returns: Pixel buffer, or NULL if not found.

### dvxResLoadText

    bool dvxResLoadText(const char *dxePath, const char *resName, char *buf, int32_t bufSize);

Load a text resource from a DXE file into a caller-provided buffer. Null-terminated and truncated to fit bufSize.

      Parameter   Description
      ---------   -----------
      dxePath     Path to DXE file
      resName     Resource name
      buf         Output buffer
      bufSize     Buffer capacity

Returns: true on success.

### dvxResLoadData

    void *dvxResLoadData(const char *dxePath, const char *resName, uint32_t *outSize);

Load a raw binary resource from a DXE file. Returns a malloc'd buffer that the caller must free.

      Parameter   Description
      ---------   -----------
      dxePath     Path to DXE file
      resName     Resource name
      outSize     Output: data size in bytes

Returns: Data buffer, or NULL if not found.

## Utilities

### dvxTextHash

    uint32_t dvxTextHash(const char *text);

Compute a djb2-xor hash for cheap dirty detection. Compare at save time with the current hash to detect changes without a shadow copy. Not cryptographic.

      Parameter   Description
      ---------   -----------
      text        Null-terminated string to hash

Returns: 32-bit hash value.

# dvxWgt.h -- Widget System

Retained-mode widget toolkit layered on the DVX window manager. Widgets form a tree (parent-child) rooted at a per-window VBox container. Layout is automatic: measure minimum sizes bottom-up, then allocate space top-down with flexbox-like weighted distribution. Widget types are registered dynamically at runtime via DXE plugins.

## WidgetT Structure

Core widget structure. Generic across all widget types; type-specific data lives in the void *data pointer managed by each widget's DXE.

      Field                                       Description
      -----                                       -----------
      int32_t type                                Widget type ID (assigned by wgtRegisterClass)
      const WidgetClassT *wclass                  Vtable for this widget type
      char name[MAX_WIDGET_NAME]                  Widget name for lookup via wgtFind
      parent, firstChild, lastChild, nextSibling  Tree linkage pointers
      WindowT *window                             Owning window
      int32_t x, y, w, h                         Computed geometry (relative to content area)
      int32_t calcMinW, calcMinH                  Computed minimum size (from layout pass)
      int32_t minW, minH, maxW, maxH, prefW, prefH  Size hints (tagged sizes)
      int32_t weight                              Extra-space distribution weight (0=fixed, 100=normal)
      WidgetAlignE align                          Main-axis alignment for children
      int32_t spacing, padding                    Tagged sizes for child spacing and padding
      uint32_t fgColor, bgColor                   Custom colors (0 = use scheme defaults)
      bool visible, enabled, readOnly             State flags
      bool swallowTab                             Tab key goes to widget, not focus navigation
      bool paintDirty                             Needs repaint (set by wgtInvalidatePaint)
      bool childDirty                             A descendant needs repaint (for WCLASS_PAINTS_CHILDREN)
      bool pressed                                WCLASS_PRESS_RELEASE: set while button is pressed
      char accelKey                               Accelerator character (0 = none)
      int32_t contentOffX, contentOffY            Content offset for mouse event coordinates
      void *userData, *data                       Application data and widget-private data
      const char *tooltip                         Tooltip text (NULL = none)
      MenuT *contextMenu                          Right-click menu (NULL = none)

Universal Callbacks:

      Callback                                           Description
      --------                                           -----------
      onClick(WidgetT *w)                                Widget clicked
      onDblClick(WidgetT *w)                             Widget double-clicked
      onChange(WidgetT *w)                               Value changed
      onFocus(WidgetT *w)                                Widget gained focus
      onBlur(WidgetT *w)                                 Widget lost focus
      onKeyPress(WidgetT *w, int32_t keyAscii)           ASCII key press
      onKeyDown(WidgetT *w, int32_t keyCode, int32_t shift)  Key down
      onKeyUp(WidgetT *w, int32_t keyCode, int32_t shift)    Key up
      onMouseDown(WidgetT *w, int32_t button, int32_t x, int32_t y)  Mouse button pressed
      onMouseUp(WidgetT *w, int32_t button, int32_t x, int32_t y)    Mouse button released
      onMouseMove(WidgetT *w, int32_t button, int32_t x, int32_t y)  Mouse moved
      onScroll(WidgetT *w, int32_t delta)                Mouse wheel
      onValidate(WidgetT *w)                             Return false to cancel a write

## Size Specification Macros

      Macro            Description
      -----            -----------
      wgtPixels(v)     Size in pixels
      wgtChars(v)      Size in character widths (multiplied by charWidth at layout)
      wgtPercent(v)    Size as percentage of parent dimension

## Widget Class Flags

      Flag                        Description
      ----                        -----------
      WCLASS_FOCUSABLE            Can receive keyboard focus (Tab navigation)
      WCLASS_HORIZ_CONTAINER      Lays out children horizontally (vs. vertical)
      WCLASS_PAINTS_CHILDREN      Widget handles child rendering itself
      WCLASS_NO_HIT_RECURSE       Hit testing stops here, no child recursion
      WCLASS_FOCUS_FORWARD        Accel hit forwards focus to next focusable sibling
      WCLASS_HAS_POPUP            Has dropdown popup overlay
      WCLASS_SCROLLABLE           Accepts mouse wheel events
      WCLASS_SCROLL_CONTAINER     Scroll container (ScrollPane)
      WCLASS_NEEDS_POLL           Needs periodic polling
      WCLASS_SWALLOWS_TAB         Tab key goes to widget, not focus navigation
      WCLASS_RELAYOUT_ON_SCROLL   Full relayout on scrollbar drag
      WCLASS_PRESS_RELEASE        Click = press + release (Button, ImageButton)
      WCLASS_ACCEL_WHEN_HIDDEN    Accelerator matching works even when invisible

## Window Integration

### wgtInitWindow

    WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win);

Initialize the widget system for a window. Creates a root VBox container that fills the content area, and installs callback handlers (onPaint, onMouse, onKey, onResize) for widget-based event dispatch. The window's userData is set to the AppContextT pointer.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      win         Window to initialize

Returns: Root VBox widget (add children to this).

## Widget Operations

### wgtGetContext

    AppContextT *wgtGetContext(const WidgetT *w);

Walk from any widget up the tree to the root, then retrieve the AppContextT stored in the window's userData. Lets any widget access the full application context.

      Parameter   Description
      ---------   -----------
      w           Any widget in the tree

Returns: Pointer to the AppContextT.

### wgtInvalidate

    void wgtInvalidate(WidgetT *w);

Mark a widget as needing both re-layout (measure + position) and repaint. Propagates upward to ancestors. Use after structural changes (adding/removing children, text changes that affect size).

      Parameter   Description
      ---------   -----------
      w           Widget to invalidate

### wgtInvalidatePaint

    void wgtInvalidatePaint(WidgetT *w);

Mark a widget as needing repaint only, without re-layout. Use for visual-only changes (checkbox toggle, selection highlight, cursor blink).

      Parameter   Description
      ---------   -----------
      w           Widget to repaint

### wgtSetText

    void wgtSetText(WidgetT *w, const char *text);

Set widget text content (dispatches to the widget class's SET_TEXT handler).

      Parameter   Description
      ---------   -----------
      w           Widget
      text        New text

### wgtGetText

    const char *wgtGetText(const WidgetT *w);

Get the widget's current text content.

      Parameter   Description
      ---------   -----------
      w           Widget

Returns: Text string (empty string if no handler).

### wgtSetEnabled

    void wgtSetEnabled(WidgetT *w, bool enabled);

Enable or disable a widget. Disabled widgets are grayed out and do not receive input.

      Parameter   Description
      ---------   -----------
      w           Widget
      enabled     true = enabled, false = disabled

### wgtSetReadOnly

    void wgtSetReadOnly(WidgetT *w, bool readOnly);

Set read-only mode. Allows scrolling and selection but blocks editing.

      Parameter   Description
      ---------   -----------
      w           Widget
      readOnly    true = read-only

### wgtSetFocused

    void wgtSetFocused(WidgetT *w);

Set keyboard focus to a widget.

      Parameter   Description
      ---------   -----------
      w           Widget to focus

### wgtGetFocused

    WidgetT *wgtGetFocused(void);

Get the currently focused widget.

Returns: Focused widget, or NULL.

### wgtSetVisible

    void wgtSetVisible(WidgetT *w, bool visible);

Show or hide a widget.

      Parameter   Description
      ---------   -----------
      w           Widget
      visible     true = visible, false = hidden

### wgtSetName

    void wgtSetName(WidgetT *w, const char *name);

Set a widget's name for lookup via wgtFind().

      Parameter   Description
      ---------   -----------
      w           Widget
      name        Name string (max MAX_WIDGET_NAME chars)

### wgtFind

    WidgetT *wgtFind(WidgetT *root, const char *name);

Find a widget by name. Searches the subtree rooted at root.

      Parameter   Description
      ---------   -----------
      root        Root of subtree to search
      name        Widget name to find

Returns: Matching widget, or NULL.

### wgtDestroy

    void wgtDestroy(WidgetT *w);

Destroy a widget and all its children. Removes from parent's child list.

      Parameter   Description
      ---------   -----------
      w           Widget to destroy

### wgtSetTooltip

    void wgtSetTooltip(WidgetT *w, const char *text);

Set tooltip text for a widget. Pass NULL to remove. Caller owns the string and it must outlive the widget.

      Parameter   Description
      ---------   -----------
      w           Widget
      text        Tooltip text, or NULL

### widgetOnResize

    void widgetOnResize(WindowT *win, int32_t newW, int32_t newH);

Default window resize handler installed by wgtInitWindow(). Re-evaluates scrollbars and relayouts the widget tree. Call from custom onResize handlers to chain to the widget system.

      Parameter    Description
      ---------    -----------
      win          Window being resized
      newW, newH   New content dimensions

## Layout

### wgtResolveSize

    int32_t wgtResolveSize(int32_t taggedSize, int32_t parentSize, int32_t charWidth);

Decode a tagged size value (WGT_SIZE_PIXELS/CHARS/PERCENT) into a concrete pixel count. Returns 0 for a raw 0 input (meaning "auto").

      Parameter     Description
      ---------     -----------
      taggedSize    Tagged size value
      parentSize    Parent dimension (for PERCENT mode)
      charWidth     Font character width (for CHARS mode)

Returns: Size in pixels.

### wgtLayout

    void wgtLayout(WidgetT *root, int32_t availW, int32_t availH, const BitmapFontT *font);

Execute the full two-pass layout algorithm. Pass 1 (bottom-up): compute minimum sizes. Pass 2 (top-down): allocate space with weighted distribution. Normally called automatically; exposed for cases where layout must be forced before the next paint.

      Parameter     Description
      ---------     -----------
      root          Root widget
      availW/H      Available space
      font          Bitmap font (for character-based sizing)

### wgtPaint

    void wgtPaint(WidgetT *root, DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors, bool fullRepaint);

Paint the entire widget tree by depth-first traversal. Each widget's clip rect is set to its bounds. Overlays (popups, tooltips) are painted in a second pass on top.

      Parameter     Description
      ---------     -----------
      root          Root widget
      d             Display context
      ops           Blit operations vtable
      font          Bitmap font
      colors        Color scheme
      fullRepaint   true = repaint every widget; false = only paintDirty widgets

## Debug

### wgtSetDebugLayout

    void wgtSetDebugLayout(AppContextT *ctx, bool enabled);

Draw colored borders around layout containers for debugging.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      enabled     true = draw debug borders

## Dynamic Widget Registration

### wgtRegisterClass

    int32_t wgtRegisterClass(const WidgetClassT *wclass);

Register a new widget class at runtime. Appends to widgetClassTable. The WidgetClassT must remain valid for the lifetime of the process (typically static const in a DXE).

      Parameter   Description
      ---------   -----------
      wclass      Widget class vtable to register

Returns: Assigned type ID.

### wgtRegisterApi

    void wgtRegisterApi(const char *name, const void *api);

Register a widget API struct under a name. Each widget DXE registers its API during initialization. Callers retrieve it via wgtGetApi() and cast to the widget-specific type.

      Parameter   Description
      ---------   -----------
      name        Widget type name (e.g. "button", "listbox")
      api         Pointer to the widget's API struct

> Warning: The create function must be the first field of the API struct. BASIC's form runtime instantiates widgets by dereferencing the api pointer as a pointer-to-function-pointer (see createWidgetByIface), so whichever field is first is what gets invoked. If the struct has multiple constructor variants, the one matching createSig must come first; put helper constructors, index accessors, and other entry points after it.

### wgtGetApi

    const void *wgtGetApi(const char *name);

Retrieve a registered widget API struct by name.

      Parameter   Description
      ---------   -----------
      name        Widget type name

Returns: Pointer to the API struct, or NULL if not found.

## Widget Interface Descriptors

### wgtRegisterIface

    void wgtRegisterIface(const char *name, const WgtIfaceT *iface);

Register an interface descriptor for a widget type. Used by the BASIC form runtime and IDE for generic property/method dispatch.

      Parameter   Description
      ---------   -----------
      name        Widget type name
      iface       Interface descriptor

### wgtGetIface

    const WgtIfaceT *wgtGetIface(const char *name);

Retrieve an interface descriptor by widget type name.

      Parameter   Description
      ---------   -----------
      name        Widget type name

Returns: Interface descriptor, or NULL.

### wgtFindByBasName

    const char *wgtFindByBasName(const char *basName);

Find a widget type name by its VB-style name (e.g. "CommandButton" -> "button"). Case-insensitive search.

      Parameter   Description
      ---------   -----------
      basName     VB-style widget name

Returns: Internal type name, or NULL.

### wgtIfaceCount

    int32_t wgtIfaceCount(void);

Return the number of registered widget interfaces.

Returns: Count of registered interfaces.

### wgtIfaceAt

    const WgtIfaceT *wgtIfaceAt(int32_t idx, const char **outName);

Get a registered widget interface by index.

      Parameter   Description
      ---------   -----------
      idx         Index (0-based)
      outName     Output: type name

Returns: Interface descriptor.

### wgtIfaceGetPath

    const char *wgtIfaceGetPath(const char *name);

Get the .wgt DXE file path for a registered widget.

      Parameter   Description
      ---------   -----------
      name        Widget type name

Returns: File path string.

### wgtIfaceSetPath

    void wgtIfaceSetPath(const char *name, const char *path);

Set the .wgt DXE file path for a registered widget (called by the loader).

      Parameter   Description
      ---------   -----------
      name        Widget type name
      path        DXE file path

### wgtIfaceGetPathIndex

    int32_t wgtIfaceGetPathIndex(const char *name);

Get the 1-based index of this widget within its .wgt file. Used to construct suffixed resource names (e.g. "name-2", "icon16-2").

      Parameter   Description
      ---------   -----------
      name        Widget type name

Returns: 1-based index within the DXE file.

## Typed Dispatch Helpers

The following inline functions provide type-safe dispatch through the WidgetClassT handler table. Each checks for a non-NULL handler before calling.

      Function                                Method ID                          Description
      --------                                ---------                          -----------
      wclsHas(w, methodId)                    --                                 Check if handler exists
      wclsPaint(w, d, ops, font, colors)      WGT_METHOD_PAINT                   Paint the widget
      wclsPaintOverlay(w, d, ops, font, colors) WGT_METHOD_PAINT_OVERLAY         Paint overlay (popups)
      wclsCalcMinSize(w, font)                WGT_METHOD_CALC_MIN_SIZE           Compute minimum size
      wclsLayout(w, font)                     WGT_METHOD_LAYOUT                  Layout children
      wclsGetLayoutMetrics(w, font, ...)      WGT_METHOD_GET_LAYOUT_METRICS      Get pad, gap, extraTop, borderW
      wclsOnMouse(w, root, vx, vy)           WGT_METHOD_ON_MOUSE                Handle mouse event
      wclsOnKey(w, key, mod)                  WGT_METHOD_ON_KEY                  Handle key event
      wclsOnAccelActivate(w, root)            WGT_METHOD_ON_ACCEL_ACTIVATE       Handle accelerator
      wclsDestroy(w)                          WGT_METHOD_DESTROY                 Destroy widget data
      wclsOnChildChanged(parent, child)       WGT_METHOD_ON_CHILD_CHANGED        Notify parent of change
      wclsGetText(w)                          WGT_METHOD_GET_TEXT                Get widget text
      wclsSetText(w, text)                    WGT_METHOD_SET_TEXT                Set widget text
      wclsClearSelection(w)                   WGT_METHOD_CLEAR_SELECTION         Clear text selection
      wclsClosePopup(w)                       WGT_METHOD_CLOSE_POPUP             Close dropdown popup
      wclsGetPopupRect(w, font, ...)          WGT_METHOD_GET_POPUP_RECT          Get popup screen rect
      wclsOnDragUpdate(w, root, x, y)         WGT_METHOD_ON_DRAG_UPDATE          Update during drag
      wclsOnDragEnd(w, root, x, y)            WGT_METHOD_ON_DRAG_END             End drag operation
      wclsGetCursorShape(w, vx, vy)           WGT_METHOD_GET_CURSOR_SHAPE        Get cursor for position
      wclsPoll(w, win)                        WGT_METHOD_POLL                    Periodic polling
      wclsQuickRepaint(w, outY, outH)         WGT_METHOD_QUICK_REPAINT           Fast partial repaint
      wclsScrollChildIntoView(parent, child)  WGT_METHOD_SCROLL_CHILD_INTO_VIEW  Scroll child visible

## Method IDs

Fixed constants used to index into WidgetClassT.handlers[]. Method IDs are stable ABI -- new methods are appended at the next sequential ID, never reordered or reused.

      ID   Symbol                              Signature
      --   ------                              ---------
      0    WGT_METHOD_PAINT                    void (w, d, ops, font, colors)
      1    WGT_METHOD_PAINT_OVERLAY            void (w, d, ops, font, colors)
      2    WGT_METHOD_CALC_MIN_SIZE            void (w, font)
      3    WGT_METHOD_LAYOUT                   void (w, font)
      4    WGT_METHOD_GET_LAYOUT_METRICS       void (w, font, pad, gap, extraTop, borderW)
      5    WGT_METHOD_ON_MOUSE                 void (w, root, vx, vy)
      6    WGT_METHOD_ON_KEY                   void (w, key, mod)
      7    WGT_METHOD_ON_ACCEL_ACTIVATE        void (w, root)
      8    WGT_METHOD_DESTROY                  void (w)
      9    WGT_METHOD_ON_CHILD_CHANGED         void (parent, child)
      10   WGT_METHOD_GET_TEXT                 const char *(w)
      11   WGT_METHOD_SET_TEXT                 void (w, text)
      12   WGT_METHOD_CLEAR_SELECTION          bool (w)
      13   WGT_METHOD_CLOSE_POPUP              void (w)
      14   WGT_METHOD_GET_POPUP_RECT           void (w, font, contentH, popX, popY, popW, popH)
      15   WGT_METHOD_ON_DRAG_UPDATE           void (w, root, x, y)
      16   WGT_METHOD_ON_DRAG_END              void (w, root, x, y)
      17   WGT_METHOD_GET_CURSOR_SHAPE         int32_t (w, vx, vy)
      18   WGT_METHOD_POLL                     void (w, win)
      19   WGT_METHOD_QUICK_REPAINT            int32_t (w, outY, outH)
      20   WGT_METHOD_SCROLL_CHILD_INTO_VIEW   void (parent, child)
      --   WGT_METHOD_COUNT = 21, WGT_METHOD_MAX = 32

WGT_CLASS_VERSION is bumped on breaking ABI changes. The framework rejects WidgetClassT structs whose version does not match.

## Widget Class Dispatch Table

### WidgetClassT

    typedef struct WidgetClassT {
        uint32_t version;
        uint32_t flags;
        void    *handlers[WGT_METHOD_MAX];
    } WidgetClassT;

      Field       Description
      -----       -----------
      version     Must equal WGT_CLASS_VERSION at registration
      flags       Bitmask of WCLASS_xxx flags
      handlers    Array of 32 function pointers indexed by WGT_METHOD_xxx

## Size Encoding Constants

      Define              Value        Description
      ------              -----        -----------
      WGT_SIZE_TYPE_MASK  0xC0000000   Top 2 bits: unit type selector
      WGT_SIZE_VAL_MASK   0x3FFFFFFF   Bottom 30 bits: numeric value
      WGT_SIZE_PIXELS     0x00000000   Unit tag: pixels
      WGT_SIZE_CHARS      0x40000000   Unit tag: character widths
      WGT_SIZE_PERCENT    0x80000000   Unit tag: percentage of parent
      WGT_WEIGHT_FILL     100          Default "flexible" weight value

## Widget Interface Descriptors

### WgtPropDescT

Describes a BASIC-exposed property on a widget type. Used by the form runtime and IDE for generic get/set dispatch.

      Field       Description
      -----       -----------
      name        BASIC property name (e.g. "Caption", "Value")
      type        Data type: WGT_IFACE_STRING, WGT_IFACE_INT, WGT_IFACE_BOOL, WGT_IFACE_FLOAT, or WGT_IFACE_ENUM
      getFn       Getter function pointer (NULL if write-only)
      setFn       Setter function pointer (NULL if read-only)
      enumNames   For WGT_IFACE_ENUM: NULL-terminated array of value names

### WgtMethodDescT

Describes an invokable method on a widget type.

      Field       Description
      -----       -----------
      name        BASIC method name (e.g. "Clear", "SetFocus")
      sig         Calling convention ID (WGT_SIG_xxx)
      fn          Function pointer

### WgtEventDescT

Describes an event beyond the standard common set (Click, DblClick, Change, GotFocus, LostFocus).

      Field       Description
      -----       -----------
      name        Event name (e.g. "Change", "Timer")

### WgtIfaceT

Top-level interface descriptor registered by each widget DXE.

      Field         Description
      -----         -----------
      basName       VB-style name (e.g. "CommandButton"), or NULL
      props         Array of WgtPropDescT
      propCount     Length of props array
      methods       Array of WgtMethodDescT
      methodCount   Length of methods array
      events        Array of WgtEventDescT (extras beyond common set)
      eventCount    Length of events array
      createSig     How to call the widget's create() function (WgtCreateSigE)
      createArgs    Default numeric args for design-time instantiation
      isContainer   true = widget can hold child widgets
      defaultEvent  Default event name for form designer
      namePrefix    Auto-name prefix (NULL = derive from basName)

## Property Data Type Constants

      Define              Value   Description
      ------              -----   -----------
      WGT_IFACE_STRING    0       const char *
      WGT_IFACE_INT       1       int32_t
      WGT_IFACE_BOOL      2       bool
      WGT_IFACE_FLOAT     3       float
      WGT_IFACE_ENUM      4       int32_t with named values

## Create Function Signature Constants

      Define                              Value   Form
      ------                              -----   ----
      WGT_CREATE_PARENT                   0       fn(parent)
      WGT_CREATE_PARENT_TEXT              1       fn(parent, const char *text)
      WGT_CREATE_PARENT_INT               2       fn(parent, int32_t)
      WGT_CREATE_PARENT_INT_INT           3       fn(parent, int32_t, int32_t)
      WGT_CREATE_PARENT_INT_INT_INT       4       fn(parent, int32_t, int32_t, int32_t)
      WGT_CREATE_PARENT_INT_BOOL          5       fn(parent, int32_t, bool)
      WGT_CREATE_PARENT_BOOL              6       fn(parent, bool)
      WGT_CREATE_PARENT_DATA              7       fn(parent, data, w, h, pitch) -- not auto-creatable

WGT_MAX_CREATE_ARGS is 3.

# dvxDlg.h -- Modal Dialogs

Pre-built modal dialog boxes that block the caller and run their own event loop via dvxUpdate() until the user dismisses them. Modal dialogs set ctx->modalWindow to prevent input from reaching other windows for the dialog's lifetime.

## Message Box Flags

Button configurations (low nibble):

      Define             Value    Description
      ------             -----    -----------
      MB_OK              0x0000   OK button only (default)
      MB_OKCANCEL        0x0001   OK and Cancel
      MB_YESNO           0x0002   Yes and No
      MB_YESNOCANCEL     0x0003   Yes, No, and Cancel
      MB_RETRYCANCEL     0x0004   Retry and Cancel

Icon types (high nibble, OR with button flags):

      Define             Value    Description
      ------             -----    -----------
      MB_ICONINFO        0x0010   Information icon
      MB_ICONWARNING     0x0020   Warning icon
      MB_ICONERROR       0x0030   Error icon
      MB_ICONQUESTION    0x0040   Question mark icon

Return values:

      Define             Value   Button pressed
      ------             -----   --------------
      ID_OK              1       OK
      ID_CANCEL          2       Cancel or dialog closed
      ID_YES             3       Yes
      ID_NO              4       No
      ID_RETRY           5       Retry

## dvxMessageBox

    int32_t dvxMessageBox(AppContextT *ctx, const char *title, const char *message, int32_t flags);

Display a modal message box. Blocks the caller by running dvxUpdate() in a loop until a button is pressed or the dialog is closed. The window is automatically destroyed on return.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      title       Window title (NULL falls back to a generic default)
      message     Body text
      flags       MB_xxx button + icon flags, OR'd together

Returns: ID_xxx of the button that was pressed.

    // Example: yes/no confirmation
    int32_t r = dvxMessageBox(ctx, "Save", "Save changes before closing?", MB_YESNOCANCEL | MB_ICONQUESTION);
    if (r == ID_YES) { saveFile(); }

## dvxErrorBox

    int32_t dvxErrorBox(AppContextT *ctx, const char *title, const char *message);

Convenience wrapper for MB_OK | MB_ICONERROR. Title defaults to "Error" when NULL.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      title       Dialog title, or NULL for "Error"
      message     Error message

Returns: ID_OK.

## dvxInfoBox

    int32_t dvxInfoBox(AppContextT *ctx, const char *title, const char *message);

Convenience wrapper for MB_OK | MB_ICONINFO.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      title       Dialog title
      message     Informational message

Returns: ID_OK.

## File Dialog

### FileFilterT

Describes a filter entry in the file dialog's format dropdown. The glob pattern is extracted from inside the parentheses.

      Field   Description
      -----   -----------
      label   e.g. "Text Files (*.txt)" or "Images (*.bmp;*.png;*.jpg;*.gif)"

### File Dialog Flags

      Define      Value    Description
      ------      -----    -----------
      FD_OPEN     0x0000   File open dialog (default)
      FD_SAVE     0x0001   File save dialog (with overwrite prompt)

### dvxFileDialog

    bool dvxFileDialog(AppContextT *ctx, const char *title, int32_t flags, const char *initialDir, const FileFilterT *filters, int32_t filterCount, char *outPath, int32_t outPathSize);

Display a modal file open/save dialog. Shows a directory listing with parent/drive-letter navigation, a filename input, and an optional filter dropdown.

      Parameter     Description
      ---------     -----------
      ctx           Application context
      title         Window title
      flags         FD_OPEN or FD_SAVE
      initialDir    Starting directory (NULL = current working directory)
      filters       Array of FileFilterT, or NULL
      filterCount   Number of filter entries
      outPath       Output buffer for selected path
      outPathSize   Capacity of outPath buffer

Returns: true if the user selected a file, false if cancelled or closed.

## Input Boxes

### dvxInputBox

    bool dvxInputBox(AppContextT *ctx, const char *title, const char *prompt, const char *defaultText, char *outBuf, int32_t outBufSize);

Display a modal input box with a prompt label, text field, and OK/Cancel buttons.

      Parameter     Description
      ---------     -----------
      ctx           Application context
      title         Window title
      prompt        Prompt label above the input field
      defaultText   Initial text (NULL = empty)
      outBuf        Output buffer
      outBufSize    Capacity of outBuf

Returns: true if OK was pressed, false if cancelled.

### dvxIntInputBox

    bool dvxIntInputBox(AppContextT *ctx, const char *title, const char *prompt, int32_t defaultVal, int32_t minVal, int32_t maxVal, int32_t step, int32_t *outVal);

Display a modal integer input box with a spinner (up/down arrows) for clamped numeric input.

      Parameter     Description
      ---------     -----------
      ctx           Application context
      title         Window title
      prompt        Prompt label
      defaultVal    Initial value
      minVal        Minimum allowed value
      maxVal        Maximum allowed value
      step          Increment per arrow click
      outVal        Output: entered value

Returns: true if OK pressed, false if cancelled.

## Choice Dialog

### dvxChoiceDialog

    bool dvxChoiceDialog(AppContextT *ctx, const char *title, const char *prompt, const char **items, int32_t itemCount, int32_t defaultIdx, int32_t *outIdx);

Display a modal dialog with a listbox of choices. The user picks one item and clicks OK, or cancels.

      Parameter     Description
      ---------     -----------
      ctx           Application context
      title         Window title
      prompt        Prompt label above the list
      items         Array of choice strings
      itemCount     Number of items
      defaultIdx    Initially highlighted item (-1 = none)
      outIdx        Output: selected index

Returns: true if a choice was made, false if cancelled.

## Save Prompt

Return codes for dvxPromptSave:

      Define            Value   Action
      ------            -----   ------
      DVX_SAVE_YES      1       Save, then proceed
      DVX_SAVE_NO       2       Discard, then proceed
      DVX_SAVE_CANCEL   3       Abort the operation

### dvxPromptSave

    int32_t dvxPromptSave(AppContextT *ctx, const char *title);

Display a canonical "Save changes?" dialog with Yes/No/Cancel buttons and an appropriate question icon.

      Parameter   Description
      ---------   -----------
      ctx         Application context
      title       Document name for message context

Returns: DVX_SAVE_YES, DVX_SAVE_NO, or DVX_SAVE_CANCEL.

# dvxRes.h -- DXE-Embedded Resource System

Resources are appended to DXE3 files (.app, .wgt, .lib) after the normal DXE content. The DXE loader never reads past its own header-specified sections, so the appended resource block is invisible to dlopen. This lets each DXE carry its own icons, localized text, help content, and binary data without separate resource files.

## File Layout

    [DXE3 content]           -- untouched, loaded by dlopen
    [resource data entries]  -- sequential, variable length
    [resource directory]     -- fixed-size entries (48 bytes each)
    [footer]                 -- magic + directory offset + entry count (16 bytes)

Reading starts from the end: seek to EOF - sizeof(footer), verify the magic, then seek to the directory.

## Constants

      Define              Value          Description
      ------              -----          -----------
      DVX_RES_ICON        1              Image data (BMP, PNG, etc.)
      DVX_RES_TEXT        2              Null-terminated string
      DVX_RES_BINARY      3              Arbitrary binary data (app-specific)
      DVX_RES_MAGIC       0x52585644     Footer signature ("DVXR" little-endian)
      DVX_RES_NAME_MAX    32             Max resource name length including null

## Structures

### DvxResDirEntryT

Directory entry describing one resource (48 bytes on disk).

      Field        Description
      -----        -----------
      name         Resource name (up to 32 chars, null-terminated)
      type         DVX_RES_ICON, DVX_RES_TEXT, or DVX_RES_BINARY
      offset       Absolute file offset of the data
      size         Data size in bytes
      reserved     Padding (must be zero)

### DvxResFooterT

Footer at the very end of a DXE file with appended resources (16 bytes).

      Field         Description
      -----         -----------
      magic         DVX_RES_MAGIC
      dirOffset     Absolute file offset of the resource directory
      entryCount    Number of directory entries
      reserved      Padding (must be zero)

### DvxResHandleT

Opaque runtime handle representing an open resource block.

      Field         Description
      -----         -----------
      path          Source file path
      entries       Directory entries (sorted by name for bsearch)
      entryCount    Number of entries

## Runtime API

### dvxResOpen

    DvxResHandleT *dvxResOpen(const char *path);

Open a resource handle by reading the footer and directory. Returns NULL if the file has no resource block or cannot be read. Entries are sorted on open for O(log n) name lookup via bsearch.

      Parameter   Description
      ---------   -----------
      path        Path to the DXE (or any file) with appended resources

Returns: Handle pointer, or NULL.

### dvxResRead

    void *dvxResRead(DvxResHandleT *h, const char *name, uint32_t *outSize);

Find a resource by name and read its data into a freshly malloc'd buffer. Caller must free the returned buffer.

      Parameter   Description
      ---------   -----------
      h           Resource handle
      name        Resource name
      outSize     Output: data size in bytes

Returns: Data buffer, or NULL if not found or I/O failed.

### dvxResFind

    const DvxResDirEntryT *dvxResFind(DvxResHandleT *h, const char *name);

Look up a resource's directory entry by name. The returned pointer is valid until dvxResClose.

      Parameter   Description
      ---------   -----------
      h           Resource handle
      name        Resource name

Returns: Pointer to directory entry, or NULL if not found.

### dvxResClose

    void dvxResClose(DvxResHandleT *h);

Close a resource handle and free its memory.

      Parameter   Description
      ---------   -----------
      h           Handle to close

### dvxResAppend

    int32_t dvxResAppend(const char *path, const char *name, uint32_t type, const void *data, uint32_t dataSize);

Append a resource to an existing DXE file. Preserves existing resources and adds the new one. Thin wrapper over the resource writer in tools/dvxResWrite.h.

      Parameter   Description
      ---------   -----------
      path        Target DXE path
      name        Resource name (up to DVX_RES_NAME_MAX - 1 chars)
      type        DVX_RES_ICON, DVX_RES_TEXT, or DVX_RES_BINARY
      data        Resource payload
      dataSize    Payload size in bytes

Returns: 0 on success, -1 on failure.

### dvxResRemove

    int32_t dvxResRemove(const char *path, const char *name);

Remove a resource from a DXE file by name. If this was the last resource, the file is truncated back to the original DXE content.

      Parameter   Description
      ---------   -----------
      path        Target DXE path
      name        Resource name to remove

Returns: 0 on success, -1 if not found or I/O failed.

## See Also

dvxResLoadIcon / dvxResLoadText / dvxResLoadData -- higher-level helpers on top of this API

# dvxPrefs.h -- INI Preferences System

Handle-based API over classic INI files. Each prefsLoad/prefsCreate returns a PrefsHandleT that must be passed to all subsequent calls and freed with prefsClose when done. Multiple INI files can be open simultaneously.

## Constants

      Define          Value                                Description
      ------          -----                                -----------
      DVX_INI_PATH    "CONFIG" DVX_PATH_SEP "DVX.INI"      Canonical system INI path

## Types

### PrefsHandleT

Opaque handle representing an in-memory INI file. Fields are not exposed.

## Lifecycle

### prefsCreate

    PrefsHandleT *prefsCreate(void);

Create an empty preferences handle with no associated file. Use this when building an INI from scratch before calling prefsSaveAs.

Returns: New handle, or NULL on allocation failure.

### prefsLoad

    PrefsHandleT *prefsLoad(const char *filename);

Load an INI file into a new handle. If the file does not exist, returns a valid empty handle with the path stored so prefsSave can write a new file later.

      Parameter   Description
      ---------   -----------
      filename    Path to INI file

Returns: Handle, or NULL on allocation failure.

### prefsSave

    bool prefsSave(PrefsHandleT *h);

Save the in-memory state back to the file that was loaded (or captured by prefsLoad for a non-existent file).

      Parameter   Description
      ---------   -----------
      h           Preferences handle

Returns: true on success.

### prefsSaveAs

    bool prefsSaveAs(PrefsHandleT *h, const char *filename);

Save to a specific file, overriding the handle's stored path.

      Parameter   Description
      ---------   -----------
      h           Preferences handle
      filename    Output file path

Returns: true on success.

### prefsClose

    void prefsClose(PrefsHandleT *h);

Release all memory held by the handle. Does not save -- call prefsSave first if needed.

      Parameter   Description
      ---------   -----------
      h           Handle to close

## Getters

### prefsGetString

    const char *prefsGetString(PrefsHandleT *h, const char *section, const char *key, const char *defaultVal);

Retrieve a string value from [section]/key. The returned pointer is valid until the key is modified or the handle is closed.

      Parameter    Description
      ---------    -----------
      h            Preferences handle
      section      Section name (without brackets)
      key          Key name
      defaultVal   Returned if the key is not present

Returns: Key value or defaultVal.

### prefsGetInt

    int32_t prefsGetInt(PrefsHandleT *h, const char *section, const char *key, int32_t defaultVal);

Retrieve an integer value. Supports decimal and negative numbers.

      Parameter    Description
      ---------    -----------
      h            Preferences handle
      section      Section name
      key          Key name
      defaultVal   Returned if the key is absent or non-numeric

Returns: Parsed int, or defaultVal.

### prefsGetBool

    bool prefsGetBool(PrefsHandleT *h, const char *section, const char *key, bool defaultVal);

Retrieve a boolean value. Recognises "true"/"yes"/"1" as true and "false"/"no"/"0" as false (case-insensitive).

      Parameter    Description
      ---------    -----------
      h            Preferences handle
      section      Section name
      key          Key name
      defaultVal   Returned if the key is absent or unrecognised

Returns: Parsed bool, or defaultVal.

## Setters

### prefsSetString

    void prefsSetString(PrefsHandleT *h, const char *section, const char *key, const char *value);

Set a string value. Creates the section and key if they do not already exist.

### prefsSetInt

    void prefsSetInt(PrefsHandleT *h, const char *section, const char *key, int32_t value);

Set an integer value (stored in decimal).

### prefsSetBool

    void prefsSetBool(PrefsHandleT *h, const char *section, const char *key, bool value);

Set a boolean value (stored as "true"/"false").

### prefsRemove

    void prefsRemove(PrefsHandleT *h, const char *section, const char *key);

Remove a key from a section. No-op if the key does not exist.

# dvxMem.h -- Per-App Memory Tracking

Wraps malloc/free/calloc/realloc/strdup with a 16-byte header that records the owning app ID and allocation size. The Task Manager displays per-app memory usage, and leaks are detected when an app is terminated.

DXE code does NOT need to include this header for tracking to work. The DXE export table maps malloc/free/calloc/realloc/strdup to these wrappers transparently. Call sites that need the explicit dvxXxx names (e.g. dvxMemGetAppUsage) or the dvxMemAppIdPtr declaration should include dvxMem.h directly.

## Globals

### dvxMemAppIdPtr

    extern int32_t *dvxMemAppIdPtr;

Pointer to the current owning app ID. The shell points this at its currentAppId field during init so every allocation is charged to the running app. When dvxMemAppIdPtr is NULL or points to zero, allocations are charged to the shell.

## Allocation Wrappers

### dvxMalloc

    void *dvxMalloc(size_t size);

Tracked malloc. Returns a pointer to user memory (header is hidden in front of it).

### dvxCalloc

    void *dvxCalloc(size_t nmemb, size_t size);

Tracked calloc.

### dvxRealloc

    void *dvxRealloc(void *ptr, size_t size);

Tracked realloc. Works correctly with tracked pointers only -- the magic header identifies them.

### dvxFree

    void dvxFree(void *ptr);

Tracked free. Falls through to the real free() if the pointer's header magic does not match, so mixing tracked and untracked pointers is safe.

### dvxStrdup

    char *dvxStrdup(const char *s);

Tracked strdup.

## Accounting

### dvxMemGetAppUsage

    uint32_t dvxMemGetAppUsage(int32_t appId);

Return the total bytes currently charged to the given app ID.

      Parameter   Description
      ---------   -----------
      appId       App ID to query

Returns: Bytes allocated for this app.

### dvxMemResetApp

    void dvxMemResetApp(int32_t appId);

Free every tracked allocation charged to the given app. Called by the shell after an app exits or crashes to reclaim its memory.

      Parameter   Description
      ---------   -----------
      appId       App ID to flush

# dvxWgtP.h -- Widget Plugin API

Included by widget .c files (DXE modules) to access core infrastructure for tree manipulation, focus management, scrollbar drawing, layout helpers, and shared interaction state. This header is NOT intended for application code -- use dvxWgt.h for the public widget API.

## Validation Macros

### VALIDATE_WIDGET / VALIDATE_WIDGET_VOID

    VALIDATE_WIDGET(w, wtype, retval);     // returns retval on mismatch
    VALIDATE_WIDGET_VOID(w, wtype);        // returns void on mismatch

Bail out of a widget method if the widget pointer is NULL or its type does not match the expected wtype. Use at the top of every widget-specific API function.

## Core Constants

      Define             Value   Description
      ------             -----   -----------
      DEFAULT_SPACING    4       Default pixel spacing between VBox/HBox children
      DEFAULT_PADDING    4       Default internal padding for containers
      SB_MIN_THUMB       14      Minimum scrollbar thumb size in pixels
      WGT_SB_W           14      Widget-internal scrollbar width
      KEY_MOD_SHIFT      0x03    Shift modifier bits
      KEY_MOD_CTRL       0x04    Ctrl modifier bit
      KEY_MOD_ALT        0x08    Alt modifier bit

## Inline Helpers

### clampInt

    static inline int32_t clampInt(int32_t val, int32_t lo, int32_t hi);

Clamp val into the [lo, hi] range.

### drawTextEmbossed

    static inline void drawTextEmbossed(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, const ColorSchemeT *colors);

Draw text twice -- once offset by (1,1) in highlight color, then overlaid in shadow color at (x,y) -- for a classic Motif-style embossed look used on disabled labels.

### drawTextAccelEmbossed

    static inline void drawTextAccelEmbossed(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, const ColorSchemeT *colors);

Embossed text with & accelerator markers. Same offset logic as drawTextEmbossed, but processes & markers.

## Shared Interaction State

Extern variables defined in widgetCore.c. These hold system-wide widget state: only one focused widget, one open popup, one pressed button at a time.

      Variable              Type       Purpose
      --------              ----       -------
      sCursorBlinkOn        bool       Current state of the text cursor blink
      sDblClickTicks        clock_t    Double-click interval in clock() ticks
      sDebugLayout          bool       When true, draw colored debug borders around containers
      sClosedPopup          WidgetT*   Widget whose popup just closed (suppresses re-open)
      sFocusedWidget        WidgetT*   Currently focused widget
      sKeyPressedBtn        WidgetT*   Button being pressed via keyboard (for release tracking)
      sOpenPopup            WidgetT*   Currently open popup (dropdown/combo list)
      sDragWidget           WidgetT*   Widget being dragged (any drag type)
      sPollWidgets          WidgetT**  Dynamic array of poll widgets (stb_ds)
      sCursorBlinkFn        fn ptr     Callback invoked when the blink flips (repaints focused text)

## Core Widget Functions

### widgetAlloc

    WidgetT *widgetAlloc(WidgetT *parent, int32_t type);

Allocate a new WidgetT, initialize its fields to defaults, link it as the last child of parent (if non-NULL), and assign its class pointer from widgetClassTable[type].

### widgetAddChild

    void widgetAddChild(WidgetT *parent, WidgetT *child);

Append child to parent's child list. Updates parent's firstChild/lastChild and child's nextSibling pointers.

### widgetRemoveChild

    void widgetRemoveChild(WidgetT *parent, WidgetT *child);

Unlink child from parent's child list. Does not destroy the child.

### widgetDestroyChildren

    void widgetDestroyChildren(WidgetT *w);

Recursively destroy all descendants of w, calling each one's wclsDestroy handler.

## Focus Management

### widgetFindNextFocusable

    WidgetT *widgetFindNextFocusable(WidgetT *root, WidgetT *after);

Find the next focusable widget in tab order after the given widget. Wraps to the beginning at the end of the tree.

### widgetFindPrevFocusable

    WidgetT *widgetFindPrevFocusable(WidgetT *root, WidgetT *before);

Find the previous focusable widget in tab order. Wraps to the end at the beginning of the tree.

### widgetFindByAccel

    WidgetT *widgetFindByAccel(WidgetT *root, char key);

Find a focusable widget whose accelKey (lowercase) matches the given character. Used for Alt+letter hotkeys on buttons and labels.

## Hit Testing

### widgetHitTest

    WidgetT *widgetHitTest(WidgetT *w, int32_t x, int32_t y);

Find the deepest widget at (x, y) within w's subtree. Respects WCLASS_NO_HIT_RECURSE so certain widget types can prevent children from being hit-tested.

## Utility Queries

### widgetCountVisibleChildren

    int32_t widgetCountVisibleChildren(const WidgetT *w);

Count children whose visible flag is true.

### widgetFrameBorderWidth

    int32_t widgetFrameBorderWidth(const WidgetT *w);

Return the effective border width for a container widget (used to inset child layout).

### widgetIsFocusable

    bool widgetIsFocusable(int32_t type);

True if the widget class with this type ID has the WCLASS_FOCUSABLE flag.

### widgetIsHorizContainer

    bool widgetIsHorizContainer(int32_t type);

True if the widget class lays out children horizontally (WCLASS_HORIZ_CONTAINER).

### multiClickDetect

    int32_t multiClickDetect(int32_t vx, int32_t vy);

Track consecutive clicks at roughly the same position within sDblClickTicks. Returns the current click count (1 for single, 2 for double, etc.).

## Clipboard

### clipboardCopy

    void clipboardCopy(const char *text, int32_t len);

Copy text to the process-wide clipboard buffer. Same underlying storage as dvxClipboardCopy.

### clipboardGet

    const char *clipboardGet(int32_t *outLen);

Retrieve clipboard text.

## Scrollbar Helpers

### ScrollHitE

Scrollbar hit-test result.

      Value                Description
      -----                -----------
      ScrollHitNoneE       Click fell outside the scrollbar
      ScrollHitArrowDecE   Up/left arrow
      ScrollHitArrowIncE   Down/right arrow
      ScrollHitPageDecE    Trough above/before the thumb
      ScrollHitPageIncE    Trough below/after the thumb
      ScrollHitThumbE      The draggable thumb

### widgetScrollbarThumb

    void widgetScrollbarThumb(int32_t trackLen, int32_t totalSize, int32_t visibleSize, int32_t scrollPos, int32_t *thumbPos, int32_t *thumbSize);

Compute thumb position and size for a scrollbar with the given geometry. Enforces SB_MIN_THUMB.

### widgetDrawScrollbarV / widgetDrawScrollbarVEx

    void widgetDrawScrollbarV(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t sbX, int32_t sbY, int32_t sbH, int32_t totalSize, int32_t visibleSize, int32_t scrollPos);
    void widgetDrawScrollbarVEx(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t sbX, int32_t sbY, int32_t sbH, int32_t totalSize, int32_t visibleSize, int32_t scrollPos, int32_t barW);

Draw a vertical scrollbar inside a widget. The Ex variant lets the caller specify bar width for non-standard scrollbars (e.g. combo popups). Standard variant uses WGT_SB_W.

### widgetDrawScrollbarH / widgetDrawScrollbarHEx

    void widgetDrawScrollbarH(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t sbX, int32_t sbY, int32_t sbW, int32_t totalSize, int32_t visibleSize, int32_t scrollPos);
    void widgetDrawScrollbarHEx(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t sbX, int32_t sbY, int32_t sbW, int32_t totalSize, int32_t visibleSize, int32_t scrollPos, int32_t barW);

Draw a horizontal scrollbar inside a widget. Standard variant uses WGT_SB_W.

### widgetScrollbarHitTest

    ScrollHitE widgetScrollbarHitTest(int32_t sbLen, int32_t relPos, int32_t totalSize, int32_t visibleSize, int32_t scrollPos);

Classify a click position along a scrollbar into ScrollHitE. sbLen is the scrollbar length, relPos is the click position along the bar.

## Layout Functions

### widgetCalcMinSizeBox / widgetCalcMinSizeTree

    void widgetCalcMinSizeBox(WidgetT *w, const BitmapFontT *font);
    void widgetCalcMinSizeTree(WidgetT *w, const BitmapFontT *font);

Generic box-container min-size calculation (bottom-up layout pass). widgetCalcMinSizeBox handles a single VBox/HBox; widgetCalcMinSizeTree recurses through the whole subtree.

### widgetLayoutBox / widgetLayoutChildren

    void widgetLayoutBox(WidgetT *w, const BitmapFontT *font);
    void widgetLayoutChildren(WidgetT *w, const BitmapFontT *font);

Generic box-container layout (top-down pass). widgetLayoutBox lays out a single container; widgetLayoutChildren processes each child's layout handler.

## Event Dispatch

### widgetOnPaint / widgetOnMouse / widgetOnKey / etc.

    void widgetOnPaint(WindowT *win, RectT *dirtyArea);
    void widgetOnMouse(WindowT *win, int32_t x, int32_t y, int32_t buttons);
    void widgetOnKey(WindowT *win, int32_t key, int32_t mod);
    void widgetOnKeyUp(WindowT *win, int32_t scancode, int32_t mod);
    void widgetOnResize(WindowT *win, int32_t newW, int32_t newH);
    void widgetOnScroll(WindowT *win, ScrollbarOrientE orient, int32_t value);
    void widgetOnFocus(WindowT *win);
    void widgetOnBlur(WindowT *win);

Window-level event handlers that dispatch to individual widgets in the tree. wgtInitWindow installs these as the window's onPaint/onMouse/onKey/etc. callbacks.

### widgetManageScrollbars

    void widgetManageScrollbars(WindowT *win, AppContextT *ctx);

Add, remove, or resize window scrollbars based on the widget tree's current min-size vs. the window content area.

## Paint Helpers

### widgetPaintOne

    void widgetPaintOne(WidgetT *w, DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors);

Paint a single widget (sets clip rect, calls the widget's PAINT handler). Does not recurse.

### widgetPaintOverlays

    void widgetPaintOverlays(WidgetT *root, DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors);

Paint the overlay pass: dropdown popups and tooltips drawn on top of the main tree.

## Pressable Button Helpers

Shared state machine for WCLASS_PRESS_RELEASE widgets (Button, ImageButton). The w->pressed flag tracks the visual state; these helpers fire the widget's onClick callback on release-within-bounds.

### widgetPressableOnMouse / widgetPressableOnKey / widgetPressableOnDragUpdate / widgetPressableOnDragEnd / widgetPressableOnAccelActivate

    void widgetPressableOnMouse(WidgetT *w, WidgetT *root, int32_t vx, int32_t vy);
    void widgetPressableOnKey(WidgetT *w, int32_t key, int32_t mod);
    void widgetPressableOnDragUpdate(WidgetT *w, WidgetT *root, int32_t x, int32_t y);
    void widgetPressableOnDragEnd(WidgetT *w, WidgetT *root, int32_t x, int32_t y);
    void widgetPressableOnAccelActivate(WidgetT *w, WidgetT *root);

Register these directly as the widget class's handlers for WGT_METHOD_ON_MOUSE, WGT_METHOD_ON_KEY, WGT_METHOD_ON_DRAG_UPDATE, WGT_METHOD_ON_DRAG_END, and WGT_METHOD_ON_ACCEL_ACTIVATE.

## Generic Text Handlers

For widgets whose data struct has a (const char *) as its first field and the WCLASS_HAS_TEXT flag set, these implement GET_TEXT / SET_TEXT directly.

### widgetTextGet / widgetTextSet

    const char *widgetTextGet(const WidgetT *w);
    void        widgetTextSet(WidgetT *w, const char *text);

Register these directly as the widget class's handlers for WGT_METHOD_GET_TEXT and WGT_METHOD_SET_TEXT. The text is strdup'd on set and freed automatically on destroy.

## Class Table

### widgetClassTable

    extern const WidgetClassT **widgetClassTable;

stb_ds dynamic array. Each widget DXE appends its class pointer via wgtRegisterClass() during wgtRegister(). Indexed by the runtime type ID assigned at registration.

# platform/dvxPlat.h -- Platform Abstraction Layer

All OS-specific and CPU-specific code is isolated behind this interface. Port DVX to a new platform by implementing a new dvxPlatformXxx.c against this header. Currently the only implementation is dvxPlatformDos.c for DJGPP/DPMI.

Platform functions must be stateless (or manage their own internal state) and must not reference AppContextT or any layer above dvxTypes.h.

## Constants

      Define                   Value   Description
      ------                   -----   -----------
      DVX_MAX_PATH             260     Maximum file path length
      PLATFORM_SYSINFO_MAX     4096    Maximum size of formatted system info text
      DVX_PATH_SEP             "\\"    Native directory separator on DOS

## Types

### PlatformKeyEventT

Keyboard event with ASCII and scancode separated. Extended keys (arrows, F-keys) have ascii == 0 and a non-zero scancode.

      Field       Description
      -----       -----------
      ascii       ASCII value, 0 for extended/function keys
      scancode    PC scancode (e.g. 0x48 = Up, 0x50 = Down)

### PlatformLogFnT

    typedef void (*PlatformLogFnT)(const char *fmt, ...);

Log function signature used by the crash handler.

### PlatformSymOverrideT

Name/function-pointer pair for registering symbol overrides with the DXE loader.

      Field   Description
      -----   -----------
      name    Symbol name as seen by DXEs
      func    Function pointer to use instead of the default

## Lifecycle

### dvxLog

    void dvxLog(const char *fmt, ...);

Append a formatted line to dvx.log. Implemented in dvx.exe and exported to every DXE via the loader.

### platformInit

    void platformInit(void);

One-time platform initialization. On DOS this installs signal handlers for clean shutdown on Ctrl+C/Ctrl+Break.

### platformYield

    void platformYield(void);

Cooperative CPU yield, used between frames when the event loop has nothing to do. On DOS this calls __dpmi_yield() to be friendly to multitaskers.

## Video

### platformVideoInit / platformVideoShutdown

    int32_t platformVideoInit(DisplayT *d, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);
    void    platformVideoShutdown(DisplayT *d);

Low-level video mode setup and teardown. Called by videoInit / videoShutdown.

### platformVideoEnumModes

    void platformVideoEnumModes(void (*cb)(int32_t w, int32_t h, int32_t bpp, void *userData), void *userData);

Enumerate LFB-capable graphics modes. Invokes cb once per available mode.

### platformVideoSetPalette

    void platformVideoSetPalette(const uint8_t *pal, int32_t firstEntry, int32_t count);

Program the VGA/VESA DAC palette registers (8-bit mode only).

### platformVideoFreeBuffers

    void platformVideoFreeBuffers(DisplayT *d);

Free the backbuffer and palette without restoring text mode. Used when switching between graphics modes live.

## Framebuffer Flush

### platformFlushRect

    void platformFlushRect(const DisplayT *d, const RectT *r);

Copy a rectangle from the system RAM backbuffer to the LFB. The single critical path where PCI bus write speed matters. On DOS, each scanline uses rep movsd for aligned 32-bit writes.

## Span Operations

### platformSpanFill8/16/32

    void platformSpanFill8(uint8_t *dst, uint32_t color, int32_t count);
    void platformSpanFill16(uint8_t *dst, uint32_t color, int32_t count);
    void platformSpanFill32(uint8_t *dst, uint32_t color, int32_t count);

Fill count pixels at dst with color. Three depth variants because the fill instruction differs by size. On DOS these use inline rep stosl / rep stosw / rep stosb asm.

### platformSpanCopy8/16/32

    void platformSpanCopy8(uint8_t *dst, const uint8_t *src, int32_t count);
    void platformSpanCopy16(uint8_t *dst, const uint8_t *src, int32_t count);
    void platformSpanCopy32(uint8_t *dst, const uint8_t *src, int32_t count);

Copy count pixels from src to dst. On DOS these use rep movsd.

## Mouse Input

### platformMouseInit

    void platformMouseInit(int32_t screenW, int32_t screenH);

Initialize the mouse driver and constrain movement to the screen bounds.

### platformMousePoll

    void platformMousePoll(int32_t *mx, int32_t *my, int32_t *buttons);

Poll current mouse state. Buttons is a bitmask: bit 0 = left, bit 1 = right, bit 2 = middle.

### platformMouseWheelInit / platformMouseWheelPoll

    bool    platformMouseWheelInit(void);
    int32_t platformMouseWheelPoll(void);

Detect and activate the CuteMouse Wheel API. platformMouseWheelPoll returns the accumulated delta (positive = scroll down) since the last poll.

### platformMouseSetAccel / platformMouseSetMickeys

    void platformMouseSetAccel(int32_t threshold);
    void platformMouseSetMickeys(int32_t horizMickeys, int32_t vertMickeys);

Set the double-speed threshold and mickey-to-pixel ratio. See dvxSetMouseConfig for a higher-level interface.

### platformMouseWarp

    void platformMouseWarp(int32_t x, int32_t y);

Move the mouse cursor to an absolute screen position. Used to clamp the cursor to window edges during resize.

## Keyboard Input

### platformKeyboardGetModifiers

    int32_t platformKeyboardGetModifiers(void);

Return the current modifier key state in BIOS shift-state format.

### platformKeyboardRead

    bool platformKeyboardRead(PlatformKeyEventT *evt);

Non-blocking read of the next key from the keyboard buffer. Returns true if a key was available.

### platformKeyUpInit / platformKeyUpShutdown / platformKeyUpRead

    void platformKeyUpInit(void);
    void platformKeyUpShutdown(void);
    bool platformKeyUpRead(PlatformKeyEventT *evt);

Key-up event detection. Install/uninstall the INT 9 hook around process lifetime. platformKeyUpRead returns true if a key release was detected since the last call.

### platformAltScanToChar

    char platformAltScanToChar(int32_t scancode);

Translate an Alt+key scancode to its corresponding ASCII character. Returns 0 for non-printable scancodes.

## System Information

### platformGetSystemInfo

    const char *platformGetSystemInfo(const DisplayT *display);

Return a pre-formatted text string with hardware/OS information (CPU, clock, memory, video, mouse, disks). Valid for the lifetime of the process.

### platformGetMemoryInfo

    bool platformGetMemoryInfo(uint32_t *totalKb, uint32_t *freeKb);

Query total and free physical memory.

## File System

### platformValidateFilename

    const char *platformValidateFilename(const char *name);

Validate a filename against platform-specific rules (8.3 on DOS). Returns NULL if valid, or a human-readable error string.

### platformMkdirRecursive

    int32_t platformMkdirRecursive(const char *path);

Create a directory and all parent directories (like mkdir -p). Existing directories are not an error.

### platformChdir

    int32_t platformChdir(const char *path);

Change the working directory, including drive letter on DOS (calls setdisk() first when the path starts with "X:").

### platformPathDirEnd

    char *platformPathDirEnd(const char *path);

Return a pointer to the last directory separator in path, or NULL. On DOS accepts both "/" and "\\".

### platformPathBaseName

    const char *platformPathBaseName(const char *path);

Return a pointer to the leaf (basename) portion of path.

### platformCopyFile

    bool platformCopyFile(const char *srcPath, const char *dstPath);

Byte-for-byte file copy. Returns false on any open, read, or write failure; a partially written destination is removed so no truncated copy is left behind.

### platformReadFile

    char *platformReadFile(const char *path, int32_t *outLen);

Slurp a whole file into a freshly malloc'd, NUL-terminated buffer. Caller frees. Binary-safe: the NUL is past the end of the reported length.

### platformGlobMatch

    bool platformGlobMatch(const char *pattern, const char *name);

Simple glob pattern match. Case-insensitive. Supports * (zero or more chars) and ? (single char).

### platformLineEnding / platformStripLineEndings

    const char *platformLineEnding(void);
    int32_t     platformStripLineEndings(char *buf, int32_t len);

Return the native line ending string, or strip line-ending characters from a buffer in place.

## String Helpers

### dvxSkipWs

    const char *dvxSkipWs(const char *s);

Advance past leading spaces and tabs. Returns s unchanged if NULL or already non-whitespace.

### dvxTrimRight

    int32_t dvxTrimRight(char *buf);

Strip trailing spaces, tabs, carriage returns, and newlines from buf in place. Returns the new length.

## DXE Module Support

### platformRegisterDxeExports

    void platformRegisterDxeExports(void);

Register platform and C runtime symbols with the dynamic module loader so DXE modules can resolve them at load time.

### platformRegisterSymOverrides

    void platformRegisterSymOverrides(const PlatformSymOverrideT *entries);

Register function pointer overrides for subsequently loaded modules. entries is terminated by {NULL, NULL}.

## Crash Recovery

### platformInstallCrashHandler

    void platformInstallCrashHandler(jmp_buf *recoveryBuf, volatile int *crashSignal, PlatformLogFnT logFn);

Install signal handlers for SIGSEGV, SIGFPE, SIGILL. On crash, logs platform-specific diagnostics via logFn, stores the signal in *crashSignal, then longjmps to recoveryBuf.

### platformLogCrashDetail

    void platformLogCrashDetail(int sig, PlatformLogFnT logFn);

Log platform-specific crash diagnostics. Called internally from the crash handler and exposed for manual invocation.

## VGA Splash Screen

### platformSplashInit / platformSplashShutdown

    void platformSplashInit(void);
    void platformSplashShutdown(void);

Enter/leave VGA mode 13h (320x200x256) used for the boot splash.

### platformSplashLoadRaw

    bool platformSplashLoadRaw(const char *path);

Load and display a raw splash file (768-byte palette + 64000-byte pixel data).

### platformSplashFillRect

    void platformSplashFillRect(int32_t x, int32_t y, int32_t w, int32_t h, uint8_t color);

Fill a rectangle on the mode 13h screen with a palette index. Used to draw the progress bar during module loading.

# libtasks -- Cooperative Task Switching

Credit-based cooperative (non-preemptive) multitasking library for DOS protected mode (DJGPP/DPMI). Each task receives (priority + 1) credits per scheduling round. Tasks run round-robin, consuming one credit per turn. When all credits are exhausted, every ready task is refilled. Higher-priority tasks run proportionally more often but never starve lower ones.

Header: libtasks/taskSwch.h

Loaded as: bin/libs/libtasks.lib

## Why Cooperative

DOS is single-threaded with no kernel scheduler. DPMI provides no preemption primitives. The DVX GUI event model is inherently single-threaded: one compositor, one input queue, one window stack. Cooperative switching lets each task yield at safe points, avoiding synchronization primitives entirely.

## Scheduling Semantics

Task storage is a stb_ds dynamic array. Terminated slots are recycled by tsCreate so the array does not grow unboundedly. The scheduler performs a linear scan for the next Ready task whose credit count is positive; when no task has credits left, every Ready task is refilled with (priority + 1) credits and the scan restarts.

      Priority            Credits per round  Approximate share
      --------            -----------------  -----------------
      TS_PRIORITY_LOW     1                  ~4% (1 of 25 possible credits)
      TS_PRIORITY_NORMAL  6                  ~22%
      TS_PRIORITY_HIGH    11                 ~41%

Actual share depends on the mix of priorities currently running. What the algorithm guarantees is that no ready task ever goes unscheduled -- even a priority-0 task always earns at least one turn per round.

### Stack Allocation

Task 0 uses the caller's stack (no separate allocation). Every other task gets a heap-allocated stack of the size passed to tsCreate (or TS_DEFAULT_STACK_SIZE if 0 is passed). Stacks are freed at task termination, either via tsExit or tsKill.

## Error Codes

      Constant         Value   Description
      --------         -----   -----------
      TS_OK            0       Success
      TS_ERR_INIT      -1      Task system not initialized
      TS_ERR_PARAM     -2      Invalid parameter (bad task ID, etc.)
      TS_ERR_FULL      -3      Task array full (should not occur; array grows)
      TS_ERR_NOMEM     -4      Memory allocation failed
      TS_ERR_STATE     -5      Invalid state transition

## Constants

      Constant                  Value   Description
      --------                  -----   -----------
      TS_DEFAULT_STACK_SIZE     32768   Default stack size per task (32 KB)
      TS_NAME_MAX               32      Maximum task name length including NUL
      TS_PRIORITY_LOW           0       Low priority (1 credit per round)
      TS_PRIORITY_NORMAL        5       Normal priority (6 credits per round)
      TS_PRIORITY_HIGH          10      High priority (11 credits per round)

## Types

### TaskStateE

Task scheduling state. Only Ready tasks participate in scheduling.

      Value                  Description
      -----                  -----------
      TaskStateReady         Eligible for scheduling
      TaskStateRunning       Currently executing (cosmetic; marks active task)
      TaskStatePaused        Skipped by scheduler until explicitly resumed
      TaskStateTerminated    Slot available for reuse

### TaskEntryT

    typedef void (*TaskEntryT)(void *arg);

Task entry point function signature. The void* argument lets the caller pass arbitrary context (e.g. a shell app descriptor).

## tsInit

    int32_t tsInit(void);

Initialize the task system. The calling context becomes task 0 (the main task). Task 0 is special: it cannot be killed or paused, and tsRecoverToMain() always returns control here. No separate stack is allocated for task 0; it uses the process stack directly.

Returns: TS_OK on success, TS_ERR_PARAM if already initialized.

## tsShutdown

    void tsShutdown(void);

Shut down the task system and free all task stacks and internal storage. Safe to call even if tsInit() was never called.

## tsCreate

    int32_t tsCreate(const char *name, TaskEntryT entry, void *arg, uint32_t stackSize, int32_t priority);

Create a new task. Terminated task slots are recycled to avoid unbounded array growth.

      Parameter    Description
      ---------    -----------
      name         Task name (truncated to TS_NAME_MAX - 1 characters)
      entry        Task entry point function
      arg          Opaque argument passed to entry
      stackSize    Stack size in bytes (pass 0 for TS_DEFAULT_STACK_SIZE)
      priority     Scheduling priority (0..10; use TS_PRIORITY_* constants)

Returns: Task ID (>= 0) on success, or a negative error code (TS_ERR_PARAM if not initialized or entry is NULL, TS_ERR_NOMEM if stack allocation failed).

## tsYield

    void tsYield(void);

Yield CPU to the next eligible ready task using credit-based round-robin. This is the sole mechanism for task switching. Every task must call this (or a GUI function that calls it) periodically, or it will monopolize the CPU.

## tsPause

    int32_t tsPause(uint32_t taskId);

Pause a task, removing it from scheduling. Cannot pause the main task (ID 0). If a task pauses itself, an implicit yield occurs.

      Parameter   Description
      ---------   -----------
      taskId      ID of the task to pause

Returns: TS_OK on success, TS_ERR_PARAM on invalid ID, or TS_ERR_STATE if the task is the main task or not in a pausable state (not Running or Ready).

## tsResume

    int32_t tsResume(uint32_t taskId);

Resume a paused task. Credits are refilled so the task gets a fair share of CPU time immediately rather than waiting for the next scheduling round.

      Parameter   Description
      ---------   -----------
      taskId      ID of the task to resume

Returns: TS_OK on success, TS_ERR_PARAM on invalid ID, TS_ERR_STATE if the task is not paused.

## tsSetPriority

    int32_t tsSetPriority(uint32_t taskId, int32_t priority);

Set a task's scheduling priority. Also refills credits so the change takes effect immediately.

      Parameter   Description
      ---------   -----------
      taskId      ID of the task to modify
      priority    New priority level (0..10)

Returns: TS_OK on success, TS_ERR_PARAM on invalid ID, or TS_ERR_STATE if the task is terminated.

## tsGetPriority

    int32_t tsGetPriority(uint32_t taskId);

Get a task's current scheduling priority.

      Parameter   Description
      ---------   -----------
      taskId      ID of the task to query

Returns: Priority value (0..10) on success, TS_ERR_PARAM on invalid ID.

## tsGetState

    TaskStateE tsGetState(uint32_t taskId);

Get a task's current scheduling state.

      Parameter   Description
      ---------   -----------
      taskId      ID of the task to query

Returns: TaskStateE value. Returns TaskStateTerminated for invalid IDs.

## tsCurrentId

    uint32_t tsCurrentId(void);

Get the ID of the currently executing task. Always valid while the task system is initialized.

Returns: Current task ID.

## tsGetName

    const char *tsGetName(uint32_t taskId);

Get a task's name string.

      Parameter   Description
      ---------   -----------
      taskId      ID of the task to query

Returns: Pointer to the task's name, or NULL on invalid ID. The pointer remains valid until the task slot is reused.

## tsExit

    void tsExit(void);

Terminate the calling task. Must not be called from the main task (ID 0). The stack is freed immediately and the slot is marked for reuse. This function never returns; it performs an internal context switch to the next ready task.

## tsKill

    int32_t tsKill(uint32_t taskId);

Forcibly terminate another task. Cannot kill the main task (ID 0) or the currently running task (use tsExit() for self-termination). Safe because cooperative scheduling guarantees the target is suspended at a yield point.

      Parameter   Description
      ---------   -----------
      taskId      ID of the task to terminate

Returns: TS_OK on success, TS_ERR_PARAM on invalid ID, or TS_ERR_STATE on illegal target (main task, self, or already terminated).

## tsRecoverToMain

    void tsRecoverToMain(void);

Crash recovery: force the scheduler back to the main task (ID 0). Call after longjmp from a signal handler that fired in a non-main task. The crashed task is NOT cleaned up by this call; call tsKill() afterward to free its resources. This exists because longjmp unwinds the crashed task's stack but the scheduler state still points to it.

## tsActiveCount

    uint32_t tsActiveCount(void);

Get the number of non-terminated tasks currently in the system.

Returns: Count of tasks in Ready, Running, or Paused state.

# DVX Shell Library

The DVX shell library manages the lifecycle of DXE applications: loading, launching, tracking, and reaping. It provides the bridge between the DVX GUI compositor and dynamically loaded DXE3 application modules.

Header: dvxshell/shellApp.h

Loaded as: bin/libs/dvxshell.lib

## App Model

The shell supports two kinds of DXE apps:

- Callback-only (hasMainLoop = false) -- appMain() runs in the shell's task 0, creates windows, registers event callbacks, and returns immediately. The app lives through GUI callbacks. Lifecycle ends when the last window is closed. Simpler and cheaper (no extra stack/task).
- Main-loop (hasMainLoop = true) -- A dedicated cooperative task is created. appMain() runs in that task and can do its own polling loop, calling tsYield() to share CPU. Lifecycle ends when appMain() returns or the task is killed. Needed for terminal emulators, games, or long computations.

Both types use the same DXE interface: an exported appDescriptor and appMain function.

## DXE Interface

Every .app DXE module must export these symbols (COFF convention uses leading underscore):

      Symbol                Type                            Required
      ------                ----                            --------
      _appDescriptor        AppDescriptorT                  Yes
      _appMain              int32_t (*)(DxeAppContextT *)   Yes
      _appShutdown          void (*)(void)                  No

The shell resolves appDescriptor at dlopen time; if missing, the load fails with an error dialog. appMain is called immediately for callback-only apps or from the new task for main-loop apps. appShutdown, if present, is called during graceful reap (but not during force kill from crashed apps).

## Callback-Only vs Main-Loop Apps

The app descriptor's hasMainLoop flag selects between two very different lifecycles:

- hasMainLoop = false (callback-only). The shell calls appMain directly on task 0 at dlopen time. The function creates windows, registers event callbacks, and returns. After that the app has no executing thread of its own -- it exists purely through GUI callbacks dispatched by dvxUpdate. The shell reaps the app automatically when its last window closes. Best for modal tools, dialogs, and event-driven utilities.
- hasMainLoop = true (main-loop). The shell creates a dedicated cooperative task (via tsCreate) with the descriptor's stackSize (or TS_DEFAULT_STACK_SIZE) and priority. appMain runs in that task and can do its own work loop, calling tsYield or any GUI function that yields. The app terminates when appMain returns (the wrapper sets AppStateTerminatingE) or when forced via shellForceKillApp. Best for terminal emulators, games, and any app with continuous background work.

Both app types use the same export interface; only the descriptor's flags differ. Apps cannot switch modes at runtime.

## Icon Conventions

Shell-level UI (Program Manager, Task Manager) displays app icons at 16x16 and 32x32. Icons are not handled by the shell itself; each app embeds its own icons via the DVX resource system (DVX_RES_ICON):

- 16x16 BMP for toolbar entries and list rows
- 32x32 BMP for desktop shortcuts and Program Manager tiles

The Program Manager reads the app's 32x32 icon resource when building shortcut tiles. Apps without an icon resource fall back to a default shell-provided bitmap.

## State Machine

App slots progress through four states:

    Free -> Loaded -> Running -> Terminating -> Free

LoadedE is transient (only during shellLoadApp before the entry point is called). TerminatingE means the app's task has exited but cleanup has not yet occurred. The shell's main loop reaps terminating apps each frame via shellReapApps().

## Contents

Types and Constants

Lifecycle API

Query API

Configuration API

Desktop Callbacks

System Information

# Types and Constants

## Constants

      Constant              Value                           Description
      --------              -----                           -----------
      SHELL_APP_NAME_MAX    64                              Maximum length of an app name string.
      SHELL_STACK_DEFAULT   0                               Use in AppDescriptorT.stackSize to get the default task stack size.
      SHELL_DESKTOP_APP     "apps/kpunch/progman/progman.app"  Default desktop application path.

## AppDescriptorT

Exported by every DXE app as a global named appDescriptor. The shell reads it at load time to determine how to launch the app.

      Field                          Type      Description
      -----                          ----      -----------
      name[SHELL_APP_NAME_MAX]       char[]    Display name of the application.
      hasMainLoop                    bool      false = callback-only, true = dedicated task.
      multiInstance                  bool      true = allow multiple simultaneous instances via temp copy.
      stackSize                      int32_t   SHELL_STACK_DEFAULT or explicit byte count for the task stack.
      priority                       int32_t   TS_PRIORITY_* value or custom priority for the task.

## DxeAppContextT

Passed as the sole argument to appMain(). Gives the app access to the shell's GUI context and its own identity. Heap-allocated by shellLoadApp so its address is stable across reallocations of the internal app slot table (apps may safely cache the pointer in their static globals).

      Field                          Type                    Description
      -----                          ----                    -----------
      shellCtx                       AppContextT *           The shell's GUI context (for creating windows, drawing, etc.).
      appId                          int32_t                 This app's unique ID (slot index, 1-based).
      appPath[DVX_MAX_PATH]          char[]                  Full path to the .app DXE file.
      appDir[DVX_MAX_PATH]           char[]                  Directory containing the .app file (for loading resources).
      configDir[DVX_MAX_PATH]        char[]                  Writable config directory (e.g. CONFIG/APPS/KPUNCH/DVXBASIC/).
      args[1024]                     char[]                  Launch arguments (empty string if none).
      helpFile[DVX_MAX_PATH]         char[]                  Help file path (for F1 context help).
      helpTopic[128]                 char[]                  Current help topic ID (updated by the app at runtime).
      onHelpQuery                    void (*)(void *ctx)     Optional callback the shell fires on F1 so the app can refresh helpTopic from context.
      helpQueryCtx                   void *                  Opaque context pointer passed to onHelpQuery.

The appDir field is derived from the .app file path at load time so apps can find their own resources via relative paths. This is necessary because the working directory is shared by all apps in DOS. The config directory is mirrored from the app path: an app at APPS/KPUNCH/DVXBASIC/dvxbasic.app gets CONFIG/APPS/KPUNCH/DVXBASIC/.

## AppStateE

      Value                 Description
      -----                 -----------
      AppStateFreeE         Slot is available for reuse.
      AppStateLoadedE       DXE loaded, entry point not yet called (transient).
      AppStateRunningE      Entry point called, app is active.
      AppStateTerminatingE  Shutdown in progress, awaiting reap.

## ShellAppT

Per-app slot in the shell's app table. Slot 0 is reserved for the shell itself; apps use slots 1 and above.

      Field                          Type                            Description
      -----                          ----                            -----------
      appId                          int32_t                         Unique ID (slot index, 1-based; 0 = shell).
      name[SHELL_APP_NAME_MAX]       char[]                          Display name from AppDescriptorT.
      path[DVX_MAX_PATH]             char[]                          Original DXE file path.
      tempPath[DVX_MAX_PATH]         char[]                          Temp copy path for multi-instance (empty if not a copy).
      dxeHandle                      void *                          dlopen() handle for the DXE module.
      state                          AppStateE                       Current lifecycle state.
      hasMainLoop                    bool                            Whether this app has a dedicated task.
      mainTaskId                     uint32_t                        Task ID if hasMainLoop, else 0.
      entryFn                        int32_t (*)(DxeAppContextT *)   Pointer to appMain.
      shutdownFn                     void (*)(void)                  Pointer to appShutdown (may be NULL).
      dxeCtx                         DxeAppContextT *                Heap-allocated context (address stable across realloc).

# App Lifecycle API

## shellAppInit

    void shellAppInit(void);

Initialize the app slot table. Seeds slot 0 (reserved for the shell). Must be called once at startup before any other shell API function.

## shellLoadApp

    int32_t shellLoadApp(AppContextT *ctx, const char *path);

Load and start an app from a DXE file. Returns the app ID (>= 1) on success, or -1 on error.

For callback-only apps, appMain() runs synchronously and returns before shellLoadApp returns. For main-loop apps, a cooperative task is created and the app begins running on the next tsYield().

If multiInstance is false in the app's descriptor and the same DXE is already loaded, the call fails with an error dialog. If multiInstance is true, the DXE is copied to a temp file so dlopen gets an independent code and data image.

## shellLoadAppWithArgs

    int32_t shellLoadAppWithArgs(AppContextT *ctx, const char *path, const char *args);

Load and run an app with arguments. The args string is copied into DxeAppContextT.args before appMain() is called. Otherwise identical to shellLoadApp().

## shellReapApps

    bool shellReapApps(AppContextT *ctx);

Scan for and reap finished apps. Call once per frame from the main loop.

Returns true if any apps were reaped, so the caller can trigger a desktop refresh. For main-loop apps, termination is detected by the AppStateTerminatingE state (set when appMain returns). For callback-only apps, termination is detected when no windows remain for that app.

## shellReapApp

    void shellReapApp(AppContextT *ctx, ShellAppT *app);

Gracefully shut down a single app. Calls the app's shutdownFn (if present), destroys all windows belonging to the app, kills its task (if any), closes the DXE handle, and frees the context. The slot returns to AppStateFreeE.

## shellForceKillApp

    void shellForceKillApp(AppContextT *ctx, ShellAppT *app);

Forcibly kill an app. Used by the Task Manager "End Task" or as part of crash recovery. Calls the app's shutdownFn (if present) so it can unregister callbacks before its DXE is unmapped, then destroys all of the app's windows, kills its task (for main-loop apps), and finally closes the DXE handle.

Cleanup order: shutdownFn first (so the app can unregister callbacks while still mapped), then windows (removes from compositor), then task (frees stack), then DXE handle (unmaps code). Closing the DXE before destroying windows would cause callbacks into unmapped code.

## shellTerminateAllApps

    void shellTerminateAllApps(AppContextT *ctx);

Force-kill all running apps. Called during shell shutdown. Iterates all slots and calls shellForceKillApp() on each active app.

# Query API

## shellGetApp

    ShellAppT *shellGetApp(int32_t appId);

Look up an app slot by ID. Returns a pointer to the ShellAppT, or NULL if the ID is out of range or the slot is free. Valid app IDs are 1 through shellAppSlotCount() - 1.

## shellAppSlotCount

    int32_t shellAppSlotCount(void);

Return the total number of app slots (including slot 0). Use as the iteration bound when scanning all slots. Slot 0 is the shell itself; app slots start at 1.

## shellRunningAppCount

    int32_t shellRunningAppCount(void);

Count running apps, not counting the shell itself. Includes apps in both AppStateLoadedE and AppStateRunningE states.

# Configuration API

Each app has a per-app configuration directory derived from its DXE path, mirrored under CONFIG/. For example, an app at APPS/KPUNCH/DVXBASIC/dvxbasic.app gets the config directory CONFIG/APPS/KPUNCH/DVXBASIC/.

## shellEnsureConfigDir

    int32_t shellEnsureConfigDir(const DxeAppContextT *ctx);

Ensure the app's config directory exists, creating all parent directories as needed. Returns 0 on success, -1 on failure.

Call this before writing any config files. The directory path comes from ctx->configDir.

## shellConfigPath

    void shellConfigPath(const DxeAppContextT *ctx, const char *filename, char *outPath, int32_t outSize);

Build a full path to a file in the app's config directory by joining ctx->configDir with the given filename.

    // Example:
    char path[DVX_MAX_PATH];
    shellConfigPath(ctx, "settings.ini", path, sizeof(path));
    // -> "CONFIG/APPS/KPUNCH/PROGMAN/settings.ini"

# Desktop Callbacks

The shell wires several AppContextT event hooks (onCtrlEsc, onF1, onTitleChange, idleCallback) during startup and exposes them to other DXEs via function-pointer extern and registration API. Desktop managers register a callback to refresh their display when apps come and go. The Task Manager DXE registers its Ctrl+Esc handler via the shellCtrlEscFn extern pointer (see Task Manager documentation).

## Shell Event Hooks

      AppContextT field    Handler                 Purpose
      -----------------    -------                 -------
      idleCallback         shellIdleDispatch       Runs every registered idle handler (see shellRegisterIdle), then yields to cooperative tasks, when dvxUpdate has no input events and no dirty rects.
      onCtrlEsc            ctrlEscHandler          Invokes shellCtrlEscFn if the Task Manager DXE is loaded.
      onF1                 f1HelpHandler           Launches the help viewer, optionally passing the focused app's helpFile and helpTopic.
      onTitleChange        titleChangeHandler      Runs shellDesktopUpdate so Program Manager window lists refresh.

## shellRegisterDesktopUpdate

    void shellRegisterDesktopUpdate(void (*updateFn)(void));

Register a callback for app state change notifications. Multiple callbacks are supported. Apps typically call this during appMain() to receive notifications.

## shellUnregisterDesktopUpdate

    void shellUnregisterDesktopUpdate(void (*updateFn)(void));

Remove a previously registered callback. Call this before app shutdown to avoid dangling function pointers.

## shellRegisterIdle

    void shellRegisterIdle(void (*fn)(void *ctx), void *ctx);

Register an idle handler invoked every idle frame by the shell main loop, regardless of which app is foreground. Background pollers (serial and secLink) register here so their connections keep pumping while another app is in front. Registration is idempotent on the (fn, ctx) pair. The registering module MUST unregister before it is unloaded -- app DXEs do this from their _appShutdown hook, which the shell calls on both graceful reap and force-kill.

## shellUnregisterIdle

    void shellUnregisterIdle(void (*fn)(void *ctx), void *ctx);

Remove a previously registered idle handler. No-op if the (fn, ctx) pair is absent, so a double-unregister is harmless.

## shellDesktopUpdate

    void shellDesktopUpdate(void);

Notify all registered desktop callbacks that app state has changed. Called internally by the shell after loading or reaping an app. Can also be called by apps that need to trigger a desktop refresh.

## shellCtrlEscFn

    extern void (*shellCtrlEscFn)(AppContextT *ctx);

Function pointer set by the taskmgr DXE's constructor. The shell calls this when Ctrl+Esc is pressed. NULL if the task manager is not loaded.

# System Information

Header: dvxshell/shellInf.h

Thin wrapper around the platform layer's hardware detection. Gathers system information at startup, logs it, and caches the result for display in dialogs.

## shellInfoInit

    void shellInfoInit(AppContextT *ctx);

Gather all hardware information via the platform layer, log each line to DVX.LOG, and store the result for later retrieval. Call once after dvxInit().

## shellGetSystemInfo

    const char *shellGetSystemInfo(void);

Return the formatted system information text. The returned pointer is valid for the lifetime of the process (static buffer in the platform layer).

## dvxSql -- SQL Database Interface

High-level wrapper around SQLite3 for DVX applications. Manages database connections and result set cursors via integer handles so BASIC code never touches raw pointers. All handles are 1-based; 0 indicates an error or invalid handle.

Header: sql/dvxSql.h

### SQLite Wrapping

dvxSql wraps the bundled SQLite3 amalgamation (sql/thirdparty/sqlite/examples/sqlite3.h). It manages two internal dynamic tables keyed by 1-based handles:

- Database table: each slot holds a sqlite3 * plus a per-database error string and affected-row count.
- Cursor table: each slot holds a sqlite3_stmt *, the owning database handle, and EOF tracking.

Growing either table doubles its capacity. Closed slots are recycled by subsequent dvxSqlOpen or dvxSqlQuery calls, keeping handle values stable for the caller.

### Handle Model

Database and cursor handles are int32_t values. A successful open or query returns a handle greater than zero. Handle 0 is reserved as the invalid/error sentinel. Closing a database automatically finalizes all cursors that belong to it, so callers do not need to track cursor lifetimes per-database.

### Connection Lifecycle

- dvxSqlOpen allocates a handle and calls sqlite3_open. The database file is created if it does not exist.
- Use dvxSqlExec for DDL and non-query DML. On success, dvxSqlAffectedRows returns the row count for the last call on this handle.
- Use dvxSqlQuery to obtain a cursor over a SELECT. Iterate with dvxSqlNext and read columns with dvxSqlFieldText, dvxSqlFieldInt, dvxSqlFieldDbl, or dvxSqlFieldByName.
- Call dvxSqlFreeResult when the cursor is no longer needed. Call dvxSqlClose when the database is no longer needed; any cursors still open on that database are finalized automatically.

### Common Patterns

- Parameterize user input with dvxSqlEscape before interpolating into SQL strings.
- Check dvxSqlError(db) for the last error on a handle; its message is stable until the next operation on the same database.
- dvxSqlFieldByName matches column names case-insensitively, suitable for most real-world schemas.

Database Operations

Cursor Operations

Utility Functions

Example

## Database Operations

### dvxSqlOpen

    int32_t dvxSqlOpen(const char *path);

Open a SQLite database file. Creates the file if it does not exist.

      Parameter    Description
      ---------    -----------
      path         Path to the database file.

Returns a database handle greater than 0 on success, or 0 on error (null path, open failure, or no free slots).

### dvxSqlClose

    void dvxSqlClose(int32_t db);

Close a database and free all associated resources. Any open cursors belonging to this database are automatically finalized.

      Parameter    Description
      ---------    -----------
      db           Database handle returned by dvxSqlOpen.

Safe to call with an invalid handle (no-op).

### dvxSqlExec

    bool dvxSqlExec(int32_t db, const char *sql);

Execute one or more SQL statements that return no result rows. Suitable for DDL (CREATE TABLE, DROP TABLE, etc.) and DML (INSERT, UPDATE, DELETE).

      Parameter    Description
      ---------    -----------
      db           Database handle.
      sql          SQL statement(s) to execute.

Returns true on success, false on error. On failure, the error message is available via dvxSqlError. On success, the affected row count is available via dvxSqlAffectedRows.

### dvxSqlError

    const char *dvxSqlError(int32_t db);

Return the last error message for a database handle. The returned string is stored internally and valid until the next operation on the same handle.

      Parameter    Description
      ---------    -----------
      db           Database handle.

Returns the error string, or "Invalid database handle" if the handle is invalid.

### dvxSqlAffectedRows

    int32_t dvxSqlAffectedRows(int32_t db);

Return the number of rows inserted, updated, or deleted by the last dvxSqlExec call on this handle.

      Parameter    Description
      ---------    -----------
      db           Database handle.

Returns the row count, or 0 if the handle is invalid.

## Cursor Operations

Result set cursors are created by dvxSqlQuery and must be freed with dvxSqlFreeResult when no longer needed. A new cursor is positioned before the first row; call dvxSqlNext to advance to the first row before reading field values.

### dvxSqlQuery

    int32_t dvxSqlQuery(int32_t db, const char *sql);

Execute a SELECT query and return a cursor handle for iterating the results. The cursor is positioned before the first row.

      Parameter    Description
      ---------    -----------
      db           Database handle.
      sql          SQL SELECT statement.

Returns a cursor handle greater than 0 on success, or 0 on error (invalid handle, null SQL, SQL syntax error, or no free cursor slots). On failure, the error message is available via dvxSqlError on the database handle.

### dvxSqlNext

    bool dvxSqlNext(int32_t rs);

Advance the cursor to the next row.

      Parameter    Description
      ---------    -----------
      rs           Cursor handle returned by dvxSqlQuery.

Returns true if a row is now available for reading, false if the cursor has reached the end or the handle is invalid.

### dvxSqlEof

    bool dvxSqlEof(int32_t rs);

Test whether the cursor is past the last row.

      Parameter    Description
      ---------    -----------
      rs           Cursor handle.

Returns true if the cursor is exhausted or the handle is invalid, false otherwise.

### dvxSqlFieldCount

    int32_t dvxSqlFieldCount(int32_t rs);

Return the number of columns in the result set.

      Parameter    Description
      ---------    -----------
      rs           Cursor handle.

Returns the column count, or 0 if the handle is invalid.

### dvxSqlFieldName

    const char *dvxSqlFieldName(int32_t rs, int32_t col);

Return the name of a column by index.

      Parameter    Description
      ---------    -----------
      rs           Cursor handle.
      col          Column index (0-based).

Returns the column name, or "" if the handle or index is invalid.

### dvxSqlFieldText

    const char *dvxSqlFieldText(int32_t rs, int32_t col);

Return the value of a column as a string.

      Parameter    Description
      ---------    -----------
      rs           Cursor handle.
      col          Column index (0-based).

Returns the text value, or "" if the handle or index is invalid or the value is NULL.

### dvxSqlFieldByName

    const char *dvxSqlFieldByName(int32_t rs, const char *name);

Return the value of a column identified by name as a string. The name match is case-insensitive.

      Parameter    Description
      ---------    -----------
      rs           Cursor handle.
      name         Column name (case-insensitive).

Returns the text value, or "" if the handle is invalid, the name is NULL, or no column with that name exists.

### dvxSqlFieldInt

    int32_t dvxSqlFieldInt(int32_t rs, int32_t col);

Return the value of a column as a 32-bit integer.

      Parameter    Description
      ---------    -----------
      rs           Cursor handle.
      col          Column index (0-based).

Returns the integer value, or 0 if the handle or index is invalid.

### dvxSqlFieldDbl

    double dvxSqlFieldDbl(int32_t rs, int32_t col);

Return the value of a column as a double-precision floating point number.

      Parameter    Description
      ---------    -----------
      rs           Cursor handle.
      col          Column index (0-based).

Returns the double value, or 0.0 if the handle or index is invalid.

### dvxSqlFreeResult

    void dvxSqlFreeResult(int32_t rs);

Close a result set cursor and free its resources. Must be called for every cursor returned by dvxSqlQuery.

      Parameter    Description
      ---------    -----------
      rs           Cursor handle.

Safe to call with an invalid handle (no-op).

## Utility Functions

### dvxSqlEscape

    int32_t dvxSqlEscape(const char *src, char *dst, int32_t dstSize);

Escape a string for safe inclusion in SQL string literals. Doubles single quotes so that O'Brien becomes O''Brien.

      Parameter    Description
      ---------    -----------
      src          Source string to escape.
      dst          Destination buffer for the escaped string.
      dstSize      Size of the destination buffer in bytes.

Returns the length of the escaped string (not including the null terminator), or -1 if the buffer was too small or any parameter is NULL/invalid.

## Example Usage

### Creating a Table and Inserting Data

    int32_t db = dvxSqlOpen("mydata.db");
    if (!db) {
        // handle error
    }

    dvxSqlExec(db, "CREATE TABLE IF NOT EXISTS contacts ("
                   "id INTEGER PRIMARY KEY, "
                   "name TEXT, "
                   "phone TEXT)");

    dvxSqlExec(db, "INSERT INTO contacts (name, phone) "
                   "VALUES ('Alice', '555-0100')");

### Querying and Iterating Results

    int32_t rs = dvxSqlQuery(db, "SELECT id, name, phone FROM contacts");
    if (!rs) {
        printf("Error: %s\n", dvxSqlError(db));
    }

    while (dvxSqlNext(rs)) {
        int32_t     id    = dvxSqlFieldInt(rs, 0);
        const char *name  = dvxSqlFieldText(rs, 1);
        const char *phone = dvxSqlFieldText(rs, 2);
        printf("%d: %s -- %s\n", id, name, phone);
    }

    dvxSqlFreeResult(rs);
    dvxSqlClose(db);

### Escaping User Input

    char escaped[512];
    dvxSqlEscape(userInput, escaped, sizeof(escaped));

    char sql[1024];
    snprintf(sql, sizeof(sql),
             "INSERT INTO notes (text) VALUES ('%s')", escaped);
    dvxSqlExec(db, sql);

# Text Help Library

Shared text editing infrastructure library for DVX widget DXEs. Provides cursor blink management, cross-widget selection clearing, word boundary logic, and a complete single-line text editing engine. Used by TextInput, Spinner, ComboBox, AnsiTerm, and other widgets that need text editing behavior.

Header: texthelp/textHelp.h

Loaded as: bin/libs/texthelp.lib

## How Widgets Use This Library

Widget DXEs that implement text editing delegate to textHelp for the four high-cost behaviors:

- Cursor blink. The library tracks a 250 ms blink timer in a static global and the focused widget reads sCursorBlinkOn (exposed via libdvx) when repainting.
- Selection clearing. When a widget gains focus it calls clearOtherSelections(self) so only one widget ever has an active text selection.
- Word boundaries. isWordChar, wordStart/wordEnd, and wordBoundaryLeft/wordBoundaryRight implement the logic for double-click word selection and Ctrl+Left/Right navigation in a uniform way.
- Single-line editing engine. widgetTextEditOnKey, widgetTextEditMouseClick, widgetTextEditDragUpdateLine, and widgetTextEditPaintLine form a pointer-parameterized implementation of keyboard, mouse, drag, and paint behaviors. Widgets (TextInput, Spinner, ComboBox, AnsiTerm) hand the library pointers to their internal buffer, cursor, scroll offset, and selection state.

The engine is intentionally pointer-parameterized rather than struct-based so widgets can reuse it without adopting a shared state struct. Each widget owns its own buffer and state and passes pointers in on every call.

## Constants

      Constant             Value    Description
      --------             -----    -----------
      TEXT_INPUT_PAD        3       Pixel padding inside text editing fields.

## wgtUpdateCursorBlink

Advances the cursor blink timer. When the blink interval (250 ms) elapses, toggles the global sCursorBlinkOn flag and invalidates the currently focused widget for repaint. Registered automatically at library load time via a constructor function that sets the sCursorBlinkFn pointer.

    void wgtUpdateCursorBlink(void);

Takes no arguments and returns nothing. Called by the core event loop.

## clearOtherSelections

Clears the text selection on whichever widget previously had one, unless that widget is the one passed as the argument. Tracks the last selected widget in a static pointer for O(1) lookup instead of walking the widget tree. Validates that the previous widget's window is still in the window stack before touching it, so stale pointers from closed windows are handled safely. If the previous selection was in a different window, that window gets a full repaint to clear the stale highlight.

    void clearOtherSelections(WidgetT *except);

      Parameter    Type         Description
      ---------    ----         -----------
      except       WidgetT *    The widget that now owns the selection. Its selection is preserved.

## isWordChar

Returns true if the character is alphanumeric or underscore. Used by word boundary functions to define what constitutes a "word" for double-click selection and Ctrl+arrow navigation.

    bool isWordChar(char c);

      Parameter    Type    Description
      ---------    ----    -----------
      c            char    The character to test.

Returns true if c is alphanumeric (a-z, A-Z, 0-9) or underscore.

## wordEnd

Scans forward from the given position, returning the index of the first non-word character. Used to find the right boundary of a word for double-click word selection.

    int32_t wordEnd(const char *buf, int32_t len, int32_t pos);

      Parameter    Type           Description
      ---------    ----           -----------
      buf          const char *   The text buffer to scan.
      len          int32_t        Length of the text in the buffer.
      pos          int32_t        Starting position (character index).

Returns the index one past the last word character.

## wordStart

Scans backward from the given position, returning the index of the first character of the current word. Used to find the left boundary of a word for double-click word selection.

    int32_t wordStart(const char *buf, int32_t pos);

      Parameter    Type           Description
      ---------    ----           -----------
      buf          const char *   The text buffer to scan.
      pos          int32_t        Starting position (character index).

Returns the index of the first character of the word containing pos.

## wordBoundaryLeft

Finds the left word boundary for Ctrl+Left navigation. Skips non-word characters first, then skips word characters, leaving the cursor at the start of the previous word.

    int32_t wordBoundaryLeft(const char *buf, int32_t pos);

      Parameter    Type           Description
      ---------    ----           -----------
      buf          const char *   The text buffer to scan.
      pos          int32_t        Starting position (character index).

Returns the index of the previous word boundary. Returns 0 if pos is already at or before the start of the buffer.

## wordBoundaryRight

Finds the right word boundary for Ctrl+Right navigation. Skips word characters first, then skips non-word characters, leaving the cursor at the start of the next word.

    int32_t wordBoundaryRight(const char *buf, int32_t len, int32_t pos);

      Parameter    Type           Description
      ---------    ----           -----------
      buf          const char *   The text buffer to scan.
      len          int32_t        Length of the text buffer.
      pos          int32_t        Starting position (character index).

Returns the index of the next word boundary. Returns len if pos is already at or past the end of the buffer.

## textEditSaveUndo

Capture a snapshot of the current buffer contents and cursor position into an undo buffer. Called by widgetTextEditOnKey before every destructive operation (insert, delete, paste, cut). Truncates to bufSize - 1 characters so the null terminator always fits.

    void textEditSaveUndo(char *buf, int32_t len,
        int32_t cursor, char *undoBuf,
        int32_t *pUndoLen, int32_t *pUndoCursor,
        int32_t bufSize);

      Parameter       Type         Description
      ---------       ----         -----------
      buf             char *       Source buffer to snapshot.
      len             int32_t      Current length of source contents.
      cursor          int32_t      Current cursor position to save.
      undoBuf         char *       Destination undo buffer. If NULL the call is a no-op.
      pUndoLen        int32_t *    [out] Length of saved undo contents.
      pUndoCursor     int32_t *    [out] Saved cursor position.
      bufSize         int32_t      Size of the destination undo buffer including the null terminator.

## widgetTextEditDragUpdateLine

Called during mouse drag to extend the selection in a single-line text field. Converts a viewport-relative pixel x coordinate to a character position and updates the cursor and selection end accordingly. Auto-scrolls the text when the mouse moves past the left or right visible edge.

    void widgetTextEditDragUpdateLine(
        int32_t vx, int32_t leftEdge, int32_t maxChars,
        const BitmapFontT *font, int32_t len,
        int32_t *pCursorPos, int32_t *pScrollOff,
        int32_t *pSelEnd);

      Parameter     Type                Description
      ---------     ----                -----------
      vx            int32_t             Mouse x position in viewport coordinates.
      leftEdge      int32_t             Pixel x of the left edge of the text area.
      maxChars      int32_t             Maximum visible characters in the field.
      font          const BitmapFontT * Bitmap font used for character width.
      len           int32_t             Total length of the text buffer.
      pCursorPos    int32_t *           [in/out] Current cursor position.
      pScrollOff    int32_t *           [in/out] Horizontal scroll offset in characters.
      pSelEnd       int32_t *           [out] Updated selection end position.

## widgetTextEditMouseClick

Handles mouse click events for single-line text widgets. Converts pixel coordinates to a character position using the font's character width. Detects multi-click sequences via the core multiClickDetect() function:

- Single click -- places the cursor and begins a potential drag selection.
- Double click -- selects the word under the cursor (if wordSelect is true), or selects all text.
- Triple click -- selects all text in the field.

    void widgetTextEditMouseClick(
        WidgetT *w, int32_t vx, int32_t vy,
        int32_t textLeftX, const BitmapFontT *font,
        const char *buf, int32_t len, int32_t scrollOff,
        int32_t *pCursorPos, int32_t *pSelStart,
        int32_t *pSelEnd, bool wordSelect,
        bool dragSelect);

      Parameter     Type                Description
      ---------     ----                -----------
      w             WidgetT *           The widget receiving the click.
      vx            int32_t             Mouse x in viewport coordinates.
      vy            int32_t             Mouse y in viewport coordinates.
      textLeftX     int32_t             Pixel x of the left edge of the text area.
      font          const BitmapFontT * Bitmap font for character width calculation.
      buf           const char *        Text buffer contents.
      len           int32_t             Length of text in the buffer.
      scrollOff     int32_t             Current horizontal scroll offset.
      pCursorPos    int32_t *           [out] Computed cursor position.
      pSelStart     int32_t *           [out] Selection start.
      pSelEnd       int32_t *           [out] Selection end.
      wordSelect    bool                If true, double-click selects word; if false, selects all.
      dragSelect    bool                If true, single-click begins drag selection.

## widgetTextEditOnKey

The core single-line text editing engine. Processes a single keystroke and updates the buffer, cursor, scroll offset, selection, and undo state. All state is passed by pointer so the function is reusable across TextInput, Spinner, ComboBox, and any other single-line widget.

    void widgetTextEditOnKey(
        WidgetT *w, int32_t key, int32_t mod,
        char *buf, int32_t bufSize,
        int32_t *pLen, int32_t *pCursor,
        int32_t *pScrollOff,
        int32_t *pSelStart, int32_t *pSelEnd,
        char *undoBuf, int32_t *pUndoLen,
        int32_t *pUndoCursor, int32_t fieldWidth);

      Parameter     Type         Description
      ---------     ----         -----------
      w             WidgetT *    The widget receiving the key event.
      key           int32_t      Key code (ASCII for printable, control code or scan|0x100 for extended).
      mod           int32_t      Modifier flags (KEY_MOD_SHIFT, etc.).
      buf           char *       [in/out] The text buffer.
      bufSize       int32_t      Total size of the buffer including null terminator.
      pLen          int32_t *    [in/out] Current text length.
      pCursor       int32_t *    [in/out] Cursor position (character index).
      pScrollOff    int32_t *    [in/out] Horizontal scroll offset.
      pSelStart     int32_t *    [in/out] Selection start (-1 if no selection).
      pSelEnd       int32_t *    [in/out] Selection end (-1 if no selection).
      undoBuf       char *       Undo buffer (same size as buf). NULL to disable undo.
      pUndoLen      int32_t *    [in/out] Length of undo buffer contents.
      pUndoCursor   int32_t *    [in/out] Cursor position saved in undo state.
      fieldWidth    int32_t      Visible field width in pixels. 0 = use widget width.

### Supported Keys

      Key              Action
      ---              ------
      Printable        Insert character at cursor (replaces selection if active).
      Backspace        Delete character before cursor or delete selection.
      Delete           Delete character after cursor or delete selection.
      Left             Move cursor left. With Shift, extend selection.
      Right            Move cursor right. With Shift, extend selection.
      Ctrl+Left        Move cursor to previous word boundary. With Shift, extend selection.
      Ctrl+Right       Move cursor to next word boundary. With Shift, extend selection.
      Home             Move cursor to start. With Shift, extend selection.
      End              Move cursor to end. With Shift, extend selection.
      Ctrl+A           Select all text.
      Ctrl+C           Copy selection to clipboard.
      Ctrl+V           Paste from clipboard (newlines stripped).
      Ctrl+X           Cut selection to clipboard.
      Ctrl+Z           Undo (swaps current and undo buffers).

Fires w->onChange after any mutation (insert, delete, paste, cut, undo). Automatically adjusts scroll offset to keep cursor visible after every operation.

## widgetTextEditPaintLine

Renders a single line of text with optional selection highlighting and a blinking cursor. Splits the visible text into up to three segments (pre-selection, selection, post-selection) and draws each with appropriate colors. The selection highlight uses the menu highlight colors from the color scheme. The cursor is drawn as a one-pixel vertical line when sCursorBlinkOn is true.

    void widgetTextEditPaintLine(
        DisplayT *d, const BlitOpsT *ops,
        const BitmapFontT *font,
        const ColorSchemeT *colors,
        int32_t textX, int32_t textY,
        const char *buf, int32_t visLen,
        int32_t scrollOff, int32_t cursorPos,
        int32_t selStart, int32_t selEnd,
        uint32_t fg, uint32_t bg,
        bool showCursor,
        int32_t cursorMinX, int32_t cursorMaxX);

      Parameter     Type                  Description
      ---------     ----                  -----------
      d             DisplayT *            Display context for drawing.
      ops           const BlitOpsT *      Blit operations table for the current pixel format.
      font          const BitmapFontT *   Bitmap font for text rendering.
      colors        const ColorSchemeT *  Color scheme (used for selection highlight colors).
      textX         int32_t               Pixel x of the start of visible text.
      textY         int32_t               Pixel y of the text baseline.
      buf           const char *          Visible portion of the text buffer (buf + scrollOff).
      visLen        int32_t               Number of visible characters to draw.
      scrollOff     int32_t               Scroll offset (used to map selection to visible range).
      cursorPos     int32_t               Absolute cursor position in the full buffer.
      selStart      int32_t               Selection start (-1 if no selection).
      selEnd        int32_t               Selection end (-1 if no selection).
      fg            uint32_t              Foreground (text) color.
      bg            uint32_t              Background color.
      showCursor    bool                  Whether to draw the cursor (false when widget lacks focus).
      cursorMinX    int32_t               Left clipping bound for cursor drawing.
      cursorMaxX    int32_t               Right clipping bound for cursor drawing.

# List Helper Library

Shared helper routines for dropdown and list-based widget DXEs (ListBox, Dropdown, ComboBox, ListView). Provides dropdown arrow rendering, item measurement, keyboard navigation, popup geometry calculation, popup list painting, type-ahead search, and popup scrollbar hit testing.

Header: listhelp/listHelp.h

Loaded as: bin/libs/listhelp.lib

## Constants

      Constant               Value               Description
      --------               -----               -----------
      DROPDOWN_BTN_WIDTH     16                  Width of the dropdown arrow button in pixels.
      DROPDOWN_MAX_VISIBLE   8                   Maximum number of items visible in a popup list before scrolling.
      POPUP_SCROLLBAR_W      SCROLLBAR_WIDTH     Popup vertical scrollbar width (mirrors the core window-manager scrollbar width).

## widgetDrawDropdownArrow

Draw the triangular dropdown arrow glyph centered at a given position.

    void widgetDrawDropdownArrow(DisplayT *d, const BlitOpsT *ops,
        int32_t centerX, int32_t centerY, uint32_t color);

      Parameter   Description
      ---------   -----------
      d           Display context.
      ops         Blit operations vtable for the active pixel depth.
      centerX     Horizontal center of the arrow in backbuffer coordinates.
      centerY     Vertical center of the arrow in backbuffer coordinates.
      color       Pre-packed pixel color for the arrow.

## widgetMaxItemLen

Scan an array of strings and return the length (in characters) of the longest item.

    int32_t widgetMaxItemLen(const char **items, int32_t count);

      Parameter   Description
      ---------   -----------
      items       Array of null-terminated string pointers.
      count       Number of items in the array.

Returns the character length of the longest item, or 0 if count is zero.

## widgetNavigateIndex

Compute a new selected index from a navigation key press. Handles Up, Down, Home, End, Page Up, and Page Down.

    int32_t widgetNavigateIndex(int32_t key, int32_t current,
        int32_t count, int32_t pageSize);

      Parameter   Description
      ---------   -----------
      key         Keyboard scancode (Up, Down, Home, End, PgUp, PgDn).
      current     Currently selected index.
      count       Total number of items in the list.
      pageSize    Number of visible items (used for PgUp/PgDn step size).

Returns the new index, clamped to [0, count-1]. Returns -1 for unrecognized keys so callers can detect whether the key was consumed.

## widgetDropdownPopupRect

Calculate the screen rectangle for a dropdown popup list, positioning it below the owning widget and clamping to screen bounds.

    void widgetDropdownPopupRect(WidgetT *w, const BitmapFontT *font,
        int32_t contentH, int32_t itemCount,
        int32_t *popX, int32_t *popY, int32_t *popW, int32_t *popH);

      Parameter   Description
      ---------   -----------
      w           The widget that owns the popup (Dropdown, ComboBox, etc.).
      font        Bitmap font used for item text (determines row height).
      contentH    Height of the widget's content area in pixels.
      itemCount   Total number of items in the list.
      popX        Output: popup X position (screen coordinates).
      popY        Output: popup Y position (screen coordinates).
      popW        Output: popup width in pixels.
      popH        Output: popup height in pixels.

The popup is sized to show up to DROPDOWN_MAX_VISIBLE items.

## widgetPaintPopupList

Render a popup item list with highlight, scrolling, and beveled border. When itemCount exceeds DROPDOWN_MAX_VISIBLE, draws a vertical scrollbar on the right edge sized according to scrollPos.

    void widgetPaintPopupList(DisplayT *d, const BlitOpsT *ops,
        const BitmapFontT *font, const ColorSchemeT *colors,
        int32_t popX, int32_t popY, int32_t popW, int32_t popH,
        const char **items, int32_t itemCount,
        int32_t hoverIdx, int32_t scrollPos);

      Parameter   Description
      ---------   -----------
      d           Display context.
      ops         Blit operations vtable.
      font        Bitmap font for rendering item text.
      colors      Color scheme for background, text, and highlight colors.
      popX        Popup X position (from widgetDropdownPopupRect).
      popY        Popup Y position.
      popW        Popup width.
      popH        Popup height.
      items       Array of null-terminated item strings.
      itemCount   Total number of items.
      hoverIdx    Index of the highlighted (hovered/selected) item, or -1 for none.
      scrollPos   Index of the first visible item (scroll offset).

## widgetTypeAheadSearch

Case-insensitive type-ahead search. Scans items forward from currentIdx + 1, wrapping around, for the next item whose first character matches ch. Used by list and dropdown widgets to jump to an item based on a single keystroke.

    int32_t widgetTypeAheadSearch(char ch, const char **items,
        int32_t itemCount, int32_t currentIdx);

      Parameter     Description
      ---------     -----------
      ch            Character to match (case-insensitive).
      items         Array of null-terminated item strings.
      itemCount     Number of items in the array.
      currentIdx    Currently selected index (search starts at currentIdx + 1 and wraps).

Returns the index of the next matching item, or -1 if no match is found or itemCount is not positive.

## widgetPopupScrollbarClick

Hit-test a popup scrollbar click. Tests whether the (x, y) coordinate falls on the popup's vertical scrollbar track; if so, updates scrollPos for up/down arrow clicks or page-up/page-down clicks in the trough. No-op on the thumb itself (callers handle drag separately).

    bool widgetPopupScrollbarClick(int32_t x, int32_t y,
        int32_t popX, int32_t popY, int32_t popW, int32_t popH,
        int32_t itemCount, int32_t visibleItems,
        int32_t *scrollPos);

      Parameter       Description
      ---------       -----------
      x               Click X in the popup's coordinate space.
      y               Click Y in the popup's coordinate space.
      popX            Popup X origin.
      popY            Popup Y origin.
      popW            Popup width.
      popH            Popup height.
      itemCount       Total number of items.
      visibleItems    Number of visible rows in the popup.
      scrollPos       [in/out] Current scroll offset; updated in place when the click hits the scrollbar.

Returns true if the click landed on the scrollbar (even if scrollPos was not changed, for example clicking the thumb), false if the click was in the item list area. When itemCount is less than or equal to DROPDOWN_MAX_VISIBLE, always returns false (there is no scrollbar).

# Task Manager

System-level task manager for DVX. Displays all running applications with a six-column ListView (Name, Title, File, Type, Memory, Status) and exposes Switch To, End Task, and Run... operations. Always accessible via Ctrl+Esc regardless of which application is focused. Persists independently of the desktop app (Program Manager).

Header: taskmgr/shellTaskMgr.h

Loaded as: bin/libs/taskmgr.lib

## Integration

The task manager is a shell-level library, not a regular DXE app. At DXE load time a GCC constructor function registers the Task Manager with the shell by setting the shellCtrlEscFn function pointer (declared extern in dvxshell/shellApp.h). The shell invokes shellCtrlEscFn on every Ctrl+Esc keystroke; if taskmgr.lib is not loaded the pointer stays NULL and Ctrl+Esc does nothing.

The Task Manager owns its window on behalf of the shell itself (appId = 0), not any running app, which is why it survives when the desktop app terminates. It registers shellTaskMgrRefresh with shellRegisterDesktopUpdate so the list refreshes live as apps load, reap, or crash.

## Integration with libtasks

The Task Manager reads from the shell's app slot table (shellGetApp, shellAppSlotCount, shellRunningAppCount) rather than from the libtasks scheduler directly. Each ShellAppT slot carries its cooperative task ID when hasMainLoop is true; End Task calls shellForceKillApp, which in turn calls tsKill on that task ID (for main-loop apps) after destroying the app's windows.

## Features

- Six-column ListView showing Name, Title, File, Type (Task or Callback), Memory (from dvxMemGetAppUsage), and Status for every running app.
- Switch To button (Alt+S): raises and focuses the selected app's topmost window, restoring it if minimized. Also triggered by double-clicking a row.
- End Task button (Alt+E): force-kills the selected app via shellForceKillApp.
- Run... button (Alt+R): opens a file dialog to browse for and launch a .app file.
- Status bar showing running app count plus total and used system memory.
- Single-instance: reopening the Task Manager while it is already visible raises and focuses the existing window rather than creating a new one.

## shellTaskMgrOpen

Open the Task Manager window, or raise it to the front if already open.

    void shellTaskMgrOpen(AppContextT *ctx);

      Parameter   Description
      ---------   -----------
      ctx         Application context (from dvxInit). Required for window creation, stack manipulation, and registering the desktop-update callback.

Called by the shell's global Ctrl+Esc handler via the shellCtrlEscFn hook.

## shellTaskMgrRefresh

Rebuild the task list display from the current shell app slot table and refresh the status bar. Registered with shellRegisterDesktopUpdate at open time so it is invoked whenever the shell detects app state changes.

    void shellTaskMgrRefresh(void);

Takes no parameters. Safe to call even if the Task Manager window is not currently open (the call is a no-op in that case).

# Serial Stack

The DVX serial/networking stack provides reliable, optionally encrypted communication over RS-232 serial ports. It is composed of four layers, each building on the one below:

- rs232 -- ISR-driven UART driver with ring buffers and flow control
- packet -- HDLC framing, CRC-16, Go-Back-N ARQ (reliable delivery)
- security -- 1024-bit Diffie-Hellman key exchange, XTEA-CTR cipher, DRBG RNG
- secLink -- Convenience wrapper: channel multiplexing, per-packet encryption

Loaded as: bin/libs/kpunch/serial/serial.lib

## Layered Architecture

    +--------------------------------------------------+
    |  Application                                     |
    |                                                  |
    |  secLinkSend()  -- send on channel, opt. encrypt |
    |  secLinkPoll()  -- receive + dispatch            |
    +--------------------------------------------------+
    |  secLink  (channel multiplex, TX/RX ciphers)     |
    +--------------------------------------------------+
    |  packet   (HDLC framing, CRC-16, Go-Back-N ARQ)  |
    +--------------------------------------------------+
    |  security -- DH key exchange, XTEA-CTR, DRBG     |
    |            (used by secLink during handshake)    |
    +--------------------------------------------------+
    |  rs232    (ISR-driven UART, 2048-byte rings)     |
    +--------------------------------------------------+
    |  UART hardware (8250 / 16450 / 16550 / 16550A)   |
    +--------------------------------------------------+

The security layer is invoked by secLink during the Diffie-Hellman handshake and for per-packet cipher operations. It has no runtime coupling to rs232 or packet, so it can be used standalone for cryptographic operations independent of the serial stack.

Layer 1: RS-232 UART Driver

Layer 2: Packet Transport

Layer 3: Security (DH + XTEA)

Layer 4: Secure Link

End-to-End Example

# RS-232 UART Driver

ISR-driven serial port driver supporting up to 4 simultaneous COM ports. A shared ISR drains UART FIFOs into per-port ring buffers (2048 bytes, power-of-2 for fast index wrapping). Flow control (XON/XOFF, RTS/CTS, DTR/DSR) operates within the ISR using watermark thresholds. All ISR data structures are DPMI-locked to prevent page faults.

Header: rs232/rs232.h

## Port Constants

      Constant          Value   Description
      --------          -----   -----------
      RS232_COM1        0       First serial port.
      RS232_COM2        1       Second serial port.
      RS232_COM3        2       Third serial port.
      RS232_COM4        3       Fourth serial port.
      RS232_NUM_PORTS   4       Total number of supported COM ports.

## Handshake Modes

      Constant                  Value   Description
      --------                  -----   -----------
      RS232_HANDSHAKE_NONE      0       No flow control.
      RS232_HANDSHAKE_XONXOFF   1       Software flow control (XON/XOFF characters).
      RS232_HANDSHAKE_RTSCTS    2       Hardware flow control via RTS/CTS lines.
      RS232_HANDSHAKE_DTRDSR    3       Hardware flow control via DTR/DSR lines.

## UART Types

Detected automatically by probing the scratch register and FIFO capability.

      Constant            Value   Description
      --------            -----   -----------
      RS232_UART_UNKNOWN  0       Detection failed.
      RS232_UART_8250     1       Original IBM PC UART. No FIFO.
      RS232_UART_16450    2       Has scratch register, no FIFO.
      RS232_UART_16550    3       Has FIFO but buggy (rare).
      RS232_UART_16550A   4       Working 16-byte FIFO. Most common in 486+ hardware.

## Error Codes

      Constant                     Value   Description
      --------                     -----   -----------
      RS232_SUCCESS                0       Operation succeeded.
      RS232_ERR_UNKNOWN            -1      Unknown error.
      RS232_ERR_NOT_OPEN           -2      Port is not open.
      RS232_ERR_ALREADY_OPEN       -3      Port is already open.
      RS232_ERR_NO_UART            -4      No UART detected at port address.
      RS232_ERR_INVALID_PORT       -5      Invalid port number.
      RS232_ERR_INVALID_BASE       -6      Invalid base I/O address.
      RS232_ERR_INVALID_IRQ        -7      Invalid IRQ number.
      RS232_ERR_INVALID_BPS        -8      Invalid baud rate.
      RS232_ERR_INVALID_DATA       -9      Invalid data bits value.
      RS232_ERR_INVALID_PARITY     -10     Invalid parity character.
      RS232_ERR_INVALID_STOP       -11     Invalid stop bits value.
      RS232_ERR_INVALID_HANDSHAKE  -12     Invalid handshake mode.
      RS232_ERR_INVALID_FIFO       -13     Invalid FIFO threshold.
      RS232_ERR_NULL_PTR           -14     NULL pointer argument.
      RS232_ERR_IRQ_NOT_FOUND      -15     Could not detect IRQ for port.
      RS232_ERR_LOCK_MEM           -16     DPMI memory lock failed.

## rs232Open

Open a COM port with the specified line parameters.

    int rs232Open(int com, int32_t bps, int dataBits,
        char parity, int stopBits, int handshake);

      Parameter   Description
      ---------   -----------
      com         Port index (RS232_COM1..RS232_COM4).
      bps         Baud rate (e.g. 9600, 19200, 38400, 57600, 115200).
      dataBits    Data bits per character (5, 6, 7, or 8).
      parity      Parity mode: 'N' (none), 'O' (odd), 'E' (even), 'M' (mark), 'S' (space).
      stopBits    Stop bits (1 or 2).
      handshake   Flow control mode (RS232_HANDSHAKE_*).

Returns RS232_SUCCESS or a negative error code.

## rs232Close

Close a COM port and release its ISR resources.

    int rs232Close(int com);

## rs232Read

Non-blocking read from the receive ring buffer.

    int rs232Read(int com, char *data, int len);

      Parameter   Description
      ---------   -----------
      com         Port index.
      data        Buffer to receive data.
      len         Maximum bytes to read.

Returns the number of bytes actually read (may be less than len).

## rs232Write

Blocking polled write directly to UART transmit holding register. Bypasses the TX ring buffer. Polls LSR_TX_HOLD_EMPTY before writing each byte. Use for small, immediate writes where order matters (the packet layer uses this for frame transmission).

    int rs232Write(int com, const char *data, int len);

Returns the number of bytes actually written (may be less than len if software flow control is asserted), or a negative error code (RS232_ERR_INVALID_PORT, RS232_ERR_NOT_OPEN, RS232_ERR_NULL_PTR).

## rs232WriteBuf

Non-blocking write to the transmit ring buffer. The ISR drains buffered data to the UART asynchronously.

    int rs232WriteBuf(int com, const char *data, int len);

Returns the number of bytes actually queued (may be less than len if the buffer is full).

## rs232Set

Change all line parameters on an open port. Internally calls rs232SetBps, rs232SetData, rs232SetParity, rs232SetStop, and rs232SetHandshake in sequence. Returns RS232_SUCCESS on success or the first negative error code encountered.

    int rs232Set(int com, int32_t bps, int dataBits,
        char parity, int stopBits, int handshake);

## Configuration Getters

      Function                   Returns
      --------                   -------
      rs232GetBase(com)          I/O base address.
      rs232GetBps(com)           Current baud rate (int32_t).
      rs232GetData(com)          Data bits setting (5-8).
      rs232GetParity(com)        Parity character: 'n', 'o', 'e', 'm', or 's' (lowercase).
      rs232GetStop(com)          Stop bits setting (1 or 2).
      rs232GetHandshake(com)     Handshake mode (RS232_HANDSHAKE_*).
      rs232GetIrq(com)           IRQ number.
      rs232GetUartType(com)      Detected UART type (RS232_UART_*).

rs232GetParity returns a lowercase character on success. Callers comparing against uppercase constants must use either both cases or tolower().

## Status Getters

      Function                   Returns
      --------                   -------
      rs232GetRxBuffered(com)    Bytes waiting in the receive ring buffer.
      rs232GetTxBuffered(com)    Bytes waiting in the transmit ring buffer.
      rs232GetCts(com)           CTS line state (0 or 1).
      rs232GetDsr(com)           DSR line state (0 or 1).
      rs232GetDtr(com)           DTR line state (0 or 1).
      rs232GetRts(com)           RTS line state (0 or 1).
      rs232GetLsr(com)           Line status register value.
      rs232GetMcr(com)           Modem control register value.
      rs232GetMsr(com)           Modem status register value.

## Configuration Setters

      Function                          Description
      --------                          -----------
      rs232SetBase(com, base)           Set I/O base address (before open).
      rs232SetBps(com, bps)             Change baud rate.
      rs232SetData(com, dataBits)       Change data bits.
      rs232SetParity(com, parity)       Change parity mode.
      rs232SetStop(com, stopBits)       Change stop bits.
      rs232SetHandshake(com, handshake) Change flow control mode.
      rs232SetIrq(com, irq)             Set IRQ number (before open).
      rs232SetMcr(com, mcr)             Set modem control register directly.
      rs232SetDtr(com, dtr)             Set DTR line state.
      rs232SetRts(com, rts)             Set RTS line state.
      rs232SetFifoThreshold(com, thr)   Set FIFO trigger level (1, 4, 8, or 14 bytes).

## Buffer Management

      Function                   Description
      --------                   -----------
      rs232ClearRxBuffer(com)    Discard all data in the receive ring buffer.
      rs232ClearTxBuffer(com)    Discard all data in the transmit ring buffer.

# Packet Transport

Reliable, ordered packet delivery over an RS-232 serial link. Uses HDLC-style byte-stuffed framing for frame delimiting, CRC-16-CCITT for error detection, and Go-Back-N ARQ with a configurable sliding window for retransmission.

Header: packet/packet.h

## Constants

      Constant            Value   Description
      --------            -----   -----------
      PKT_MAX_PAYLOAD     255     Maximum bytes per packet payload.
      PKT_DEFAULT_WINDOW  4       Default sliding window size (unacknowledged frames in flight).
      PKT_MAX_WINDOW      8       Maximum sliding window size.

## Error Codes

      Constant                Value   Description
      --------                -----   -----------
      PKT_SUCCESS             0       Operation succeeded.
      PKT_ERR_INVALID_PARAM   -6      Invalid parameter (NULL handle, bad data pointer, length out of range).
      PKT_ERR_TX_FULL         -7      Transmit window is full (non-blocking send only).
      PKT_ERR_DISCONNECTED    -9      Serial port returned a negative read (disconnect/error).

## PktRecvCallbackT

Callback type for received packets.

    typedef void (*PktRecvCallbackT)(void *ctx,
        const uint8_t *data, int len);

      Parameter   Description
      ---------   -----------
      ctx         User context pointer (passed to pktOpen).
      data        Payload bytes (valid only during the callback).
      len         Payload length.

## pktOpen

Open a packetized connection over an already-open COM port. Only one packet connection may exist on a given COM port at a time; a second pktOpen call on the same port returns NULL to avoid silent framing corruption.

    PktConnT *pktOpen(int com, int windowSize,
        PktRecvCallbackT callback, void *callbackCtx);

      Parameter     Description
      ---------     -----------
      com           COM port index (RS232_COM1..RS232_COM4). Must already be open via rs232Open.
      windowSize    Sliding window size (1..PKT_MAX_WINDOW). Pass 0 for PKT_DEFAULT_WINDOW. Values greater than PKT_MAX_WINDOW are clamped.
      callback      Called when a complete, CRC-verified, in-order packet is received. The data pointer is valid only during the callback.
      callbackCtx   User pointer passed to the callback.

Returns an opaque PktConnT handle, or NULL on failure (invalid port, duplicate open, or allocation failure).

## pktClose

Close a packetized connection and release its registry slot. Does not close the underlying COM port. The caller is responsible for calling rs232Close separately when no longer needed.

    void pktClose(PktConnT *conn);

## pktSend

Send a data packet. The payload is copied into an internal retransmit slot before transmission, so the caller may reuse the supplied buffer immediately.

    int pktSend(PktConnT *conn, const uint8_t *data,
        int len, bool block);

      Parameter   Description
      ---------   -----------
      conn        Connection handle from pktOpen.
      data        Payload bytes (1..PKT_MAX_PAYLOAD).
      len         Payload length.
      block       If true, poll pktPoll internally until transmit window has space. If false, return PKT_ERR_TX_FULL immediately when the window is full.

Returns PKT_SUCCESS on success, PKT_ERR_INVALID_PARAM for NULL/out-of-range input, PKT_ERR_TX_FULL for a non-blocking call with a full window, or PKT_ERR_DISCONNECTED if the serial port drops during a blocking wait.

## pktPoll

Poll for incoming data, process received frames, and handle retransmits. Must be called frequently in the main loop. The callback is invoked synchronously for each complete, CRC-verified, in-order data frame, so the caller should be prepared for reentrant pktSend calls from within the callback.

    int pktPoll(PktConnT *conn);

Returns the number of valid data packets delivered to the callback this call, or PKT_ERR_INVALID_PARAM if conn is NULL, or PKT_ERR_DISCONNECTED if the serial layer returned a negative read.

## pktReset

Reset the local connection state (sequence numbers, transmit slots, RX state machine) and send a RST frame to the remote side. The remote's RST handler clears its own state and echoes a RST back. Useful for recovering from a desynchronized connection.

    int pktReset(PktConnT *conn);

Returns PKT_SUCCESS on success or PKT_ERR_INVALID_PARAM if conn is NULL.

## pktCanSend

Check whether there is room in the transmit window for another packet. Returns false when conn is NULL or the transmit window is full.

    bool pktCanSend(PktConnT *conn);

## pktGetPending

Get the number of unacknowledged packets currently in the transmit window. Ranges from 0 (all sent packets acknowledged) to windowSize (window full).

    int pktGetPending(PktConnT *conn);

Returns the pending count on success, or PKT_ERR_INVALID_PARAM if conn is NULL.

# Security (DH + XTEA)

Cryptographic primitives for the serial stack: 1024-bit Diffie-Hellman key exchange (RFC 2409 Group 2), XTEA block cipher in CTR mode, and an XTEA-CTR DRBG random number generator.

XTEA requires no lookup tables and compiles to approximately 20 instructions per round, making it suitable for 486-class hardware where AES S-box tables would thrash the 8KB cache.

Header: security/security.h

## Constants

      Constant           Value   Description
      --------           -----   -----------
      SEC_DH_KEY_SIZE    128     Size of a DH public key in bytes (1024 bits).
      SEC_XTEA_KEY_SIZE  16      Size of an XTEA key in bytes (128 bits).

## Error Codes

      Constant           Value   Description
      --------           -----   -----------
      SEC_SUCCESS        0       Operation succeeded.
      SEC_ERR_PARAM      -1      Invalid parameter.
      SEC_ERR_NOT_READY  -2      DH context not ready (keys not generated or secret not computed).

## RNG Functions

The RNG uses XTEA-CTR as a DRBG. Hardware entropy from PIT timer jitter is weak (~20 bits); supplement with keyboard timing or mouse jitter before generating DH keys.

    void secRngSeed(const uint8_t *entropy, int len);
    int  secRngGatherEntropy(uint8_t *buf, int len);
    void secRngAddEntropy(const uint8_t *data, int len);
    void secRngBytes(uint8_t *buf, int len);

      Function              Description
      --------              -----------
      secRngSeed            Seed the DRBG from an entropy buffer.
      secRngGatherEntropy   Gather hardware entropy (PIT jitter, BIOS tick count) into a buffer.
      secRngAddEntropy      Mix additional entropy into the DRBG state.
      secRngBytes           Generate pseudorandom bytes.

## Diffie-Hellman Key Exchange

1024-bit DH with 256-bit private exponents using the RFC 2409 Group 2 safe prime.

    SecDhT *secDhCreate(void);
    int     secDhGenerateKeys(SecDhT *dh);
    int     secDhGetPublicKey(SecDhT *dh, uint8_t *buf, int *len);
    int     secDhComputeSecret(SecDhT *dh,
                const uint8_t *remotePub, int len);
    int     secDhDeriveKey(SecDhT *dh, uint8_t *key, int keyLen);
    void    secDhDestroy(SecDhT *dh);

      Function            Description
      --------            -----------
      secDhCreate         Allocate a new DH context.
      secDhGenerateKeys   Generate a private exponent and public key. RNG must be seeded first.
      secDhGetPublicKey   Copy the local public key into buf. *len receives the key size.
      secDhComputeSecret  Compute the shared secret from the remote public key.
      secDhDeriveKey      Derive a symmetric key (XTEA key) from the shared secret via hashing.
      secDhDestroy        Free the DH context and all associated memory.

Typical usage order: secDhCreate, secDhGenerateKeys, exchange public keys, secDhComputeSecret, secDhDeriveKey, secDhDestroy.

## XTEA-CTR Cipher

XTEA in counter mode. Encrypt and decrypt are the same operation (XOR with keystream). The counter must never repeat with the same key.

    SecCipherT *secCipherCreate(const uint8_t *key);
    void        secCipherCrypt(SecCipherT *c,
                    uint8_t *data, int len);
    void        secCipherDestroy(SecCipherT *c);

      Function             Description
      --------             -----------
      secCipherCreate      Allocate a cipher context with a 128-bit key. Returns NULL on allocation failure or NULL key. Initial counter is zero.
      secCipherCrypt       Encrypt or decrypt data in place. The counter increments by one every 8 bytes (one XTEA block).
      secCipherDestroy    Securely zero the cipher context (key and counter state) and free its memory.

secCipherCreate returns NULL if the key pointer is NULL or allocation fails. secCipherCrypt is a no-op when any of c/data is NULL or len <= 0.

# Secure Link

Top-level API composing all three lower layers (rs232, packet, security) into a single interface. Provides channel multiplexing (0-127) and per-packet encryption control over a reliable serial link.

Each packet carries a one-byte header: bit 7 is the encrypted flag, bits 6..0 are the channel number. Unencrypted packets can be sent before the handshake completes (e.g., for version negotiation).

Header: seclink/secLink.h

## Constants

      Constant                  Value   Description
      --------                  -----   -----------
      SECLINK_MAX_PAYLOAD       254     Maximum plaintext bytes per send (PKT_MAX_PAYLOAD minus 1-byte channel header).
      SECLINK_MAX_CHANNEL       127     Highest valid channel number.
      SECLINK_NUM_CHANNELS      128     Array size needed to hold one slot per channel (SECLINK_MAX_CHANNEL + 1).
      SECLINK_CHAN_BUF_SIZE     4096    Recommended per-channel receive buffer size for callers that buffer inbound data between the receive callback and an application read.

## Error Codes

      Constant                 Value   Description
      --------                 -----   -----------
      SECLINK_SUCCESS          0       Operation succeeded.
      SECLINK_ERR_PARAM        -1      Invalid parameter (NULL pointer, bad channel, bad length).
      SECLINK_ERR_SERIAL       -2      RS-232 layer error.
      SECLINK_ERR_ALLOC        -3      Memory allocation failed.
      SECLINK_ERR_HANDSHAKE    -4      DH handshake failed (key generation, send, or disconnect during exchange).
      SECLINK_ERR_NOT_READY    -5      Handshake not yet completed (encrypted send attempted).
      SECLINK_ERR_SEND         -6      Packet send failed, or non-blocking send when window is full.

## SecLinkRecvT

Receive callback type. Delivers decrypted plaintext with the channel number.

    typedef void (*SecLinkRecvT)(void *ctx,
        const uint8_t *data, int len, uint8_t channel);

## secLinkOpen

Open a secure serial link. Opens the COM port via rs232Open and creates a packet layer (default window size) with an internal receive dispatcher. The handshake must be performed separately via secLinkHandshake before encrypted data can be sent.

    SecLinkT *secLinkOpen(int com, int32_t bps, int dataBits,
        char parity, int stopBits, int handshake,
        SecLinkRecvT callback, void *ctx);

      Parameter   Description
      ---------   -----------
      com         COM port index (RS232_COM1..RS232_COM4).
      bps         Baud rate.
      dataBits    Data bits per character (5-8).
      parity      Parity mode ('N', 'O', 'E', 'M', 'S' or lowercase).
      stopBits    Stop bits (1 or 2).
      handshake   Flow control mode (RS232_HANDSHAKE_*).
      callback    Called when a packet is received, after decryption if applicable. Plaintext data pointer is valid only during the callback.
      ctx         User pointer passed to the callback.

Returns an opaque SecLinkT handle, or NULL on failure (allocation failure, rs232Open error, or pktOpen error). On failure all partially initialized resources are cleaned up.

## secLinkClose

Close the link and free all associated resources in reverse of open order: securely destroy TX and RX ciphers (which scrubs key material), destroy any remaining DH context, close the packet layer, close the COM port, and finally free the link struct itself. Safe to call with a NULL link (no-op).

    void secLinkClose(SecLinkT *link);

## secLinkHandshake

Perform a Diffie-Hellman key exchange and derive the session cipher keys. Blocks, polling the packet layer in a loop, until both sides have swapped public keys. The RNG must be seeded (via secRngSeed, secRngGatherEntropy + secRngSeed, or secRngAddEntropy) before calling this, or the generated private key will be predictable.

    int secLinkHandshake(SecLinkT *link);

Internally:

- Creates a DH context via secDhCreate, generates 1024-bit keys via secDhGenerateKeys, and exports the 128-byte public key.
- Sends the public key as a single packet via pktSend (blocking).
- Polls pktPoll until the remote's public key arrives and the internal callback completes the handshake (computes the shared secret, derives directional TX and RX cipher keys, transitions to READY, destroys the DH context for forward secrecy).

Returns SECLINK_SUCCESS on success, SECLINK_ERR_PARAM on NULL link, SECLINK_ERR_ALLOC on DH context allocation failure, or SECLINK_ERR_HANDSHAKE for DH key generation failure, packet send failure, or serial disconnect during the exchange.

### Directional Key Derivation

To prevent CTR-mode keystream collision, the two sides never use the same TX key. After computing the shared secret, each side derives a master XTEA key via secDhDeriveKey and then XORs it with a direction byte:

- The side with the lexicographically lower public key uses masterKey XOR 0xAA for TX and masterKey XOR 0x55 for RX.
- The other side uses the reverse assignment.

Both sides initialize their cipher counters to zero and advance monotonically from there.

## secLinkSend

Send data on a channel, optionally encrypted. Prepends a one-byte channel header (bit 7 = encrypt flag, bits 6..0 = channel number), then encrypts the payload only (never the header) when encrypt is true.

    int secLinkSend(SecLinkT *link, const uint8_t *data,
        int len, uint8_t channel, bool encrypt, bool block);

      Parameter   Description
      ---------   -----------
      link        Connection handle from secLinkOpen.
      data        Plaintext payload (1..SECLINK_MAX_PAYLOAD bytes).
      len         Payload length. Must be in 1..SECLINK_MAX_PAYLOAD.
      channel     Logical channel number (0..SECLINK_MAX_CHANNEL).
      encrypt     If true, encrypt before sending (requires completed handshake).
      block       If true, block until the transmit window has space. If false, return SECLINK_ERR_SEND immediately when the window is full.

Returns SECLINK_SUCCESS on success or a negative error code (SECLINK_ERR_PARAM, SECLINK_ERR_NOT_READY, SECLINK_ERR_SEND).

Cipher counter safety: the function checks transmit window space BEFORE encrypting the payload. Encrypting first and then failing to send would advance the TX cipher counter while the data never reached the wire, permanently desynchronizing the TX cipher state from the remote's RX cipher. This ordering is critical for correctness when non-blocking sends are used.

## secLinkSendBuf

Send an arbitrarily large buffer by splitting into SECLINK_MAX_PAYLOAD chunks. Always blocks until all data is sent.

    int secLinkSendBuf(SecLinkT *link, const uint8_t *data,
        int len, uint8_t channel, bool encrypt);

Returns SECLINK_SUCCESS or the first error encountered.

## secLinkPoll

Poll for incoming data. Delegates to pktPoll, which drains the RS-232 ring buffer, processes received frames, checks retransmit timers, and dispatches each complete packet to an internal callback that strips the channel header, decrypts when the encrypt flag is set, and forwards plaintext to the user callback.

    int secLinkPoll(SecLinkT *link);

Returns the number of packets delivered to the callback this call, SECLINK_ERR_PARAM if link is NULL, or one of the pktPoll error codes (PKT_ERR_DISCONNECTED, PKT_ERR_INVALID_PARAM). Must be called frequently in the main loop.

## secLinkIsReady

Check whether the handshake is complete and the link is ready for encrypted traffic. Cleartext sends do not require the link to be ready.

    bool secLinkIsReady(SecLinkT *link);

Returns true only when link is non-NULL and the internal state is STATE_READY (that is, secLinkHandshake has completed). Returns false on NULL or before the handshake.

## secLinkGetPending

Get the number of unacknowledged packets in the transmit window. Delegates directly to pktGetPending on the underlying packet connection. Useful for non-blocking send loops to decide when to throttle.

    int secLinkGetPending(SecLinkT *link);

Returns the pending count on success or SECLINK_ERR_PARAM when link is NULL.

# End-to-End Example

Below is a complete secure BBS client that opens COM1, exchanges DH keys, and then shuttles terminal traffic over a single encrypted channel. It demonstrates the typical serial stack usage: open the link, seed the RNG, run the handshake, then enter a poll+send loop.

    #include "rs232/rs232.h"
    #include "packet/packet.h"
    #include "security/security.h"
    #include "seclink/secLink.h"
    #include <stdio.h>
    #include <string.h>

    #define CHAN_TERMINAL 0

    static void onPacket(void *ctx, const uint8_t *data,
                         int len, uint8_t channel)
    {
        (void)ctx;
        if (channel == CHAN_TERMINAL) {
            fwrite(data, 1, len, stdout);
            fflush(stdout);
        }
    }

    int main(void) {
        // Seed the RNG from hardware entropy plus any user-derived
        // randomness (keyboard timing, etc.).
        uint8_t entropy[16];
        int got = secRngGatherEntropy(entropy, sizeof(entropy));
        secRngSeed(entropy, got);

        // Open the link at 115200 8N1 with RTS/CTS flow control.
        SecLinkT *link = secLinkOpen(
            RS232_COM1, 115200, 8, 'N', 1,
            RS232_HANDSHAKE_RTSCTS,
            onPacket, NULL);
        if (!link) {
            fprintf(stderr, "secLinkOpen failed\n");
            return 1;
        }

        // Run the DH key exchange.  Blocks until both sides
        // have swapped public keys and derived cipher keys.
        if (secLinkHandshake(link) != SECLINK_SUCCESS) {
            fprintf(stderr, "Handshake failed\n");
            secLinkClose(link);
            return 1;
        }

        // Send an encrypted banner and then relay keyboard input.
        const char *hello = "Hello, secure BBS!\r\n";
        secLinkSend(link, (const uint8_t *)hello,
                    (int)strlen(hello), CHAN_TERMINAL, true, true);

        while (!feof(stdin)) {
            // Deliver any incoming packets to onPacket().
            secLinkPoll(link);

            // If the user typed something, forward it encrypted.
            int ch = getchar();
            if (ch == EOF) {
                break;
            }
            uint8_t byte = (uint8_t)ch;
            secLinkSend(link, &byte, 1, CHAN_TERMINAL, true, true);
        }

        secLinkClose(link);
        return 0;
    }

Notes:

- secLinkOpen internally calls rs232Open and pktOpen. secLinkClose tears them down in reverse order.
- The RNG must be seeded before secLinkHandshake. secRngGatherEntropy provides roughly 20 bits of hardware entropy; supplement with user interaction timing for cryptographic use.
- secLinkPoll must be called frequently to drain the RX ring buffer, process ACKs, and dispatch received packets to the callback.
- For bulk transfers larger than SECLINK_MAX_PAYLOAD (254 bytes), use secLinkSendBuf which splits the data into chunks automatically.

# BASIC Runtime Library

Stack-based p-code virtual machine and value system for DVX BASIC. Embeddable: the host provides I/O and UI callbacks. No DVX GUI dependencies in the core runtime.

Headers: apps/dvxbasic/runtime/vm.h, apps/dvxbasic/runtime/values.h

Value System (values.h)

Virtual Machine (vm.h)

# Value System

Tagged union value type for the VM evaluation stack, variables, and array elements. Strings, arrays, and UDT instances are reference-counted for automatic memory management without a garbage collector.

Header: apps/dvxbasic/runtime/values.h

## Type Tags

      Constant         Value   C Union Field   Description
      --------         -----   -------------   -----------
      BAS_TYPE_INTEGER 0       intVal          16-bit signed integer.
      BAS_TYPE_LONG    1       longVal         32-bit signed integer.
      BAS_TYPE_SINGLE  2       sngVal          32-bit float.
      BAS_TYPE_DOUBLE  3       dblVal          64-bit float.
      BAS_TYPE_STRING  4       strVal          Reference-counted dynamic string.
      BAS_TYPE_BOOLEAN 5       boolVal         True (-1) or False (0).
      BAS_TYPE_ARRAY   6       arrVal          Reference-counted array.
      BAS_TYPE_UDT     7       udtVal          Reference-counted user-defined type.
      BAS_TYPE_OBJECT  8       objVal          Opaque host pointer (form, control).
      BAS_TYPE_REF     9       refVal          ByRef pointer to a BasValueT slot.

## BasValueT

Tagged union holding any BASIC value.

    struct BasValueTag {
        uint8_t type;   // BAS_TYPE_*
        union {
            int16_t     intVal;
            int32_t     longVal;
            float       sngVal;
            double      dblVal;
            BasStringT *strVal;
            int16_t     boolVal;
            BasArrayT  *arrVal;
            BasUdtT    *udtVal;
            void       *objVal;
            BasValueT  *refVal;
        };
    };

## Value Constructors

    BasValueT basValInteger(int16_t v);
    BasValueT basValLong(int32_t v);
    BasValueT basValSingle(float v);
    BasValueT basValDouble(double v);
    BasValueT basValString(BasStringT *s);
    BasValueT basValStringFromC(const char *text);
    BasValueT basValBool(bool v);
    BasValueT basValObject(void *obj);

Each returns a BasValueT with the appropriate type tag set. basValString increments the string's reference count.

## Value Lifetime

    BasValueT basValCopy(BasValueT v);
    void      basValRelease(BasValueT *v);

      Function       Description
      --------       -----------
      basValCopy     Copy a value. Increments reference count for strings, arrays, and UDTs.
      basValRelease  Release a value. Decrements reference count and frees if it reaches zero.

## Type Conversion

    BasValueT basValToInteger(BasValueT v);
    BasValueT basValToLong(BasValueT v);
    BasValueT basValToSingle(BasValueT v);
    BasValueT basValToDouble(BasValueT v);
    BasValueT basValToString(BasValueT v);
    BasValueT basValToBool(BasValueT v);

Each returns a new value of the target type. The original is not released; the caller manages both lifetimes.

## Value Utilities

      Function                          Description
      --------                          -----------
      basValToNumber(v)                 Convert any numeric value to double.
      basValFormatString(v)             Return a new ref-counted string representation of v.
      basValIsTruthy(v)                 True if non-zero number or non-empty string.
      basValCompare(a, b)               Compare two values. Returns -1, 0, or 1.
      basValCompareCI(a, b)             Case-insensitive comparison (OPTION COMPARE TEXT).
      basValPromoteType(a, b)           Determine common type for binary ops (e.g. Integer + Single -> Single).

## BasStringT

Reference-counted string with flexible array member for inline storage.

    typedef struct {
        int32_t refCount;
        int32_t len;
        int32_t cap;
        char    data[];
    } BasStringT;

### String Functions

      Function                            Description
      --------                            -----------
      basStringNew(text, len)             Allocate from a C string. refCount starts at 1.
      basStringAlloc(cap)                 Allocate an empty string with given capacity.
      basStringRef(s)                     Increment reference count. Returns s.
      basStringUnref(s)                   Decrement reference count. Frees when it reaches zero.
      basStringConcat(a, b)               Concatenate two strings. Returns a new string (refCount 1).
      basStringSub(s, start, len)         Extract a substring. Returns a new string (refCount 1).
      basStringCompare(a, b)              Compare. Returns <0, 0, >0 (like strcmp).
      basStringCompareCI(a, b)            Case-insensitive compare.

The global basEmptyString is a singleton that is never freed.

## BasArrayT

Reference-counted multi-dimensional array (up to BAS_ARRAY_MAX_DIMS = 8 dimensions).

    typedef struct {
        int32_t    refCount;
        uint8_t    elementType;
        int32_t    dims;
        int32_t    lbound[BAS_ARRAY_MAX_DIMS];
        int32_t    ubound[BAS_ARRAY_MAX_DIMS];
        int32_t    totalElements;
        BasValueT *elements;
    } BasArrayT;

### Array Functions

      Function                                  Description
      --------                                  -----------
      basArrayNew(dims, lbounds, ubounds, type) Allocate an array. refCount starts at 1.
      basArrayFree(arr)                         Free all elements and release the array.
      basArrayRef(arr)                          Increment reference count.
      basArrayUnref(arr)                        Decrement reference count. Frees at zero.
      basArrayIndex(arr, indices, ndims)        Compute flat index from multi-dimensional indices. Returns -1 if out of bounds.

## BasUdtT

Reference-counted user-defined type instance.

    typedef struct {
        int32_t    refCount;
        int32_t    typeId;
        int32_t    fieldCount;
        BasValueT *fields;
    } BasUdtT;

### UDT Functions

      Function                          Description
      --------                          -----------
      basUdtNew(typeId, fieldCount)     Allocate a UDT instance. refCount starts at 1.
      basUdtFree(udt)                   Free all fields and release.
      basUdtRef(udt)                    Increment reference count.
      basUdtUnref(udt)                  Decrement reference count. Frees at zero.

# Virtual Machine

Stack-based p-code interpreter. Executes compiled BASIC bytecode modules. The host provides I/O, UI, SQL, and external library callbacks. The VM has no DVX dependencies; it can be embedded in any C program.

Header: apps/dvxbasic/runtime/vm.h

## VM Limits

      Constant                Value   Description
      --------                -----   -----------
      BAS_VM_STACK_SIZE       256     Evaluation stack depth.
      BAS_VM_CALL_STACK_SIZE  64      Maximum call nesting depth.
      BAS_VM_MAX_GLOBALS      512     Global variable slots.
      BAS_VM_MAX_LOCALS       64      Local variables per stack frame.
      BAS_VM_MAX_FOR_DEPTH    32      Maximum nested FOR loop depth.
      BAS_VM_MAX_FILES        16      Open file channels (1-based).

## BasVmResultE

Result codes returned by basVmRun and basVmStep.

      Code                    Value   Description
      ----                    -----   -----------
      BAS_VM_OK               0       Program completed normally.
      BAS_VM_HALTED           1       HALT instruction reached.
      BAS_VM_ERROR            2       Runtime error.
      BAS_VM_STACK_OVERFLOW   3       Evaluation stack overflow.
      BAS_VM_STACK_UNDERFLOW  4       Evaluation stack underflow.
      BAS_VM_CALL_OVERFLOW    5       Call stack overflow.
      BAS_VM_DIV_BY_ZERO      6       Division by zero.
      BAS_VM_TYPE_MISMATCH    7       Type mismatch in operation.
      BAS_VM_OUT_OF_MEMORY    8       Memory allocation failed.
      BAS_VM_BAD_OPCODE       9       Unknown opcode encountered.
      BAS_VM_FILE_ERROR       10      File I/O error.
      BAS_VM_SUBSCRIPT_RANGE  11      Array subscript out of range.
      BAS_VM_STEP_LIMIT       12      Step limit reached (not an error).
      BAS_VM_BREAKPOINT       13      Breakpoint or step completed (not an error).

## Lifecycle

    BasVmT *basVmCreate(void);
    void    basVmDestroy(BasVmT *vm);
    void    basVmLoadModule(BasVmT *vm, BasModuleT *module);
    void    basVmReset(BasVmT *vm);

      Function         Description
      --------         -----------
      basVmCreate      Allocate and initialize a new VM instance.
      basVmDestroy     Destroy the VM and free all resources.
      basVmLoadModule  Load a compiled module (BasModuleT) into the VM.
      basVmReset       Reset to initial state (clear stack, globals, PC).

## Execution

    BasVmResultE basVmRun(BasVmT *vm);
    BasVmResultE basVmStep(BasVmT *vm);
    void         basVmSetStepLimit(BasVmT *vm, int32_t limit);

      Function           Description
      --------           -----------
      basVmRun           Execute the loaded module until it ends, halts, yields, errors, or hits a breakpoint/step limit.
      basVmStep          Execute a single instruction and return. Useful for debugger stepping.
      basVmSetStepLimit  Set maximum instructions per basVmRun call. 0 = unlimited (default). Returns BAS_VM_STEP_LIMIT when reached.

## I/O Callbacks

The host provides these callbacks for PRINT, INPUT, and DoEvents statements.

    void basVmSetPrintCallback(BasVmT *vm, BasPrintFnT fn, void *ctx);
    void basVmSetInputCallback(BasVmT *vm, BasInputFnT fn, void *ctx);
    void basVmSetDoEventsCallback(BasVmT *vm, BasDoEventsFnT fn, void *ctx);

### Callback Types

    typedef void (*BasPrintFnT)(void *ctx, const char *text, bool newline);
    typedef bool (*BasInputFnT)(void *ctx, const char *prompt,
        char *buf, int32_t bufSize);
    typedef bool (*BasDoEventsFnT)(void *ctx);

      Type             Description
      ----             -----------
      BasPrintFnT      Called for PRINT output. text is null-terminated. newline indicates line advance.
      BasInputFnT      Called for INPUT. Fill buf (up to bufSize-1 chars). Return true on success, false on cancel.
      BasDoEventsFnT   Called for DoEvents. Process pending events and return. Return false to stop the program.

## UI Callbacks

For form and control integration. The VM resolves all UI operations through these callbacks, keeping it independent of any specific GUI toolkit.

    void basVmSetUiCallbacks(BasVmT *vm, const BasUiCallbacksT *ui);

### BasUiCallbacksT

      Field         Signature                                            Description
      -----         ---------                                            -----------
      getProp       BasValueT (*)(ctx, ctrlRef, propName)                Get a control property value.
      setProp       void (*)(ctx, ctrlRef, propName, value)              Set a control property.
      callMethod    BasValueT (*)(ctx, ctrlRef, methodName, args, argc)  Call a method on a control.
      createCtrl    void *(*)(ctx, formRef, typeName, ctrlName)          Create a control on a form.
      findCtrl      void *(*)(ctx, formRef, ctrlName)                    Find a control by name.
      findCtrlIdx   void *(*)(ctx, formRef, ctrlName, index)             Find a control array element.
      loadForm      void *(*)(ctx, formName)                             Load a form by name.
      unloadForm    void (*)(ctx, formRef)                               Unload a form.
      showForm      void (*)(ctx, formRef, modal)                        Show a form (modal or modeless).
      hideForm      void (*)(ctx, formRef)                               Hide a form (keep in memory).
      msgBox        int32_t (*)(ctx, message, flags)                     Display a message box.
      inputBox      BasStringT *(*)(ctx, prompt, title, defaultText)     Display an input box.
      ctx           void *                                               User pointer passed to all callbacks.

## SQL Callbacks

For database integration.

    void basVmSetSqlCallbacks(BasVmT *vm, const BasSqlCallbacksT *sql);

### BasSqlCallbacksT

      Field           Signature                                  Description
      -----           ---------                                  -----------
      sqlOpen          int32_t (*)(path)                          Open a database. Returns handle.
      sqlClose         void (*)(db)                               Close a database.
      sqlExec          bool (*)(db, sql)                          Execute a non-query SQL statement.
      sqlError         const char *(*)(db)                        Get last error message.
      sqlQuery         int32_t (*)(db, sql)                       Execute a query. Returns result set handle.
      sqlNext          bool (*)(rs)                               Advance to next row.
      sqlEof           bool (*)(rs)                               Check if at end of result set.
      sqlFieldCount    int32_t (*)(rs)                            Get number of columns.
      sqlFieldName     const char *(*)(rs, col)                   Get column name by index.
      sqlFieldText     const char *(*)(rs, col)                   Get column value as text by index.
      sqlFieldByName   const char *(*)(rs, name)                  Get column value as text by name.
      sqlFieldInt      int32_t (*)(rs, col)                       Get column value as integer.
      sqlFieldDbl      double (*)(rs, col)                        Get column value as double.
      sqlFreeResult    void (*)(rs)                               Free a result set.
      sqlAffectedRows  int32_t (*)(db)                            Get number of rows affected by last statement.

## External Library Callbacks

For DECLARE LIBRARY support. The VM resolves external functions at runtime via the host.

    void basVmSetExternCallbacks(BasVmT *vm,
        const BasExternCallbacksT *ext);

### BasExternCallbacksT

      Field           Signature                                                Description
      -----           ---------                                                -----------
      resolveExtern   void *(*)(ctx, libName, funcName)                        Resolve a native function by library and symbol name. Cached after first call.
      callExtern      BasValueT (*)(ctx, funcPtr, funcName, args, argc, retType) Call a resolved native function, marshalling arguments and return value.
      ctx             void *                                                   User pointer passed to both callbacks.

## Form Context

Set the active form context during event dispatch.

    void basVmSetCurrentForm(BasVmT *vm, void *formRef);
    void basVmSetCurrentFormVars(BasVmT *vm,
        BasValueT *vars, int32_t count);

## Stack Access

Push and pop values on the evaluation stack for host integration.

    bool basVmPush(BasVmT *vm, BasValueT val);
    bool basVmPop(BasVmT *vm, BasValueT *val);

Both return true on success, false on stack overflow/underflow.

## Error Reporting

    const char *basVmGetError(const BasVmT *vm);

Returns the current error message string. Valid after basVmRun returns BAS_VM_ERROR.

## Sub/Function Calls from Host

Call a SUB or FUNCTION by its code address from host code.

    bool basVmCallSub(BasVmT *vm, int32_t codeAddr);
    bool basVmCallSubWithArgs(BasVmT *vm, int32_t codeAddr,
        const BasValueT *args, int32_t argCount);
    bool basVmCallSubWithArgsOut(BasVmT *vm, int32_t codeAddr,
        const BasValueT *args, int32_t argCount,
        BasValueT *outArgs, int32_t outCount);

      Function                Description
      --------                -----------
      basVmCallSub            Call a SUB with no arguments.
      basVmCallSubWithArgs    Call a SUB with arguments pushed onto the stack frame.
      basVmCallSubWithArgsOut Call a SUB and read back modified argument values after it returns.

All three push a call frame, execute until the SUB returns, then restore the previous execution state. Return true on normal completion, false on error or if the VM is not idle.

## Debugger API

    void    basVmSetBreakpoints(BasVmT *vm,
                int32_t *lines, int32_t count);
    void    basVmStepInto(BasVmT *vm);
    void    basVmStepOver(BasVmT *vm);
    void    basVmStepOut(BasVmT *vm);
    void    basVmRunToCursor(BasVmT *vm, int32_t line);
    int32_t basVmGetCurrentLine(const BasVmT *vm);

      Function              Description
      --------              -----------
      basVmSetBreakpoints   Set the breakpoint list (sorted array of source line numbers, host-owned memory).
      basVmStepInto         Break at the next OP_LINE instruction.
      basVmStepOver         Break when call depth returns to the current level.
      basVmStepOut          Break when call depth drops below the current level.
      basVmRunToCursor      Break when execution reaches the specified source line.
      basVmGetCurrentLine   Get the current source line number (from the last OP_LINE instruction).

The breakpoint callback notifies the host when a breakpoint fires during nested sub calls:

    typedef void (*BasBreakpointFnT)(void *ctx, int32_t line);

## BasModuleT

Compiled module produced by the BASIC compiler and loaded into the VM.

    typedef struct {
        uint8_t          *code;
        int32_t           codeLen;
        BasStringT      **constants;
        int32_t           constCount;
        int32_t           globalCount;
        int32_t           entryPoint;
        BasValueT        *dataPool;
        int32_t           dataCount;
        BasProcEntryT    *procs;
        int32_t           procCount;
        BasFormVarInfoT  *formVarInfo;
        int32_t           formVarInfoCount;
        BasDebugVarT     *debugVars;
        int32_t           debugVarCount;
        BasDebugUdtDefT  *debugUdtDefs;
        int32_t           debugUdtDefCount;
    } BasModuleT;

      Field              Description
      -----              -----------
      code               P-code bytecode array.
      codeLen            Length of bytecode in bytes.
      constants          String constant pool.
      constCount         Number of string constants.
      globalCount        Number of global variable slots needed.
      entryPoint         PC of the first instruction (module-level code).
      dataPool           DATA statement value pool (for READ).
      dataCount          Number of values in the data pool.
      procs              Procedure table (SUBs and FUNCTIONs).
      procCount          Number of procedures.
      formVarInfo        Per-form variable counts and init code addresses.
      formVarInfoCount   Number of forms with form-scoped variables.
      debugVars          Variable names and metadata for the debugger.
      debugVarCount      Number of debug variable entries.
      debugUdtDefs       UDT type definitions for the debugger.
      debugUdtDefCount   Number of debug UDT definitions.

# DVX Widget System

Complete reference for the DVX GUI widget toolkit. All widgets are implemented as dynamically loaded DXE modules. They are created via convenience macros that wrap the per-widget API function tables. The base WidgetT structure is defined in libdvx/dvxWgt.h; individual widget headers live in widgets/.

Individual widgets are documented in their own sections. See the table of contents for the full list.

## Base WidgetT (Common Properties, Events, and Operations)

Every widget inherits from the WidgetT structure defined in libdvx/dvxWgt.h. The fields and callbacks listed here are available on all widget types.

### Common Properties

      Field              Type                Description
      -----              ----                -----------
      name               char[32]            Widget name for lookup via wgtFind().
      x, y, w, h         int32_t             Computed geometry relative to the window content area (set by layout).
      minW, minH          int32_t (tagged)    Minimum size hints. Use wgtPixels(), wgtChars(), or wgtPercent(). 0 = auto.
      maxW, maxH          int32_t (tagged)    Maximum size constraints. 0 = no limit.
      prefW, prefH        int32_t (tagged)    Preferred size. 0 = auto.
      weight             int32_t             Extra-space distribution weight. 0 = fixed, 100 = normal. A widget with weight=200 gets twice the extra space of one with weight=100.
      align              WidgetAlignE        Main-axis alignment for children: AlignStartE, AlignCenterE, AlignEndE.
      spacing            int32_t (tagged)    Spacing between children (containers only). 0 = default.
      padding            int32_t (tagged)    Internal padding (containers only). 0 = default.
      fgColor            uint32_t            Foreground color override. 0 = use color scheme default.
      bgColor            uint32_t            Background color override. 0 = use color scheme default.
      visible            bool                Visibility state.
      enabled            bool                Enabled state. Disabled widgets are grayed out and ignore input.
      readOnly           bool                Read-only mode: allows scrolling/selection but blocks editing.
      swallowTab         bool                When true, Tab key goes to the widget instead of navigating focus.
      accelKey           char                Lowercase accelerator character. 0 if none.
      tooltip            const char *        Tooltip text. NULL = none. Caller owns the string.
      contextMenu        MenuT *             Right-click context menu. NULL = none. Caller owns.
      userData           void *              Application-defined user data pointer.

### Size Specification Macros

      Macro              Description
      -----              -----------
      wgtPixels(v)       Size in pixels.
      wgtChars(v)        Size in character widths (multiplied by font charWidth).
      wgtPercent(v)      Size as a percentage of parent dimension.

### Common Events (Callbacks)

These callback function pointers are available on every WidgetT. Set them directly on the widget struct.

      Callback           Signature                                                   Description
      --------           ---------                                                   -----------
      onClick            void (*)(WidgetT *w)                                        Fires on mouse click / activation.
      onDblClick         void (*)(WidgetT *w)                                        Fires on double-click.
      onChange           void (*)(WidgetT *w)                                        Fires when the widget's value changes (text, selection, check state, etc.).
      onFocus            void (*)(WidgetT *w)                                        Fires when the widget receives keyboard focus.
      onBlur             void (*)(WidgetT *w)                                        Fires when the widget loses keyboard focus.
      onKeyPress         void (*)(WidgetT *w, int32_t keyAscii)                      Fires on a printable key press (ASCII value).
      onKeyDown          void (*)(WidgetT *w, int32_t keyCode, int32_t shift)        Fires on key down (scan code + shift state).
      onKeyUp            void (*)(WidgetT *w, int32_t keyCode, int32_t shift)        Fires on key up.
      onMouseDown        void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y)  Fires on mouse button press.
      onMouseUp          void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y)  Fires on mouse button release.
      onMouseMove        void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y)  Fires on mouse movement over the widget.
      onScroll           void (*)(WidgetT *w, int32_t delta)                         Fires on mouse wheel scroll.
      onValidate         bool (*)(WidgetT *w)                                        Validation callback. Return false to cancel a pending write.

### Common Operations

      Function                                                    Description
      --------                                                    -----------
      WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win)      Initialize widgets for a window. Returns the root VBox container.
      AppContextT *wgtGetContext(const WidgetT *w)                 Walk up from any widget to retrieve the AppContextT.
      void wgtInvalidate(WidgetT *w)                               Mark widget for re-layout and repaint. Propagates to ancestors.
      void wgtInvalidatePaint(WidgetT *w)                          Mark widget for repaint only (no layout recalculation).
      void wgtSetText(WidgetT *w, const char *text)                Set widget text (label, button, textinput, etc.).
      const char *wgtGetText(const WidgetT *w)                     Get widget text.
      void wgtSetEnabled(WidgetT *w, bool enabled)                 Enable or disable a widget.
      void wgtSetReadOnly(WidgetT *w, bool readOnly)               Set read-only mode.
      void wgtSetFocused(WidgetT *w)                               Set keyboard focus to a widget.
      WidgetT *wgtGetFocused(void)                                 Get the currently focused widget.
      void wgtSetVisible(WidgetT *w, bool visible)                 Show or hide a widget.
      void wgtSetName(WidgetT *w, const char *name)                Set widget name for lookup.
      WidgetT *wgtFind(WidgetT *root, const char *name)            Find a widget by name in the subtree.
      void wgtDestroy(WidgetT *w)                                  Destroy a widget and all its children.
      void wgtSetTooltip(WidgetT *w, const char *text)             Set tooltip text. Pass NULL to remove.

## AnsiTerm

A VT100/ANSI-compatible terminal emulator widget designed for connecting to BBS systems over the serial link. Uses a traditional text-mode cell buffer (character + attribute byte pairs) with the CP437 character set and 16-color CGA palette. Supports cursor movement, screen/line erase, scrolling regions, SGR colors, DEC private modes, and a configurable scrollback buffer. Communication is abstracted through read/write function pointers, allowing the terminal to work with raw serial ports, the secLink encrypted channel, or any other byte-oriented transport.

The widget renders through two paint paths: a full paint used by the normal widget pipeline, and a fast incremental repaint (wgtAnsiTermRepaint) that pushes dirty rows directly to the window content buffer for low-latency serial echo.

Header: widgets/ansiTerm.h

### Creation

    WidgetT *term = wgtAnsiTerm(parent, 80, 25);

### API Functions

      Function                                                      Description
      --------                                                      -----------
      WidgetT *wgtAnsiTerm(parent, cols, rows)                      Create an ANSI terminal widget with the given column/row dimensions.
      void wgtAnsiTermWrite(w, data, len)                           Write raw bytes into the terminal's ANSI parser. data is a const uint8_t * buffer.
      void wgtAnsiTermClear(w)                                      Clear the terminal screen and reset the cursor to the home position.
      void wgtAnsiTermSetComm(w, ctx, readFn, writeFn)              Attach a communication channel. readFn and writeFn are I/O callbacks; ctx is passed as their first argument.
      void wgtAnsiTermSetScrollback(w, maxLines)                    Set the maximum number of scrollback lines.
      int32_t wgtAnsiTermPoll(w)                                    Poll the communication channel for incoming data and feed it into the parser. Returns number of bytes consumed.
      int32_t wgtAnsiTermRepaint(w, outY, outH)                     Fast repaint path that renders dirty rows directly into the window's content buffer, bypassing the widget pipeline. Returns the number of rows repainted and the dirty region via outY/outH.

### API Struct (wgtRegisterApi "ansiterm")

The sApi struct exposes these function pointers:

      Slot             Function
      ----             --------
      create           wgtAnsiTerm
      write            wgtAnsiTermWrite
      clear            wgtAnsiTermClear
      setComm          wgtAnsiTermSetComm
      setScrollback    wgtAnsiTermSetScrollback
      poll             wgtAnsiTermPoll
      repaint          wgtAnsiTermRepaint

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      Cols         Integer    Read-only    Number of columns.
      Rows         Integer    Read-only    Number of rows.
      Scrollback   Integer    Write-only   Maximum number of scrollback lines.

### Methods (BASIC Interface)

      Method       Description
      ------       -----------
      Clear        Clear the terminal screen.
      Poll         Process any pending bytes on the attached communication channel.
      Write        Write a string into the terminal (with ANSI escape processing).

### Events

AnsiTerm uses the common events only. No widget-specific events are defined.

### Keyboard Shortcuts

Within the terminal widget:

      Key              Action
      ---              ------
      Ctrl+C           Copy selection to the clipboard (when a selection exists).
      Ctrl+V           Send the clipboard contents to the attached write function.
      Arrows           Send VT100 cursor escape sequences.
      Home/End         Send VT100 Home/End sequences.
      PgUp/PgDn/Del    Send the corresponding VT100 escape sequences.

## Box (VBox / HBox / Frame)

Container widgets that arrange their children in a vertical column (VBox), horizontal row (HBox), or a titled group box (Frame). These are the primary layout building blocks. Children are laid out using a weight-based algorithm with configurable spacing, padding, and alignment.

Frame is a labelled grouping container with a Motif-style beveled border. Its title text sits centered vertically on the top border line with a small background-filled gap behind the title, giving the classic Windows 3.1 / Motif group box appearance. Internally, Frame behaves like a VBox for layout purposes.

The widget DXE registers three separate interface entries ("vbox", "hbox", "frame") so the form designer can create each type independently.

Header: widgets/box.h

### Creation

    WidgetT *row   = wgtHBox(parent);
    WidgetT *col   = wgtVBox(parent);
    WidgetT *group = wgtFrame(parent, "Options");

### API Functions

      Function                                            Description
      --------                                            -----------
      WidgetT *wgtVBox(parent)                            Create a vertical box container. Children stack top-to-bottom.
      WidgetT *wgtHBox(parent)                            Create a horizontal box container. Children stack left-to-right.
      WidgetT *wgtFrame(parent, title)                    Create a titled group box. Children stack vertically inside the bordered frame. The title string may include a '&' prefix for an accelerator key.

### API Struct (wgtRegisterApi "box")

      Slot     Function
      ----     --------
      vBox     wgtVBox
      hBox     wgtHBox
      frame    wgtFrame

The designer also registers per-type APIs: "vbox", "hbox", and "frame" each expose a single create slot.

### Properties

Box containers use the common WidgetT fields for layout control. There are no widget-specific properties registered with the interface system.

      Field      Description
      -----      -----------
      align      Main-axis alignment of children. HBox: Start=left, Center=center, End=right. VBox: Start=top, Center=center, End=bottom.
      spacing    Gap between children (tagged size).
      padding    Internal padding around children (tagged size).
      weight     Controls how the box itself stretches within its parent.

Frame text is managed via the standard wgtSetText() / wgtGetText() interface (the widget has WCLASS_HAS_TEXT). BASIC code can set its title via the generic "Caption" or "Text" property.

### Events

Containers use the common events only. No widget-specific events or methods are registered.

### Default Event

"Click" on all three types.

## Button

A push button with a text label. Fires onClick when pressed and released. Uses a two-phase press model: the button visually depresses on mouse-down and fires onClick only when the mouse is released while still inside the button bounds -- dragging the mouse off cancels the press. Supports accelerator keys via '&' prefix in the text (e.g. "&OK" underlines 'O' and binds Alt+O).

Disabled buttons use the classic "embossed" rendering (highlight text offset by +1,+1 and shadow text at 0,0) for a chiseled appearance.

Header: widgets/button.h

### Creation

    WidgetT *btn = wgtButton(parent, "&OK");
    btn->onClick = onOkClicked;

### API Functions

      Function                                      Description
      --------                                      -----------
      WidgetT *wgtButton(parent, text)              Create a push button with the given label text. Pass NULL for no text. Text is copied into the widget.

### API Struct (wgtRegisterApi "button")

      Slot     Function
      ----     --------
      create   wgtButton

### Properties

Uses common WidgetT properties. Label text is managed via wgtSetText() / wgtGetText(). Set accelKey for keyboard shortcut (automatically parsed from '&' prefix in the text). The button is focusable (WCLASS_FOCUSABLE) and draws a focus rectangle when it holds keyboard focus.

No widget-specific properties are registered with the interface system. BASIC code sets the label via the generic "Caption" or "Text" property.

### Methods

No widget-specific methods.

### Events

      Callback     Description
      --------     -----------
      onClick      Fires when the button is clicked (mouse press and release inside, or Space/Enter when focused).

### Default Event

"Click" (VB basName: CommandButton, namePrefix: Command).

## Canvas

A freeform drawing surface with a fixed-size pixel buffer stored in the display's native pixel format. Provides drawing primitives (lines, rectangles, circles, text, individual pixels) and supports save/load to image files (BMP/PNG/etc. via dvxLoadImage/dvxSaveImage). Mouse interaction is available via a callback. The buffer is rendered to screen as a straight blit with no per-pixel conversion.

Canvas coordinates are independent of widget position: (0,0) is the top-left of the canvas content, not the widget. The widget frames the buffer with a 2-pixel sunken bevel.

Header: widgets/canvas.h

### Creation

    WidgetT *cv = wgtCanvas(parent, 320, 200);

### API Functions

      Function                                                             Description
      --------                                                             -----------
      WidgetT *wgtCanvas(parent, w, h)                                     Create a canvas with the given pixel dimensions. Buffer is initialized to white.
      void wgtCanvasClear(w, color)                                        Fill the entire canvas with a packed color.
      void wgtCanvasSetPenColor(w, color)                                  Set the drawing pen color (packed display color).
      void wgtCanvasSetPenSize(w, size)                                    Set the drawing pen size in pixels (affects DrawLine dot thickness).
      void wgtCanvasDrawLine(w, x0, y0, x1, y1)                           Draw a line using Bresenham's algorithm with the current pen color and size.
      void wgtCanvasDrawRect(w, x, y, width, height)                      Draw a 1-pixel rectangle outline using the current pen color.
      void wgtCanvasFillRect(w, x, y, width, height)                      Fill a rectangle using the current pen color.
      void wgtCanvasFillCircle(w, cx, cy, radius)                         Fill a circle using the current pen color (integer sqrt; no FPU needed).
      void wgtCanvasSetPixel(w, x, y, color)                              Set a single pixel to the given packed color.
      uint32_t wgtCanvasGetPixel(w, x, y)                                 Read a single pixel. Returns packed color.
      void wgtCanvasDrawText(w, x, y, text)                               Draw text at the given canvas coordinates using the current pen color.
      void wgtCanvasSetMouseCallback(w, cb)                                Set a mouse callback. Signature: void (*cb)(WidgetT *w, int32_t cx, int32_t cy, bool drag). cx/cy are canvas-relative, drag=true on mouse-move during press.
      int32_t wgtCanvasSave(w, path)                                       Save the canvas buffer to an image file. Returns 0 on success, -1 on error.
      int32_t wgtCanvasLoad(w, path)                                       Load an image file into the canvas (resizes buffer to match). Returns 0 on success, -1 on error.
      void wgtCanvasResize(w, newW, newH)                                 Resize the canvas buffer. New pixels are filled with white.

### API Struct (wgtRegisterApi "canvas")

      Slot                 Function
      ----                 --------
      create               wgtCanvas
      clear                wgtCanvasClear
      setPenColor          wgtCanvasSetPenColor
      setPenSize           wgtCanvasSetPenSize
      setMouseCallback     wgtCanvasSetMouseCallback
      save                 wgtCanvasSave
      load                 wgtCanvasLoad
      drawLine             wgtCanvasDrawLine
      drawRect             wgtCanvasDrawRect
      fillRect             wgtCanvasFillRect
      fillCircle           wgtCanvasFillCircle
      setPixel             wgtCanvasSetPixel
      getPixel             wgtCanvasGetPixel
      drawText             wgtCanvasDrawText
      resize               wgtCanvasResize

### Properties

Canvas has no widget-specific properties registered with the interface system. Drawing state (pen color, pen size) is managed by the API functions above.

### Methods (BASIC Interface)

      Method                                        Description
      ------                                        -----------
      Clear color%                                  Fill the entire canvas with a 0x00RRGGBB color.
      DrawLine x0%, y0%, x1%, y1%, color%           Draw a line between two points.
      DrawRect x%, y%, w%, h%, color%               Draw a rectangle outline.
      DrawText x%, y%, text$                        Draw text at the given position.
      FillCircle cx%, cy%, radius%, color%          Fill a circle.
      FillRect x%, y%, w%, h%, color%               Fill a rectangle.
      GetPixel(x%, y%)                              Returns the 0x00RRGGBB color at a pixel.
      Load path$                                    Load an image file onto the canvas.
      Resize w%, h%                                 Resize the canvas (fills new area with white).
      Save path$                                    Save the canvas to an image file.
      SetPenColor color%                            Set the drawing color (0x00RRGGBB).
      SetPenSize size%                              Set the pen size in pixels.
      SetPixel x%, y%, color%                       Set a single pixel.

### Events

      Callback                                          Description
      --------                                          -----------
      onClick                                           Fires when the canvas is clicked.
      Mouse callback (via wgtCanvasSetMouseCallback)    Fires on mouse down and drag with canvas-local coordinates.

### Default Event

"Click" (VB basName: PictureBox, namePrefix: Picture).

## Checkbox

A toggle control with a text label. Clicking toggles between checked and unchecked states. Fires onChange each time the state flips. Supports accelerator keys (via '&' in the text) and keyboard toggle via Space or Enter when focused.

The check mark is drawn as an "X" pattern rather than a traditional checkmark glyph. The focus rectangle wraps the label text (not the box), matching the Windows 3.1 convention.

Header: widgets/checkbox.h

### Creation

    WidgetT *cb = wgtCheckbox(parent, "Enable &logging");

### API Functions

      Function                                                Description
      --------                                                -----------
      WidgetT *wgtCheckbox(parent, text)                      Create a checkbox with the given label text.
      bool wgtCheckboxIsChecked(w)                            Returns true if the checkbox is checked.
      void wgtCheckboxSetChecked(w, checked)                  Set the checked state programmatically. Triggers a repaint but does NOT fire onChange.

### API Struct (wgtRegisterApi "checkbox")

      Slot          Function
      ----          --------
      create        wgtCheckbox
      isChecked     wgtCheckboxIsChecked
      setChecked    wgtCheckboxSetChecked

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      Value        Boolean    Read/Write   Whether the checkbox is checked.

Label text is managed via the standard wgtSetText() / wgtGetText() interface. BASIC code uses the generic "Caption" or "Text" property.

### Methods

No widget-specific methods.

### Events

      Callback     Description
      --------     -----------
      onClick      Fires when clicked (after the toggle has already applied).
      onChange     Fires when the checked state changes (mouse click or keyboard toggle).

### Default Event

"Click" (VB basName: CheckBox).

## ComboBox

A combination of a single-line text input and a drop-down list. The user can type a value or select one from the list. When the user picks a list item, its text is copied into the edit buffer. Supports full text editing (cursor movement, selection, clipboard, undo) via the texthelp library, and a popup overlay list via the listhelp library.

Depends on "texthelp" and "listhelp" helper libraries (declared in combobox.dep).

Header: widgets/comboBox.h

### Creation

    WidgetT *cb = wgtComboBox(parent, 128);
    wgtComboBoxAddItem(cb, "Arial");
    wgtComboBoxAddItem(cb, "Courier");
    wgtComboBoxAddItem(cb, "Times");

### API Functions

      Function                                                Description
      --------                                                -----------
      WidgetT *wgtComboBox(parent, maxLen)                    Create a combo box. maxLen is the maximum editable text length (0 => default 256).
      void wgtComboBoxSetItems(w, items, count)               Set the dropdown items from a const char ** array. Items are not copied -- caller owns them.
      int32_t wgtComboBoxGetSelected(w)                       Get the index of the last selected item (-1 if the text was typed freely).
      void wgtComboBoxSetSelected(w, idx)                     Select an item by index. Copies its text into the edit buffer.
      void wgtComboBoxAddItem(w, text)                        Append an item to the owned list (strdup'd).
      void wgtComboBoxRemoveItem(w, idx)                      Remove an owned item by index.
      void wgtComboBoxClear(w)                                Remove all owned items and reset the selection.
      const char *wgtComboBoxGetItem(w, idx)                  Get the text of an item by index.
      int32_t wgtComboBoxGetItemCount(w)                      Get the total number of items.

### API Struct (wgtRegisterApi "combobox")

      Slot           Function
      ----           --------
      create         wgtComboBox
      setItems       wgtComboBoxSetItems
      getSelected    wgtComboBoxGetSelected
      setSelected    wgtComboBoxSetSelected
      addItem        wgtComboBoxAddItem
      removeItem     wgtComboBoxRemoveItem
      clear          wgtComboBoxClear
      getItem        wgtComboBoxGetItem
      getItemCount   wgtComboBoxGetItemCount

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      ListIndex    Integer    Read/Write   Index of the currently selected item (-1 if none).

Editable text is accessible via the generic "Text" property. "ListCount" is available through the ListCount method.

### Methods (BASIC Interface)

      Method              Description
      ------              -----------
      AddItem text$       Append an item to the dropdown list.
      Clear               Remove all items and clear the selection.
      List(index%)        Return the text of the item at the given index.
      ListCount()         Return the total number of items.
      RemoveItem index%   Remove the item at the given index.

### Events

      Callback     Description
      --------     -----------
      onChange     Fires when the selection or text changes.

### Default Event

"Click" (VB basName: ComboBox).

## DataCtrl

A VB3-style Data control for database binding. Displays a visible navigation bar (|< < > >|) that connects to a SQLite database via dvxSql* functions. Reads all rows from the RecordSource query into an in-memory cache for bidirectional navigation. Fires a Reposition event each time the current row changes so bound controls can update. Supports master-detail linking between Data controls (via MasterSource / MasterField / DetailField), INSERT via AddNew, and DELETE via Delete. UPDATEs use the KeyColumn to identify the row.

The widget depends on the "dvxsql" library DXE; the navigation logic caches the full result set so there is no round-trip for MoveNext/MovePrev.

Header: widgets/dataCtrl.h

### Creation

    WidgetT *data = wgtDataCtrl(parent);

Set properties (DatabaseName, RecordSource, KeyColumn, etc.) and then call dataCtrlRefresh to populate.

### API Functions

      Function                                                   Description
      --------                                                   -----------
      WidgetT *dataCtrlCreate(parent)                            Create a Data control. Exposed as create in the API struct.
      void dataCtrlRefresh(w)                                    Re-execute the RecordSource query and rebuild the row cache.
      void dataCtrlMoveFirst(w)                                  Move the cursor to the first row.
      void dataCtrlMovePrev(w)                                   Move the cursor to the previous row.
      void dataCtrlMoveNext(w)                                   Move the cursor to the next row.
      void dataCtrlMoveLast(w)                                   Move the cursor to the last row.
      const char *dataCtrlGetField(w, colName)                   Get the value of a column in the current row (case-insensitive).
      void dataCtrlSetField(w, colName, value)                   Set the value of a column in the current row. Marks the row dirty.
      void dataCtrlUpdate(w)                                     Flush pending changes (INSERT or UPDATE) to the database.
      void dataCtrlUpdateRow(w)                                  Legacy wrapper around dataCtrlUpdate.
      void dataCtrlAddNew(w)                                     Append a blank row and move the cursor to it. The row is dirty and new until Update is called.
      void dataCtrlDelete(w)                                     Delete the current row from the cache and the database.
      void dataCtrlSetMasterValue(w, val)                        Set the master-detail filter value. Normally managed by the form runtime.
      int32_t dataCtrlGetRowCount(w)                             Get the total number of cached rows.
      int32_t dataCtrlGetColCount(w)                             Get the number of columns in the result set.
      const char *dataCtrlGetColName(w, col)                     Get the name of a column by index.
      const char *dataCtrlGetCellText(w, row, col)               Get the text of a specific cell.
      void dataCtrlSetCurrentRow(w, row)                         Set the current row by index. Auto-saves the previous row if dirty.

### API Struct (wgtRegisterApi "data")

      Slot                 Function
      ----                 --------
      create               dataCtrlCreate
      refresh              dataCtrlRefresh
      moveFirst            dataCtrlMoveFirst
      movePrev             dataCtrlMovePrev
      moveNext             dataCtrlMoveNext
      moveLast             dataCtrlMoveLast
      getField             dataCtrlGetField
      setField             dataCtrlSetField
      updateRow            dataCtrlUpdateRow
      update               dataCtrlUpdate
      addNew               dataCtrlAddNew
      delete               dataCtrlDelete
      setMasterValue       dataCtrlSetMasterValue
      getRowCount          dataCtrlGetRowCount
      getColCount          dataCtrlGetColCount
      getColName           dataCtrlGetColName
      getCellText          dataCtrlGetCellText
      setCurrentRow        dataCtrlSetCurrentRow

### Properties (BASIC Interface)

      Property       Type       Access       Description
      --------       ----       ------       -----------
      DatabaseName   String     Read/Write   Path to the SQLite database file.
      RecordSource   String     Read/Write   SQL query or table name for the result set.
      KeyColumn      String     Read/Write   Primary key column name (used for UPDATE/DELETE).
      MasterSource   String     Read/Write   Name of the master Data control for master-detail linking.
      MasterField    String     Read/Write   Column in the master control to read for the filter value.
      DetailField    String     Read/Write   Column in this table to filter by the master value.
      Caption        String     Read/Write   Text displayed on the navigator bar.
      BOF            Boolean    Read-only    True when the cursor is at the first row (or no rows).
      EOF            Boolean    Read-only    True when the cursor is past the last row (or no rows).

### Methods (BASIC Interface)

      Method         Description
      ------         -----------
      AddNew         Append a blank row and move to it.
      Delete         Delete the current row.
      MoveFirst      Move the cursor to the first row.
      MoveLast       Move the cursor to the last row.
      MoveNext       Move the cursor to the next row.
      MovePrevious   Move the cursor to the previous row.
      Refresh        Re-execute the query and rebuild the cache.
      Update         Write pending changes to the database.

### Events

      Event          Description
      -----          -----------
      Reposition     Fires when the current row changes. Default event.
      Validate       Fires before writing. Return false to cancel the write.

## DbGrid

A database grid widget that displays all records from a Data control in a scrollable, sortable table. Columns auto-populate from the Data control's column names and can be hidden, resized (by dragging a column border), and renamed by the application. Clicking a column header sorts the display ascending/descending. Selecting a row syncs the Data control's cursor position. The grid reads directly from the Data control's cached rows, so there is no separate copy of the data.

The grid supports alternating row shading, vertical and horizontal scrollbars, keyboard navigation (arrows, Page Up/Down, Home, End), and double-click activation (fires onDblClick).

Header: widgets/dbGrid.h

### Creation

    WidgetT *grid = wgtDbGrid(parent);
    dbGridSetDataWidget(grid, dataCtrl);

### API Functions

      Function                                                   Description
      --------                                                   -----------
      WidgetT *dbGridCreate(parent)                              Create a database grid widget. Exposed as create in the API struct.
      void dbGridSetDataWidget(w, dataWidget)                    Bind the grid to a Data control. Auto-populates columns from the Data control's column names.
      void dbGridRefresh(w)                                      Re-read the Data control's state and repaint the grid. Rebuilds the sort index if sorting is active.
      void dbGridSetColumnVisible(w, fieldName, visible)         Show or hide a column by field name.
      void dbGridSetColumnHeader(w, fieldName, header)           Set a display header for a column (overrides the field name).
      void dbGridSetColumnWidth(w, fieldName, width)             Set a column's width (tagged size, 0 = auto).
      int32_t dbGridGetSelectedRow(w)                            Get the index of the currently selected data row (-1 if none).

### API Struct (wgtRegisterApi "dbgrid")

      Slot                 Function
      ----                 --------
      create               dbGridCreate
      setDataWidget        dbGridSetDataWidget
      refresh              dbGridRefresh
      setColumnVisible     dbGridSetColumnVisible
      setColumnHeader      dbGridSetColumnHeader
      setColumnWidth       dbGridSetColumnWidth
      getSelectedRow       dbGridGetSelectedRow

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      GridLines    Boolean    Read/Write   Whether to draw grid lines between cells (default: true).

### Methods (BASIC Interface)

      Method       Description
      ------       -----------
      Refresh      Re-read the Data control and repaint.

### Events

      Event        Description
      -----        -----------
      Click        Fires when a row is clicked (selection change).
      DblClick     Fires when a row is double-clicked. Default event.

### Default Event

"DblClick" (VB basName: DBGrid, namePrefix: DBGrid).

## Dropdown

A drop-down list that displays a single selected item and expands to a popup list when clicked. Unlike ComboBox, the user cannot type free text -- only list items can be selected. Keyboard navigation: Down/Up to move, Enter to select, type-ahead search on printable keys. The popup overlay is rendered above all other widgets via the widget paint overlay mechanism.

Depends on the "listhelp" helper library (declared in dropdown.dep).

Header: widgets/dropdown.h

### Creation

    WidgetT *dd = wgtDropdown(parent);
    wgtDropdownAddItem(dd, "Red");
    wgtDropdownAddItem(dd, "Green");
    wgtDropdownAddItem(dd, "Blue");

### API Functions

      Function                                            Description
      --------                                            -----------
      WidgetT *wgtDropdown(parent)                        Create a dropdown list.
      void wgtDropdownSetItems(w, items, count)           Set the list from a caller-owned const char ** array.
      int32_t wgtDropdownGetSelected(w)                   Get the index of the selected item (-1 if none).
      void wgtDropdownSetSelected(w, idx)                 Set the selected item by index.
      void wgtDropdownAddItem(w, text)                    Append an owned item (strdup'd).
      void wgtDropdownRemoveItem(w, idx)                  Remove an owned item by index.
      void wgtDropdownClear(w)                            Remove all owned items.
      const char *wgtDropdownGetItem(w, idx)              Get the text of an item by index.
      int32_t wgtDropdownGetItemCount(w)                  Get the total number of items.

### API Struct (wgtRegisterApi "dropdown")

      Slot           Function
      ----           --------
      create         wgtDropdown
      setItems       wgtDropdownSetItems
      getSelected    wgtDropdownGetSelected
      setSelected    wgtDropdownSetSelected
      addItem        wgtDropdownAddItem
      removeItem     wgtDropdownRemoveItem
      clear          wgtDropdownClear
      getItem        wgtDropdownGetItem
      getItemCount   wgtDropdownGetItemCount

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      ListIndex    Integer    Read/Write   Index of the currently selected item (-1 if none).

### Methods (BASIC Interface)

      Method              Description
      ------              -----------
      AddItem text$       Append an item to the drop-down list.
      Clear               Remove all items.
      List(index%)        Return the text of the item at the given index.
      ListCount()         Return the total number of items.
      RemoveItem index%   Remove the item at the given index.

### Events

      Callback     Description
      --------     -----------
      onChange     Fires when the selected item changes.

### Default Event

"Click" (VB basName: DropDown).

## ImageButton

A clickable button that displays an image instead of text. Has the same press/release visual feedback and focus handling as a regular Button. Can be created from raw pixel data or loaded from an image file. Typically used to populate a Toolbar.

Header: widgets/imgBtn.h

### Creation

    WidgetT *btn = wgtImageButtonFromFile(parent, "icons/save.bmp");
    btn->onClick = onSaveClicked;

### API Functions

      Function                                                             Description
      --------                                                             -----------
      WidgetT *wgtImageButton(parent, data, w, h, pitch)                   Create from raw pixel data (in display's native format).
      WidgetT *wgtImageButtonFromFile(parent, path)                        Create by loading an image file.
      void wgtImageButtonSetData(w, data, imgW, imgH, pitch)               Replace the image with new raw pixel data.
      void wgtImageButtonLoadFile(w, path)                                 Replace the image by loading a new file.

### API Struct (wgtRegisterApi "imagebutton")

      Slot         Function
      ----         --------
      create       wgtImageButton
      fromFile     wgtImageButtonFromFile
      setData      wgtImageButtonSetData
      loadFile     wgtImageButtonLoadFile

### Properties (BASIC Interface)

      Property      Type       Access       Description
      --------      ----       ------       -----------
      Picture       String     Read/Write   Setting writes a file path (loads image). Reading returns the current path.
      ImageWidth    Integer    Read-only    Width of the currently loaded image in pixels.
      ImageHeight   Integer    Read-only    Height of the currently loaded image in pixels.

### Methods

No widget-specific BASIC methods. Setting Picture loads a new image.

### Events

      Callback     Description
      --------     -----------
      onClick      Fires when the image button is clicked (press and release inside).

### Default Event

"Click" (VB basName: ImageButton).

## Image

Displays a bitmap image. Can be created from raw pixel data or loaded from a file on disk (BMP/PNG/etc. via dvxLoadImage). Supports optional stretching to fill the widget and transparent color keys for chroma-key style masking.

Header: widgets/image.h

### Creation

    WidgetT *img = wgtImageFromFile(parent, "logo.bmp");
    // or from raw pixels:
    // WidgetT *img = wgtImage(parent, pixelData, w, h, pitch);

### API Functions

      Function                                                             Description
      --------                                                             -----------
      WidgetT *wgtImage(parent, data, w, h, pitch)                         Create from raw pixel data (in display's native format).
      WidgetT *wgtImageFromFile(parent, path)                              Create by loading an image file.
      void wgtImageSetData(w, data, imgW, imgH, pitch)                     Replace the displayed image with new raw pixel data.
      void wgtImageLoadFile(w, path)                                       Replace by loading a new file. Static but exposed via the API struct.
      void wgtImageSetTransparent(w, hasTransparency, keyColor)            Set chroma-key color. Pixels matching keyColor are not drawn.

### API Struct (wgtRegisterApi "image")

      Slot             Function
      ----             --------
      create           wgtImage
      fromFile         wgtImageFromFile
      setData          wgtImageSetData
      loadFile         wgtImageLoadFile
      setTransparent   wgtImageSetTransparent

### Properties (BASIC Interface)

      Property      Type       Access       Description
      --------      ----       ------       -----------
      Picture       String     Read/Write   Setting writes a file path (loads image). Reading returns the current path.
      Stretch       Boolean    Read/Write   When true, the image stretches to fill the widget; when false, shown at natural size.
      ImageWidth    Integer    Read-only    Width of the currently loaded image in pixels.
      ImageHeight   Integer    Read-only    Height of the currently loaded image in pixels.

### Methods

No widget-specific BASIC methods. Setting Picture loads a new image.

### Events

      Callback     Description
      --------     -----------
      onClick      Fires when the image is clicked.

### Default Event

"Click" (VB basName: Image).

## Label

A static text label. Does not accept keyboard focus directly, but supports accelerator keys that forward focus to the next focusable sibling (WCLASS_FOCUS_FORWARD). Useful for describing other widgets. Supports left, center, and right text alignment.

Header: widgets/label.h

### Creation

    WidgetT *lbl = wgtLabel(parent, "&Name:");

### API Functions

      Function                                            Description
      --------                                            -----------
      WidgetT *wgtLabel(parent, text)                     Create a text label.
      void wgtLabelSetAlign(w, align)                     Set the text alignment (AlignStartE = left, AlignCenterE = center, AlignEndE = right).
      WidgetAlignE wgtLabelGetAlign(w)                    Get the current text alignment.

### API Struct (wgtRegisterApi "label")

      Slot       Function
      ----       --------
      create     wgtLabel
      setAlign   wgtLabelSetAlign

### Properties (BASIC Interface)

      Property     Type                         Access       Description
      --------     ----                         ------       -----------
      Alignment    Enum (Left, Center, Right)   Read/Write   Text alignment within the label.

Label text is managed via the standard wgtSetText() / wgtGetText() interface. BASIC code uses the generic "Caption" or "Text" property. Place an '&' before a character in the caption to mark an accelerator key.

### Methods

No widget-specific methods.

### Events

Labels are not focusable, so they typically have no event callbacks. The common onClick callback will fire if the label is clicked.

### Default Event

"Click" (VB basName: Label).

## ListBox

A scrollable list of text items. Supports single and multi-select modes (Shift-click for range, Ctrl-click to toggle), drag-to-reorder, mouse wheel scroll, and keyboard navigation (Up/Down/PgUp/PgDn/Home/End with type-ahead search on printable keys). Depends on the "listhelp" helper library (declared in listbox.dep).

Items can either be set from a caller-owned array (wgtListBoxSetItems) or managed internally via AddItem/RemoveItem/Clear. The two modes are mutually exclusive per widget.

Header: widgets/listBox.h

### Creation

    WidgetT *lb = wgtListBox(parent);
    wgtListBoxAddItem(lb, "Alpha");
    wgtListBoxAddItem(lb, "Beta");
    wgtListBoxAddItem(lb, "Gamma");

### API Functions

      Function                                                     Description
      --------                                                     -----------
      WidgetT *wgtListBox(parent)                                  Create a list box.
      void wgtListBoxSetItems(w, items, count)                     Set items from a caller-owned const char ** array.
      int32_t wgtListBoxGetSelected(w)                             Get the primary selected index (-1 if none).
      void wgtListBoxSetSelected(w, idx)                           Set the selected index. Scrolls the item into view.
      void wgtListBoxSetMultiSelect(w, multi)                      Enable or disable multi-select mode.
      bool wgtListBoxIsItemSelected(w, idx)                        Returns true if the item is selected (multi-select mode).
      void wgtListBoxSetItemSelected(w, idx, selected)             Select or deselect a specific item (multi-select mode).
      void wgtListBoxSelectAll(w)                                  Select every item (multi-select mode).
      void wgtListBoxClearSelection(w)                             Deselect all items.
      void wgtListBoxSetReorderable(w, r)                          Enable drag-to-reorder of items.
      void wgtListBoxAddItem(w, text)                              Append an owned item (strdup'd).
      void wgtListBoxRemoveItem(w, idx)                            Remove an owned item by index.
      void wgtListBoxClear(w)                                      Remove all owned items.
      const char *wgtListBoxGetItem(w, idx)                        Get the text of an item by index.
      int32_t wgtListBoxGetItemCount(w)                            Get the total number of items.

### API Struct (wgtRegisterApi "listbox")

      Slot               Function
      ----               --------
      create             wgtListBox
      setItems           wgtListBoxSetItems
      getSelected        wgtListBoxGetSelected
      setSelected        wgtListBoxSetSelected
      setMultiSelect     wgtListBoxSetMultiSelect
      isItemSelected     wgtListBoxIsItemSelected
      setItemSelected    wgtListBoxSetItemSelected
      selectAll          wgtListBoxSelectAll
      clearSelection     wgtListBoxClearSelection
      setReorderable     wgtListBoxSetReorderable
      addItem            wgtListBoxAddItem
      removeItem         wgtListBoxRemoveItem
      clear              wgtListBoxClear
      getItem            wgtListBoxGetItem
      getItemCount       wgtListBoxGetItemCount

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      ListIndex    Integer    Read/Write   Index of the currently selected item.

### Methods (BASIC Interface)

      Method                            Description
      ------                            -----------
      AddItem text$                     Append an item.
      Clear                             Remove all items.
      ClearSelection                    Deselect all items.
      IsItemSelected(index%)            Returns True if the item is selected (multi-select mode).
      List(index%)                      Return the text of the item at the given index.
      ListCount()                       Return the total number of items.
      RemoveItem index%                 Remove the item at the given index.
      SelectAll                         Select all items.
      SetItemSelected index%, sel       Select or deselect a specific item.
      SetItems spec$                    Bulk-load items from a pipe-delimited string (e.g. "Red|Green|Blue"); replaces existing items.
      SetMultiSelect multi              Enable or disable multi-select mode.
      SetReorderable r                  Enable or disable drag-to-reorder.

### Events

      Callback     Description
      --------     -----------
      onClick      Fires when an item is clicked.
      onDblClick   Fires when an item is double-clicked.
      onChange     Fires when the selection changes.

### Default Event

"Click" (VB basName: ListBox).

## ListView

A multi-column list with sortable headers. Supports single and multi-selection, column alignment, header click sorting, and drag-to-reorder. Data is provided as a flat array of strings (row-major order, one string per cell).

Header: widgets/listView.h

### Creation

    WidgetT *lv = wgtListView(parent);
    ListViewColT cols[] = {
        { "Name", wgtChars(20), ListViewAlignLeftE },
        { "Size", wgtChars(10), ListViewAlignRightE }
    };
    wgtListViewSetColumns(lv, cols, 2);
    const char *cells[] = { "file.txt", "1234", "readme.md", "5678" };
    wgtListViewSetData(lv, cells, 2);

### Column Definition

    typedef struct {
        const char      *title;
        int32_t          width;   // tagged size (wgtPixels/wgtChars/wgtPercent, 0 = auto)
        ListViewAlignE   align;   // ListViewAlignLeftE, ListViewAlignCenterE, ListViewAlignRightE
    } ListViewColT;

### Sort Direction

    typedef enum {
        ListViewSortNoneE,
        ListViewSortAscE,
        ListViewSortDescE
    } ListViewSortE;

### Macros

      Macro                                              Description
      -----                                              -----------
      wgtListView(parent)                                Create a list view.
      wgtListViewSetColumns(w, cols, count)              Define columns from an array of ListViewColT.
      wgtListViewSetData(w, cellData, rowCount)          Set row data. cellData is a flat const char ** array of size rowCount * colCount.
      wgtListViewGetSelected(w)                          Get the index of the selected row (-1 if none).
      wgtListViewSetSelected(w, idx)                     Set the selected row by index.
      wgtListViewSetSort(w, col, dir)                    Set the sort column and direction.
      wgtListViewSetHeaderClickCallback(w, cb)           Set a callback for header clicks. Signature: void (*cb)(WidgetT *w, int32_t col, ListViewSortE dir).
      wgtListViewSetMultiSelect(w, multi)                Enable or disable multi-selection.
      wgtListViewIsItemSelected(w, idx)                  Check if a specific row is selected.
      wgtListViewSetItemSelected(w, idx, selected)       Select or deselect a specific row.
      wgtListViewSelectAll(w)                            Select all rows.
      wgtListViewClearSelection(w)                       Deselect all rows.
      wgtListViewSetReorderable(w, reorderable)          Enable drag-to-reorder of rows.

### Events

      Callback     Description
      --------     -----------
      onClick      Fires when a row is clicked.
      onDblClick   Fires when a row is double-clicked.
      onChange     Fires when the selection changes.

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      ListIndex    Integer    Read/Write   Index of the currently selected row.

### Methods (BASIC Interface)

      Method                          Description
      ------                          -----------
      AddItem text$                   Add a row (sets first column text).
      Clear                           Remove all rows.
      ClearSelection                  Deselect all rows.
      GetCell(row%, col%)             Returns the text of a cell.
      IsItemSelected(index%)          Check if a specific row is selected.
      RemoveItem index%               Remove a row by index.
      RowCount()                      Returns the number of rows.
      SelectAll                       Select all rows.
      SetCell row%, col%, text$       Set the text of a cell.
      SetColumns spec$                Define columns from a pipe-delimited spec string ("Name,Width|Name,Width").
      SetItemSelected idx%, sel       Select or deselect a specific row by index.
      SetMultiSelect multi            Enable or disable multi-selection.
      SetReorderable reorderable      Enable or disable drag-to-reorder.
      SetSort col%, dir%              Set the sort column and direction (0=none, 1=ascending, 2=descending).

### Default Event

"Click" (VB basName: ListView).

## ProgressBar

A visual indicator of progress, displayed as a filled bar. Supports both horizontal and vertical orientations. Value ranges from 0 to 100.

Header: widgets/progress.h

### Creation

      Macro                    Description
      -----                    -----------
      wgtProgressBar(parent)   Create a horizontal progress bar.
      wgtProgressBarV(parent)  Create a vertical progress bar.

### API Functions

      Function                            Description
      --------                            -----------
      WidgetT *wgtProgressBar(parent)     Create a horizontal progress bar.
      WidgetT *wgtProgressBarV(parent)    Create a vertical progress bar.
      void wgtProgressBarSetValue(w, val) Set the progress value (0-100). Clamped to 0..maxValue.
      int32_t wgtProgressBarGetValue(w)   Get the current progress value.

### API Struct (wgtRegisterApi "progressbar")

      Slot       Function
      ----       --------
      create     wgtProgressBar
      createV    wgtProgressBarV
      setValue   wgtProgressBarSetValue
      getValue   wgtProgressBarGetValue

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      Value        Integer    Read/Write   Current progress value (0-100).

### Methods

No widget-specific methods.

### Events

ProgressBar is a display-only widget. Typically no callbacks are set.

### Default Event

None. (VB basName: ProgressBar.)

## Radio Button

A mutually exclusive selection control. Radio buttons must be placed inside a radio group container. Only one radio button within a group can be selected at a time.

Header: widgets/radio.h

### Creation

    WidgetT *grp = wgtRadioGroup(parent);
    WidgetT *r1  = wgtRadio(grp, "Option A");
    WidgetT *r2  = wgtRadio(grp, "Option B");

### API Functions

      Function                                       Description
      --------                                       -----------
      WidgetT *wgtRadioGroup(parent)                 Create a radio group container.
      WidgetT *wgtRadio(parent, text)                Create a radio button inside a group.
      void wgtRadioGroupSetSelected(group, idx)      Set the selected radio button by index within the group.
      int32_t wgtRadioGetIndex(w)                    Get the index of this radio button within its group.

### API Struct (wgtRegisterApi "radio")

      Slot                Function
      ----                --------
      group               wgtRadioGroup
      create              wgtRadio
      groupSetSelected    wgtRadioGroupSetSelected
      getIndex            wgtRadioGetIndex

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      Value        Integer    Read-only    Index of this radio button within its group.

Caption is managed via the standard wgtSetText() / wgtGetText() interface (WCLASS_HAS_TEXT).

### Methods (BASIC Interface)

      Method                  Description
      ------                  -----------
      SetSelected idx%        Set the selected radio button by index within the group.

### Events

      Callback     Description
      --------     -----------
      onClick      Fires on the radio button when clicked.
      onChange     Fires when the selection changes.

### Default Event

"Click" (VB basName: OptionButton, namePrefix: Option).

## ScrollPane

A scrollable container that provides vertical and/or horizontal scrollbars when its content exceeds the visible area. Place a single child (typically a VBox or HBox) inside the scroll pane.

Header: widgets/scrlPane.h

### Creation

    WidgetT *sp = wgtScrollPane(parent);
    WidgetT *content = wgtVBox(sp);
    // add children to content...

### API Functions

      Function                                          Description
      --------                                          -----------
      WidgetT *wgtScrollPane(parent)                    Create a scroll pane container.
      void wgtScrollPaneScrollToChild(sp, child)        Scroll so that the given child widget is visible.
      void wgtScrollPaneScrollToTop(w)                  Scroll back to the top-left of the content.
      void wgtScrollPaneSetNoBorder(w, noBorder)        When true, removes the border around the scroll pane.

### API Struct (wgtRegisterApi "scrollpane")

      Slot             Function
      ----             --------
      create           wgtScrollPane
      scrollToChild    wgtScrollPaneScrollToChild
      setNoBorder      wgtScrollPaneSetNoBorder
      scrollToTop      wgtScrollPaneScrollToTop

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      NoBorder     Boolean    Read/Write   Whether the border around the scroll pane is hidden.

### Methods

No widget-specific methods.

### Events

      Callback     Description
      --------     -----------
      onScroll     Fires when the scroll position changes.

### Default Event

None. (VB basName: ScrollPane, namePrefix: Scroll.)

## Separator

A visual dividing line used to separate groups of widgets. Available in horizontal and vertical orientations.

Header: widgets/separatr.h

### API Functions

      Function                            Description
      --------                            -----------
      WidgetT *wgtHSeparator(parent)      Create a horizontal separator line.
      WidgetT *wgtVSeparator(parent)      Create a vertical separator line.

### API Struct (wgtRegisterApi "separator")

      Slot           Function
      ----           --------
      hSeparator     wgtHSeparator
      vSeparator     wgtVSeparator

### Properties

No widget-specific properties.

### Methods

No widget-specific methods.

### Events

Separator is a visual-only widget. No events.

### Default Event

None. (VB basName: Line.)

## Slider

A horizontal slider (track bar) for selecting an integer value within a range. The user drags the thumb or clicks the track to change the value.

Header: widgets/slider.h

### Creation

    WidgetT *sl = wgtSlider(parent, 0, 100);

### API Functions

      Function                                          Description
      --------                                          -----------
      WidgetT *wgtSlider(parent, minVal, maxVal)        Create a slider with the given integer range.
      void wgtSliderSetValue(w, value)                  Set the slider value programmatically.
      int32_t wgtSliderGetValue(w)                      Get the current slider value.

### API Struct (wgtRegisterApi "slider")

      Slot       Function
      ----       --------
      create     wgtSlider
      setValue   wgtSliderSetValue
      getValue   wgtSliderGetValue

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      Value        Integer    Read/Write   Current slider value.

### Methods

No widget-specific methods.

### Events

      Callback     Description
      --------     -----------
      onChange     Fires when the slider value changes.

### Default Event

"Change" (VB basName: HScrollBar, namePrefix: HScroll).

## Spacer

An invisible widget used for layout purposes. By default it has weight=100, so it absorbs available extra space. Useful for pushing other widgets apart or aligning them to edges.

Header: widgets/spacer.h

### Creation

    WidgetT *row = wgtHBox(parent);
    wgtButton(row, "OK");
    wgtSpacer(row);           // pushes Cancel to the right
    wgtButton(row, "Cancel");

### API Functions

      Function                       Description
      --------                       -----------
      WidgetT *wgtSpacer(parent)     Create an invisible spacer widget.

### API Struct (wgtRegisterApi "spacer")

      Slot       Function
      ----       --------
      create     wgtSpacer

### Properties, Methods, Events

Spacer is an invisible layout widget. No type-specific properties, methods, or events.

### Default Event

None. (VB basName: Spacer.)

## Spinner

A numeric input with up/down buttons for incrementing and decrementing a value within a range. Supports both integer and floating-point (real) modes.

Header: widgets/spinner.h

### Creation

    WidgetT *sp = wgtSpinner(parent, 0, 100, 1);

### API Functions

      Function                                                Description
      --------                                                -----------
      WidgetT *wgtSpinner(parent, minVal, maxVal, step)       Create a spinner with the given integer range and step size.
      void wgtSpinnerSetValue(w, value)                       Set the integer value.
      int32_t wgtSpinnerGetValue(w)                           Get the current integer value.
      void wgtSpinnerSetRange(w, minVal, maxVal)              Set the integer range.
      void wgtSpinnerSetStep(w, step)                         Set the integer step size.
      void wgtSpinnerSetRealMode(w, enable)                   Switch to floating-point mode.
      double wgtSpinnerGetRealValue(w)                        Get the current floating-point value.
      void wgtSpinnerSetRealValue(w, value)                   Set the floating-point value.
      void wgtSpinnerSetRealRange(w, minVal, maxVal)          Set the floating-point range.
      void wgtSpinnerSetRealStep(w, step)                     Set the floating-point step size.
      void wgtSpinnerSetDecimals(w, decimals)                 Set the number of decimal places displayed in real mode.

### API Struct (wgtRegisterApi "spinner")

      Slot           Function
      ----           --------
      create         wgtSpinner
      setValue       wgtSpinnerSetValue
      getValue       wgtSpinnerGetValue
      setRange       wgtSpinnerSetRange
      setStep        wgtSpinnerSetStep
      setRealMode    wgtSpinnerSetRealMode
      getRealValue   wgtSpinnerGetRealValue
      setRealValue   wgtSpinnerSetRealValue
      setRealRange   wgtSpinnerSetRealRange
      setRealStep    wgtSpinnerSetRealStep
      setDecimals    wgtSpinnerSetDecimals

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      Value        Integer    Read/Write   Current integer value.
      RealMode     Boolean    Read/Write   Whether floating-point mode is active.
      Decimals     Integer    Read/Write   Number of decimal places displayed in real mode.

### Methods (BASIC Interface)

      Method                Description
      ------                -----------
      SetRange min%, max%   Set the integer range.
      SetStep step%         Set the integer step size.

### Events

      Callback     Description
      --------     -----------
      onChange     Fires when the value changes.

### Default Event

"Change" (VB basName: SpinButton, namePrefix: Spin).

## Splitter

A two-pane container with a draggable divider. The user drags the splitter bar to resize the two panes. Can be oriented vertically (left/right panes) or horizontally (top/bottom panes). Add exactly two children.

Header: widgets/splitter.h

### Creation

    WidgetT *sp = wgtSplitter(parent, true);  // vertical = left|right
    WidgetT *left  = wgtVBox(sp);
    WidgetT *right = wgtVBox(sp);

### API Functions

      Function                                       Description
      --------                                       -----------
      WidgetT *wgtSplitter(parent, vertical)         Create a splitter. vertical=true for left/right panes (vertical divider), false for top/bottom.
      void wgtSplitterSetPos(w, pos)                 Set the divider position in pixels from the leading edge.
      int32_t wgtSplitterGetPos(w)                   Get the current divider position in pixels.

### API Struct (wgtRegisterApi "splitter")

      Slot       Function
      ----       --------
      create     wgtSplitter
      setPos     wgtSplitterSetPos
      getPos     wgtSplitterGetPos

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      Position     Integer    Read/Write   Divider position in pixels.

### Methods

No widget-specific methods.

### Events

Splitter has no widget-specific events. Common events apply.

### Default Event

None. (VB basName: Splitter.)

## StatusBar

A horizontal bar typically placed at the bottom of a window for displaying status text and informational widgets. Children are laid out horizontally.

Header: widgets/statBar.h

### Creation

    WidgetT *sb = wgtStatusBar(parent);
    wgtLabel(sb, "Ready");

### API Functions

      Function                          Description
      --------                          -----------
      WidgetT *wgtStatusBar(parent)     Create a status bar container.

### API Struct (wgtRegisterApi "statusbar")

      Slot       Function
      ----       --------
      create     wgtStatusBar

### Properties, Methods, Events

StatusBar has no widget-specific properties, methods, or events. Add child widgets (labels, progress bars, etc.) to populate.

### Default Event

None. (VB basName: StatusBar.)

## TabControl

A tabbed container that displays one page at a time with clickable tabs along the top. Each tab page is a container that holds its own child widgets.

Header: widgets/tabCtrl.h

### Creation

    WidgetT *tabs = wgtTabControl(parent);
    WidgetT *page1 = wgtTabPage(tabs, "General");
    WidgetT *page2 = wgtTabPage(tabs, "Advanced");
    // add children to page1, page2...

### API Functions

      Function                                       Description
      --------                                       -----------
      WidgetT *wgtTabControl(parent)                 Create a tab control.
      WidgetT *wgtTabPage(parent, title)             Add a tab page with the given title. Returns the page container widget.
      void wgtTabControlSetActive(w, idx)            Set the active tab by index (0-based).
      int32_t wgtTabControlGetActive(w)              Get the index of the active tab.

### API Struct (wgtRegisterApi "tabcontrol")

      Slot         Function
      ----         --------
      create       wgtTabControl
      page         wgtTabPage
      setActive    wgtTabControlSetActive
      getActive    wgtTabControlGetActive

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      TabIndex     Integer    Read/Write   Index of the currently active tab (0-based).

### Methods (BASIC Interface)

      Method                Description
      ------                -----------
      AddPage title$        Add a new tab page with the given title.
      GetActive()           Returns the index of the active tab.
      SetActive idx%        Set the active tab by index (0-based).

### Events

      Callback     Description
      --------     -----------
      onChange     Fires when the active tab changes.

### Default Event

"Click" (VB basName: TabStrip).

## TextInput / TextArea

Single-line text input, password input, masked input, and multi-line text area with optional syntax colorization, line numbers, find/replace, and gutter decorators.

Header: widgets/textInpt.h

### Creation

      Macro                            Description
      -----                            -----------
      wgtTextInput(parent, maxLen)     Create a single-line text input. maxLen is the maximum number of characters.
      wgtPasswordInput(parent, maxLen) Create a password input (characters displayed as bullets).
      wgtMaskedInput(parent, mask)     Create a masked input field. The mask string defines the input format.
      wgtTextArea(parent, maxLen)      Create a multi-line text area.

### API Functions (TextArea-specific)

      Function                                                    Description
      --------                                                    -----------
      void wgtTextAreaAppendText(w, text)                         Append text to the end of the buffer and invalidate the widget.
      void wgtTextAreaSetColorize(w, fn, ctx)                     Set a syntax colorization callback. The callback receives each line and fills a color index array.
      void wgtTextAreaGoToLine(w, line)                           Scroll to and place the cursor on the given line number.
      void wgtTextAreaSetAutoIndent(w, enable)                    Enable or disable automatic indentation on newline.
      void wgtTextAreaSetShowLineNumbers(w, show)                 Show or hide line numbers in the gutter.
      void wgtTextAreaSetCaptureTabs(w, capture)                  When true, Tab key inserts a tab/spaces instead of moving focus.
      void wgtTextAreaSetTabWidth(w, width)                       Set the tab stop width in characters.
      void wgtTextAreaSetUseTabChar(w, useChar)                   When true, insert literal tab characters; when false, insert spaces.
      bool wgtTextAreaFindNext(w, needle, caseSens, fwd)          Search for the next occurrence. Returns true if found.
      int32_t wgtTextAreaReplaceAll(w, needle, repl, caseSens)    Replace all occurrences. Returns the number of replacements made.
      bool wgtTextAreaReplaceSelection(w, needle, repl, caseSens, fwd)  If the current selection matches needle, replace it, then find the next occurrence in direction fwd. Returns true if anything was replaced or found.
      void wgtTextAreaSetLineDecorator(w, fn, ctx)                Set a gutter line decorator callback. Returns a color and receives the line number.
      int32_t wgtTextAreaGetCursorLine(w)                         Get the current cursor line number.
      void wgtTextAreaSetGutterClickCallback(w, fn)               Set a callback for gutter clicks (e.g. for breakpoint toggling).
      int32_t wgtTextAreaGetWordAtCursor(w, buf, bufSize)         Copy the word under the cursor into buf. Returns its length.
      void wgtTextAreaSetSyntaxColors(w, colors, count)           Set the color palette used by the colorizer.
      void wgtTextAreaCursorToEnd(w)                              Move the cursor to the very end of the buffer (past the last character).

### API Struct (wgtRegisterApi "textinput")

The combined "textinput" API exposes all four constructors plus the TextArea functions. The designer uses per-type APIs registered under the names "textbox" (single-line) and "textarea" (multi-line), each exposing only a create slot.

### Properties (BASIC Interface)

TextBox has no widget-specific properties. Text is managed via the generic "Text" property. TextArea exposes:

      Property     Type       Access       Description
      --------     ----       ------       -----------
      CursorLine   Integer    Read-only    Current cursor line number (0-based).

### Methods (BASIC Interface, TextArea)

      Method                                            Description
      ------                                            -----------
      FindNext needle$, caseSensitive, forward          Search for the next occurrence. Returns True if found.
      GetWordAtCursor()                                 Returns the word under the cursor.
      GoToLine line%                                    Scroll to and position the cursor on a line.
      ReplaceAll needle$, replacement$, caseSensitive   Replace all occurrences. Returns the count.
      SetAutoIndent enabled                             Enable or disable automatic indentation on newline.
      SetCaptureTabs enabled                            When True, Tab inserts whitespace instead of moving focus.
      SetShowLineNumbers show                           Show or hide line numbers in the gutter.
      SetSyntaxMode mode$                               Activate built-in syntax highlighting (e.g. "dhs", "bas"; "" to disable).
      SetTabWidth width%                                Set the tab stop width in characters.
      SetUseTabChar useChar                             When True, Tab inserts a literal tab; when False, spaces.

### Events

      Callback     Description
      --------     -----------
      onChange     Fires when the text content changes.
      onKeyPress   Fires on each key press (ASCII value).
      onValidate   Called before committing a change. Return false to cancel.

### Default Event

"Change" for both TextBox (basName: TextBox) and TextArea (basName: TextArea).

## Timer

A non-visual widget that fires its onClick callback at a regular interval. Useful for animations, polling, and periodic updates. Must be explicitly started after creation.

Header: widgets/timer.h

### Creation

    WidgetT *tmr = wgtTimer(parent, 1000, true);  // 1 second, repeating
    tmr->onClick = onTimerTick;
    wgtTimerStart(tmr);

### API Functions

      Function                                          Description
      --------                                          -----------
      WidgetT *wgtTimer(parent, intervalMs, repeat)     Create a timer. intervalMs is the interval in milliseconds. repeat: true for repeating, false for one-shot.
      void wgtTimerStart(w)                             Start the timer.
      void wgtTimerStop(w)                              Stop the timer.
      void wgtTimerSetInterval(w, intervalMs)           Change the timer interval.
      int32_t wgtTimerGetInterval(w)                    Returns the current interval in milliseconds.
      bool wgtTimerIsRunning(w)                         Returns true if the timer is currently running.
      void wgtTimerSetEnabled(w, enabled)               Start or stop the timer based on enabled flag.
      void wgtUpdateTimers(void)                        Global tick function. Called by the event loop to advance all active timers.

### API Struct (wgtRegisterApi "timer")

      Slot           Function
      ----           --------
      create         wgtTimer
      start          wgtTimerStart
      stop           wgtTimerStop
      setInterval    wgtTimerSetInterval
      isRunning      wgtTimerIsRunning
      updateTimers   wgtUpdateTimers

### Events

      Callback     Description
      --------     -----------
      onClick      Fires each time the timer elapses (the BASIC layer surfaces this as the "Timer" event).

### Properties (BASIC Interface)

      Property     Type       Access       Description
      --------     ----       ------       -----------
      Enabled      Boolean    Read/Write   Whether the timer is running. Reading returns the running state; writing starts or stops it.
      Interval     Integer    Read/Write   Timer interval in milliseconds.

### Methods (BASIC Interface)

      Method       Description
      ------       -----------
      Start        Start the timer.
      Stop         Stop the timer.

### Extra Events (BASIC Interface)

      Event        Description
      -----        -----------
      Timer        Fires each time the timer elapses. Default event.

## Toolbar

A horizontal container for toolbar buttons and controls. Typically placed at the top of a window. Children (usually ImageButtons or Buttons) are laid out horizontally with toolbar-appropriate spacing.

Header: widgets/toolbar.h

### Creation

    WidgetT *tb = wgtToolbar(parent);
    wgtImageButtonFromFile(tb, "icons/save.bmp");
    wgtImageButtonFromFile(tb, "icons/open.bmp");

### API Functions

      Function                          Description
      --------                          -----------
      WidgetT *wgtToolbar(parent)       Create a toolbar container.

### API Struct (wgtRegisterApi "toolbar")

      Slot       Function
      ----       --------
      create     wgtToolbar

### Properties, Methods, Events

Toolbar has no widget-specific properties, methods, or events. Add children (buttons, separators, etc.) to populate.

### Default Event

None. (VB basName: Toolbar.)

## TreeView

A hierarchical tree control with expandable/collapsible nodes. Supports single and multi-selection and drag-to-reorder. Tree items are added as children of the TreeView or of other tree items to create nested hierarchies.

Header: widgets/treeView.h

### Creation

    WidgetT *tv    = wgtTreeView(parent);
    WidgetT *root  = wgtTreeItem(tv, "Root");
    WidgetT *child = wgtTreeItem(root, "Child");

### API Functions

      Function                                              Description
      --------                                              -----------
      WidgetT *wgtTreeView(parent)                          Create a tree view control.
      WidgetT *wgtTreeItem(parent, text)                    Add a tree item as a child of the tree view or another tree item.
      WidgetT *wgtTreeViewGetSelected(w)                    Get the currently selected tree item (NULL if none).
      void wgtTreeViewSetSelected(w, item)                  Set the selected tree item.
      void wgtTreeViewSetMultiSelect(w, multi)              Enable or disable multi-selection.
      void wgtTreeViewSetReorderable(w, reorderable)        Enable drag-to-reorder of items.
      void wgtTreeItemSetExpanded(w, expanded)              Expand or collapse a tree item.
      bool wgtTreeItemIsExpanded(w)                         Check if a tree item is expanded.
      bool wgtTreeItemIsSelected(w)                         Check if a tree item is selected (multi-select mode).
      void wgtTreeItemSetSelected(w, selected)              Select or deselect a tree item.

### API Struct (wgtRegisterApi "treeview")

      Slot              Function
      ----              --------
      create            wgtTreeView
      getSelected       wgtTreeViewGetSelected
      setSelected       wgtTreeViewSetSelected
      setMultiSelect    wgtTreeViewSetMultiSelect
      setReorderable    wgtTreeViewSetReorderable
      item              wgtTreeItem
      itemSetExpanded   wgtTreeItemSetExpanded
      itemIsExpanded    wgtTreeItemIsExpanded
      itemIsSelected    wgtTreeItemIsSelected
      itemSetSelected   wgtTreeItemSetSelected

### Properties

No widget-specific properties.

### Methods (BASIC Interface)

      Method                                Description
      ------                                -----------
      AddChildItem parentIdx%, text$        Add a child node under the node at the given index.
      AddItem text$                         Add a root-level node.
      Clear                                 Remove all nodes.
      GetItemText(index%)                   Returns the text of the node at the given depth-first index.
      IsExpanded(index%)                    Returns True if the node is expanded.
      IsItemSelected(index%)                Returns True if the node is selected.
      ItemCount()                           Returns the total number of nodes.
      SetExpanded index%, expanded          Expand or collapse the node.
      SetItemSelected index%, selected      Select or deselect the node.
      SetMultiSelect multi                  Enable or disable multi-selection.
      SetReorderable reorderable            Enable or disable drag-to-reorder.

### Events

      Callback     Description
      --------     -----------
      onClick      Fires when a tree item is clicked.
      onDblClick   Fires when a tree item is double-clicked.
      onChange     Fires when the selection changes.

### Default Event

"Click" (VB basName: TreeView).

## WrapBox

A flow/wrap layout container that arranges children left-to-right, wrapping to the next row when the available width is exceeded. Each row's height is the maximum child height in that row. Supports configurable spacing between items and rows, and per-row alignment for short rows.

Header: widgets/wrapBox.h

### Creation

    WidgetT *wrap = wgtWrapBox(parent);
    wgtButton(wrap, "Tag 1");
    wgtButton(wrap, "Tag 2");
    wgtButton(wrap, "Tag 3");

### API Functions

      Function               Description
      --------               -----------
      wgtWrapBox(parent)     Create a wrap box container. Macro that calls the registered "wrapbox" create slot.

### API Struct (wgtRegisterApi "wrapbox")

      Slot       Function
      ----       --------
      create     wrapBoxCreate

### Properties (Common Container Fields)

WrapBox uses the common WidgetT container fields for layout control:

      Property     Description
      --------     -----------
      spacing      Gap between children in both the horizontal and vertical directions (tagged size). Default is 4 pixels.
      padding      Internal padding around children (tagged size). Default is 2 pixels.

### Properties (BASIC Interface)

      Property     Type                         Access       Description
      --------     ----                         ------       -----------
      Alignment    Enum (Left, Center, Right)   Read/Write   Row alignment for rows that do not fill the full width.

### Methods

No widget-specific methods.

### Events

WrapBox is a container widget. It uses the common events only. No widget-specific events are defined.

### Default Event

"Click" (VB basName: WrapBox, namePrefix: WrapBox).