# The MIT License (MIT)
#
# Copyright (C) 2026 Scott Duensing
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

.section Architecture
.topic api.overview
.title DVX GUI API Reference
.toc 0 DVX GUI API Reference
.default
.index DVX API
.index API Reference

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

.h2 Headers

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

.link api.types dvxTypes.h -- Shared Type Definitions
.link api.cursor dvxCur.h -- Cursor Definitions
.link api.font dvxFont.h -- Bitmap Font Data
.link api.palette dvxPal.h -- 8-bit Palette
.link api.video dvxVideo.h -- Layer 1: Video Backend
.link api.draw dvxDraw.h -- Layer 2: Drawing Primitives
.link api.comp dvxComp.h -- Layer 3: Compositor
.link api.wm dvxWm.h -- Layer 4: Window Manager
.link api.app dvxApp.h -- Layer 5: Application API
.link api.dialog dvxDlg.h -- Modal Dialogs
.link api.resource dvxRes.h -- Resource System
.link api.prefs dvxPrefs.h -- Preferences
.link api.mem dvxMem.h -- Memory Tracking
.link api.widget dvxWgt.h -- Widget System
.link api.widgetplugin dvxWgtP.h -- Widget Plugin API
.link api.platform platform/dvxPlat.h -- Platform Layer

.topic api.types
.title dvxTypes.h -- Shared Type Definitions
.toc 1 dvxTypes.h -- Shared Type Definitions
.index dvxTypes.h
.index PixelFormatT
.index DisplayT
.index RectT
.index BlitOpsT
.index BevelStyleT
.index BitmapFontT
.index ColorSchemeT
.index ColorIdE
.index DirtyListT
.index WindowT
.index WindowStackT
.index MenuT
.index MenuItemT
.index MenuBarT
.index ScrollbarT
.index AccelTableT
.index AccelEntryT
.index VideoModeInfoT
.index CursorT

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

.h2 Core Structures

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

.table
  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
.endtable

.h3 DisplayT

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

.table
  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
.endtable

.h3 RectT

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

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

.h3 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).

.table
  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
.endtable

.h3 BevelStyleT

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

.table
  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)
.endtable

.h3 BitmapFontT

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

.table
  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
.endtable

.h3 ColorSchemeT

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

.table
  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
.endtable

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

.h3 DirtyListT

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

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

.h3 WindowT

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

.table
  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
.endtable

Callbacks:

.table
  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
.endtable

.h3 WindowStackT

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

.table
  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
.endtable

.h3 MenuT / MenuItemT / MenuBarT

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

.table
  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
.endtable

.h3 ScrollbarT

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

.table
  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
.endtable

.h3 AccelTableT / AccelEntryT

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

.table
  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
.endtable

.h3 VideoModeInfoT

Describes an available video mode (enumerated at init).

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

.h3 CursorT

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

.table
  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)
.endtable

.h2 Bevel Convenience Macros

.table
  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
.endtable

.h2 Chrome Constants

.table
  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
  CHROME_CLOSE_BTN_SIZE   16      Close button gadget size
.endtable

.h2 Hit Test Constants

.table
  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)
.endtable

.h2 Mouse Button Flags

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

.h2 Accelerator Modifier Flags

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

.h2 Extended Key Codes

.table
  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
.endtable

.h2 Resize Edge Flags

.table
  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)
.endtable

.h2 Utility Macros

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

.topic api.cursor
.title dvxCur.h -- Cursor Definitions
.toc 1 dvxCur.h -- Cursor Definitions
.index dvxCur.h
.index Cursor Shapes
.index CURSOR_ARROW
.index CURSOR_BUSY

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

.h2 Cursor Shape IDs

.table
  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
.endtable

.h2 Data

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

.h3 dvxCursor

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

.topic api.font
.title dvxFont.h -- Bitmap Font Data
.toc 1 dvxFont.h -- Bitmap Font Data
.index dvxFont.h
.index Font
.index CP437
.index BitmapFontT

.h1 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:

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

.h2 Data

.h3 font8x16

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

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

.h2 Constants

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

.topic api.palette
.title dvxPal.h -- 8-bit Palette
.toc 1 dvxPal.h -- 8-bit Palette
.index dvxPal.h
.index Palette
.index 8-bit mode

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

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

.table
  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)
.endtable

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.

.h2 Chrome Color Indices

.table
  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
.endtable

.h2 Inline Functions

.h3 dvxGeneratePalette

.code
static inline void dvxGeneratePalette(uint8_t *pal);
.endcode

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.

.table
  Parameter   Description
  ---------   -----------
  pal         Output RGB buffer (768 bytes)
.endtable

.h3 dvxNearestPalEntry

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

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.

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

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

.topic api.video
.title dvxVideo.h -- Layer 1: VESA VBE Video Backend
.toc 1 dvxVideo.h -- Layer 1: Video Backend
.index dvxVideo.h
.index videoInit
.index videoShutdown
.index packColor
.index setClipRect
.index resetClipRect
.index VESA
.index LFB

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

.h2 videoInit

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

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.

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

Returns: 0 on success, negative on failure.

.h2 videoShutdown

.code
void videoShutdown(DisplayT *d);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  d           Display context to shut down
.endtable

.h2 packColor

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

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.

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

Returns: Native pixel value suitable for direct framebuffer write.

.h2 unpackColor

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

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.

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

.h2 setClipRect

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

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.

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

.h2 resetClipRect

.code
void resetClipRect(DisplayT *d);
.endcode

Reset the clip rectangle to the full display dimensions.

.table
  Parameter   Description
  ---------   -----------
  d           Display context
.endtable

.topic api.draw
.title dvxDraw.h -- Layer 2: Drawing Primitives
.toc 1 dvxDraw.h -- Layer 2: Drawing Primitives
.index dvxDraw.h
.index drawInit
.index rectFill
.index rectCopy
.index rectCopyGrayscale
.index drawBevel
.index drawChar
.index drawText
.index drawTextN
.index textWidth
.index accelParse
.index drawTextAccel
.index textWidthAccel
.index drawMaskedBitmap
.index drawTermRow
.index drawFocusRect
.index drawHLine
.index drawVLine

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

.h2 drawInit

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

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

.table
  Parameter   Description
  ---------   -----------
  ops         BlitOpsT to populate
  d           Initialized display context
.endtable

.h2 rectFill

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

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

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

.h2 rectCopy

.code
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);
.endcode

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

.table
  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
.endtable

.h2 rectCopyGrayscale

.code
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);
.endcode

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.

.table
  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
.endtable

.h2 rectCopyTransparent

.code
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);
.endcode

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.

.table
  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
.endtable

.h2 drawBevel

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

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

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

.h2 drawChar

.code
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);
.endcode

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

.table
  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
.endtable

Returns: Advance width (always charWidth).

.h2 drawText

.code
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);
.endcode

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

.table
  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
.endtable

.h2 drawTextN

.code
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);
.endcode

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

.table
  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
.endtable

.h2 textWidth

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

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

.table
  Parameter   Description
  ---------   -----------
  font        Bitmap font
  text        Null-terminated string
.endtable

Returns: Width in pixels.

.h2 accelParse

.code
char accelParse(const char *text);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  text        Text with optional & accelerator marker
.endtable

Returns: Lowercase accelerator character, or 0 if none.

.h2 drawTextAccel

.code
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);
.endcode

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.

.table
  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
.endtable

.h2 textWidthAccel

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

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

.table
  Parameter   Description
  ---------   -----------
  font        Bitmap font
  text        Text with optional & markers
.endtable

Returns: Width in pixels.

.h2 drawMaskedBitmap

.code
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);
.endcode

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

.table
  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
.endtable

.h2 drawTermRow

.code
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);
.endcode

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.

.table
  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)
.endtable

.h2 drawFocusRect

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

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

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

.h2 drawHLine

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

Draw a horizontal line (1px tall).

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

.h2 drawVLine

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

Draw a vertical line (1px wide).

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

.topic api.comp
.title dvxComp.h -- Layer 3: Dirty Rectangle Compositor
.toc 1 dvxComp.h -- Layer 3: Compositor
.index dvxComp.h
.index dirtyListInit
.index dirtyListAdd
.index dirtyListMerge
.index dirtyListClear
.index flushRect
.index rectIntersect
.index rectIsEmpty

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

.h2 dirtyListInit

.code
void dirtyListInit(DirtyListT *dl);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  dl          Dirty list to initialize
.endtable

.h2 dirtyListAdd

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

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

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

.h2 dirtyListMerge

.code
void dirtyListMerge(DirtyListT *dl);
.endcode

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.

.table
  Parameter   Description
  ---------   -----------
  dl          Dirty list to merge
.endtable

.h2 dirtyListClear

.code
void dirtyListClear(DirtyListT *dl);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  dl          Dirty list to clear
.endtable

.h2 flushRect

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

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.

.table
  Parameter   Description
  ---------   -----------
  d           Display context
  r           Rectangle to flush
.endtable

.h2 rectIntersect

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

Compute the intersection of two rectangles.

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

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

.h2 rectIsEmpty

.code
bool rectIsEmpty(const RectT *r);
.endcode

Test whether a rectangle has zero or negative area.

.table
  Parameter   Description
  ---------   -----------
  r           Rectangle to test
.endtable

Returns: true if w <= 0 or h <= 0.

.topic api.wm
.title dvxWm.h -- Layer 4: Window Manager
.toc 1 dvxWm.h -- Layer 4: Window Manager
.index dvxWm.h
.index wmInit
.index wmCreateWindow
.index wmDestroyWindow
.index wmRaiseWindow
.index wmSetFocus
.index wmUpdateContentRect
.index wmReallocContentBuf
.index wmMinWindowSize
.index wmAddMenuBar
.index wmAddMenu
.index wmAddMenuItem
.index wmAddSubMenu
.index wmCreateMenu
.index wmDrawChrome
.index wmHitTest
.index wmDragBegin
.index wmResizeBegin
.index wmMaximize
.index wmMinimize
.index wmRestore

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

.h2 Initialization

.h3 wmInit

.code
void wmInit(WindowStackT *stack);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  stack       Window stack to initialize
.endtable

.h2 Window Lifecycle

.h3 wmCreateWindow

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

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.

.table
  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
.endtable

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

.h3 wmDestroyWindow

.code
void wmDestroyWindow(WindowStackT *stack, WindowT *win);
.endcode

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.

.table
  Parameter   Description
  ---------   -----------
  stack       Window stack
  win         Window to destroy
.endtable

.h2 Z-Order and Focus

.h3 wmRaiseWindow

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

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.

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

.h3 wmSetFocus

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

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

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

.h2 Geometry

.h3 wmUpdateContentRect

.code
void wmUpdateContentRect(WindowT *win);
.endcode

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.

.table
  Parameter   Description
  ---------   -----------
  win         Window to update
.endtable

.h3 wmReallocContentBuf

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

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.

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

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

.h3 wmMinWindowSize

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

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

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

.h2 Menu Bar

.h3 wmAddMenuBar

.code
MenuBarT *wmAddMenuBar(WindowT *win);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  win         Window to add menu bar to
.endtable

Returns: Pointer to the new MenuBarT.

.h3 wmDestroyMenuBar

.code
void wmDestroyMenuBar(WindowT *win);
.endcode

Free the menu bar and reclaim the content area.

.table
  Parameter   Description
  ---------   -----------
  win         Window to remove menu bar from
.endtable

.h3 wmAddMenu

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

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

.table
  Parameter   Description
  ---------   -----------
  bar         Menu bar
  label       Menu label text
.endtable

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

.h3 wmAddMenuItem

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

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

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

.h3 wmAddMenuCheckItem

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

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

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

.h3 wmAddMenuRadioItem

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

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

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

.h3 wmAddMenuSeparator

.code
void wmAddMenuSeparator(MenuT *menu);
.endcode

Insert a horizontal separator line. Separators are not interactive.

.table
  Parameter   Description
  ---------   -----------
  menu        Menu to append separator to
.endtable

.h3 wmRemoveMenuItem

.code
bool wmRemoveMenuItem(MenuT *menu, int32_t id);
.endcode

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

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

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

.h3 wmClearMenuItems

.code
void wmClearMenuItems(MenuT *menu);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  menu        Menu to empty
.endtable

.h3 wmMenuItemIsChecked

.code
bool wmMenuItemIsChecked(MenuBarT *bar, int32_t id);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  bar         Menu bar
  id          Command ID to query
.endtable

Returns: true if checked.

.h3 wmMenuItemSetChecked

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

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.

.table
  Parameter   Description
  ---------   -----------
  bar         Menu bar
  id          Command ID
  checked     New checked state
.endtable

.h3 wmMenuItemSetEnabled

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

Enable or disable a menu item by command ID.

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

.h3 wmAddSubMenu

.code
MenuT *wmAddSubMenu(MenuT *parentMenu, const char *label);
.endcode

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

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

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

.h3 wmCreateMenu

.code
MenuT *wmCreateMenu(void);
.endcode

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.

.h3 wmFreeMenu

.code
void wmFreeMenu(MenuT *menu);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  menu        Menu to free
.endtable

.h2 Scrollbars

.h3 wmAddVScrollbar

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

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

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

Returns: Pointer to the new ScrollbarT.

.h3 wmAddHScrollbar

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

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

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

Returns: Pointer to the new ScrollbarT.

.h2 Drawing

.h3 wmDrawChrome

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

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.

.table
  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
.endtable

.h3 wmDrawContent

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

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

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

.h3 wmDrawScrollbars

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

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

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

.h3 wmDrawMinimizedIcons

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

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.

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

.h3 wmDrawVScrollbarAt

.code
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);
.endcode

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.

.table
  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
.endtable

.h2 Hit Testing

.h3 wmHitTest

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

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

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

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

.h3 wmResizeEdgeHit

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

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

.table
  Parameter   Description
  ---------   -----------
  win         Window
  mx, my      Screen coordinates
.endtable

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

.h3 wmMinimizedIconHit

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

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

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

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

.h2 Drag and Resize

.h3 wmDragBegin

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

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

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

.h3 wmDragMove

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

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

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

.h3 wmDragEnd

.code
void wmDragEnd(WindowStackT *stack);
.endcode

End the current drag operation. Clears dragWindow state.

.table
  Parameter   Description
  ---------   -----------
  stack       Window stack
.endtable

.h3 wmResizeBegin

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

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

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

.h3 wmResizeMove

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

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.

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

.h3 wmResizeEnd

.code
void wmResizeEnd(WindowStackT *stack);
.endcode

End the current resize operation. Clears resizeWindow state.

.table
  Parameter   Description
  ---------   -----------
  stack       Window stack
.endtable

.h2 Scrollbar Interaction

.h3 wmScrollbarClick

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

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.

.table
  Parameter   Description
  ---------   -----------
  stack       Window stack
  dl          Dirty list
  idx         Stack index of window
  orient      SCROLL_VERTICAL or SCROLL_HORIZONTAL
  mx, my      Click screen coordinates
.endtable

.h3 wmScrollbarDrag

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

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

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

.h3 wmScrollbarEnd

.code
void wmScrollbarEnd(WindowStackT *stack);
.endcode

End an active scrollbar thumb drag.

.table
  Parameter   Description
  ---------   -----------
  stack       Window stack
.endtable

.h2 Minimize / Maximize / Restore

.h3 wmMaximize

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

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

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

.h3 wmMinimize

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

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

.table
  Parameter   Description
  ---------   -----------
  stack       Window stack
  dl          Dirty list
  win         Window to minimize
.endtable

.h3 wmRestore

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

Restore a maximized window to its pre-maximize geometry.

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

.h3 wmRestoreMinimized

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

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

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

.h2 Minimized Icon Layout

.h3 wmMinimizedIconPos

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

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

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

.h3 wmMinimizedIconRect

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

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

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

.h2 Miscellaneous

.h3 wmSetTitle

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

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

.table
  Parameter   Description
  ---------   -----------
  win         Window
  dl          Dirty list
  title       New title text
.endtable

.h3 wmSetIcon

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

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

.table
  Parameter   Description
  ---------   -----------
  win         Window
  path        Image file path
  d           Display context
.endtable

Returns: 0 on success, -1 on failure.

.topic api.app
.title dvxApp.h -- Layer 5: Application API
.toc 1 dvxApp.h -- Layer 5: Application API
.index dvxApp.h
.index AppContextT
.index dvxInit
.index dvxShutdown
.index dvxRun
.index dvxUpdate
.index dvxQuit
.index dvxCreateWindow
.index dvxCreateWindowCentered
.index dvxDestroyWindow
.index dvxRaiseWindow
.index dvxFitWindow
.index dvxFitWindowH
.index dvxFitWindowW
.index dvxResizeWindow
.index dvxMinimizeWindow
.index dvxMaximizeWindow
.index dvxHideWindow
.index dvxShowWindow
.index dvxInvalidateRect
.index dvxInvalidateWindow
.index dvxSetTitle
.index dvxSetWindowIcon
.index dvxSetBusy
.index dvxGetFont
.index dvxGetColors
.index dvxGetDisplay
.index dvxGetBlitOps
.index dvxGetVideoModes
.index dvxSetColor
.index dvxGetColor
.index dvxApplyColorScheme
.index dvxResetColorScheme
.index dvxLoadTheme
.index dvxSaveTheme
.index dvxColorName
.index dvxColorLabel
.index dvxSetWallpaper
.index dvxSetWallpaperMode
.index dvxSetMouseConfig
.index dvxCreateAccelTable
.index dvxFreeAccelTable
.index dvxAddAccel
.index dvxCascadeWindows
.index dvxTileWindows
.index dvxTileWindowsH
.index dvxTileWindowsV
.index dvxLoadImage
.index dvxLoadImageAlpha
.index dvxLoadImageFromMemory
.index dvxFreeImage
.index dvxImageInfo
.index dvxSaveImage
.index dvxScreenshot
.index dvxWindowScreenshot
.index dvxClipboardCopy
.index dvxClipboardGet
.index dvxResLoadIcon
.index dvxResLoadText
.index dvxResLoadData
.index dvxTextHash
.index dvxChangeVideoMode

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

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

.h2 Initialization and Shutdown

.h3 dvxInit

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

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.

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

Returns: 0 on success, negative on failure.

.h3 dvxShutdown

.code
void dvxShutdown(AppContextT *ctx);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
.endtable

.h3 dvxChangeVideoMode

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

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

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

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

.h2 Event Loop

.h3 dvxRun

.code
void dvxRun(AppContextT *ctx);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
.endtable

.h3 dvxUpdate

.code
bool dvxUpdate(AppContextT *ctx);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
.endtable

Returns: false when the GUI wants to exit.

.h3 dvxQuit

.code
void dvxQuit(AppContextT *ctx);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
.endtable

.h2 Window Management

.h3 dvxCreateWindow

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

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

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

Returns: Pointer to new WindowT.

.h3 dvxCreateWindowCentered

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

Convenience wrapper that centers the window on screen.

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

Returns: Pointer to new WindowT.

.h3 dvxDestroyWindow

.code
void dvxDestroyWindow(AppContextT *ctx, WindowT *win);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  win         Window to destroy
.endtable

.h3 dvxRaiseWindow

.code
void dvxRaiseWindow(AppContextT *ctx, WindowT *win);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  win         Window to raise
.endtable

.h3 dvxFitWindow

.code
void dvxFitWindow(AppContextT *ctx, WindowT *win);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  win         Window to fit
.endtable

.h3 dvxFitWindowW

.code
void dvxFitWindowW(AppContextT *ctx, WindowT *win);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  win         Window to fit
.endtable

.h3 dvxFitWindowH

.code
void dvxFitWindowH(AppContextT *ctx, WindowT *win);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  win         Window to fit
.endtable

.h3 dvxResizeWindow

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

Programmatically resize a window to the specified outer dimensions.

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

.h3 dvxMinimizeWindow

.code
void dvxMinimizeWindow(AppContextT *ctx, WindowT *win);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  win         Window to minimize
.endtable

.h3 dvxMaximizeWindow

.code
void dvxMaximizeWindow(AppContextT *ctx, WindowT *win);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  win         Window to maximize
.endtable

.h3 dvxHideWindow

.code
void dvxHideWindow(AppContextT *ctx, WindowT *win);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  win         Window to hide
.endtable

.h3 dvxShowWindow

.code
void dvxShowWindow(AppContextT *ctx, WindowT *win);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  win         Window to show
.endtable

.h2 Invalidation

.h3 dvxInvalidateRect

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

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.

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

.h3 dvxInvalidateWindow

.code
void dvxInvalidateWindow(AppContextT *ctx, WindowT *win);
.endcode

Mark the entire window content area as dirty.

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  win         Window to invalidate
.endtable

.h2 Window Properties

.h3 dvxSetTitle

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

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  win         Window
  title       New title text
.endtable

.h3 dvxSetWindowIcon

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

Load an icon for a window from an image file.

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  win         Window
  path        Image file path
.endtable

Returns: 0 on success, -1 on failure.

.h3 dvxSetBusy

.code
void dvxSetBusy(AppContextT *ctx, bool busy);
.endcode

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

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

.h2 Accessors

.h3 dvxGetFont

.code
const BitmapFontT *dvxGetFont(const AppContextT *ctx);
.endcode

Get a pointer to the default font.

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
.endtable

Returns: Pointer to the active BitmapFontT.

.h3 dvxGetColors

.code
const ColorSchemeT *dvxGetColors(const AppContextT *ctx);
.endcode

Get a pointer to the current color scheme.

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
.endtable

Returns: Pointer to the active ColorSchemeT.

.h3 dvxGetDisplay

.code
DisplayT *dvxGetDisplay(AppContextT *ctx);
.endcode

Get a pointer to the display context.

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
.endtable

Returns: Pointer to the DisplayT.

.h3 dvxGetBlitOps

.code
const BlitOpsT *dvxGetBlitOps(const AppContextT *ctx);
.endcode

Get a pointer to the blit operations vtable.

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
.endtable

Returns: Pointer to the active BlitOpsT.

.h3 dvxGetVideoModes

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

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

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

Returns: Pointer to the VideoModeInfoT array.

.h2 Color Scheme

.h3 dvxSetColor

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

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

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

.h3 dvxGetColor

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

Get a color's RGB values by ID.

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

.h3 dvxApplyColorScheme

.code
void dvxApplyColorScheme(AppContextT *ctx);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
.endtable

.h3 dvxResetColorScheme

.code
void dvxResetColorScheme(AppContextT *ctx);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
.endtable

.h3 dvxLoadTheme

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

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

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

Returns: true on success.

.h3 dvxSaveTheme

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

Save the current color scheme to a theme file.

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  filename    Output file path
.endtable

Returns: true on success.

.h3 dvxColorName

.code
const char *dvxColorName(ColorIdE id);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  id          Color ID
.endtable

Returns: Static string.

.h3 dvxColorLabel

.code
const char *dvxColorLabel(ColorIdE id);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  id          Color ID
.endtable

Returns: Static string.

.h2 Wallpaper

.h3 dvxSetWallpaper

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

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

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

Returns: true on success.

.h3 dvxSetWallpaperMode

.code
void dvxSetWallpaperMode(AppContextT *ctx, WallpaperModeE mode);
.endcode

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

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

.h2 Mouse Configuration

.h3 dvxSetMouseConfig

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

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

.table
  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)
.endtable

.h2 Accelerators

.h3 dvxCreateAccelTable

.code
AccelTableT *dvxCreateAccelTable(void);
.endcode

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

Returns: Pointer to new AccelTableT.

.h3 dvxFreeAccelTable

.code
void dvxFreeAccelTable(AccelTableT *table);
.endcode

Free an accelerator table and its entries.

.table
  Parameter   Description
  ---------   -----------
  table       Table to free
.endtable

.h3 dvxAddAccel

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

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

.table
  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
.endtable

.h2 Window Arrangement

.h3 dvxCascadeWindows

.code
void dvxCascadeWindows(AppContextT *ctx);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
.endtable

.h3 dvxTileWindows

.code
void dvxTileWindows(AppContextT *ctx);
.endcode

Arrange visible windows in an NxM grid filling the screen.

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
.endtable

.h3 dvxTileWindowsH

.code
void dvxTileWindowsH(AppContextT *ctx);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
.endtable

.h3 dvxTileWindowsV

.code
void dvxTileWindowsV(AppContextT *ctx);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
.endtable

.h2 Image I/O

.h3 dvxLoadImage

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

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

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

Returns: Pixel buffer, or NULL on failure.

.h3 dvxLoadImageFromMemory

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

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

.table
  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
.endtable

Returns: Pixel buffer, or NULL on failure.

.h3 dvxLoadImageAlpha

.code
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);
.endcode

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.

.table
  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)
.endtable

Returns: Pixel buffer, or NULL on failure.

.h3 dvxFreeImage

.code
void dvxFreeImage(uint8_t *data);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  data        Buffer to free
.endtable

.h3 dvxImageInfo

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

Query image dimensions without decoding the full file.

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

Returns: true on success.

.h3 dvxSaveImage

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

Save native-format pixel data to a PNG file.

.table
  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
.endtable

Returns: 0 on success, -1 on failure.

.h2 Screenshots

.h3 dvxScreenshot

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

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  path        Output PNG file path
.endtable

Returns: 0 on success, -1 on failure.

.h3 dvxWindowScreenshot

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

Save a window's content to a PNG file.

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

Returns: 0 on success, -1 on failure.

.h2 Clipboard

.h3 dvxClipboardCopy

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

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

.table
  Parameter   Description
  ---------   -----------
  text        Text to copy
  len         Length in bytes
.endtable

.h3 dvxClipboardGet

.code
const char *dvxClipboardGet(int32_t *outLen);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  outLen      Output: length of clipboard text
.endtable

Returns: Clipboard text, or NULL.

.h2 Resource Loading

.h3 dvxResLoadIcon

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

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

.table
  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
.endtable

Returns: Pixel buffer, or NULL if not found.

.h3 dvxResLoadText

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

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

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

Returns: true on success.

.h3 dvxResLoadData

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

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

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

Returns: Data buffer, or NULL if not found.

.h2 Utilities

.h3 dvxTextHash

.code
uint32_t dvxTextHash(const char *text);
.endcode

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.

.table
  Parameter   Description
  ---------   -----------
  text        Null-terminated string to hash
.endtable

Returns: 32-bit hash value.

.topic api.widget
.title dvxWgt.h -- Widget System
.toc 1 dvxWgt.h -- Widget System
.index dvxWgt.h
.index WidgetT
.index WidgetClassT
.index wgtInitWindow
.index wgtGetContext
.index wgtInvalidate
.index wgtInvalidatePaint
.index wgtSetText
.index wgtGetText
.index wgtSetEnabled
.index wgtSetReadOnly
.index wgtSetFocused
.index wgtGetFocused
.index wgtSetVisible
.index wgtSetName
.index wgtFind
.index wgtDestroy
.index wgtSetTooltip
.index wgtResolveSize
.index wgtLayout
.index wgtPaint
.index wgtSetDebugLayout
.index wgtRegisterClass
.index wgtRegisterApi
.index wgtGetApi
.index wgtRegisterIface
.index wgtGetIface
.index wgtFindByBasName
.index wgtPixels
.index wgtChars
.index wgtPercent

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

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

.table
  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)
.endtable

Universal Callbacks:

.table
  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
.endtable

.h2 Size Specification Macros

.table
  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
.endtable

.h2 Widget Class Flags

.table
  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
.endtable

.h2 Window Integration

.h3 wgtInitWindow

.code
WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win);
.endcode

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.

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  win         Window to initialize
.endtable

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

.h2 Widget Operations

.h3 wgtGetContext

.code
AppContextT *wgtGetContext(const WidgetT *w);
.endcode

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.

.table
  Parameter   Description
  ---------   -----------
  w           Any widget in the tree
.endtable

Returns: Pointer to the AppContextT.

.h3 wgtInvalidate

.code
void wgtInvalidate(WidgetT *w);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  w           Widget to invalidate
.endtable

.h3 wgtInvalidatePaint

.code
void wgtInvalidatePaint(WidgetT *w);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  w           Widget to repaint
.endtable

.h3 wgtSetText

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

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

.table
  Parameter   Description
  ---------   -----------
  w           Widget
  text        New text
.endtable

.h3 wgtGetText

.code
const char *wgtGetText(const WidgetT *w);
.endcode

Get the widget's current text content.

.table
  Parameter   Description
  ---------   -----------
  w           Widget
.endtable

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

.h3 wgtSetEnabled

.code
void wgtSetEnabled(WidgetT *w, bool enabled);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  w           Widget
  enabled     true = enabled, false = disabled
.endtable

.h3 wgtSetReadOnly

.code
void wgtSetReadOnly(WidgetT *w, bool readOnly);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  w           Widget
  readOnly    true = read-only
.endtable

.h3 wgtSetFocused

.code
void wgtSetFocused(WidgetT *w);
.endcode

Set keyboard focus to a widget.

.table
  Parameter   Description
  ---------   -----------
  w           Widget to focus
.endtable

.h3 wgtGetFocused

.code
WidgetT *wgtGetFocused(void);
.endcode

Get the currently focused widget.

Returns: Focused widget, or NULL.

.h3 wgtSetVisible

.code
void wgtSetVisible(WidgetT *w, bool visible);
.endcode

Show or hide a widget.

.table
  Parameter   Description
  ---------   -----------
  w           Widget
  visible     true = visible, false = hidden
.endtable

.h3 wgtSetName

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

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

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

.h3 wgtFind

.code
WidgetT *wgtFind(WidgetT *root, const char *name);
.endcode

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

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

Returns: Matching widget, or NULL.

.h3 wgtDestroy

.code
void wgtDestroy(WidgetT *w);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  w           Widget to destroy
.endtable

.h3 wgtSetTooltip

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

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

.table
  Parameter   Description
  ---------   -----------
  w           Widget
  text        Tooltip text, or NULL
.endtable

.h3 widgetOnResize

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

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.

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

.h2 Layout

.h3 wgtResolveSize

.code
int32_t wgtResolveSize(int32_t taggedSize, int32_t parentSize, int32_t charWidth);
.endcode

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

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

Returns: Size in pixels.

.h3 wgtLayout

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

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.

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

.h3 wgtPaint

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

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.

.table
  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
.endtable

.h2 Debug

.h3 wgtSetDebugLayout

.code
void wgtSetDebugLayout(AppContextT *ctx, bool enabled);
.endcode

Draw colored borders around layout containers for debugging.

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

.h2 Dynamic Widget Registration

.h3 wgtRegisterClass

.code
int32_t wgtRegisterClass(const WidgetClassT *wclass);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  wclass      Widget class vtable to register
.endtable

Returns: Assigned type ID.

.h3 wgtRegisterApi

.code
void wgtRegisterApi(const char *name, const void *api);
.endcode

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.

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

.h3 wgtGetApi

.code
const void *wgtGetApi(const char *name);
.endcode

Retrieve a registered widget API struct by name.

.table
  Parameter   Description
  ---------   -----------
  name        Widget type name
.endtable

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

.h2 Widget Interface Descriptors

.h3 wgtRegisterIface

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

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

.table
  Parameter   Description
  ---------   -----------
  name        Widget type name
  iface       Interface descriptor
.endtable

.h3 wgtGetIface

.code
const WgtIfaceT *wgtGetIface(const char *name);
.endcode

Retrieve an interface descriptor by widget type name.

.table
  Parameter   Description
  ---------   -----------
  name        Widget type name
.endtable

Returns: Interface descriptor, or NULL.

.h3 wgtFindByBasName

.code
const char *wgtFindByBasName(const char *basName);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  basName     VB-style widget name
.endtable

Returns: Internal type name, or NULL.

.h3 wgtIfaceCount

.code
int32_t wgtIfaceCount(void);
.endcode

Return the number of registered widget interfaces.

Returns: Count of registered interfaces.

.h3 wgtIfaceAt

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

Get a registered widget interface by index.

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

Returns: Interface descriptor.

.h3 wgtIfaceGetPath

.code
const char *wgtIfaceGetPath(const char *name);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  name        Widget type name
.endtable

Returns: File path string.

.h3 wgtIfaceSetPath

.code
void wgtIfaceSetPath(const char *name, const char *path);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  name        Widget type name
  path        DXE file path
.endtable

.h3 wgtIfaceGetPathIndex

.code
int32_t wgtIfaceGetPathIndex(const char *name);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  name        Widget type name
.endtable

Returns: 1-based index within the DXE file.

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

.table
  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
.endtable

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

.table
  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
.endtable

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

.h2 Widget Class Dispatch Table

.h3 WidgetClassT

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

.table
  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
.endtable

.h2 Size Encoding Constants

.table
  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
.endtable

.h2 Widget Interface Descriptors

.h3 WgtPropDescT

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

.table
  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
.endtable

.h3 WgtMethodDescT

Describes an invokable method on a widget type.

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

.h3 WgtEventDescT

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

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

.h3 WgtIfaceT

Top-level interface descriptor registered by each widget DXE.

.table
  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)
.endtable

.h2 Property Data Type Constants

.table
  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
.endtable

.h2 Create Function Signature Constants

.table
  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
.endtable

WGT_MAX_CREATE_ARGS is 3.

.topic api.dialog
.title dvxDlg.h -- Modal Dialogs
.toc 1 dvxDlg.h -- Modal Dialogs
.index dvxDlg.h
.index dvxMessageBox
.index dvxFileDialog
.index dvxInputBox
.index dvxIntInputBox
.index dvxChoiceDialog
.index dvxPromptSave
.index dvxErrorBox
.index dvxInfoBox

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

.h2 Message Box Flags

Button configurations (low nibble):

.table
  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
.endtable

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

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

Return values:

.table
  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
.endtable

.h2 dvxMessageBox

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

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.

.table
  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
.endtable

Returns: ID_xxx of the button that was pressed.

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

.h2 dvxErrorBox

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

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

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

Returns: ID_OK.

.h2 dvxInfoBox

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

Convenience wrapper for MB_OK | MB_ICONINFO.

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  title       Dialog title
  message     Informational message
.endtable

Returns: ID_OK.

.h2 File Dialog

.h3 FileFilterT

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

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

.h3 File Dialog Flags

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

.h3 dvxFileDialog

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

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

.table
  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
.endtable

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

.h2 Input Boxes

.h3 dvxInputBox

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

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

.table
  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
.endtable

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

.h3 dvxIntInputBox

.code
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);
.endcode

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

.table
  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
.endtable

Returns: true if OK pressed, false if cancelled.

.h2 Choice Dialog

.h3 dvxChoiceDialog

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

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

.table
  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
.endtable

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

.h2 Save Prompt

Return codes for dvxPromptSave:

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

.h3 dvxPromptSave

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

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

.table
  Parameter   Description
  ---------   -----------
  ctx         Application context
  title       Document name for message context
.endtable

Returns: DVX_SAVE_YES, DVX_SAVE_NO, or DVX_SAVE_CANCEL.

.topic api.resource
.title dvxRes.h -- Resource System
.toc 1 dvxRes.h -- Resource System
.index dvxRes.h
.index Resources
.index DvxResHandleT
.index dvxResOpen
.index dvxResRead
.index dvxResFind
.index dvxResClose
.index dvxResAppend
.index dvxResRemove

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

.h2 File Layout

.code
[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)
.endcode

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

.h2 Constants

.table
  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
.endtable

.h2 Structures

.h3 DvxResDirEntryT

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

.table
  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)
.endtable

.h3 DvxResFooterT

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

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

.h3 DvxResHandleT

Opaque runtime handle representing an open resource block.

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

.h2 Runtime API

.h3 dvxResOpen

.code
DvxResHandleT *dvxResOpen(const char *path);
.endcode

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.

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

Returns: Handle pointer, or NULL.

.h3 dvxResRead

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

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

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

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

.h3 dvxResFind

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

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

.table
  Parameter   Description
  ---------   -----------
  h           Resource handle
  name        Resource name
.endtable

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

.h3 dvxResClose

.code
void dvxResClose(DvxResHandleT *h);
.endcode

Close a resource handle and free its memory.

.table
  Parameter   Description
  ---------   -----------
  h           Handle to close
.endtable

.h3 dvxResAppend

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

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.

.table
  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
.endtable

Returns: 0 on success, -1 on failure.

.h3 dvxResRemove

.code
int32_t dvxResRemove(const char *path, const char *name);
.endcode

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.

.table
  Parameter   Description
  ---------   -----------
  path        Target DXE path
  name        Resource name to remove
.endtable

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

.h2 See Also

.link api.app dvxResLoadIcon / dvxResLoadText / dvxResLoadData -- higher-level helpers on top of this API

.topic api.prefs
.title dvxPrefs.h -- Preferences System
.toc 1 dvxPrefs.h -- Preferences System
.index dvxPrefs.h
.index Preferences
.index PrefsHandleT
.index prefsLoad
.index prefsSave
.index prefsGetString
.index prefsGetInt
.index prefsGetBool
.index prefsSetString
.index prefsSetInt
.index prefsSetBool

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

.h2 Constants

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

.h2 Types

.h3 PrefsHandleT

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

.h2 Lifecycle

.h3 prefsCreate

.code
PrefsHandleT *prefsCreate(void);
.endcode

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.

.h3 prefsLoad

.code
PrefsHandleT *prefsLoad(const char *filename);
.endcode

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.

.table
  Parameter   Description
  ---------   -----------
  filename    Path to INI file
.endtable

Returns: Handle, or NULL on allocation failure.

.h3 prefsSave

.code
bool prefsSave(PrefsHandleT *h);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  h           Preferences handle
.endtable

Returns: true on success.

.h3 prefsSaveAs

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

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

.table
  Parameter   Description
  ---------   -----------
  h           Preferences handle
  filename    Output file path
.endtable

Returns: true on success.

.h3 prefsClose

.code
void prefsClose(PrefsHandleT *h);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  h           Handle to close
.endtable

.h2 Getters

.h3 prefsGetString

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

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

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

Returns: Key value or defaultVal.

.h3 prefsGetInt

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

Retrieve an integer value. Supports decimal and negative numbers.

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

Returns: Parsed int, or defaultVal.

.h3 prefsGetBool

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

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

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

Returns: Parsed bool, or defaultVal.

.h2 Setters

.h3 prefsSetString

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

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

.h3 prefsSetInt

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

Set an integer value (stored in decimal).

.h3 prefsSetBool

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

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

.h3 prefsRemove

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

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

.topic api.mem
.title dvxMem.h -- Memory Tracking
.toc 1 dvxMem.h -- Memory Tracking
.index dvxMem.h
.index dvxMalloc
.index dvxFree
.index dvxCalloc
.index dvxRealloc
.index dvxStrdup
.index dvxMemGetAppUsage
.index dvxMemResetApp
.index dvxMemSnapshotLoad

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

.h2 Globals

.h3 dvxMemAppIdPtr

.code
extern int32_t *dvxMemAppIdPtr;
.endcode

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.

.h2 Allocation Wrappers

.h3 dvxMalloc

.code
void *dvxMalloc(size_t size);
.endcode

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

.h3 dvxCalloc

.code
void *dvxCalloc(size_t nmemb, size_t size);
.endcode

Tracked calloc.

.h3 dvxRealloc

.code
void *dvxRealloc(void *ptr, size_t size);
.endcode

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

.h3 dvxFree

.code
void dvxFree(void *ptr);
.endcode

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.

.h3 dvxStrdup

.code
char *dvxStrdup(const char *s);
.endcode

Tracked strdup.

.h2 Accounting

.h3 dvxMemSnapshotLoad

.code
void dvxMemSnapshotLoad(int32_t appId);
.endcode

Record a baseline memory snapshot for the given app. Called right before app code starts so later calls to dvxMemGetAppUsage can report net growth.

.table
  Parameter   Description
  ---------   -----------
  appId       App ID to snapshot
.endtable

.h3 dvxMemGetAppUsage

.code
uint32_t dvxMemGetAppUsage(int32_t appId);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  appId       App ID to query
.endtable

Returns: Bytes allocated for this app.

.h3 dvxMemResetApp

.code
void dvxMemResetApp(int32_t appId);
.endcode

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

.table
  Parameter   Description
  ---------   -----------
  appId       App ID to flush
.endtable

.topic api.widgetplugin
.title dvxWgtP.h -- Widget Plugin API
.toc 1 dvxWgtP.h -- Widget Plugin API
.index dvxWgtP.h
.index widgetAlloc
.index widgetAddChild
.index widgetDestroyChildren
.index widgetHitTest
.index widgetFindNextFocusable
.index widgetFindPrevFocusable
.index widgetFindByAccel
.index widgetDrawScrollbarH
.index widgetDrawScrollbarV

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

.h2 Validation Macros

.h3 VALIDATE_WIDGET / VALIDATE_WIDGET_VOID

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

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.

.h2 Core Constants

.table
  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
.endtable

.h2 Inline Helpers

.h3 clampInt

.code
static inline int32_t clampInt(int32_t val, int32_t lo, int32_t hi);
.endcode

Clamp val into the [lo, hi] range.

.h3 drawTextEmbossed

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

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.

.h3 drawTextAccelEmbossed

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

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

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

.table
  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)
  sPollWidgetCount      int32_t    Count of widgets with WCLASS_NEEDS_POLL flag set
  sPollWidgets          WidgetT**  Dynamic array of poll widgets (stb_ds)
  sCursorBlinkFn        fn ptr     Callback invoked when the blink flips (repaints focused text)
.endtable

.h2 Core Widget Functions

.h3 widgetAlloc

.code
WidgetT *widgetAlloc(WidgetT *parent, int32_t type);
.endcode

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

.h3 widgetAddChild

.code
void widgetAddChild(WidgetT *parent, WidgetT *child);
.endcode

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

.h3 widgetRemoveChild

.code
void widgetRemoveChild(WidgetT *parent, WidgetT *child);
.endcode

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

.h3 widgetDestroyChildren

.code
void widgetDestroyChildren(WidgetT *w);
.endcode

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

.h2 Focus Management

.h3 widgetFindNextFocusable

.code
WidgetT *widgetFindNextFocusable(WidgetT *root, WidgetT *after);
.endcode

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

.h3 widgetFindPrevFocusable

.code
WidgetT *widgetFindPrevFocusable(WidgetT *root, WidgetT *before);
.endcode

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

.h3 widgetFindByAccel

.code
WidgetT *widgetFindByAccel(WidgetT *root, char key);
.endcode

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

.h2 Hit Testing

.h3 widgetHitTest

.code
WidgetT *widgetHitTest(WidgetT *w, int32_t x, int32_t y);
.endcode

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.

.h2 Utility Queries

.h3 widgetCountVisibleChildren

.code
int32_t widgetCountVisibleChildren(const WidgetT *w);
.endcode

Count children whose visible flag is true.

.h3 widgetFrameBorderWidth

.code
int32_t widgetFrameBorderWidth(const WidgetT *w);
.endcode

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

.h3 widgetIsFocusable

.code
bool widgetIsFocusable(int32_t type);
.endcode

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

.h3 widgetIsHorizContainer

.code
bool widgetIsHorizContainer(int32_t type);
.endcode

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

.h3 multiClickDetect

.code
int32_t multiClickDetect(int32_t vx, int32_t vy);
.endcode

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

.h2 Clipboard

.h3 clipboardCopy

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

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

.h3 clipboardGet

.code
const char *clipboardGet(int32_t *outLen);
.endcode

Retrieve clipboard text.

.h3 clipboardMaxLen

.code
int32_t clipboardMaxLen(void);
.endcode

Return the fixed capacity of the clipboard buffer in bytes.

.h2 Scrollbar Helpers

.h3 ScrollHitE

Scrollbar hit-test result.

.table
  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
.endtable

.h3 widgetScrollbarThumb

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

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

.h3 widgetDrawScrollbarV / widgetDrawScrollbarVEx

.code
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);
.endcode

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.

.h3 widgetDrawScrollbarH / widgetDrawScrollbarHEx

.code
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);
.endcode

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

.h3 widgetScrollbarHitTest

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

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

.h2 Layout Functions

.h3 widgetCalcMinSizeBox / widgetCalcMinSizeTree

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

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

.h3 widgetLayoutBox / widgetLayoutChildren

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

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

.h2 Event Dispatch

.h3 widgetOnPaint / widgetOnMouse / widgetOnKey / etc.

.code
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);
.endcode

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

.h3 widgetManageScrollbars

.code
void widgetManageScrollbars(WindowT *win, AppContextT *ctx);
.endcode

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

.h2 Paint Helpers

.h3 widgetPaintOne

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

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

.h3 widgetPaintOverlays

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

Paint the overlay pass: dropdown popups and tooltips drawn on top of the main tree.

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

.h3 widgetPressableOnMouse / widgetPressableOnKey / widgetPressableOnDragUpdate / widgetPressableOnDragEnd / widgetPressableOnAccelActivate

.code
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);
.endcode

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.

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

.h3 widgetTextGet / widgetTextSet

.code
const char *widgetTextGet(const WidgetT *w);
void        widgetTextSet(WidgetT *w, const char *text);
.endcode

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.

.h2 Class Table

.h3 widgetClassTable

.code
extern const WidgetClassT **widgetClassTable;
.endcode

stb_ds dynamic array. Each widget DXE appends its class pointer via wgtRegisterClass() during wgtRegister(). Indexed by the runtime type ID assigned at registration.

.topic api.platform
.title platform/dvxPlat.h -- Platform Layer
.toc 1 platform/dvxPlat.h -- Platform Layer
.index dvxPlat.h
.index Platform Layer
.index PlatformKeyEventT
.index platformVideoInit
.index platformFlushRect
.index platformMousePoll
.index platformKeyboardRead
.index dvxLog

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

.h2 Constants

.table
  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
.endtable

.h2 Types

.h3 PlatformKeyEventT

Keyboard event with ASCII and scancode separated. Extended keys (arrows, F-keys) have ascii == 0 and a non-zero scancode.

.table
  Field       Description
  -----       -----------
  ascii       ASCII value, 0 for extended/function keys
  scancode    PC scancode (e.g. 0x48 = Up, 0x50 = Down)
.endtable

.h3 PlatformLogFnT

.code
typedef void (*PlatformLogFnT)(const char *fmt, ...);
.endcode

Log function signature used by the crash handler.

.h3 PlatformSymOverrideT

Name/function-pointer pair for registering symbol overrides with the DXE loader.

.table
  Field   Description
  -----   -----------
  name    Symbol name as seen by DXEs
  func    Function pointer to use instead of the default
.endtable

.h2 Lifecycle

.h3 dvxLog

.code
void dvxLog(const char *fmt, ...);
.endcode

Append a formatted line to dvx.log. Implemented in dvx.exe and exported to every DXE via the loader.

.h3 platformInit

.code
void platformInit(void);
.endcode

One-time platform initialization. On DOS this installs signal handlers for clean shutdown on Ctrl+C/Ctrl+Break.

.h3 platformYield

.code
void platformYield(void);
.endcode

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.

.h2 Video

.h3 platformVideoInit / platformVideoShutdown

.code
int32_t platformVideoInit(DisplayT *d, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);
void    platformVideoShutdown(DisplayT *d);
.endcode

Low-level video mode setup and teardown. Called by videoInit / videoShutdown.

.h3 platformVideoEnumModes

.code
void platformVideoEnumModes(void (*cb)(int32_t w, int32_t h, int32_t bpp, void *userData), void *userData);
.endcode

Enumerate LFB-capable graphics modes. Invokes cb once per available mode.

.h3 platformVideoSetPalette

.code
void platformVideoSetPalette(const uint8_t *pal, int32_t firstEntry, int32_t count);
.endcode

Program the VGA/VESA DAC palette registers (8-bit mode only).

.h3 platformVideoFreeBuffers

.code
void platformVideoFreeBuffers(DisplayT *d);
.endcode

Free the backbuffer and palette without restoring text mode. Used when switching between graphics modes live.

.h2 Framebuffer Flush

.h3 platformFlushRect

.code
void platformFlushRect(const DisplayT *d, const RectT *r);
.endcode

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.

.h2 Span Operations

.h3 platformSpanFill8/16/32

.code
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);
.endcode

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.

.h3 platformSpanCopy8/16/32

.code
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);
.endcode

Copy count pixels from src to dst. On DOS these use rep movsd.

.h2 Mouse Input

.h3 platformMouseInit

.code
void platformMouseInit(int32_t screenW, int32_t screenH);
.endcode

Initialize the mouse driver and constrain movement to the screen bounds.

.h3 platformMousePoll

.code
void platformMousePoll(int32_t *mx, int32_t *my, int32_t *buttons);
.endcode

Poll current mouse state. Buttons is a bitmask: bit 0 = left, bit 1 = right, bit 2 = middle.

.h3 platformMouseWheelInit / platformMouseWheelPoll

.code
bool    platformMouseWheelInit(void);
int32_t platformMouseWheelPoll(void);
.endcode

Detect and activate the CuteMouse Wheel API. platformMouseWheelPoll returns the accumulated delta (positive = scroll down) since the last poll.

.h3 platformMouseSetAccel / platformMouseSetMickeys

.code
void platformMouseSetAccel(int32_t threshold);
void platformMouseSetMickeys(int32_t horizMickeys, int32_t vertMickeys);
.endcode

Set the double-speed threshold and mickey-to-pixel ratio. See dvxSetMouseConfig for a higher-level interface.

.h3 platformMouseWarp

.code
void platformMouseWarp(int32_t x, int32_t y);
.endcode

Move the mouse cursor to an absolute screen position. Used to clamp the cursor to window edges during resize.

.h2 Keyboard Input

.h3 platformKeyboardGetModifiers

.code
int32_t platformKeyboardGetModifiers(void);
.endcode

Return the current modifier key state in BIOS shift-state format.

.h3 platformKeyboardRead

.code
bool platformKeyboardRead(PlatformKeyEventT *evt);
.endcode

Non-blocking read of the next key from the keyboard buffer. Returns true if a key was available.

.h3 platformKeyUpInit / platformKeyUpShutdown / platformKeyUpRead

.code
void platformKeyUpInit(void);
void platformKeyUpShutdown(void);
bool platformKeyUpRead(PlatformKeyEventT *evt);
.endcode

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.

.h3 platformAltScanToChar

.code
char platformAltScanToChar(int32_t scancode);
.endcode

Translate an Alt+key scancode to its corresponding ASCII character. Returns 0 for non-printable scancodes.

.h2 System Information

.h3 platformGetSystemInfo

.code
const char *platformGetSystemInfo(const DisplayT *display);
.endcode

Return a pre-formatted text string with hardware/OS information (CPU, clock, memory, video, mouse, disks). Valid for the lifetime of the process.

.h3 platformGetMemoryInfo

.code
bool platformGetMemoryInfo(uint32_t *totalKb, uint32_t *freeKb);
.endcode

Query total and free physical memory.

.h2 File System

.h3 platformValidateFilename

.code
const char *platformValidateFilename(const char *name);
.endcode

Validate a filename against platform-specific rules (8.3 on DOS). Returns NULL if valid, or a human-readable error string.

.h3 platformMkdirRecursive

.code
int32_t platformMkdirRecursive(const char *path);
.endcode

Create a directory and all parent directories (like mkdir -p). Existing directories are not an error.

.h3 platformChdir

.code
int32_t platformChdir(const char *path);
.endcode

Change the working directory, including drive letter on DOS (calls setdisk() first when the path starts with "X:").

.h3 platformPathDirEnd

.code
char *platformPathDirEnd(const char *path);
.endcode

Return a pointer to the last directory separator in path, or NULL. On DOS accepts both "/" and "\\".

.h3 platformPathBaseName

.code
const char *platformPathBaseName(const char *path);
.endcode

Return a pointer to the leaf (basename) portion of path.

.h3 platformReadFile

.code
char *platformReadFile(const char *path, int32_t *outLen);
.endcode

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.

.h3 platformGlobMatch

.code
bool platformGlobMatch(const char *pattern, const char *name);
.endcode

Simple glob pattern match. Case-insensitive. Supports * (zero or more chars) and ? (single char).

.h3 platformLineEnding / platformStripLineEndings

.code
const char *platformLineEnding(void);
int32_t     platformStripLineEndings(char *buf, int32_t len);
.endcode

Return the native line ending string, or strip line-ending characters from a buffer in place.

.h2 String Helpers

.h3 dvxSkipWs

.code
const char *dvxSkipWs(const char *s);
.endcode

Advance past leading spaces and tabs. Returns s unchanged if NULL or already non-whitespace.

.h3 dvxTrimRight

.code
int32_t dvxTrimRight(char *buf);
.endcode

Strip trailing spaces, tabs, carriage returns, and newlines from buf in place. Returns the new length.

.h2 DXE Module Support

.h3 platformRegisterDxeExports

.code
void platformRegisterDxeExports(void);
.endcode

Register platform and C runtime symbols with the dynamic module loader so DXE modules can resolve them at load time.

.h3 platformRegisterSymOverrides

.code
void platformRegisterSymOverrides(const PlatformSymOverrideT *entries);
.endcode

Register function pointer overrides for subsequently loaded modules. entries is terminated by {NULL, NULL}.

.h2 Crash Recovery

.h3 platformInstallCrashHandler

.code
void platformInstallCrashHandler(jmp_buf *recoveryBuf, volatile int *crashSignal, PlatformLogFnT logFn);
.endcode

Install signal handlers for SIGSEGV, SIGFPE, SIGILL. On crash, logs platform-specific diagnostics via logFn, stores the signal in *crashSignal, then longjmps to recoveryBuf.

.h3 platformLogCrashDetail

.code
void platformLogCrashDetail(int sig, PlatformLogFnT logFn);
.endcode

Log platform-specific crash diagnostics. Called internally from the crash handler and exposed for manual invocation.

.h2 VGA Splash Screen

.h3 platformSplashInit / platformSplashShutdown

.code
void platformSplashInit(void);
void platformSplashShutdown(void);
.endcode

Enter/leave VGA mode 13h (320x200x256) used for the boot splash.

.h3 platformSplashLoadRaw

.code
bool platformSplashLoadRaw(const char *path);
.endcode

Load and display a raw splash file (768-byte palette + 64000-byte pixel data).

.h3 platformSplashFillRect

.code
void platformSplashFillRect(int32_t x, int32_t y, int32_t w, int32_t h, uint8_t color);
.endcode

Fill a rectangle on the mode 13h screen with a palette index. Used to draw the progress bar during module loading.
