AI_Slop/DVX_GUI
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
DVX_GUI/docs/dvx_system_reference.html

5372 lines
301 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Welcome!</title>
<style>
body { font-family: sans-serif; margin: 0; padding: 0; display: flex; }
nav { width: 250px; min-width: 250px; background: #f0f0f0; padding: 16px;
border-right: 1px solid #ccc; height: 100vh; overflow-y: auto;
position: sticky; top: 0; box-sizing: border-box; }
nav ul { list-style: none; padding-left: 16px; margin: 4px 0; }
nav > ul { padding-left: 0; }
nav a { text-decoration: none; color: #0066cc; }
nav a:hover { text-decoration: underline; }
main { flex: 1; padding: 24px 32px; max-width: 800px; }
h1 { border-bottom: 2px solid #333; padding-bottom: 4px; }
h2 { border-bottom: 1px solid #999; padding-bottom: 2px; margin-top: 32px; }
h3 { margin-top: 24px; }
pre { background: #f8f8f8; border: 1px solid #ddd; padding: 8px;
overflow-x: auto; font-size: 14px; }
blockquote { background: #fffde7; border-left: 4px solid #ffc107;
padding: 8px 12px; margin: 12px 0; }
hr { border: none; border-top: 1px solid #ccc; margin: 24px 0; }
img { max-width: 100%; }
.topic { margin-bottom: 48px; }
</style>
</head>
<body>
<nav>
<h3>Contents</h3>
<ul>
<li><a href="#sys.welcome">Welcome!</a></li>
<li><strong>Architecture</strong>
<ul>
<li><a href="#arch.overview">System Overview</a>
<ul>
<li><a href="#arch.layers">Five-Layer Architecture</a></li>
<li><a href="#arch.pipeline">Display Pipeline</a></li>
<li><a href="#arch.windows">Window System</a></li>
<li><a href="#arch.widgets">Widget System</a></li>
<li><a href="#arch.dxe">DXE Module System</a></li>
<li><a href="#arch.events">Event Model</a></li>
<li><a href="#arch.fonts">Font System</a></li>
<li><a href="#arch.colors">Color System</a></li>
<li><a href="#arch.platform">Platform Layer</a></li>
<li><a href="#arch.build">Build System</a></li>
</ul>
</li>
<li><a href="#api.overview">DVX GUI API Reference</a>
<ul>
<li><a href="#api.types">dvxTypes.h -- Shared Type Definitions</a></li>
<li><a href="#api.cursor">dvxCursor.h -- Cursor Definitions</a></li>
<li><a href="#api.video">dvxVideo.h -- Layer 1: Video Backend</a></li>
<li><a href="#api.draw">dvxDraw.h -- Layer 2: Drawing Primitives</a></li>
<li><a href="#api.comp">dvxComp.h -- Layer 3: Compositor</a></li>
<li><a href="#api.wm">dvxWm.h -- Layer 4: Window Manager</a></li>
<li><a href="#api.app">dvxApp.h -- Layer 5: Application API</a></li>
<li><a href="#api.widget">dvxWidget.h -- Widget System</a></li>
</ul>
</li>
</ul>
</li>
<li><strong>Libraries</strong>
<ul>
<li><a href="#libtasks">libtasks -- Cooperative Task Switching</a></li>
<li><a href="#shell.overview">DVX Shell Library</a>
<ul>
<li><a href="#shell.types">Types and Constants</a></li>
<li><a href="#shell.lifecycle">Lifecycle API</a></li>
<li><a href="#shell.query">Query API</a></li>
<li><a href="#shell.config">Configuration API</a></li>
<li><a href="#shell.desktop">Desktop Callbacks</a></li>
<li><a href="#shell.info">System Information</a></li>
</ul>
</li>
<li><a href="#sql.overview">dvxSql -- SQL Database Interface</a>
<ul>
<li><a href="#sql.db">Database Operations</a></li>
<li><a href="#sql.cursor">Cursor Operations</a></li>
<li><a href="#sql.utility">Utility Functions</a></li>
<li><a href="#sql.example">Example Usage</a></li>
</ul>
</li>
<li><a href="#lib.texthelp">Text Help Library</a>
<ul>
<li><a href="#lib.texthelp.cursorblink">wgtUpdateCursorBlink</a></li>
<li><a href="#lib.texthelp.clearother">clearOtherSelections</a></li>
<li><a href="#lib.texthelp.iswordchar">isWordChar</a></li>
<li><a href="#lib.texthelp.wordend">wordEnd</a></li>
<li><a href="#lib.texthelp.wordstart">wordStart</a></li>
<li><a href="#lib.texthelp.dragupdate">widgetTextEditDragUpdateLine</a></li>
<li><a href="#lib.texthelp.mouseclick">widgetTextEditMouseClick</a></li>
<li><a href="#lib.texthelp.onkey">widgetTextEditOnKey</a></li>
<li><a href="#lib.texthelp.paintline">widgetTextEditPaintLine</a></li>
</ul>
</li>
<li><a href="#lib.listhelp">List Helper Library</a></li>
<li><a href="#lib.taskmgr">Task Manager</a></li>
<li><a href="#lib.serial">Serial Stack</a>
<ul>
<li><a href="#lib.serial.rs232">RS-232 UART Driver</a></li>
<li><a href="#lib.serial.packet">Packet Transport</a></li>
<li><a href="#lib.serial.security">Security (DH + XTEA)</a></li>
<li><a href="#lib.serial.seclink">Secure Link</a></li>
</ul>
</li>
<li><a href="#lib.basrt">BASIC Runtime Library</a>
<ul>
<li><a href="#lib.basrt.values">Value System</a></li>
<li><a href="#lib.basrt.vm">Virtual Machine</a></li>
</ul>
</li>
</ul>
</li>
<li><strong>Widgets</strong>
<ul>
<li><a href="#widget.base">Widget System</a></li>
<li><a href="#widget.ansiterm">AnsiTerm</a></li>
<li><a href="#widget.box">Layout Containers</a></li>
<li><a href="#widget.box">Box (VBox / HBox / Frame)</a></li>
<li><a href="#widget.button">Button</a></li>
<li><a href="#widget.canvas">Canvas</a></li>
<li><a href="#widget.checkbox">Checkbox</a></li>
<li><a href="#widget.combobox">ComboBox</a></li>
<li><a href="#widget.datactrl">Data Widgets</a></li>
<li><a href="#widget.datactrl">DataCtrl</a></li>
<li><a href="#widget.dbgrid">DbGrid</a></li>
<li><a href="#widget.dropdown">Dropdown</a></li>
<li><a href="#widget.imagebutton">ImageButton</a></li>
<li><a href="#widget.image">Display Widgets</a></li>
<li><a href="#widget.image">Image</a></li>
<li><a href="#widget.label">Label</a></li>
<li><a href="#widget.listbox">ListBox</a></li>
<li><a href="#widget.listview">ListView</a></li>
<li><a href="#widget.progressbar">ProgressBar</a></li>
<li><a href="#widget.radio">Radio Button</a></li>
<li><a href="#widget.scrollpane">ScrollPane</a></li>
<li><a href="#widget.separator">Separator</a></li>
<li><a href="#widget.slider">Slider</a></li>
<li><a href="#widget.spacer">Spacer</a></li>
<li><a href="#widget.spinner">Spinner</a></li>
<li><a href="#widget.splitter">Splitter</a></li>
<li><a href="#widget.statusbar">StatusBar</a></li>
<li><a href="#widget.tabcontrol">TabControl</a></li>
<li><a href="#widget.textinput">Input Widgets</a></li>
<li><a href="#widget.textinput">TextInput / TextArea</a></li>
<li><a href="#widget.timer">Non-Visual Widgets</a></li>
<li><a href="#widget.timer">Timer</a></li>
<li><a href="#widget.toolbar">Container Widgets</a></li>
<li><a href="#widget.toolbar">Toolbar</a></li>
<li><a href="#widget.treeview">TreeView</a></li>
<li><a href="#widget.wrapbox">WrapBox</a></li>
</ul>
</li>
</ul>
<h3>Index</h3>
<ul>
<li><a href="#arch.overview">DVX</a></li>
<li><a href="#arch.overview">Architecture</a></li>
<li><a href="#arch.overview">DJGPP</a></li>
<li><a href="#arch.overview">DPMI</a></li>
<li><a href="#arch.layers">Layers</a></li>
<li><a href="#arch.layers">dvxVideo</a></li>
<li><a href="#arch.layers">dvxDraw</a></li>
<li><a href="#arch.layers">dvxComp</a></li>
<li><a href="#arch.layers">dvxWm</a></li>
<li><a href="#arch.layers">dvxApp</a></li>
<li><a href="#arch.pipeline">Display Pipeline</a></li>
<li><a href="#arch.pipeline">Backbuffer</a></li>
<li><a href="#arch.pipeline">Linear Framebuffer</a></li>
<li><a href="#arch.pipeline">LFB</a></li>
<li><a href="#arch.pipeline">Dirty Rects</a></li>
<li><a href="#arch.pipeline">Double Buffer</a></li>
<li><a href="#arch.pipeline">Compositing</a></li>
<li><a href="#arch.pipeline">DisplayT</a></li>
<li><a href="#arch.pipeline">BlitOpsT</a></li>
<li><a href="#arch.pipeline">DirtyListT</a></li>
<li><a href="#arch.windows">Window</a></li>
<li><a href="#arch.windows">WindowT</a></li>
<li><a href="#arch.windows">Z-Order</a></li>
<li><a href="#arch.windows">Chrome</a></li>
<li><a href="#arch.windows">Hit Testing</a></li>
<li><a href="#arch.windows">Menu System</a></li>
<li><a href="#arch.windows">Minimized Windows</a></li>
<li><a href="#arch.windows">Window Stack</a></li>
<li><a href="#arch.windows">Menus</a></li>
<li><a href="#arch.windows">Submenus</a></li>
<li><a href="#arch.widgets">Widgets</a></li>
<li><a href="#arch.widgets">WidgetT</a></li>
<li><a href="#arch.widgets">WidgetClassT</a></li>
<li><a href="#arch.widgets">Layout Engine</a></li>
<li><a href="#arch.widgets">Widget API</a></li>
<li><a href="#arch.widgets">Layout</a></li>
<li><a href="#arch.widgets">Flexbox</a></li>
<li><a href="#arch.widgets">WgtIfaceT</a></li>
<li><a href="#arch.dxe">DXE</a></li>
<li><a href="#arch.dxe">DXE3</a></li>
<li><a href="#arch.dxe">Modules</a></li>
<li><a href="#arch.dxe">Dynamic Loading</a></li>
<li><a href="#arch.dxe">Boot Sequence</a></li>
<li><a href="#arch.dxe">Crash Recovery</a></li>
<li><a href="#arch.dxe">Memory Tracking</a></li>
<li><a href="#arch.events">Events</a></li>
<li><a href="#arch.events">Input</a></li>
<li><a href="#arch.events">Mouse</a></li>
<li><a href="#arch.events">Keyboard</a></li>
<li><a href="#arch.events">Polling</a></li>
<li><a href="#arch.events">Cooperative</a></li>
<li><a href="#arch.events">Event Dispatch</a></li>
<li><a href="#arch.events">Accelerator Tables</a></li>
<li><a href="#arch.events">Cursor</a></li>
<li><a href="#arch.events">Double-Click</a></li>
<li><a href="#arch.fonts">Fonts</a></li>
<li><a href="#arch.fonts">Bitmap Font</a></li>
<li><a href="#arch.fonts">BitmapFontT</a></li>
<li><a href="#arch.fonts">Text Rendering</a></li>
<li><a href="#arch.fonts">CP437</a></li>
<li><a href="#arch.colors">Colors</a></li>
<li><a href="#arch.colors">Pixel Format</a></li>
<li><a href="#arch.colors">PixelFormatT</a></li>
<li><a href="#arch.colors">ColorSchemeT</a></li>
<li><a href="#arch.colors">Theming</a></li>
<li><a href="#arch.colors">Bevel</a></li>
<li><a href="#arch.platform">Platform Layer</a></li>
<li><a href="#arch.platform">dvxPlatform</a></li>
<li><a href="#arch.platform">VESA</a></li>
<li><a href="#arch.platform">VBE</a></li>
<li><a href="#arch.platform">INT 33h</a></li>
<li><a href="#arch.platform">INT 16h</a></li>
<li><a href="#arch.platform">Assembly</a></li>
<li><a href="#arch.platform">rep stosl</a></li>
<li><a href="#arch.platform">rep movsd</a></li>
<li><a href="#arch.build">Build</a></li>
<li><a href="#arch.build">Makefile</a></li>
<li><a href="#arch.build">Cross-Compilation</a></li>
<li><a href="#arch.build">dxe3gen</a></li>
<li><a href="#arch.build">mkcd.sh</a></li>
<li><a href="#arch.build">ISO</a></li>
<li><a href="#api.overview">DVX API</a></li>
<li><a href="#api.overview">API Reference</a></li>
<li><a href="#api.types">dvxTypes.h</a></li>
<li><a href="#api.types">PixelFormatT</a></li>
<li><a href="#api.types">DisplayT</a></li>
<li><a href="#api.types">RectT</a></li>
<li><a href="#api.types">BlitOpsT</a></li>
<li><a href="#api.types">BevelStyleT</a></li>
<li><a href="#api.types">BitmapFontT</a></li>
<li><a href="#api.types">ColorSchemeT</a></li>
<li><a href="#api.types">ColorIdE</a></li>
<li><a href="#api.types">DirtyListT</a></li>
<li><a href="#api.types">WindowT</a></li>
<li><a href="#api.types">WindowStackT</a></li>
<li><a href="#api.types">MenuT</a></li>
<li><a href="#api.types">MenuItemT</a></li>
<li><a href="#api.types">MenuBarT</a></li>
<li><a href="#api.types">ScrollbarT</a></li>
<li><a href="#api.types">AccelTableT</a></li>
<li><a href="#api.types">AccelEntryT</a></li>
<li><a href="#api.types">VideoModeInfoT</a></li>
<li><a href="#api.types">CursorT</a></li>
<li><a href="#api.cursor">dvxCursor.h</a></li>
<li><a href="#api.cursor">Cursor Shapes</a></li>
<li><a href="#api.cursor">CURSOR_ARROW</a></li>
<li><a href="#api.cursor">CURSOR_BUSY</a></li>
<li><a href="#api.video">dvxVideo.h</a></li>
<li><a href="#api.video">videoInit</a></li>
<li><a href="#api.video">videoShutdown</a></li>
<li><a href="#api.video">packColor</a></li>
<li><a href="#api.video">setClipRect</a></li>
<li><a href="#api.video">resetClipRect</a></li>
<li><a href="#api.video">VESA</a></li>
<li><a href="#api.video">LFB</a></li>
<li><a href="#api.draw">dvxDraw.h</a></li>
<li><a href="#api.draw">drawInit</a></li>
<li><a href="#api.draw">rectFill</a></li>
<li><a href="#api.draw">rectCopy</a></li>
<li><a href="#api.draw">rectCopyGrayscale</a></li>
<li><a href="#api.draw">drawBevel</a></li>
<li><a href="#api.draw">drawChar</a></li>
<li><a href="#api.draw">drawText</a></li>
<li><a href="#api.draw">drawTextN</a></li>
<li><a href="#api.draw">textWidth</a></li>
<li><a href="#api.draw">accelParse</a></li>
<li><a href="#api.draw">drawTextAccel</a></li>
<li><a href="#api.draw">textWidthAccel</a></li>
<li><a href="#api.draw">drawMaskedBitmap</a></li>
<li><a href="#api.draw">drawTermRow</a></li>
<li><a href="#api.draw">drawFocusRect</a></li>
<li><a href="#api.draw">drawHLine</a></li>
<li><a href="#api.draw">drawVLine</a></li>
<li><a href="#api.comp">dvxComp.h</a></li>
<li><a href="#api.comp">dirtyListInit</a></li>
<li><a href="#api.comp">dirtyListAdd</a></li>
<li><a href="#api.comp">dirtyListMerge</a></li>
<li><a href="#api.comp">dirtyListClear</a></li>
<li><a href="#api.comp">flushRect</a></li>
<li><a href="#api.comp">rectIntersect</a></li>
<li><a href="#api.comp">rectIsEmpty</a></li>
<li><a href="#api.wm">dvxWm.h</a></li>
<li><a href="#api.wm">wmInit</a></li>
<li><a href="#api.wm">wmCreateWindow</a></li>
<li><a href="#api.wm">wmDestroyWindow</a></li>
<li><a href="#api.wm">wmRaiseWindow</a></li>
<li><a href="#api.wm">wmSetFocus</a></li>
<li><a href="#api.wm">wmUpdateContentRect</a></li>
<li><a href="#api.wm">wmReallocContentBuf</a></li>
<li><a href="#api.wm">wmMinWindowSize</a></li>
<li><a href="#api.wm">wmAddMenuBar</a></li>
<li><a href="#api.wm">wmAddMenu</a></li>
<li><a href="#api.wm">wmAddMenuItem</a></li>
<li><a href="#api.wm">wmAddSubMenu</a></li>
<li><a href="#api.wm">wmCreateMenu</a></li>
<li><a href="#api.wm">wmDrawChrome</a></li>
<li><a href="#api.wm">wmHitTest</a></li>
<li><a href="#api.wm">wmDragBegin</a></li>
<li><a href="#api.wm">wmResizeBegin</a></li>
<li><a href="#api.wm">wmMaximize</a></li>
<li><a href="#api.wm">wmMinimize</a></li>
<li><a href="#api.wm">wmRestore</a></li>
<li><a href="#api.app">dvxApp.h</a></li>
<li><a href="#api.app">AppContextT</a></li>
<li><a href="#api.app">dvxInit</a></li>
<li><a href="#api.app">dvxShutdown</a></li>
<li><a href="#api.app">dvxRun</a></li>
<li><a href="#api.app">dvxUpdate</a></li>
<li><a href="#api.app">dvxQuit</a></li>
<li><a href="#api.app">dvxCreateWindow</a></li>
<li><a href="#api.app">dvxCreateWindowCentered</a></li>
<li><a href="#api.app">dvxDestroyWindow</a></li>
<li><a href="#api.app">dvxRaiseWindow</a></li>
<li><a href="#api.app">dvxFitWindow</a></li>
<li><a href="#api.app">dvxResizeWindow</a></li>
<li><a href="#api.app">dvxMinimizeWindow</a></li>
<li><a href="#api.app">dvxMaximizeWindow</a></li>
<li><a href="#api.app">dvxHideWindow</a></li>
<li><a href="#api.app">dvxShowWindow</a></li>
<li><a href="#api.app">dvxInvalidateRect</a></li>
<li><a href="#api.app">dvxInvalidateWindow</a></li>
<li><a href="#api.app">dvxSetTitle</a></li>
<li><a href="#api.app">dvxSetWindowIcon</a></li>
<li><a href="#api.app">dvxSetBusy</a></li>
<li><a href="#api.app">dvxGetFont</a></li>
<li><a href="#api.app">dvxGetColors</a></li>
<li><a href="#api.app">dvxGetDisplay</a></li>
<li><a href="#api.app">dvxGetBlitOps</a></li>
<li><a href="#api.app">dvxGetVideoModes</a></li>
<li><a href="#api.app">dvxSetColor</a></li>
<li><a href="#api.app">dvxGetColor</a></li>
<li><a href="#api.app">dvxApplyColorScheme</a></li>
<li><a href="#api.app">dvxResetColorScheme</a></li>
<li><a href="#api.app">dvxLoadTheme</a></li>
<li><a href="#api.app">dvxSaveTheme</a></li>
<li><a href="#api.app">dvxColorName</a></li>
<li><a href="#api.app">dvxColorLabel</a></li>
<li><a href="#api.app">dvxSetWallpaper</a></li>
<li><a href="#api.app">dvxSetWallpaperMode</a></li>
<li><a href="#api.app">dvxSetMouseConfig</a></li>
<li><a href="#api.app">dvxCreateAccelTable</a></li>
<li><a href="#api.app">dvxFreeAccelTable</a></li>
<li><a href="#api.app">dvxAddAccel</a></li>
<li><a href="#api.app">dvxCascadeWindows</a></li>
<li><a href="#api.app">dvxTileWindows</a></li>
<li><a href="#api.app">dvxLoadImage</a></li>
<li><a href="#api.app">dvxFreeImage</a></li>
<li><a href="#api.app">dvxImageInfo</a></li>
<li><a href="#api.app">dvxSaveImage</a></li>
<li><a href="#api.app">dvxScreenshot</a></li>
<li><a href="#api.app">dvxWindowScreenshot</a></li>
<li><a href="#api.app">dvxClipboardCopy</a></li>
<li><a href="#api.app">dvxClipboardGet</a></li>
<li><a href="#api.app">dvxResLoadIcon</a></li>
<li><a href="#api.app">dvxResLoadText</a></li>
<li><a href="#api.app">dvxResLoadData</a></li>
<li><a href="#api.app">dvxTextHash</a></li>
<li><a href="#api.app">dvxChangeVideoMode</a></li>
<li><a href="#api.widget">dvxWidget.h</a></li>
<li><a href="#api.widget">WidgetT</a></li>
<li><a href="#api.widget">WidgetClassT</a></li>
<li><a href="#api.widget">wgtInitWindow</a></li>
<li><a href="#api.widget">wgtGetContext</a></li>
<li><a href="#api.widget">wgtInvalidate</a></li>
<li><a href="#api.widget">wgtInvalidatePaint</a></li>
<li><a href="#api.widget">wgtSetText</a></li>
<li><a href="#api.widget">wgtGetText</a></li>
<li><a href="#api.widget">wgtSetEnabled</a></li>
<li><a href="#api.widget">wgtSetReadOnly</a></li>
<li><a href="#api.widget">wgtSetFocused</a></li>
<li><a href="#api.widget">wgtGetFocused</a></li>
<li><a href="#api.widget">wgtSetVisible</a></li>
<li><a href="#api.widget">wgtSetName</a></li>
<li><a href="#api.widget">wgtFind</a></li>
<li><a href="#api.widget">wgtDestroy</a></li>
<li><a href="#api.widget">wgtSetTooltip</a></li>
<li><a href="#api.widget">wgtResolveSize</a></li>
<li><a href="#api.widget">wgtLayout</a></li>
<li><a href="#api.widget">wgtPaint</a></li>
<li><a href="#api.widget">wgtSetDebugLayout</a></li>
<li><a href="#api.widget">wgtRegisterClass</a></li>
<li><a href="#api.widget">wgtRegisterApi</a></li>
<li><a href="#api.widget">wgtGetApi</a></li>
<li><a href="#api.widget">wgtRegisterIface</a></li>
<li><a href="#api.widget">wgtGetIface</a></li>
<li><a href="#api.widget">wgtFindByBasName</a></li>
<li><a href="#api.widget">wgtPixels</a></li>
<li><a href="#api.widget">wgtChars</a></li>
<li><a href="#api.widget">wgtPercent</a></li>
<li><a href="#libtasks">libtasks</a></li>
<li><a href="#libtasks">Task Switching</a></li>
<li><a href="#libtasks">Cooperative Multitasking</a></li>
<li><a href="#libtasks">taskswitch.h</a></li>
<li><a href="#shell.overview">DVX Shell</a></li>
<li><a href="#shell.overview">shellApp.h</a></li>
<li><a href="#shell.overview">DXE Application Loading</a></li>
<li><a href="#shell.types">AppDescriptorT</a></li>
<li><a href="#shell.types">DxeAppContextT</a></li>
<li><a href="#shell.types">ShellAppT</a></li>
<li><a href="#shell.types">AppStateE</a></li>
<li><a href="#shell.types">SHELL_APP_NAME_MAX</a></li>
<li><a href="#shell.types">SHELL_STACK_DEFAULT</a></li>
<li><a href="#shell.types">SHELL_DESKTOP_APP</a></li>
<li><a href="#shell.lifecycle">shellAppInit</a></li>
<li><a href="#shell.lifecycle">shellLoadApp</a></li>
<li><a href="#shell.lifecycle">shellLoadAppWithArgs</a></li>
<li><a href="#shell.lifecycle">shellReapApps</a></li>
<li><a href="#shell.lifecycle">shellReapApp</a></li>
<li><a href="#shell.lifecycle">shellForceKillApp</a></li>
<li><a href="#shell.lifecycle">shellTerminateAllApps</a></li>
<li><a href="#shell.query">shellGetApp</a></li>
<li><a href="#shell.query">shellAppSlotCount</a></li>
<li><a href="#shell.query">shellRunningAppCount</a></li>
<li><a href="#shell.config">shellEnsureConfigDir</a></li>
<li><a href="#shell.config">shellConfigPath</a></li>
<li><a href="#shell.desktop">shellRegisterDesktopUpdate</a></li>
<li><a href="#shell.desktop">shellUnregisterDesktopUpdate</a></li>
<li><a href="#shell.desktop">shellDesktopUpdate</a></li>
<li><a href="#shell.desktop">shellCtrlEscFn</a></li>
<li><a href="#shell.info">shellInfoInit</a></li>
<li><a href="#shell.info">shellGetSystemInfo</a></li>
<li><a href="#sql.overview">dvxSql</a></li>
<li><a href="#sql.overview">SQL</a></li>
<li><a href="#sql.overview">SQLite</a></li>
<li><a href="#sql.overview">Database</a></li>
<li><a href="#sql.db">dvxSqlOpen</a></li>
<li><a href="#sql.db">dvxSqlClose</a></li>
<li><a href="#sql.db">dvxSqlExec</a></li>
<li><a href="#sql.db">dvxSqlError</a></li>
<li><a href="#sql.db">dvxSqlAffectedRows</a></li>
<li><a href="#sql.cursor">dvxSqlQuery</a></li>
<li><a href="#sql.cursor">dvxSqlNext</a></li>
<li><a href="#sql.cursor">dvxSqlEof</a></li>
<li><a href="#sql.cursor">dvxSqlFieldCount</a></li>
<li><a href="#sql.cursor">dvxSqlFieldName</a></li>
<li><a href="#sql.cursor">dvxSqlFieldText</a></li>
<li><a href="#sql.cursor">dvxSqlFieldByName</a></li>
<li><a href="#sql.cursor">dvxSqlFieldInt</a></li>
<li><a href="#sql.cursor">dvxSqlFieldDbl</a></li>
<li><a href="#sql.cursor">dvxSqlFreeResult</a></li>
<li><a href="#sql.utility">dvxSqlEscape</a></li>
<li><a href="#sql.example">SQL Example</a></li>
<li><a href="#lib.texthelp">textHelp</a></li>
<li><a href="#lib.texthelp">Text Editing</a></li>
<li><a href="#lib.texthelp">Shared Library</a></li>
<li><a href="#lib.texthelp.cursorblink">wgtUpdateCursorBlink</a></li>
<li><a href="#lib.texthelp.cursorblink">Cursor Blink</a></li>
<li><a href="#lib.texthelp.clearother">clearOtherSelections</a></li>
<li><a href="#lib.texthelp.clearother">Selection</a></li>
<li><a href="#lib.texthelp.iswordchar">isWordChar</a></li>
<li><a href="#lib.texthelp.wordend">wordEnd</a></li>
<li><a href="#lib.texthelp.wordstart">wordStart</a></li>
<li><a href="#lib.texthelp.dragupdate">widgetTextEditDragUpdateLine</a></li>
<li><a href="#lib.texthelp.dragupdate">Drag Select</a></li>
<li><a href="#lib.texthelp.mouseclick">widgetTextEditMouseClick</a></li>
<li><a href="#lib.texthelp.mouseclick">Mouse Click</a></li>
<li><a href="#lib.texthelp.mouseclick">Multi-Click</a></li>
<li><a href="#lib.texthelp.mouseclick">Word Select</a></li>
<li><a href="#lib.texthelp.onkey">widgetTextEditOnKey</a></li>
<li><a href="#lib.texthelp.onkey">Key Handling</a></li>
<li><a href="#lib.texthelp.onkey">Text Editing</a></li>
<li><a href="#lib.texthelp.onkey">Undo</a></li>
<li><a href="#lib.texthelp.onkey">Clipboard</a></li>
<li><a href="#lib.texthelp.paintline">widgetTextEditPaintLine</a></li>
<li><a href="#lib.texthelp.paintline">Text Rendering</a></li>
<li><a href="#lib.texthelp.paintline">Selection Highlight</a></li>
<li><a href="#lib.listhelp">listhelp</a></li>
<li><a href="#lib.listhelp">widgetDrawDropdownArrow</a></li>
<li><a href="#lib.listhelp">widgetMaxItemLen</a></li>
<li><a href="#lib.listhelp">widgetNavigateIndex</a></li>
<li><a href="#lib.listhelp">widgetDropdownPopupRect</a></li>
<li><a href="#lib.listhelp">widgetPaintPopupList</a></li>
<li><a href="#lib.taskmgr">Task Manager</a></li>
<li><a href="#lib.taskmgr">shellTaskMgrOpen</a></li>
<li><a href="#lib.taskmgr">shellTaskMgrRefresh</a></li>
<li><a href="#lib.serial">Serial</a></li>
<li><a href="#lib.serial">RS-232</a></li>
<li><a href="#lib.serial">HDLC</a></li>
<li><a href="#lib.serial">XTEA</a></li>
<li><a href="#lib.serial">Diffie-Hellman</a></li>
<li><a href="#lib.serial">secLink</a></li>
<li><a href="#lib.serial.rs232">rs232</a></li>
<li><a href="#lib.serial.rs232">UART</a></li>
<li><a href="#lib.serial.rs232">COM Port</a></li>
<li><a href="#lib.serial.rs232">rs232Open</a></li>
<li><a href="#lib.serial.rs232">rs232Close</a></li>
<li><a href="#lib.serial.rs232">rs232Read</a></li>
<li><a href="#lib.serial.rs232">rs232Write</a></li>
<li><a href="#lib.serial.packet">packet</a></li>
<li><a href="#lib.serial.packet">HDLC</a></li>
<li><a href="#lib.serial.packet">CRC-16</a></li>
<li><a href="#lib.serial.packet">Go-Back-N</a></li>
<li><a href="#lib.serial.packet">pktOpen</a></li>
<li><a href="#lib.serial.packet">pktClose</a></li>
<li><a href="#lib.serial.packet">pktSend</a></li>
<li><a href="#lib.serial.packet">pktPoll</a></li>
<li><a href="#lib.serial.security">Security</a></li>
<li><a href="#lib.serial.security">Diffie-Hellman</a></li>
<li><a href="#lib.serial.security">XTEA</a></li>
<li><a href="#lib.serial.security">XTEA-CTR</a></li>
<li><a href="#lib.serial.security">DRBG</a></li>
<li><a href="#lib.serial.security">secDhCreate</a></li>
<li><a href="#lib.serial.security">secCipherCreate</a></li>
<li><a href="#lib.serial.security">secRngBytes</a></li>
<li><a href="#lib.serial.seclink">secLink</a></li>
<li><a href="#lib.serial.seclink">secLinkOpen</a></li>
<li><a href="#lib.serial.seclink">secLinkClose</a></li>
<li><a href="#lib.serial.seclink">secLinkHandshake</a></li>
<li><a href="#lib.serial.seclink">secLinkSend</a></li>
<li><a href="#lib.serial.seclink">secLinkPoll</a></li>
<li><a href="#lib.basrt">BASIC Runtime</a></li>
<li><a href="#lib.basrt">BasVmT</a></li>
<li><a href="#lib.basrt">BasValueT</a></li>
<li><a href="#lib.basrt">BasStringT</a></li>
<li><a href="#lib.basrt">BasArrayT</a></li>
<li><a href="#lib.basrt">BasModuleT</a></li>
<li><a href="#lib.basrt.values">BasValueT</a></li>
<li><a href="#lib.basrt.values">BasStringT</a></li>
<li><a href="#lib.basrt.values">BasArrayT</a></li>
<li><a href="#lib.basrt.values">BasUdtT</a></li>
<li><a href="#lib.basrt.values">basStringNew</a></li>
<li><a href="#lib.basrt.values">basArrayNew</a></li>
<li><a href="#lib.basrt.values">basValCopy</a></li>
<li><a href="#lib.basrt.values">basValRelease</a></li>
<li><a href="#lib.basrt.vm">BasVmT</a></li>
<li><a href="#lib.basrt.vm">BasModuleT</a></li>
<li><a href="#lib.basrt.vm">BasVmResultE</a></li>
<li><a href="#lib.basrt.vm">basVmCreate</a></li>
<li><a href="#lib.basrt.vm">basVmRun</a></li>
<li><a href="#lib.basrt.vm">basVmStep</a></li>
<li><a href="#lib.basrt.vm">basVmDestroy</a></li>
<li><a href="#lib.basrt.vm">basVmCallSub</a></li>
<li><a href="#widget.base">WidgetT</a></li>
<li><a href="#widget.base">Widget Base</a></li>
<li><a href="#widget.base">Common Properties</a></li>
<li><a href="#widget.base">Common Events</a></li>
<li><a href="#widget.base">wgtPixels</a></li>
<li><a href="#widget.base">wgtChars</a></li>
<li><a href="#widget.base">wgtPercent</a></li>
<li><a href="#widget.base">onClick</a></li>
<li><a href="#widget.base">onChange</a></li>
<li><a href="#widget.base">onKeyPress</a></li>
<li><a href="#widget.base">onKeyDown</a></li>
<li><a href="#widget.base">onMouseDown</a></li>
<li><a href="#widget.base">wgtInitWindow</a></li>
<li><a href="#widget.base">wgtGetContext</a></li>
<li><a href="#widget.base">wgtInvalidate</a></li>
<li><a href="#widget.base">wgtSetText</a></li>
<li><a href="#widget.base">wgtGetText</a></li>
<li><a href="#widget.base">wgtSetEnabled</a></li>
<li><a href="#widget.base">wgtSetFocused</a></li>
<li><a href="#widget.base">wgtSetVisible</a></li>
<li><a href="#widget.base">wgtFind</a></li>
<li><a href="#widget.base">wgtDestroy</a></li>
<li><a href="#widget.ansiterm">AnsiTerm</a></li>
<li><a href="#widget.ansiterm">wgtAnsiTerm</a></li>
<li><a href="#widget.ansiterm">Terminal</a></li>
<li><a href="#widget.ansiterm">VT100</a></li>
<li><a href="#widget.ansiterm">wgtAnsiTermWrite</a></li>
<li><a href="#widget.ansiterm">wgtAnsiTermClear</a></li>
<li><a href="#widget.ansiterm">wgtAnsiTermSetComm</a></li>
<li><a href="#widget.ansiterm">wgtAnsiTermSetScrollback</a></li>
<li><a href="#widget.ansiterm">wgtAnsiTermPoll</a></li>
<li><a href="#widget.ansiterm">wgtAnsiTermRepaint</a></li>
<li><a href="#widget.box">VBox</a></li>
<li><a href="#widget.box">HBox</a></li>
<li><a href="#widget.box">Frame</a></li>
<li><a href="#widget.box">wgtVBox</a></li>
<li><a href="#widget.box">wgtHBox</a></li>
<li><a href="#widget.box">wgtFrame</a></li>
<li><a href="#widget.box">Layout</a></li>
<li><a href="#widget.button">Button</a></li>
<li><a href="#widget.button">wgtButton</a></li>
<li><a href="#widget.canvas">Canvas</a></li>
<li><a href="#widget.canvas">wgtCanvas</a></li>
<li><a href="#widget.canvas">wgtCanvasClear</a></li>
<li><a href="#widget.canvas">wgtCanvasDrawLine</a></li>
<li><a href="#widget.canvas">wgtCanvasDrawRect</a></li>
<li><a href="#widget.canvas">wgtCanvasFillRect</a></li>
<li><a href="#widget.canvas">wgtCanvasFillCircle</a></li>
<li><a href="#widget.canvas">wgtCanvasSetPixel</a></li>
<li><a href="#widget.canvas">wgtCanvasGetPixel</a></li>
<li><a href="#widget.canvas">wgtCanvasDrawText</a></li>
<li><a href="#widget.canvas">wgtCanvasSave</a></li>
<li><a href="#widget.canvas">wgtCanvasLoad</a></li>
<li><a href="#widget.canvas">wgtCanvasSetPenColor</a></li>
<li><a href="#widget.canvas">wgtCanvasSetPenSize</a></li>
<li><a href="#widget.canvas">wgtCanvasSetMouseCallback</a></li>
<li><a href="#widget.checkbox">Checkbox</a></li>
<li><a href="#widget.checkbox">wgtCheckbox</a></li>
<li><a href="#widget.checkbox">wgtCheckboxIsChecked</a></li>
<li><a href="#widget.checkbox">wgtCheckboxSetChecked</a></li>
<li><a href="#widget.combobox">ComboBox</a></li>
<li><a href="#widget.combobox">wgtComboBox</a></li>
<li><a href="#widget.combobox">wgtComboBoxSetItems</a></li>
<li><a href="#widget.combobox">wgtComboBoxGetSelected</a></li>
<li><a href="#widget.combobox">wgtComboBoxSetSelected</a></li>
<li><a href="#widget.datactrl">DataCtrl</a></li>
<li><a href="#widget.datactrl">wgtDataCtrl</a></li>
<li><a href="#widget.datactrl">Database Binding</a></li>
<li><a href="#widget.datactrl">Master-Detail</a></li>
<li><a href="#widget.datactrl">wgtDataCtrlRefresh</a></li>
<li><a href="#widget.datactrl">wgtDataCtrlMoveFirst</a></li>
<li><a href="#widget.datactrl">wgtDataCtrlMoveNext</a></li>
<li><a href="#widget.datactrl">wgtDataCtrlGetField</a></li>
<li><a href="#widget.datactrl">wgtDataCtrlSetField</a></li>
<li><a href="#widget.datactrl">wgtDataCtrlUpdate</a></li>
<li><a href="#widget.datactrl">wgtDataCtrlAddNew</a></li>
<li><a href="#widget.datactrl">wgtDataCtrlDelete</a></li>
<li><a href="#widget.dbgrid">DbGrid</a></li>
<li><a href="#widget.dbgrid">wgtDbGrid</a></li>
<li><a href="#widget.dbgrid">wgtDbGridSetDataWidget</a></li>
<li><a href="#widget.dbgrid">Database Grid</a></li>
<li><a href="#widget.dbgrid">wgtDbGridRefresh</a></li>
<li><a href="#widget.dbgrid">wgtDbGridSetColumnVisible</a></li>
<li><a href="#widget.dbgrid">wgtDbGridSetColumnHeader</a></li>
<li><a href="#widget.dbgrid">wgtDbGridSetColumnWidth</a></li>
<li><a href="#widget.dbgrid">wgtDbGridGetSelectedRow</a></li>
<li><a href="#widget.dropdown">Dropdown</a></li>
<li><a href="#widget.dropdown">wgtDropdown</a></li>
<li><a href="#widget.dropdown">wgtDropdownSetItems</a></li>
<li><a href="#widget.dropdown">wgtDropdownGetSelected</a></li>
<li><a href="#widget.dropdown">wgtDropdownSetSelected</a></li>
<li><a href="#widget.imagebutton">ImageButton</a></li>
<li><a href="#widget.imagebutton">wgtImageButton</a></li>
<li><a href="#widget.imagebutton">wgtImageButtonFromFile</a></li>
<li><a href="#widget.imagebutton">wgtImageButtonSetData</a></li>
<li><a href="#widget.imagebutton">wgtImageButtonLoadFile</a></li>
<li><a href="#widget.image">Image</a></li>
<li><a href="#widget.image">wgtImage</a></li>
<li><a href="#widget.image">wgtImageFromFile</a></li>
<li><a href="#widget.image">wgtImageSetData</a></li>
<li><a href="#widget.image">wgtImageLoadFile</a></li>
<li><a href="#widget.label">Label</a></li>
<li><a href="#widget.label">wgtLabel</a></li>
<li><a href="#widget.label">wgtLabelSetAlign</a></li>
<li><a href="#widget.listbox">ListBox</a></li>
<li><a href="#widget.listbox">wgtListBox</a></li>
<li><a href="#widget.listbox">wgtListBoxSetItems</a></li>
<li><a href="#widget.listbox">wgtListBoxGetSelected</a></li>
<li><a href="#widget.listbox">wgtListBoxSetSelected</a></li>
<li><a href="#widget.listbox">wgtListBoxSetMultiSelect</a></li>
<li><a href="#widget.listbox">wgtListBoxIsItemSelected</a></li>
<li><a href="#widget.listbox">wgtListBoxSetReorderable</a></li>
<li><a href="#widget.listbox">wgtListBoxSelectAll</a></li>
<li><a href="#widget.listbox">wgtListBoxClearSelection</a></li>
<li><a href="#widget.listview">ListView</a></li>
<li><a href="#widget.listview">wgtListView</a></li>
<li><a href="#widget.listview">wgtListViewSetColumns</a></li>
<li><a href="#widget.listview">wgtListViewSetData</a></li>
<li><a href="#widget.listview">ListViewColT</a></li>
<li><a href="#widget.listview">ListViewSortE</a></li>
<li><a href="#widget.listview">wgtListViewGetSelected</a></li>
<li><a href="#widget.listview">wgtListViewSetSelected</a></li>
<li><a href="#widget.listview">wgtListViewSetSort</a></li>
<li><a href="#widget.listview">wgtListViewSetHeaderClickCallback</a></li>
<li><a href="#widget.listview">wgtListViewSetMultiSelect</a></li>
<li><a href="#widget.listview">wgtListViewSelectAll</a></li>
<li><a href="#widget.listview">wgtListViewClearSelection</a></li>
<li><a href="#widget.listview">wgtListViewSetReorderable</a></li>
<li><a href="#widget.progressbar">ProgressBar</a></li>
<li><a href="#widget.progressbar">wgtProgressBar</a></li>
<li><a href="#widget.progressbar">wgtProgressBarV</a></li>
<li><a href="#widget.progressbar">wgtProgressBarSetValue</a></li>
<li><a href="#widget.progressbar">wgtProgressBarGetValue</a></li>
<li><a href="#widget.radio">Radio</a></li>
<li><a href="#widget.radio">RadioGroup</a></li>
<li><a href="#widget.radio">wgtRadio</a></li>
<li><a href="#widget.radio">wgtRadioGroup</a></li>
<li><a href="#widget.radio">wgtRadioGroupSetSelected</a></li>
<li><a href="#widget.radio">wgtRadioGetIndex</a></li>
<li><a href="#widget.scrollpane">ScrollPane</a></li>
<li><a href="#widget.scrollpane">wgtScrollPane</a></li>
<li><a href="#widget.scrollpane">wgtScrollPaneScrollToChild</a></li>
<li><a href="#widget.scrollpane">wgtScrollPaneSetNoBorder</a></li>
<li><a href="#widget.separator">Separator</a></li>
<li><a href="#widget.separator">wgtHSeparator</a></li>
<li><a href="#widget.separator">wgtVSeparator</a></li>
<li><a href="#widget.slider">Slider</a></li>
<li><a href="#widget.slider">wgtSlider</a></li>
<li><a href="#widget.slider">wgtSliderSetValue</a></li>
<li><a href="#widget.slider">wgtSliderGetValue</a></li>
<li><a href="#widget.spacer">Spacer</a></li>
<li><a href="#widget.spacer">wgtSpacer</a></li>
<li><a href="#widget.spinner">Spinner</a></li>
<li><a href="#widget.spinner">wgtSpinner</a></li>
<li><a href="#widget.spinner">wgtSpinnerSetValue</a></li>
<li><a href="#widget.spinner">wgtSpinnerGetValue</a></li>
<li><a href="#widget.spinner">wgtSpinnerSetRealMode</a></li>
<li><a href="#widget.spinner">wgtSpinnerSetRange</a></li>
<li><a href="#widget.spinner">wgtSpinnerSetStep</a></li>
<li><a href="#widget.spinner">wgtSpinnerGetRealValue</a></li>
<li><a href="#widget.spinner">wgtSpinnerSetRealValue</a></li>
<li><a href="#widget.spinner">wgtSpinnerSetRealRange</a></li>
<li><a href="#widget.spinner">wgtSpinnerSetRealStep</a></li>
<li><a href="#widget.spinner">wgtSpinnerSetDecimals</a></li>
<li><a href="#widget.splitter">Splitter</a></li>
<li><a href="#widget.splitter">wgtSplitter</a></li>
<li><a href="#widget.splitter">wgtSplitterSetPos</a></li>
<li><a href="#widget.splitter">wgtSplitterGetPos</a></li>
<li><a href="#widget.statusbar">StatusBar</a></li>
<li><a href="#widget.statusbar">wgtStatusBar</a></li>
<li><a href="#widget.tabcontrol">TabControl</a></li>
<li><a href="#widget.tabcontrol">TabPage</a></li>
<li><a href="#widget.tabcontrol">wgtTabControl</a></li>
<li><a href="#widget.tabcontrol">wgtTabPage</a></li>
<li><a href="#widget.tabcontrol">wgtTabControlSetActive</a></li>
<li><a href="#widget.tabcontrol">wgtTabControlGetActive</a></li>
<li><a href="#widget.textinput">TextInput</a></li>
<li><a href="#widget.textinput">TextArea</a></li>
<li><a href="#widget.textinput">wgtTextInput</a></li>
<li><a href="#widget.textinput">wgtTextArea</a></li>
<li><a href="#widget.textinput">wgtPasswordInput</a></li>
<li><a href="#widget.textinput">wgtMaskedInput</a></li>
<li><a href="#widget.textinput">wgtTextAreaSetColorize</a></li>
<li><a href="#widget.textinput">wgtTextAreaGoToLine</a></li>
<li><a href="#widget.textinput">wgtTextAreaSetAutoIndent</a></li>
<li><a href="#widget.textinput">wgtTextAreaSetShowLineNumbers</a></li>
<li><a href="#widget.textinput">wgtTextAreaFindNext</a></li>
<li><a href="#widget.textinput">wgtTextAreaReplaceAll</a></li>
<li><a href="#widget.timer">Timer</a></li>
<li><a href="#widget.timer">wgtTimer</a></li>
<li><a href="#widget.timer">wgtTimerStart</a></li>
<li><a href="#widget.timer">wgtTimerStop</a></li>
<li><a href="#widget.timer">wgtTimerSetInterval</a></li>
<li><a href="#widget.timer">wgtTimerIsRunning</a></li>
<li><a href="#widget.timer">wgtUpdateTimers</a></li>
<li><a href="#widget.toolbar">Toolbar</a></li>
<li><a href="#widget.toolbar">wgtToolbar</a></li>
<li><a href="#widget.treeview">TreeView</a></li>
<li><a href="#widget.treeview">TreeItem</a></li>
<li><a href="#widget.treeview">wgtTreeView</a></li>
<li><a href="#widget.treeview">wgtTreeItem</a></li>
<li><a href="#widget.treeview">wgtTreeViewGetSelected</a></li>
<li><a href="#widget.treeview">wgtTreeViewSetSelected</a></li>
<li><a href="#widget.treeview">wgtTreeViewSetMultiSelect</a></li>
<li><a href="#widget.treeview">wgtTreeViewSetReorderable</a></li>
<li><a href="#widget.treeview">wgtTreeItemSetExpanded</a></li>
<li><a href="#widget.treeview">wgtTreeItemIsExpanded</a></li>
<li><a href="#widget.treeview">wgtTreeItemIsSelected</a></li>
<li><a href="#widget.treeview">wgtTreeItemSetSelected</a></li>
<li><a href="#widget.wrapbox">WrapBox</a></li>
<li><a href="#widget.wrapbox">wgtWrapBox</a></li>
</ul>
</nav>
<main>
<div class="topic" id="sys.welcome">
<h1>Welcome!</h1>
<h2>Welcome!</h2>
<p>DVX (DOS Visual eXecutive) is a graphical user interface environment for DOS, designed for 486-class hardware and above. This help file covers the system architecture, core API, libraries, and widget toolkit.</p>
</div>
<div class="topic" id="arch.overview">
<h1>DVX Architecture Overview</h1>
<h2>DVX Architecture Overview</h2>
<p>DOS Visual eXecutive -- A Windowing GUI for DJGPP/DPMI</p>
<p>DVX (DOS Visual eXecutive) is a complete windowing GUI compositor targeting DJGPP/DPMI on DOS. It provides overlapping windows with Motif-style chrome, a retained-mode widget toolkit, cooperative multitasking of DXE-loaded applications, and a dirty-rectangle compositor optimized for 486/Pentium hardware.</p>
<h3>Key Design Constraints</h3>
<ul>
<li>VESA VBE 2.0+ LFB only -- no bank switching. If the hardware cannot provide a linear framebuffer, initialization fails.</li>
<li>486 baseline -- all hot paths are written to be fast on a 486, with Pentium-specific paths where the gain is significant.</li>
<li>Single-tasking cooperative model -- applications yield the CPU via tsYield(); there is no preemptive scheduler.</li>
<li>86Box is the trusted reference platform for testing. DOSBox-X is not used; any bugs observed are treated as DVX bugs.</li>
</ul>
<p>No external font or cursor files -- all bitmaps are compiled in as static const data.</p>
<p>The runtime environment consists of a bootstrap loader (dvx.exe) that loads core DXE libraries, widget plugins, and the shell, which in turn loads and manages DXE application modules.</p>
<h3>Contents</h3>
<p><a href="#arch.layers">Five-Layer Architecture</a></p>
<p><a href="#arch.pipeline">Display Pipeline</a></p>
<p><a href="#arch.windows">Window System</a></p>
<p><a href="#arch.widgets">Widget System</a></p>
<p><a href="#arch.dxe">DXE Module System</a></p>
<p><a href="#arch.events">Event Model</a></p>
<p><a href="#arch.fonts">Font System</a></p>
<p><a href="#arch.colors">Color System</a></p>
<p><a href="#arch.platform">Platform Layer</a></p>
<p><a href="#arch.build">Build System</a></p>
</div>
<div class="topic" id="arch.layers">
<h1>Five-Layer Architecture</h1>
<h2>Five-Layer Architecture</h2>
<p>DVX is organized into five layers, each implemented as a single .h/.c pair. Every header includes dvxTypes.h (the shared type definitions) to avoid circular dependencies. The layers are strictly stacked: each layer depends only on the layers below it.</p>
<pre><code> Applications (DXE .app modules)
==================================================
| |
| +------------------------------------------+ |
| | Layer 5: dvxApp (Application API) | | dvxApp.h / dvxApp.c
| | Event loop, window creation, public API | |
| +------------------------------------------+ |
| | Layer 4: dvxWm (Window Manager) | | dvxWm.h / dvxWm.c
| | Window stack, chrome, drag, resize | |
| +------------------------------------------+ |
| | Layer 3: dvxComp (Compositor) | | dvxComp.h / dvxComp.c
| | Dirty rect tracking, merge, LFB flush | |
| +------------------------------------------+ |
| | Layer 2: dvxDraw (Drawing Primitives) | | dvxDraw.h / dvxDraw.c
| | Rects, bevels, text, blits, cursors | |
| +------------------------------------------+ |
| | Layer 1: dvxVideo (Video Backend) | | dvxVideo.h / dvxVideo.c
| | VESA VBE, LFB mapping, pixel format | |
| +------------------------------------------+ |
| |
| +------------------------------------------+ |
| | Platform Layer (dvxPlatform.h) | | dvxPlatformDos.c
| | OS-specific: video, input, asm spans | |
| +------------------------------------------+ |
| |
| +------------------------------------------+ |
| | Shared Types (dvxTypes.h) | |
| | DisplayT, WindowT, RectT, ColorSchemeT | |
| +------------------------------------------+ |
==================================================</code></pre>
<h3>Layer Summary</h3>
<pre> Layer Header Responsibility
----- ------ --------------
1 - Video dvxVideo.h VESA VBE mode negotiation, LFB mapping via DPMI, backbuffer allocation, packColor() (RGB to native pixel format), display-wide clip rectangle.
2 - Draw dvxDraw.h All 2D drawing: rectFill, rectCopy, drawBevel, drawText/drawTextN, drawMaskedBitmap (cursor), drawTermRow (batch terminal row). Stateless beyond clip rect. Dispatches hot inner loops through BlitOpsT function pointers.
3 - Compositor dvxComp.h Dirty rectangle tracking (dirtyListAdd), pairwise merge of overlapping rects (dirtyListMerge), and flushRect to copy dirty regions from backBuf to LFB.
4 - Window Manager dvxWm.h Window lifecycle, Z-order stack, chrome drawing (title bars, bevels, close/minimize/maximize gadgets), hit testing, drag/resize, menu bars, scrollbars, system menu, keyboard move/resize, minimized icon bar.
5 - Application dvxApp.h Public API aggregating all layers into AppContextT. Provides dvxInit/dvxShutdown, dvxRun/dvxUpdate, window creation helpers, image loading, clipboard, accelerator tables, theme management, wallpaper, video mode switching, screenshot capture.</pre>
</div>
<div class="topic" id="arch.pipeline">
<h1>Display Pipeline</h1>
<h2>Display Pipeline</h2>
<p>The double-buffer strategy is the single most important performance decision in DVX. All drawing goes to a system RAM backbuffer (DisplayT.backBuf); only dirty rectangles are flushed to the linear framebuffer (DisplayT.lfb) in video memory.</p>
<p>This matters because writes to video memory over the PCI bus are 10-50x slower than writes to main RAM on 486/Pentium hardware for random-access patterns.</p>
<h3>Per-Frame Compositing Pipeline</h3>
<pre><code> 1. Input poll (mouse, keyboard)
|
2. Event dispatch (focus window callbacks)
|
3. Layers call dirtyListAdd() for changed regions
|
4. dirtyListMerge() consolidates overlapping rects
|
5. For each merged dirty rect:
a. Clip and redraw desktop background (or wallpaper)
b. For each window (back-to-front, painter's algorithm):
- wmDrawChrome() -- frame, title bar, gadgets, menu bar
- wmDrawContent() -- blit per-window content buffer
- wmDrawScrollbars()
c. Draw minimized window icons
d. Draw popup menus / tooltips (overlay pass)
e. Draw software mouse cursor
|
6. flushRect() -- copy each dirty rect from backBuf to LFB
|
7. Yield (platformYield)</code></pre>
<h3>Key Data Structures</h3>
<p>DisplayT -- Central display context: width, height, pitch, pixel format, LFB pointer, backbuffer pointer, palette, clip rectangle. Passed by pointer through every layer -- no globals.</p>
<p>BlitOpsT -- Vtable of span fill/copy function pointers resolved at init time for the active pixel depth. On DOS these dispatch to hand-written rep stosl / rep movsd asm inner loops.</p>
<p>DirtyListT -- Fixed-capacity dynamic array of RectT. Linear scanning for merge candidates is cache-friendly at typical sizes (under 128 rects). If the list fills up, the compositor merges aggressively or falls back to full-screen repaint.</p>
<h3>Why This Works on a 486</h3>
<ul>
<li>A full 640x480x32bpp frame is 1.2 MB -- far too much to flush every frame over a slow PCI bus.</li>
<li>A typical dirty region during normal interaction (typing, menu open) is a few KB.</li>
<li>Merging overlapping dirty rects into larger rects reduces per-rect overhead and improves bus utilization.</li>
</ul>
<p>Per-window content buffers persist across frames, so windows don't repaint on expose -- only when their own content changes.</p>
</div>
<div class="topic" id="arch.windows">
<h1>Window System</h1>
<h2>Window System</h2>
<h3>WindowT Structure</h3>
<p>Each WindowT is the central object of the window manager. Key fields:</p>
<pre> Field Group Purpose
----------- -------
Geometry (x, y, w, h) Outer frame rectangle (including chrome).
Content area (contentX/Y/W/H) Computed from frame minus chrome. Where application content lives.
Content buffer (contentBuf, contentPitch) Per-window backbuffer in native pixel format. Persists across frames.
Chrome state (menuBar, vScroll, hScroll) Optional menu bar and scrollbars. Affect content area computation.
Widget tree (widgetRoot) Root of the retained-mode widget tree (NULL if using raw callbacks).
Callbacks onPaint, onKey, onKeyUp, onMouse, onResize, onClose, onMenu, onScroll, onFocus, onBlur, onCursorQuery.</pre>
<h3>Window Stack (Z-Order)</h3>
<p>WindowStackT is an array of WindowT* ordered front-to-back: index count-1 is the topmost window. This allows:</p>
<ul>
<li>Back-to-front iteration for painting (painter's algorithm).</li>
<li>Front-to-back iteration for hit testing (first hit wins).</li>
</ul>
<p>Reordering by pointer swap (no copying of large WindowT structs).</p>
<p>Only one drag/resize/scroll operation can be active system-wide at a time (single mouse), so that state lives on the stack, not on individual windows.</p>
<h3>Chrome Layout</h3>
<pre><code> +-------------------------------------------+
| 4px outer border (raised bevel) |
| +-------------------------------------+ |
| | [X] Title Bar Text [_] [^] [X] | | 20px title height
| +-------------------------------------+ |
| | 2px inner border | |
| +-------------------------------------+ |
| | Menu Bar (optional, 20px) | |
| +-------------------------------------+ |
| | | |
| | Content Area | |
| | | |
| | | S | | S = vertical scrollbar
| | | B | | (16px wide)
| +-------------------------------------+ |
| | Horizontal Scrollbar (optional) | | 16px tall
| +-------------------------------------+ |
| 4px outer border |
+-------------------------------------------+</code></pre>
<p>Chrome constants are compile-time defines:</p>
<pre><code> CHROME_BORDER_WIDTH = 4px
CHROME_TITLE_HEIGHT = 20px
CHROME_INNER_BORDER = 2px
CHROME_MENU_HEIGHT = 20px
SCROLLBAR_WIDTH = 16px
CHROME_CLOSE_BTN_SIZE = 16px</code></pre>
<h3>Hit Test Regions</h3>
<p>wmHitTest() iterates the stack front-to-back and returns a hit-part identifier: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, HIT_RESIZE, HIT_MENU, HIT_VSCROLL, HIT_HSCROLL, HIT_MINIMIZE, HIT_MAXIMIZE. Resize edge detection returns a bitmask of RESIZE_LEFT, RESIZE_RIGHT, RESIZE_TOP, RESIZE_BOTTOM (corners combine two edges).</p>
<h3>Menu System</h3>
<p>Menus use fixed-size arrays with inline char buffers (no heap strings). Up to 8 menus per bar, items dynamically allocated. Supports cascading submenus via MenuItemT.subMenu pointer. Item types: normal, checkbox, radio. Separators are non-interactive items. The popup state (PopupStateT) tracks a stack of parent frames for cascading submenu nesting.</p>
<h3>Minimized Windows</h3>
<p>Minimized windows display as 64x64 icons at the bottom of the screen with beveled borders, similar to a classic desktop icon bar. Icons show a scaled-down preview of the window's content buffer, refreshed one per frame in a round-robin fashion to amortize the scaling cost.</p>
</div>
<div class="topic" id="arch.widgets">
<h1>Widget System</h1>
<h2>Widget System</h2>
<p>The widget system (dvxWidget.h) is a retained-mode toolkit layered on top of the window manager. Widgets form a tree rooted at a per-window VBox container.</p>
<h3>WidgetT Base Structure</h3>
<p>Every widget shares the same WidgetT struct. The type field is a runtime-assigned integer ID. The wclass pointer references the widget's WidgetClassT vtable. Widget-specific private data is stored in w-&gt;data (opaque void*).</p>
<p>Tree linkage: parent, firstChild, lastChild, nextSibling. No prevSibling -- this halves pointer overhead and removal is still O(n) for typical tree depths of 5-10.</p>
<h3>Layout Engine</h3>
<p>Two-pass flexbox-like algorithm:</p>
<ul>
<li>Bottom-up (calcMinSize) -- compute minimum sizes for every widget, starting from leaves.</li>
</ul>
<p>Top-down (layout) -- allocate space within available bounds, distributing extra space according to weight values (0 = fixed, 100 = normal stretch).</p>
<p>Size hints use a tagged encoding: the top 2 bits of an int32_t select the unit (pixels, character widths, or percentage of parent), the low 30 bits hold the value. Macros: wgtPixels(v), wgtChars(v), wgtPercent(v).</p>
<h3>Widget Class Dispatch (WidgetClassT)</h3>
<p>Each widget type provides a WidgetClassT with a handlers[] array indexed by stable method IDs. Method IDs are never reordered or reused -- new methods append at the end. This provides ABI-stable dispatch so that widget DXEs compiled against an older DVX version continue to work.</p>
<p>Methods include: PAINT, PAINT_OVERLAY, CALC_MIN_SIZE, LAYOUT, ON_MOUSE, ON_KEY, ON_ACCEL_ACTIVATE, DESTROY, GET_TEXT, SET_TEXT, POLL, and more (21 defined, room for 32).</p>
<h4>Class Flags</h4>
<pre> Flag Meaning
---- -------
WCLASS_FOCUSABLE Can receive keyboard focus (Tab navigation)
WCLASS_HORIZ_CONTAINER Lays out children horizontally (HBox)
WCLASS_PAINTS_CHILDREN Widget handles child rendering itself
WCLASS_SCROLLABLE Accepts mouse wheel events
WCLASS_SCROLL_CONTAINER ScrollPane -- scrolling viewport
WCLASS_NEEDS_POLL Needs periodic polling (e.g. AnsiTerm comms)
WCLASS_SWALLOWS_TAB Tab key goes to widget, not focus navigation
WCLASS_PRESS_RELEASE Click = press + release (buttons)</pre>
<h3>Available Widget Types</h3>
<p>Each widget is a separate .wgt DXE module. 29 widget types are included:</p>
<pre> Widget Description
------ -----------
Box (VBox/HBox) Vertical and horizontal layout containers
Button Clickable push button with label
Canvas Raw drawing surface for custom painting
Checkbox Boolean toggle with checkmark
ComboBox Text input with dropdown list
DataCtrl Data-bound control for database operations
DbGrid Database grid (tabular data display)
Dropdown Dropdown selection list
Image Static image display
ImageButton Button with bitmap icon
Label Static text label
ListBox Scrollable selection list
ListView Multi-column list with headers and sorting
ProgressBar Determinate progress indicator
Radio Radio button (mutual exclusion group)
ScrollPane Scrollable viewport container
Separator Visual divider line
Slider Value selection via draggable thumb
Spacer Empty space for layout
Spinner Numeric input with up/down arrows
Splitter Resizable split pane
StatusBar Window status bar with sections
TabControl Tabbed page container
Terminal (AnsiTerm) ANSI terminal emulator widget
TextInput Single-line text entry field
Timer Periodic timer events
Toolbar Toolbar with icon buttons
TreeView Hierarchical tree display
WrapBox Flow layout (wrapping horizontal container)</pre>
<h3>Widget API Registry</h3>
<p>Each widget DXE registers a small API struct under a name during wgtRegister(). Callers retrieve it via wgtGetApi(&quot;button&quot;) and cast to the widget-specific API type. Per-widget headers provide typed accessors so callers avoid manual casts. Adding a new widget requires zero changes to the core.</p>
<h3>Widget Interface Descriptors (WgtIfaceT)</h3>
<p>Each widget can register an interface descriptor that describes its BASIC-facing properties, methods, and events. These descriptors are used by the form runtime and IDE for generic dispatch and property panel enumeration. Properties have typed getters/setters (WGT_IFACE_STRING, WGT_IFACE_INT, WGT_IFACE_BOOL, WGT_IFACE_ENUM).</p>
</div>
<div class="topic" id="arch.dxe">
<h1>DXE Module System</h1>
<h2>DXE Module System</h2>
<p>DVX uses DJGPP's DXE3 (Dynamic eXtension) format for all loadable modules. DXE3 supports RTLD_GLOBAL symbol sharing -- symbols exported by one module are visible to all subsequently loaded modules. This is critical: widget DXEs call core API functions (e.g. rectFill, wgtInvalidate) that are exported by the core library DXE.</p>
<h3>Module Types</h3>
<pre> Extension Directory Purpose Examples
--------- --------- ------- --------
.lib LIBS/ Core libraries loaded first. Provide infrastructure APIs. libtasks.lib, libdvx.lib, dvxshell.lib
.wgt WIDGETS/ Widget type plugins. Each exports wgtRegister(). button.wgt, listview.wgt, terminal.wgt
.app APPS/*/ Application modules. Each exports appDescriptor and appMain(). Loaded on demand by the shell. progman.app, notepad.app, cpanel.app</pre>
<h3>Boot Sequence</h3>
<pre><code> dvx.exe (loader)
|
+-- Enter VGA mode 13h, display splash screen with progress bar
|
+-- Scan LIBS/ for *.lib, WIDGETS/ for *.wgt
|
+-- Read .dep files for each module (dependency base names)
|
+-- Topological sort: load modules in dependency order
| - dlopen() with RTLD_GLOBAL
| - Each .wgt that exports wgtRegister() has it called
|
+-- Find and call shellMain() (exported by dvxshell.lib)
|
+-- dvxInit() -- video mode, input, font, colors, cursors
|
+-- Load desktop app (progman.app)
|
+-- Main loop:
dvxUpdate() -&gt; tsYield() -&gt; shellReapApps()</code></pre>
<h3>Application Lifecycle</h3>
<p>Two kinds of DXE apps:</p>
<h4>Callback-only (hasMainLoop = false)</h4>
<p>appMain() creates windows, registers callbacks, and returns. The app lives through GUI callbacks driven by the shell's main loop. Lifecycle ends when the last window is closed. No extra task stack needed -- simpler and cheaper.</p>
<h4>Main-loop (hasMainLoop = true)</h4>
<p>A dedicated cooperative task is created. appMain() runs in that task with its own loop, calling tsYield() to share CPU. Needed for apps with continuous work (terminal emulators, games). Lifecycle ends when appMain() returns.</p>
<h3>Crash Recovery</h3>
<p>The platform layer installs signal handlers for SIGSEGV, SIGFPE, SIGILL. On crash, the handler logs platform-specific diagnostics (register dump on DJGPP), then longjmps back to the shell's main loop. The crashed app is killed; other apps and the shell survive. This provides Windows 3.1-style fault tolerance.</p>
<h3>Per-App Memory Tracking</h3>
<p>All allocations route through dvxMalloc/dvxFree wrappers that prepend a 16-byte header recording the owning app ID and allocation size. The Task Manager displays per-app memory usage, and leaks are detected at app termination.</p>
</div>
<div class="topic" id="arch.events">
<h1>Event Model</h1>
<h2>Event Model</h2>
<p>DVX uses a cooperative polling model. The main loop (dvxRun / dvxUpdate) runs this cycle each frame:</p>
<ul>
<li>Poll mouse -- platformMousePoll() returns position and button bitmask. Compare with previous frame for press/release edge detection.</li>
<li>Poll keyboard -- platformKeyboardRead() returns ASCII + scancode. Non-blocking; returns false if buffer is empty.</li>
<li>Dispatch to focused window -- the event loop fires window callbacks (onKey, onMouse, etc.) on the focused window. If the window has a widget tree, the widget system's installed handlers dispatch to individual widgets.</li>
<li>Compositor pass -- merge dirty rects, composite, flush to LFB.</li>
</ul>
<p>Yield -- platformYield() or idle callback.</p>
<h3>Event Dispatch Chain</h3>
<pre><code> Mouse/Keyboard Input
|
Global handlers (Ctrl+Esc, modal filter)
|
Accelerator table check (focused window)
|
Window callback (onMouse / onKey)
|
[If widget tree installed:]
|
widgetOnMouse / widgetOnKey
|
Widget hit test (widgetHitTest)
|
wclsOnMouse / wclsOnKey (vtable dispatch)
|
Universal callbacks (onClick, onChange, etc.)</code></pre>
<h3>Accelerator Tables</h3>
<p>Per-window accelerator tables map key + modifier combinations to command IDs. The runtime normalizes key/modifier at registration time (uppercase key, strip shift from modifiers) so matching at dispatch time is two integer comparisons per entry. Matched accelerators fire the window's onMenu callback with the command ID, unifying the menu and hotkey code paths.</p>
<h3>Mouse Cursor</h3>
<p>Software-rendered cursor using the classic AND/XOR mask approach. Seven cursor shapes are compiled in: arrow, horizontal resize, vertical resize, NW-SE diagonal resize, NE-SW diagonal resize, busy (hourglass), and crosshair. The cursor is painted into the backbuffer on top of the composited frame and the affected region is flushed to the LFB each frame.</p>
<h3>Double-Click Detection</h3>
<p>Timestamp-based: two clicks on the same target (title bar, minimized icon, close gadget) within the configurable double-click interval trigger the double-click action. Separate tracking for each target type.</p>
</div>
<div class="topic" id="arch.fonts">
<h1>Font System</h1>
<h2>Font System</h2>
<p>DVX uses fixed-width 8-pixel-wide bitmap fonts only. One size is provided: 8x16, matching the standard VGA ROM font and CP437 encoding (256 glyphs).</p>
<h3>BitmapFontT</h3>
<pre><code> typedef struct {
int32_t charWidth; // fixed width per glyph (always 8)
int32_t charHeight; // 16
int32_t firstChar; // typically 0
int32_t numChars; // typically 256
const uint8_t *glyphData; // packed 1bpp, charHeight bytes per glyph
} BitmapFontT;</code></pre>
<p>Design rationale:</p>
<ul>
<li>Character positions are pure multiplication (x = col * 8).</li>
<li>Glyph lookup is a single array index.</li>
<li>Each scanline of a glyph is exactly one byte (1bpp at 8 pixels wide).</li>
<li>No glyph-width tables, kerning, or per-character positioning needed.</li>
</ul>
<p>8-pixel width aligns with byte boundaries -- no bit shifting in per-scanline rendering.</p>
<h3>Text Rendering Functions</h3>
<p>drawChar() -- Renders a single character. Supports opaque (background fill) and transparent modes.</p>
<p>drawTextN() -- Optimized batch rendering for a known character count. Clips once for the entire run, fills background in a single rectFill, then overlays glyph foreground pixels. Significantly faster than per-character rendering for long runs.</p>
<p>drawTermRow() -- Renders an 80-column terminal row in a single pass, with per-cell foreground/background from a 16-color palette, blink attribute support, and cursor rendering. Exists because per-character terminal rendering is unacceptably slow on target hardware.</p>
<p>drawTextAccel() -- Renders text with &amp; accelerator markers. The character after &amp; is underlined to indicate the keyboard shortcut.</p>
<h3>Performance Optimization</h3>
<p>AppContextT stores a fixed-point 16.16 reciprocal of font.charHeight (charHeightRecip) so that dividing by charHeight (for pixel-to-row conversion in terminal/text widgets) becomes a multiply+shift instead of an integer divide, which costs 40+ cycles on a 486.</p>
</div>
<div class="topic" id="arch.colors">
<h1>Color System</h1>
<h2>Color System</h2>
<h3>Pixel Format</h3>
<p>PixelFormatT describes the active VESA mode's pixel encoding. Populated once from the VBE mode info block. Stores shift, mask, and bit count for each channel so packColor() can convert RGB to native format with shift-and-mask arithmetic -- no per-pixel computation.</p>
<p>Supported depths:</p>
<pre> Depth Bytes/Pixel Notes
----- ----------- -----
8 bpp 1 Palette mode. Nearest-index via 6x6x6 color cube + grey ramp.
15 bpp 2 5-5-5 RGB (1 bit unused).
16 bpp 2 5-6-5 RGB.
32 bpp 4 8-8-8 RGB (8 bits unused).</pre>
<h3>ColorSchemeT -- Theming</h3>
<p>All 20 UI colors are pre-packed into display pixel format at init time. Every color is a uint32_t that can be written directly to the framebuffer with zero per-pixel conversion. The scheme must be regenerated on video mode change, but mode changes require re-init anyway.</p>
<p>Color roles mirror classic Motif/Windows 3.x conventions:</p>
<ul>
<li>desktop -- desktop background</li>
<li>windowFace, windowHighlight, windowShadow -- window chrome bevel triplet</li>
<li>activeTitleBg/Fg, inactiveTitleBg/Fg -- focused vs. unfocused title bar</li>
<li>contentBg/Fg -- window content area</li>
<li>menuBg/Fg, menuHighlightBg/Fg -- menus</li>
<li>buttonFace -- button background</li>
<li>scrollbarBg/Fg/Trough -- scrollbar components</li>
</ul>
<p>cursorFg/Bg -- mouse cursor colors</p>
<p>Source RGB values are kept in AppContextT.colorRgb[] for theme save/load. Themes are stored as INI files with a [colors] section. The API provides dvxLoadTheme(), dvxSaveTheme(), dvxSetColor(), and dvxResetColorScheme().</p>
<h3>Bevel Styles</h3>
<p>Bevels are the defining visual element of the Motif aesthetic. Convenience macros create bevel style descriptors by swapping highlight and shadow colors:</p>
<pre><code> BEVEL_RAISED(colorScheme, borderWidth) -- raised 3D look
BEVEL_SUNKEN(colorScheme, face, borderWidth) -- sunken/inset look
BEVEL_TROUGH(colorScheme) -- 1px scrollbar trough
BEVEL_SB_BUTTON(colorScheme) -- scrollbar button</code></pre>
</div>
<div class="topic" id="arch.platform">
<h1>Platform Layer</h1>
<h2>Platform Layer</h2>
<p>All OS-specific and CPU-specific code is isolated behind dvxPlatform.h. To port DVX, implement a new dvxPlatformXxx.c against this header.</p>
<h3>Implementations</h3>
<pre> File Target Details
---- ------ -------
dvxPlatformDos.c DJGPP/DPMI Real VESA VBE, INT 33h mouse, INT 16h keyboard, rep movsd/rep stosl asm spans, DPMI physical memory mapping for LFB, INT 9 hook for key-up, CuteMouse Wheel API.</pre>
<h3>Abstraction Areas</h3>
<h4>Video</h4>
<p>platformVideoInit() -- mode probe and framebuffer setup. platformVideoShutdown() -- restore previous mode. platformVideoEnumModes() -- enumerate available modes.</p>
<h4>Framebuffer Flush</h4>
<p>platformFlushRect() -- copy dirty rect from backBuf to LFB. On DOS, each scanline uses rep movsd for near-optimal aligned 32-bit writes over the PCI bus.</p>
<h4>Optimized Memory Spans</h4>
<p>Six functions: platformSpanFill8/16/32() and platformSpanCopy8/16/32(). Called once per scanline of every rectangle fill, blit, and text draw. On DOS these use inline assembly for critical inner loops.</p>
<h4>Mouse Input</h4>
<p>Polling model. platformMousePoll() returns position and button bitmask. Wheel support via CuteMouse API.</p>
<h4>Keyboard Input</h4>
<p>platformKeyboardRead() -- non-blocking key read. platformKeyUpRead() -- key release detection (requires INT 9 hook on DOS). platformAltScanToChar() -- scancode-to-ASCII lookup for Alt+key combinations.</p>
<h4>Crash Recovery</h4>
<p>platformInstallCrashHandler() -- signal handlers + longjmp for fault tolerance.</p>
<h4>DXE Support</h4>
<p>platformRegisterDxeExports() -- register C runtime and platform symbols for DXE resolution. platformRegisterSymOverrides() -- register function pointer overrides for module loader.</p>
</div>
<div class="topic" id="arch.build">
<h1>Build System</h1>
<h2>Build System</h2>
<h3>Cross-Compilation</h3>
<p>DVX is cross-compiled from Linux using a DJGPP cross-compiler (i586-pc-msdosdjgpp-gcc). The top-level Makefile orchestrates building all subsystems in dependency order.</p>
<pre><code> make -- build everything
./mkcd.sh -- build + create ISO for 86Box</code></pre>
<h3>Build Targets</h3>
<pre><code> all: core tasks loader texthelp listhelp tools widgets shell taskmgr serial sql apps</code></pre>
<pre> Target Output Description
------ ------ -----------
core bin/libs/libdvx.lib GUI core library (draw, comp, wm, app, widget infrastructure)
tasks bin/libs/libtasks.lib Cooperative task switcher
loader bin/dvx.exe Bootstrap loader (the DOS executable)
widgets bin/widgets/*.wgt 29 widget type plugins
shell bin/libs/dvxshell.lib DVX Shell (app management, desktop)
taskmgr bin/libs/taskmgr.lib Task Manager (loaded as a separate DXE)
texthelp shared library Shared text editing helpers (clipboard, word boundaries)
listhelp shared library Shared dropdown/list helpers
apps bin/apps/*/*.app Application modules (progman, notepad, clock, etc.)
tools bin/dvxres Resource compiler (runs on Linux, builds resource sections into DXEs)
serial serial DXE libs UART driver, HDLC packets, security, seclink
sql SQL DXE lib SQLite integration</pre>
<h3>DXE3 Build Process</h3>
<p>Each DXE module is compiled to an object file with GCC, then linked with dxe3gen:</p>
<pre><code> # Compile
i586-pc-msdosdjgpp-gcc -O2 -march=i486 -mtune=i586 -c -o widget.o widget.c
# Link as DXE with exported symbols
dxe3gen -o widget.wgt -E _wgtRegister -U widget.o
# Optionally append resources
dvxres build widget.wgt widget.res</code></pre>
<p>The -E flag specifies exported symbols (prefixed with underscore per DJGPP convention). -U marks unresolved symbols as OK (they'll be resolved at load time from previously loaded DXEs).</p>
<h3>Deployment (mkcd.sh)</h3>
<ul>
<li>Runs make all.</li>
<li>Verifies critical outputs exist (dvx.exe, libtasks.lib, libdvx.lib, dvxshell.lib).</li>
<li>Counts widget modules.</li>
<li>Creates an ISO 9660 image from bin/ using mkisofs: -iso-level 1 (strict 8.3 filenames for DOS), -J (Joliet extensions for long names), -V DVX (volume label).</li>
</ul>
<p>Places the ISO at ~/.var/app/net._86box._86Box/data/86Box/dvx.iso for 86Box to mount as CD-ROM.</p>
<h3>Compiler Flags</h3>
<pre><code> -O2 Optimization level 2
-march=i486 486 instruction set baseline
-mtune=i586 Optimize scheduling for Pentium
-Wall -Wextra Full warnings</code></pre>
<h3>Directory Layout</h3>
<pre><code> dvxgui/
+-- core/ Core library sources (dvxVideo, dvxDraw, dvxComp, dvxWm, dvxApp, widget infra)
| +-- platform/ Platform abstraction (dvxPlatform.h, dvxPlatformDos.c)
| +-- thirdparty/ stb_image, stb_ds, stb_image_write
+-- loader/ Bootstrap loader (dvx.exe)
+-- tasks/ Cooperative task switcher (libtasks.lib)
+-- shell/ DVX Shell (dvxshell.lib)
+-- widgets/ Widget DXE modules (*.wgt), each in its own subdirectory
| +-- box/ VBox/HBox layout containers
| +-- button/ Push button
| +-- textInput/ Text entry field
| +-- listView/ Multi-column list
| +-- ... (29 widget types total)
+-- texthelp/ Shared text editing helpers
+-- listhelp/ Shared dropdown/list helpers
+-- apps/ Application DXE modules (*.app)
| +-- progman/ Program Manager (desktop)
| +-- notepad/ Text editor
| +-- cpanel/ Control Panel
| +-- imgview/ Image viewer
| +-- clock/ Clock
| +-- dvxdemo/ Demo / showcase app
| +-- dvxbasic/ DVX BASIC compiler and VM
+-- tools/ Build tools (dvxres resource compiler)
+-- rs232/ ISR-driven UART driver
+-- packet/ HDLC framing, CRC-16, sliding window
+-- security/ DH key exchange, XTEA cipher, DRBG RNG
+-- seclink/ Encrypted channel wrapper
+-- serial/ Combined serial stack DXE
+-- proxy/ Linux proxy (86Box &lt;-&gt; secLink &lt;-&gt; telnet)
+-- sql/ SQLite integration
+-- bin/ Build output (dvx.exe, libs/, widgets/, apps/, config/)
+-- obj/ Intermediate object files
+-- docs/ Documentation</code></pre>
</div>
<div class="topic" id="api.overview">
<h1>DVX GUI API Reference</h1>
<h2>DVX GUI API Reference</h2>
<p>DOS Visual eXecutive -- Complete public API documentation generated from source headers.</p>
<p>The DVX GUI is built as a five-layer architecture. Each layer is defined in its own header file. This reference covers every public function, type, and constant.</p>
<h3>Layers</h3>
<ul>
<li>dvxTypes.h -- Shared type definitions</li>
<li>dvxCursor.h -- Cursor definitions</li>
<li>dvxVideo.h -- Layer 1: VESA VBE Video Backend</li>
<li>dvxDraw.h -- Layer 2: Drawing Primitives</li>
<li>dvxComp.h -- Layer 3: Dirty Rectangle Compositor</li>
<li>dvxWm.h -- Layer 4: Window Manager</li>
<li>dvxApp.h -- Layer 5: Application API</li>
</ul>
<p>dvxWidget.h -- Widget System</p>
<p><a href="#api.types">dvxTypes.h -- Shared Type Definitions</a></p>
<p><a href="#api.cursor">dvxCursor.h -- Cursor Definitions</a></p>
<p><a href="#api.video">dvxVideo.h -- Layer 1: VESA VBE Video Backend</a></p>
<p><a href="#api.draw">dvxDraw.h -- Layer 2: Drawing Primitives</a></p>
<p><a href="#api.comp">dvxComp.h -- Layer 3: Dirty Rectangle Compositor</a></p>
<p><a href="#api.wm">dvxWm.h -- Layer 4: Window Manager</a></p>
<p><a href="#api.app">dvxApp.h -- Layer 5: Application API</a></p>
<p><a href="#api.widget">dvxWidget.h -- Widget System</a></p>
</div>
<div class="topic" id="api.types">
<h1>dvxTypes.h -- Shared Type Definitions</h1>
<h2>dvxTypes.h -- Shared Type Definitions</h2>
<p>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.</p>
<h3>Core Structures</h3>
<h4>PixelFormatT</h4>
<p>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.</p>
<pre> 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</pre>
<h4>DisplayT</h4>
<p>Single display context passed by pointer through every layer. All drawing targets the backBuf; only dirty rects are flushed to lfb.</p>
<pre> 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</pre>
<h4>RectT</h4>
<p>Rectangle in origin + extent form. Used throughout the compositor, window manager, and widget layout engine.</p>
<pre> Field Description
----- -----------
int32_t x, y Top-left corner
int32_t w, h Width and height</pre>
<h4>BlitOpsT</h4>
<p>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).</p>
<pre> 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</pre>
<h4>BevelStyleT</h4>
<p>Bevel drawing parameters. Swapping highlight/shadow flips raised vs. sunken appearance.</p>
<pre> 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)</pre>
<h4>BitmapFontT</h4>
<p>Fixed-width 8-pixel-wide bitmap font descriptor. One size provided: 8x16 (standard VGA ROM font, CP437 encoding).</p>
<pre> Field Description
----- -----------
int32_t charWidth Fixed width per glyph (always 8)
int32_t charHeight Glyph height (14 or 16)
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</pre>
<h4>ColorSchemeT</h4>
<p>All UI colors pre-packed into display pixel format at init time. Theme support is achieved by swapping this struct.</p>
<pre> 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</pre>
<h4>ColorIdE</h4>
<p>Enum for addressing individual colors in ColorSchemeT. Order matches struct field order.</p>
<p>Values: ColorDesktopE, ColorWindowFaceE, ColorWindowHighlightE, ColorWindowShadowE, ColorActiveTitleBgE, ColorActiveTitleFgE, ColorInactiveTitleBgE, ColorInactiveTitleFgE, ColorContentBgE, ColorContentFgE, ColorMenuBgE, ColorMenuFgE, ColorMenuHighlightBgE, ColorMenuHighlightFgE, ColorButtonFaceE, ColorScrollbarBgE, ColorScrollbarFgE, ColorScrollbarTroughE, ColorCursorFgE, ColorCursorBgE, ColorCountE.</p>
<h4>DirtyListT</h4>
<p>Fixed-capacity list of dirty rectangles. Dynamic array, grows on demand.</p>
<pre> Field Description
----- -----------
RectT *rects Dynamic array of dirty rectangles
int32_t count Current number of dirty rects
int32_t cap Allocated capacity</pre>
<h4>WindowT</h4>
<p>Central window object. Each window owns a persistent content backbuffer and receives events through callback function pointers.</p>
<pre> 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 contentDirty true when contentBuf has changed
bool needsPaint true until first onPaint call
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</pre>
<p>Callbacks:</p>
<pre> 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 btn) 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 val) Scrollbar value changed
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</pre>
<h4>WindowStackT</h4>
<p>Z-ordered window stack (front-to-back: index count-1 is topmost). Owns system-wide drag/resize/scroll interaction state.</p>
<pre> 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 resizeWindow, resizeEdge Active resize state
int32_t scrollWindow, scrollOrient, scrollDragOff Active scroll drag state</pre>
<h4>MenuT / MenuItemT / MenuBarT</h4>
<p>Menu system types. Fixed-size label buffers (MAX_MENU_LABEL = 32). Cascading submenus supported via MenuItemT.subMenu pointer.</p>
<pre> Field Description
----- -----------
MenuItemT.label Item text (supports &amp; 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.subMenu Child menu for cascading (NULL if leaf)
MenuBarT.activeIdx Open popup index (-1 = none)</pre>
<h4>ScrollbarT</h4>
<p>Window-level scrollbar state. Managed by the WM layer, drawn after content.</p>
<pre> 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</pre>
<h4>AccelTableT / AccelEntryT</h4>
<p>Per-window keyboard accelerator table. Entries are matched against keystrokes in the event loop and fire onMenu(cmdId) on match.</p>
<pre> 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</pre>
<h4>VideoModeInfoT</h4>
<p>Describes an available video mode (enumerated at init).</p>
<pre> Field Description
----- -----------
int32_t w, h Resolution
int32_t bpp Bits per pixel</pre>
<h4>CursorT</h4>
<p>Software-rendered 16x16 cursor using AND/XOR mask encoding.</p>
<pre> 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)</pre>
<h3>Bevel Convenience Macros</h3>
<pre> 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</pre>
<h3>Chrome Constants</h3>
<pre> 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</pre>
<h3>Hit Test Constants</h3>
<pre> 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)</pre>
<h3>Mouse Button Flags</h3>
<pre> Define Value Description
------ ----- -----------
MOUSE_LEFT 1 Left mouse button
MOUSE_RIGHT 2 Right mouse button
MOUSE_MIDDLE 4 Middle mouse button</pre>
<h3>Accelerator Modifier Flags</h3>
<pre> Define Value Description
------ ----- -----------
ACCEL_SHIFT 0x03 Shift key (matches BIOS shift state bits)
ACCEL_CTRL 0x04 Ctrl key
ACCEL_ALT 0x08 Alt key</pre>
<h3>Extended Key Codes</h3>
<pre> 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</pre>
<h3>Resize Edge Flags</h3>
<pre> 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)</pre>
<h3>Utility Macros</h3>
<pre> Macro Description
----- -----------
DVX_MIN(a, b) Return the smaller of two values
DVX_MAX(a, b) Return the larger of two values</pre>
</div>
<div class="topic" id="api.cursor">
<h1>dvxCursor.h -- Cursor Definitions</h1>
<h2>dvxCursor.h -- Cursor Definitions</h2>
<p>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.</p>
<h3>Cursor Shape IDs</h3>
<pre> 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</pre>
<h3>Data</h3>
<h4>dvxCursors[CURSOR_COUNT]</h4>
<p>Static const array of CursorT structs, indexed by CURSOR_xxx constants. Each entry includes the AND mask, XOR data, dimensions, and hot spot coordinates.</p>
</div>
<div class="topic" id="api.video">
<h1>dvxVideo.h -- Layer 1: VESA VBE Video Backend</h1>
<h2>dvxVideo.h -- Layer 1: VESA VBE Video Backend</h2>
<p>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.</p>
<h3>videoInit</h3>
<pre><code>int32_t videoInit(DisplayT *d, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
d Display context to initialize
requestedW/H Desired screen resolution
preferredBpp Preferred bits per pixel (8, 15, 16, or 32)</pre>
<p>Returns: 0 on success, negative on failure.</p>
<h3>videoShutdown</h3>
<pre><code>void videoShutdown(DisplayT *d);</code></pre>
<p>Restore VGA text mode (mode 3), unmap the LFB, and free the backbuffer. Safe to call even if videoInit() failed.</p>
<pre> Parameter Description
--------- -----------
d Display context to shut down</pre>
<h3>packColor</h3>
<pre><code>uint32_t packColor(const DisplayT *d, uint8_t r, uint8_t g, uint8_t b);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
d Display context (provides pixel format)
r, g, b Color components (0-255)</pre>
<p>Returns: Native pixel value suitable for direct framebuffer write.</p>
<h3>setClipRect</h3>
<pre><code>void setClipRect(DisplayT *d, int32_t x, int32_t y, int32_t w, int32_t h);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
d Display context
x, y, w, h Clip rectangle in screen coordinates</pre>
<h3>resetClipRect</h3>
<pre><code>void resetClipRect(DisplayT *d);</code></pre>
<p>Reset the clip rectangle to the full display dimensions.</p>
<pre> Parameter Description
--------- -----------
d Display context</pre>
</div>
<div class="topic" id="api.draw">
<h1>dvxDraw.h -- Layer 2: Drawing Primitives</h1>
<h2>dvxDraw.h -- Layer 2: Drawing Primitives</h2>
<p>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.</p>
<h3>drawInit</h3>
<pre><code>void drawInit(BlitOpsT *ops, const DisplayT *d);</code></pre>
<p>Populate a BlitOpsT with the correct span functions for the display's pixel depth. Must be called once after videoInit().</p>
<pre> Parameter Description
--------- -----------
ops BlitOpsT to populate
d Initialized display context</pre>
<h3>rectFill</h3>
<pre><code>void rectFill(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);</code></pre>
<p>Fill a rectangle with a solid color. Clips to the display clip rect. Workhorse for backgrounds, window fills, and clear operations.</p>
<pre> Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
x, y, w, h Rectangle to fill
color Packed pixel color</pre>
<h3>rectCopy</h3>
<pre><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);</code></pre>
<p>Copy a rectangle from an arbitrary source buffer into the backbuffer. Used to blit per-window content buffers during compositing.</p>
<pre> 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</pre>
<h3>rectCopyGrayscale</h3>
<pre><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);</code></pre>
<p>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.</p>
<pre> 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</pre>
<h3>drawBevel</h3>
<pre><code>void drawBevel(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const BevelStyleT *style);</code></pre>
<p>Draw a beveled frame. Top/left edges in highlight color, bottom/right in shadow. Interior filled with face color if non-zero.</p>
<pre> Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
x, y, w, h Outer bevel rectangle
style Bevel colors and width</pre>
<h3>drawChar</h3>
<pre><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);</code></pre>
<p>Draw a single character glyph. When opaque is true, the background fills the entire cell; when false, only foreground pixels are drawn (transparent background).</p>
<pre> 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</pre>
<p>Returns: Advance width (always charWidth).</p>
<h3>drawText</h3>
<pre><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);</code></pre>
<p>Draw a null-terminated string. Calls drawChar per character.</p>
<pre> 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</pre>
<h3>drawTextN</h3>
<pre><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);</code></pre>
<p>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).</p>
<pre> 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</pre>
<h3>textWidth</h3>
<pre><code>int32_t textWidth(const BitmapFontT *font, const char *text);</code></pre>
<p>Return the pixel width of a null-terminated string (strlen(text) * charWidth).</p>
<pre> Parameter Description
--------- -----------
font Bitmap font
text Null-terminated string</pre>
<p>Returns: Width in pixels.</p>
<h3>accelParse</h3>
<pre><code>char accelParse(const char *text);</code></pre>
<p>Scan text for an &amp; prefix and return the following character as a lowercase accelerator key. &quot;&amp;File&quot; returns 'f', &quot;E&amp;xit&quot; returns 'x'.</p>
<pre> Parameter Description
--------- -----------
text Text with optional &amp; accelerator marker</pre>
<p>Returns: Lowercase accelerator character, or 0 if none.</p>
<h3>drawTextAccel</h3>
<pre><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);</code></pre>
<p>Draw text with &amp; accelerator markers. The character after &amp; is drawn underlined to indicate the keyboard shortcut. &amp;&amp; produces a literal &amp;. Used for menu items and button labels.</p>
<pre> Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
font Bitmap font
x, y Start position
text Text with &amp; markers
fg, bg Foreground and background packed colors
opaque true = fill background, false = transparent</pre>
<h3>textWidthAccel</h3>
<pre><code>int32_t textWidthAccel(const BitmapFontT *font, const char *text);</code></pre>
<p>Measure text width excluding &amp; markers (so &quot;&amp;File&quot; measures as 4 chars).</p>
<pre> Parameter Description
--------- -----------
font Bitmap font
text Text with optional &amp; markers</pre>
<p>Returns: Width in pixels.</p>
<h3>drawMaskedBitmap</h3>
<pre><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);</code></pre>
<p>Draw a 1-bit AND/XOR masked bitmap. Used for software-rendered mouse cursors.</p>
<pre> 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</pre>
<h3>drawTermRow</h3>
<pre><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);</code></pre>
<p>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.</p>
<pre> 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)</pre>
<h3>drawFocusRect</h3>
<pre><code>void drawFocusRect(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);</code></pre>
<p>Draw a 1px dotted rectangle (alternating pixels). Used for keyboard focus indicators, matching the Windows 3.x focus rectangle convention.</p>
<pre> Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
x, y, w, h Focus rectangle bounds
color Dot color (packed)</pre>
<h3>drawHLine</h3>
<pre><code>void drawHLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, uint32_t color);</code></pre>
<p>Draw a horizontal line (1px tall).</p>
<pre> Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
x, y Start position
w Width in pixels
color Packed pixel color</pre>
<h3>drawVLine</h3>
<pre><code>void drawVLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t h, uint32_t color);</code></pre>
<p>Draw a vertical line (1px wide).</p>
<pre> Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
x, y Start position
h Height in pixels
color Packed pixel color</pre>
</div>
<div class="topic" id="api.comp">
<h1>dvxComp.h -- Layer 3: Dirty Rectangle Compositor</h1>
<h2>dvxComp.h -- Layer 3: Dirty Rectangle Compositor</h2>
<p>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.</p>
<h3>dirtyListInit</h3>
<pre><code>void dirtyListInit(DirtyListT *dl);</code></pre>
<p>Zero the dirty rect count. Called at the start of each frame.</p>
<pre> Parameter Description
--------- -----------
dl Dirty list to initialize</pre>
<h3>dirtyListAdd</h3>
<pre><code>void dirtyListAdd(DirtyListT *dl, int32_t x, int32_t y, int32_t w, int32_t h);</code></pre>
<p>Enqueue a dirty rectangle. Grows dynamically; triggers merge at a soft capacity limit.</p>
<pre> Parameter Description
--------- -----------
dl Dirty list
x, y, w, h Dirty rectangle in screen coordinates</pre>
<h3>dirtyListMerge</h3>
<pre><code>void dirtyListMerge(DirtyListT *dl);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
dl Dirty list to merge</pre>
<h3>dirtyListClear</h3>
<pre><code>void dirtyListClear(DirtyListT *dl);</code></pre>
<p>Reset the dirty list to empty (sets count to 0).</p>
<pre> Parameter Description
--------- -----------
dl Dirty list to clear</pre>
<h3>flushRect</h3>
<pre><code>void flushRect(DisplayT *d, const RectT *r);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
d Display context
r Rectangle to flush</pre>
<h3>rectIntersect</h3>
<pre><code>bool rectIntersect(const RectT *a, const RectT *b, RectT *result);</code></pre>
<p>Compute the intersection of two rectangles.</p>
<pre> Parameter Description
--------- -----------
a, b Input rectangles
result Output: intersection rectangle (valid only when return is true)</pre>
<p>Returns: true if the rectangles overlap, false if disjoint.</p>
<h3>rectIsEmpty</h3>
<pre><code>bool rectIsEmpty(const RectT *r);</code></pre>
<p>Test whether a rectangle has zero or negative area.</p>
<pre> Parameter Description
--------- -----------
r Rectangle to test</pre>
<p>Returns: true if w &lt;= 0 or h &lt;= 0.</p>
</div>
<div class="topic" id="api.wm">
<h1>dvxWm.h -- Layer 4: Window Manager</h1>
<h2>dvxWm.h -- Layer 4: Window Manager</h2>
<p>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.</p>
<h3>Initialization</h3>
<h4>wmInit</h4>
<pre><code>void wmInit(WindowStackT *stack);</code></pre>
<p>Zero the window stack. Must be called before any other WM function.</p>
<pre> Parameter Description
--------- -----------
stack Window stack to initialize</pre>
<h3>Window Lifecycle</h3>
<h4>wmCreateWindow</h4>
<pre><code>WindowT *wmCreateWindow(WindowStackT *stack, DisplayT *d, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);</code></pre>
<p>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.</p>
<pre> 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</pre>
<p>Returns: Pointer to new WindowT, or NULL on failure.</p>
<h4>wmDestroyWindow</h4>
<pre><code>void wmDestroyWindow(WindowStackT *stack, WindowT *win);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
win Window to destroy</pre>
<h3>Z-Order and Focus</h3>
<h4>wmRaiseWindow</h4>
<pre><code>void wmRaiseWindow(WindowStackT *stack, DirtyListT *dl, int32_t idx);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
dl Dirty list for repaint marking
idx Stack index of window to raise</pre>
<h4>wmSetFocus</h4>
<pre><code>void wmSetFocus(WindowStackT *stack, DirtyListT *dl, int32_t idx);</code></pre>
<p>Transfer keyboard focus to the window at stack index idx. Unfocuses the previously focused window and dirties both title bars.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
dl Dirty list
idx Stack index of window to focus</pre>
<h3>Geometry</h3>
<h4>wmUpdateContentRect</h4>
<pre><code>void wmUpdateContentRect(WindowT *win);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
win Window to update</pre>
<h4>wmReallocContentBuf</h4>
<pre><code>int32_t wmReallocContentBuf(WindowT *win, const DisplayT *d);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
win Window to reallocate
d Display context (for bytes-per-pixel)</pre>
<p>Returns: 0 on success, -1 on allocation failure.</p>
<h4>wmMinWindowSize</h4>
<pre><code>void wmMinWindowSize(const WindowT *win, int32_t *minW, int32_t *minH);</code></pre>
<p>Get the minimum window size. Accounts for chrome, gadgets, and menu bar.</p>
<pre> Parameter Description
--------- -----------
win Window
minW, minH Output: minimum width and height</pre>
<h3>Menu Bar</h3>
<h4>wmAddMenuBar</h4>
<pre><code>MenuBarT *wmAddMenuBar(WindowT *win);</code></pre>
<p>Allocate and attach a menu bar to a window. Adjusts content area to make room (CHROME_MENU_HEIGHT pixels). One menu bar per window.</p>
<pre> Parameter Description
--------- -----------
win Window to add menu bar to</pre>
<p>Returns: Pointer to the new MenuBarT.</p>
<h4>wmDestroyMenuBar</h4>
<pre><code>void wmDestroyMenuBar(WindowT *win);</code></pre>
<p>Free the menu bar and reclaim the content area.</p>
<pre> Parameter Description
--------- -----------
win Window to remove menu bar from</pre>
<h4>wmAddMenu</h4>
<pre><code>MenuT *wmAddMenu(MenuBarT *bar, const char *label);</code></pre>
<p>Append a dropdown menu to the menu bar. The label supports &amp; accelerator markers (e.g. &quot;&amp;File&quot;).</p>
<pre> Parameter Description
--------- -----------
bar Menu bar
label Menu label text</pre>
<p>Returns: Pointer to the new MenuT to populate with items.</p>
<h4>wmAddMenuItem</h4>
<pre><code>void wmAddMenuItem(MenuT *menu, const char *label, int32_t id);</code></pre>
<p>Append a clickable item to a menu. The id is passed to the window's onMenu callback when selected.</p>
<pre> Parameter Description
--------- -----------
menu Menu to append to
label Item label (supports &amp; markers)
id Application-defined command ID</pre>
<h4>wmAddMenuCheckItem</h4>
<pre><code>void wmAddMenuCheckItem(MenuT *menu, const char *label, int32_t id, bool checked);</code></pre>
<p>Add a checkbox-style menu item. Check state toggles on click; rendered with a checkmark glyph.</p>
<pre> Parameter Description
--------- -----------
menu Menu to append to
label Item label
id Command ID
checked Initial checked state</pre>
<h4>wmAddMenuRadioItem</h4>
<pre><code>void wmAddMenuRadioItem(MenuT *menu, const char *label, int32_t id, bool checked);</code></pre>
<p>Add a radio-style menu item. Radio groups are defined implicitly by consecutive radio items; selecting one unchecks the others in the group.</p>
<pre> Parameter Description
--------- -----------
menu Menu to append to
label Item label
id Command ID
checked Initial checked state</pre>
<h4>wmAddMenuSeparator</h4>
<pre><code>void wmAddMenuSeparator(MenuT *menu);</code></pre>
<p>Insert a horizontal separator line. Separators are not interactive.</p>
<pre> Parameter Description
--------- -----------
menu Menu to append separator to</pre>
<h4>wmMenuItemIsChecked</h4>
<pre><code>bool wmMenuItemIsChecked(MenuBarT *bar, int32_t id);</code></pre>
<p>Query the checked state of a menu item by command ID. Searches all menus in the bar.</p>
<pre> Parameter Description
--------- -----------
bar Menu bar
id Command ID to query</pre>
<p>Returns: true if checked.</p>
<h4>wmMenuItemSetChecked</h4>
<pre><code>void wmMenuItemSetChecked(MenuBarT *bar, int32_t id, bool checked);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
bar Menu bar
id Command ID
checked New checked state</pre>
<h4>wmMenuItemSetEnabled</h4>
<pre><code>void wmMenuItemSetEnabled(MenuBarT *bar, int32_t id, bool enabled);</code></pre>
<p>Enable or disable a menu item by command ID.</p>
<pre> Parameter Description
--------- -----------
bar Menu bar
id Command ID
enabled true = enabled, false = grayed out</pre>
<h4>wmAddSubMenu</h4>
<pre><code>MenuT *wmAddSubMenu(MenuT *parentMenu, const char *label);</code></pre>
<p>Create a cascading submenu attached to a parent menu. The child MenuT is heap-allocated and freed when the parent window is destroyed.</p>
<pre> Parameter Description
--------- -----------
parentMenu Parent menu to attach submenu to
label Submenu label text</pre>
<p>Returns: Pointer to the child MenuT, or NULL on allocation failure.</p>
<h4>wmCreateMenu</h4>
<pre><code>MenuT *wmCreateMenu(void);</code></pre>
<p>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().</p>
<p>Returns: Pointer to the new MenuT.</p>
<h4>wmFreeMenu</h4>
<pre><code>void wmFreeMenu(MenuT *menu);</code></pre>
<p>Free a standalone menu allocated with wmCreateMenu(). Also frees any heap-allocated submenu children recursively.</p>
<pre> Parameter Description
--------- -----------
menu Menu to free</pre>
<h3>Scrollbars</h3>
<h4>wmAddVScrollbar</h4>
<pre><code>ScrollbarT *wmAddVScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize);</code></pre>
<p>Attach a vertical scrollbar to the right edge of the window's content area. Shrinks contentW by SCROLLBAR_WIDTH pixels.</p>
<pre> Parameter Description
--------- -----------
win Window
min, max Scroll value range
pageSize Visible portion (controls thumb size)</pre>
<p>Returns: Pointer to the new ScrollbarT.</p>
<h4>wmAddHScrollbar</h4>
<pre><code>ScrollbarT *wmAddHScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize);</code></pre>
<p>Attach a horizontal scrollbar to the bottom edge. Shrinks contentH by SCROLLBAR_WIDTH pixels.</p>
<pre> Parameter Description
--------- -----------
win Window
min, max Scroll value range
pageSize Visible portion</pre>
<p>Returns: Pointer to the new ScrollbarT.</p>
<h3>Drawing</h3>
<h4>wmDrawChrome</h4>
<pre><code>void wmDrawChrome(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo);</code></pre>
<p>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.</p>
<pre> 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</pre>
<h4>wmDrawContent</h4>
<pre><code>void wmDrawContent(DisplayT *d, const BlitOpsT *ops, WindowT *win, const RectT *clipTo);</code></pre>
<p>Blit the window's content backbuffer into the display backbuffer, clipped to the dirty rect. Pure copy operation (no drawing).</p>
<pre> Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
win Window
clipTo Dirty rectangle</pre>
<h4>wmDrawScrollbars</h4>
<pre><code>void wmDrawScrollbars(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo);</code></pre>
<p>Draw scrollbars (track, arrows, proportional thumb) for a window. Drawn after content so scrollbars overlay the content area edge.</p>
<pre> Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
colors Color scheme
win Window
clipTo Dirty rectangle</pre>
<h4>wmDrawMinimizedIcons</h4>
<pre><code>void wmDrawMinimizedIcons(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, const WindowStackT *stack, const RectT *clipTo);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
colors Color scheme
stack Window stack
clipTo Dirty rectangle</pre>
<h3>Hit Testing</h3>
<h4>wmHitTest</h4>
<pre><code>int32_t wmHitTest(const WindowStackT *stack, int32_t mx, int32_t my, int32_t *hitPart);</code></pre>
<p>Determine which window and chrome region is under the given screen coordinates. Iterates front-to-back (highest Z first) so the topmost window wins.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
mx, my Screen coordinates
hitPart Output: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, etc.</pre>
<p>Returns: Stack index of hit window, or -1 for desktop.</p>
<h4>wmResizeEdgeHit</h4>
<pre><code>int32_t wmResizeEdgeHit(const WindowT *win, int32_t mx, int32_t my);</code></pre>
<p>Determine which edge(s) of a window's border zone are targeted for resize.</p>
<pre> Parameter Description
--------- -----------
win Window
mx, my Screen coordinates</pre>
<p>Returns: Bitmask of RESIZE_LEFT / RESIZE_RIGHT / RESIZE_TOP / RESIZE_BOTTOM.</p>
<h4>wmMinimizedIconHit</h4>
<pre><code>int32_t wmMinimizedIconHit(const WindowStackT *stack, const DisplayT *d, int32_t mx, int32_t my);</code></pre>
<p>Hit-test minimized icons at the bottom of the screen.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
d Display context
mx, my Screen coordinates</pre>
<p>Returns: Stack index of the minimized window, or -1.</p>
<h3>Drag and Resize</h3>
<h4>wmDragBegin</h4>
<pre><code>void wmDragBegin(WindowStackT *stack, int32_t idx, int32_t mouseX, int32_t mouseY);</code></pre>
<p>Begin a window drag operation. Records the mouse offset from the window origin.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
idx Stack index of window to drag
mouseX/Y Current mouse position</pre>
<h4>wmDragMove</h4>
<pre><code>void wmDragMove(WindowStackT *stack, DirtyListT *dl, int32_t mouseX, int32_t mouseY, int32_t screenW, int32_t screenH);</code></pre>
<p>Update window position during an active drag. Dirties both old and new positions.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
dl Dirty list
mouseX/Y Current mouse position
screenW/H Screen dimensions (for clamping)</pre>
<h4>wmDragEnd</h4>
<pre><code>void wmDragEnd(WindowStackT *stack);</code></pre>
<p>End the current drag operation. Clears dragWindow state.</p>
<pre> Parameter Description
--------- -----------
stack Window stack</pre>
<h4>wmResizeBegin</h4>
<pre><code>void wmResizeBegin(WindowStackT *stack, int32_t idx, int32_t edge, int32_t mouseX, int32_t mouseY);</code></pre>
<p>Begin a window resize operation. Records which edge(s) are being dragged.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
idx Stack index
edge Bitmask of RESIZE_xxx flags
mouseX/Y Current mouse position</pre>
<h4>wmResizeMove</h4>
<pre><code>void wmResizeMove(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, int32_t *mouseX, int32_t *mouseY);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
dl Dirty list
d Display context
mouseX/Y In/out: mouse position (clamped on return)</pre>
<h4>wmResizeEnd</h4>
<pre><code>void wmResizeEnd(WindowStackT *stack);</code></pre>
<p>End the current resize operation. Clears resizeWindow state.</p>
<pre> Parameter Description
--------- -----------
stack Window stack</pre>
<h3>Scrollbar Interaction</h3>
<h4>wmScrollbarClick</h4>
<pre><code>void wmScrollbarClick(WindowStackT *stack, DirtyListT *dl, int32_t idx, int32_t orient, int32_t mx, int32_t my);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
dl Dirty list
idx Stack index of window
orient SCROLL_VERTICAL or SCROLL_HORIZONTAL
mx, my Click screen coordinates</pre>
<h4>wmScrollbarDrag</h4>
<pre><code>void wmScrollbarDrag(WindowStackT *stack, DirtyListT *dl, int32_t mx, int32_t my);</code></pre>
<p>Update the scroll value during an active thumb drag. Maps mouse position along the track to a proportional scroll value.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
dl Dirty list
mx, my Current mouse position</pre>
<h4>wmScrollbarEnd</h4>
<pre><code>void wmScrollbarEnd(WindowStackT *stack);</code></pre>
<p>End an active scrollbar thumb drag.</p>
<pre> Parameter Description
--------- -----------
stack Window stack</pre>
<h3>Minimize / Maximize / Restore</h3>
<h4>wmMaximize</h4>
<pre><code>void wmMaximize(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);</code></pre>
<p>Maximize a window. Saves current geometry, then expands to screen or maxW/maxH bounds.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
dl Dirty list
d Display context
win Window to maximize</pre>
<h4>wmMinimize</h4>
<pre><code>void wmMinimize(WindowStackT *stack, DirtyListT *dl, WindowT *win);</code></pre>
<p>Minimize a window. Hides the window and shows an icon at the bottom of the screen.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
dl Dirty list
win Window to minimize</pre>
<h4>wmRestore</h4>
<pre><code>void wmRestore(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);</code></pre>
<p>Restore a maximized window to its pre-maximize geometry.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
dl Dirty list
d Display context
win Maximized window to restore</pre>
<h4>wmRestoreMinimized</h4>
<pre><code>void wmRestoreMinimized(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);</code></pre>
<p>Restore a minimized window (show it again and remove the icon).</p>
<pre> Parameter Description
--------- -----------
stack Window stack
dl Dirty list
d Display context
win Minimized window to restore</pre>
<h3>Minimized Icon Layout</h3>
<h4>wmMinimizedIconPos</h4>
<pre><code>void wmMinimizedIconPos(const DisplayT *d, int32_t index, int32_t *x, int32_t *y);</code></pre>
<p>Compute the screen position of a minimized icon by ordinal index. Icons wrap into rows from bottom to top when the screen fills up.</p>
<pre> Parameter Description
--------- -----------
d Display context
index Ordinal index of the minimized icon
x, y Output: screen position</pre>
<h4>wmMinimizedIconRect</h4>
<pre><code>void wmMinimizedIconRect(const WindowStackT *stack, const DisplayT *d, int32_t *y, int32_t *h);</code></pre>
<p>Compute the screen rect covering all minimized icon rows. Used to dirty the icon area when windows are minimized or restored.</p>
<pre> Parameter Description
--------- -----------
stack Window stack
d Display context
y, h Output: vertical extent of icon area</pre>
<h3>Miscellaneous</h3>
<h4>wmSetTitle</h4>
<pre><code>void wmSetTitle(WindowT *win, DirtyListT *dl, const char *title);</code></pre>
<p>Set the window title and dirty the title bar for repaint.</p>
<pre> Parameter Description
--------- -----------
win Window
dl Dirty list
title New title text</pre>
<h4>wmSetIcon</h4>
<pre><code>int32_t wmSetIcon(WindowT *win, const char *path, const DisplayT *d);</code></pre>
<p>Load an icon image for a window from a file. Converts to display pixel format.</p>
<pre> Parameter Description
--------- -----------
win Window
path Image file path
d Display context</pre>
<p>Returns: 0 on success, -1 on failure.</p>
</div>
<div class="topic" id="api.app">
<h1>dvxApp.h -- Layer 5: Application API</h1>
<h2>dvxApp.h -- Layer 5: Application API</h2>
<p>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.</p>
<h3>AppContextT</h3>
<p>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.</p>
<h3>Initialization and Shutdown</h3>
<h4>dvxInit</h4>
<pre><code>int32_t dvxInit(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
ctx Application context to initialize
requestedW/H Desired screen resolution
preferredBpp Preferred bits per pixel</pre>
<p>Returns: 0 on success, negative on failure.</p>
<h4>dvxShutdown</h4>
<pre><code>void dvxShutdown(AppContextT *ctx);</code></pre>
<p>Tear down the GUI stack in reverse order: destroy all windows, restore text mode, release input devices. Safe to call after a failed dvxInit().</p>
<pre> Parameter Description
--------- -----------
ctx Application context</pre>
<h4>dvxChangeVideoMode</h4>
<pre><code>int32_t dvxChangeVideoMode(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);</code></pre>
<p>Switch to a new video mode live. Reallocates the backbuffer, all window content buffers, repacks colors, rescales wallpaper, and repositions off-screen windows.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
requestedW/H New resolution
preferredBpp New bits per pixel</pre>
<p>Returns: 0 on success, -1 on failure (old mode restored).</p>
<h3>Event Loop</h3>
<h4>dvxRun</h4>
<pre><code>void dvxRun(AppContextT *ctx);</code></pre>
<p>Enter the main event loop. Polls input, dispatches events, composites dirty regions, and yields on each iteration. Returns when ctx-&gt;running becomes false.</p>
<pre> Parameter Description
--------- -----------
ctx Application context</pre>
<h4>dvxUpdate</h4>
<pre><code>bool dvxUpdate(AppContextT *ctx);</code></pre>
<p>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).</p>
<pre> Parameter Description
--------- -----------
ctx Application context</pre>
<p>Returns: false when the GUI wants to exit.</p>
<h4>dvxQuit</h4>
<pre><code>void dvxQuit(AppContextT *ctx);</code></pre>
<p>Request exit from the main event loop (sets ctx-&gt;running = false).</p>
<pre> Parameter Description
--------- -----------
ctx Application context</pre>
<h3>Window Management</h3>
<h4>dvxCreateWindow</h4>
<pre><code>WindowT *dvxCreateWindow(AppContextT *ctx, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);</code></pre>
<p>Create a window at an explicit screen position. The window is raised to the top, focused, and its entire region is dirtied.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
title Window title
x, y Screen position
w, h Outer frame dimensions
resizable true = allow user resize</pre>
<p>Returns: Pointer to new WindowT.</p>
<h4>dvxCreateWindowCentered</h4>
<pre><code>WindowT *dvxCreateWindowCentered(AppContextT *ctx, const char *title, int32_t w, int32_t h, bool resizable);</code></pre>
<p>Convenience wrapper that centers the window on screen.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
title Window title
w, h Outer frame dimensions
resizable true = allow user resize</pre>
<p>Returns: Pointer to new WindowT.</p>
<h4>dvxDestroyWindow</h4>
<pre><code>void dvxDestroyWindow(AppContextT *ctx, WindowT *win);</code></pre>
<p>Destroy a window, free all its resources, and dirty its former region.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window to destroy</pre>
<h4>dvxRaiseWindow</h4>
<pre><code>void dvxRaiseWindow(AppContextT *ctx, WindowT *win);</code></pre>
<p>Raise a window to the top of the Z-order and give it focus.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window to raise</pre>
<h4>dvxFitWindow</h4>
<pre><code>void dvxFitWindow(AppContextT *ctx, WindowT *win);</code></pre>
<p>Resize a window to exactly fit its widget tree's computed minimum size (plus chrome). Used for dialog boxes and fixed-layout windows.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window to fit</pre>
<h4>dvxFitWindowW</h4>
<pre><code>void dvxFitWindowW(AppContextT *ctx, WindowT *win);</code></pre>
<p>Resize window width only to fit widget tree's minimum width (plus chrome).</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window to fit</pre>
<h4>dvxFitWindowH</h4>
<pre><code>void dvxFitWindowH(AppContextT *ctx, WindowT *win);</code></pre>
<p>Resize window height only to fit widget tree's minimum height (plus chrome).</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window to fit</pre>
<h4>dvxResizeWindow</h4>
<pre><code>void dvxResizeWindow(AppContextT *ctx, WindowT *win, int32_t newW, int32_t newH);</code></pre>
<p>Programmatically resize a window to the specified outer dimensions.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window to resize
newW, newH New outer frame dimensions</pre>
<h4>dvxMinimizeWindow</h4>
<pre><code>void dvxMinimizeWindow(AppContextT *ctx, WindowT *win);</code></pre>
<p>Minimize a window (show as icon at bottom of screen).</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window to minimize</pre>
<h4>dvxMaximizeWindow</h4>
<pre><code>void dvxMaximizeWindow(AppContextT *ctx, WindowT *win);</code></pre>
<p>Maximize a window (expand to fill screen or maxW/maxH).</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window to maximize</pre>
<h4>dvxHideWindow</h4>
<pre><code>void dvxHideWindow(AppContextT *ctx, WindowT *win);</code></pre>
<p>Hide a window without destroying it. Marks the exposed region dirty.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window to hide</pre>
<h4>dvxShowWindow</h4>
<pre><code>void dvxShowWindow(AppContextT *ctx, WindowT *win);</code></pre>
<p>Show a previously hidden window. Marks its region dirty for repaint.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window to show</pre>
<h3>Invalidation</h3>
<h4>dvxInvalidateRect</h4>
<pre><code>void dvxInvalidateRect(AppContextT *ctx, WindowT *win, int32_t x, int32_t y, int32_t w, int32_t h);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window
x, y, w, h Dirty rectangle in content-relative coordinates</pre>
<h4>dvxInvalidateWindow</h4>
<pre><code>void dvxInvalidateWindow(AppContextT *ctx, WindowT *win);</code></pre>
<p>Mark the entire window content area as dirty.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window to invalidate</pre>
<h3>Window Properties</h3>
<h4>dvxSetTitle</h4>
<pre><code>void dvxSetTitle(AppContextT *ctx, WindowT *win, const char *title);</code></pre>
<p>Set a window's title text and dirty the title bar.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window
title New title text</pre>
<h4>dvxSetWindowIcon</h4>
<pre><code>int32_t dvxSetWindowIcon(AppContextT *ctx, WindowT *win, const char *path);</code></pre>
<p>Load an icon for a window from an image file.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window
path Image file path</pre>
<p>Returns: 0 on success, -1 on failure.</p>
<h4>dvxSetBusy</h4>
<pre><code>void dvxSetBusy(AppContextT *ctx, bool busy);</code></pre>
<p>Set or clear busy state. While busy, the hourglass cursor is shown and input is blocked.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
busy true = show hourglass, false = normal</pre>
<h3>Accessors</h3>
<h4>dvxGetFont</h4>
<pre><code>const BitmapFontT *dvxGetFont(const AppContextT *ctx);</code></pre>
<p>Get a pointer to the default font.</p>
<pre> Parameter Description
--------- -----------
ctx Application context</pre>
<p>Returns: Pointer to the active BitmapFontT.</p>
<h4>dvxGetColors</h4>
<pre><code>const ColorSchemeT *dvxGetColors(const AppContextT *ctx);</code></pre>
<p>Get a pointer to the current color scheme.</p>
<pre> Parameter Description
--------- -----------
ctx Application context</pre>
<p>Returns: Pointer to the active ColorSchemeT.</p>
<h4>dvxGetDisplay</h4>
<pre><code>DisplayT *dvxGetDisplay(AppContextT *ctx);</code></pre>
<p>Get a pointer to the display context.</p>
<pre> Parameter Description
--------- -----------
ctx Application context</pre>
<p>Returns: Pointer to the DisplayT.</p>
<h4>dvxGetBlitOps</h4>
<pre><code>const BlitOpsT *dvxGetBlitOps(const AppContextT *ctx);</code></pre>
<p>Get a pointer to the blit operations vtable.</p>
<pre> Parameter Description
--------- -----------
ctx Application context</pre>
<p>Returns: Pointer to the active BlitOpsT.</p>
<h4>dvxGetVideoModes</h4>
<pre><code>const VideoModeInfoT *dvxGetVideoModes(const AppContextT *ctx, int32_t *count);</code></pre>
<p>Return the list of available video modes enumerated at init time.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
count Output: number of mode entries</pre>
<p>Returns: Pointer to the VideoModeInfoT array.</p>
<h3>Color Scheme</h3>
<h4>dvxSetColor</h4>
<pre><code>void dvxSetColor(AppContextT *ctx, ColorIdE id, uint8_t r, uint8_t g, uint8_t b);</code></pre>
<p>Set a single color by ID. Repacks to native pixel format and invalidates the entire screen.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
id Color ID (ColorIdE)
r, g, b RGB values (0-255)</pre>
<h4>dvxGetColor</h4>
<pre><code>void dvxGetColor(const AppContextT *ctx, ColorIdE id, uint8_t *r, uint8_t *g, uint8_t *b);</code></pre>
<p>Get a color's RGB values by ID.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
id Color ID (ColorIdE)
r, g, b Output: RGB values</pre>
<h4>dvxApplyColorScheme</h4>
<pre><code>void dvxApplyColorScheme(AppContextT *ctx);</code></pre>
<p>Apply all colors from ctx-&gt;colorRgb[] at once (repack + full repaint).</p>
<pre> Parameter Description
--------- -----------
ctx Application context</pre>
<h4>dvxResetColorScheme</h4>
<pre><code>void dvxResetColorScheme(AppContextT *ctx);</code></pre>
<p>Reset all colors to the built-in defaults and repaint.</p>
<pre> Parameter Description
--------- -----------
ctx Application context</pre>
<h4>dvxLoadTheme</h4>
<pre><code>bool dvxLoadTheme(AppContextT *ctx, const char *filename);</code></pre>
<p>Load a theme file (INI format with [colors] section) and apply it.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
filename Path to theme INI file</pre>
<p>Returns: true on success.</p>
<h4>dvxSaveTheme</h4>
<pre><code>bool dvxSaveTheme(const AppContextT *ctx, const char *filename);</code></pre>
<p>Save the current color scheme to a theme file.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
filename Output file path</pre>
<p>Returns: true on success.</p>
<h4>dvxColorName</h4>
<pre><code>const char *dvxColorName(ColorIdE id);</code></pre>
<p>Return the INI key name for a color ID (e.g. &quot;desktop&quot;, &quot;windowFace&quot;).</p>
<pre> Parameter Description
--------- -----------
id Color ID</pre>
<p>Returns: Static string.</p>
<h4>dvxColorLabel</h4>
<pre><code>const char *dvxColorLabel(ColorIdE id);</code></pre>
<p>Return a human-readable display label (e.g. &quot;Desktop&quot;, &quot;Cursor Color&quot;).</p>
<pre> Parameter Description
--------- -----------
id Color ID</pre>
<p>Returns: Static string.</p>
<h3>Wallpaper</h3>
<h4>dvxSetWallpaper</h4>
<pre><code>bool dvxSetWallpaper(AppContextT *ctx, const char *path);</code></pre>
<p>Load and apply a wallpaper image using the current wallpaperMode (stretch/tile/center). Pass NULL to clear the wallpaper.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
path Image file path, or NULL to clear</pre>
<p>Returns: true on success.</p>
<h4>dvxSetWallpaperMode</h4>
<pre><code>void dvxSetWallpaperMode(AppContextT *ctx, WallpaperModeE mode);</code></pre>
<p>Change the wallpaper display mode and re-render. No effect if no wallpaper is loaded.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
mode WallpaperStretchE, WallpaperTileE, or WallpaperCenterE</pre>
<h3>Mouse Configuration</h3>
<h4>dvxSetMouseConfig</h4>
<pre><code>void dvxSetMouseConfig(AppContextT *ctx, int32_t wheelDir, int32_t dblClickMs, int32_t accelThreshold);</code></pre>
<p>Configure mouse behavior.</p>
<pre> 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)</pre>
<h3>Accelerators</h3>
<h4>dvxCreateAccelTable</h4>
<pre><code>AccelTableT *dvxCreateAccelTable(void);</code></pre>
<p>Allocate a new accelerator table. Attach to a window via win-&gt;accelTable.</p>
<p>Returns: Pointer to new AccelTableT.</p>
<h4>dvxFreeAccelTable</h4>
<pre><code>void dvxFreeAccelTable(AccelTableT *table);</code></pre>
<p>Free an accelerator table and its entries.</p>
<pre> Parameter Description
--------- -----------
table Table to free</pre>
<h4>dvxAddAccel</h4>
<pre><code>void dvxAddAccel(AccelTableT *table, int32_t key, int32_t modifiers, int32_t cmdId);</code></pre>
<p>Register a keyboard shortcut. On match, fires the window's onMenu callback with cmdId.</p>
<pre> 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</pre>
<h3>Window Arrangement</h3>
<h4>dvxCascadeWindows</h4>
<pre><code>void dvxCascadeWindows(AppContextT *ctx);</code></pre>
<p>Cascade all visible, non-minimized windows. Each is offset diagonally by the title bar height.</p>
<pre> Parameter Description
--------- -----------
ctx Application context</pre>
<h4>dvxTileWindows</h4>
<pre><code>void dvxTileWindows(AppContextT *ctx);</code></pre>
<p>Arrange visible windows in an NxM grid filling the screen.</p>
<pre> Parameter Description
--------- -----------
ctx Application context</pre>
<h4>dvxTileWindowsH</h4>
<pre><code>void dvxTileWindowsH(AppContextT *ctx);</code></pre>
<p>Tile windows horizontally (side by side, equal width, full height).</p>
<pre> Parameter Description
--------- -----------
ctx Application context</pre>
<h4>dvxTileWindowsV</h4>
<pre><code>void dvxTileWindowsV(AppContextT *ctx);</code></pre>
<p>Tile windows vertically (stacked, full width, equal height).</p>
<pre> Parameter Description
--------- -----------
ctx Application context</pre>
<h3>Image I/O</h3>
<h4>dvxLoadImage</h4>
<pre><code>uint8_t *dvxLoadImage(const AppContextT *ctx, const char *path, int32_t *outW, int32_t *outH, int32_t *outPitch);</code></pre>
<p>Load an image file (BMP, PNG, JPEG, GIF) and convert to the display's native pixel format. Caller must free with dvxFreeImage().</p>
<pre> Parameter Description
--------- -----------
ctx Application context
path Image file path
outW, outH Output: image dimensions
outPitch Output: row pitch in bytes</pre>
<p>Returns: Pixel buffer, or NULL on failure.</p>
<h4>dvxLoadImageFromMemory</h4>
<pre><code>uint8_t *dvxLoadImageFromMemory(const AppContextT *ctx, const uint8_t *data, int32_t dataLen, int32_t *outW, int32_t *outH, int32_t *outPitch);</code></pre>
<p>Load an image from a memory buffer. Same output format as dvxLoadImage(). Caller must free with dvxFreeImage().</p>
<pre> 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</pre>
<p>Returns: Pixel buffer, or NULL on failure.</p>
<h4>dvxFreeImage</h4>
<pre><code>void dvxFreeImage(uint8_t *data);</code></pre>
<p>Free a pixel buffer returned by dvxLoadImage() or dvxLoadImageFromMemory().</p>
<pre> Parameter Description
--------- -----------
data Buffer to free</pre>
<h4>dvxImageInfo</h4>
<pre><code>bool dvxImageInfo(const char *path, int32_t *outW, int32_t *outH);</code></pre>
<p>Query image dimensions without decoding the full file.</p>
<pre> Parameter Description
--------- -----------
path Image file path
outW, outH Output: image dimensions</pre>
<p>Returns: true on success.</p>
<h4>dvxSaveImage</h4>
<pre><code>int32_t dvxSaveImage(const AppContextT *ctx, const uint8_t *data, int32_t w, int32_t h, int32_t pitch, const char *path);</code></pre>
<p>Save native-format pixel data to a PNG file.</p>
<pre> 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</pre>
<p>Returns: 0 on success, -1 on failure.</p>
<h3>Screenshots</h3>
<h4>dvxScreenshot</h4>
<pre><code>int32_t dvxScreenshot(AppContextT *ctx, const char *path);</code></pre>
<p>Save the entire screen (backbuffer contents) to a PNG file. Converts from native pixel format to RGB.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
path Output PNG file path</pre>
<p>Returns: 0 on success, -1 on failure.</p>
<h4>dvxWindowScreenshot</h4>
<pre><code>int32_t dvxWindowScreenshot(AppContextT *ctx, WindowT *win, const char *path);</code></pre>
<p>Save a window's content to a PNG file.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window
path Output PNG file path</pre>
<p>Returns: 0 on success, -1 on failure.</p>
<h3>Clipboard</h3>
<h4>dvxClipboardCopy</h4>
<pre><code>void dvxClipboardCopy(const char *text, int32_t len);</code></pre>
<p>Copy text to the process-wide clipboard buffer. Simple static buffer (not inter-process).</p>
<pre> Parameter Description
--------- -----------
text Text to copy
len Length in bytes</pre>
<h4>dvxClipboardGet</h4>
<pre><code>const char *dvxClipboardGet(int32_t *outLen);</code></pre>
<p>Retrieve the current clipboard contents. Returns a pointer to the internal buffer (valid until the next dvxClipboardCopy), or NULL if empty.</p>
<pre> Parameter Description
--------- -----------
outLen Output: length of clipboard text</pre>
<p>Returns: Clipboard text, or NULL.</p>
<h3>Resource Loading</h3>
<h4>dvxResLoadIcon</h4>
<pre><code>uint8_t *dvxResLoadIcon(AppContextT *ctx, const char *dxePath, const char *resName, int32_t *outW, int32_t *outH, int32_t *outPitch);</code></pre>
<p>Load an icon/image resource from a DXE file and decode to native pixel format. Caller must free with dvxFreeImage().</p>
<pre> 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</pre>
<p>Returns: Pixel buffer, or NULL if not found.</p>
<h4>dvxResLoadText</h4>
<pre><code>bool dvxResLoadText(const char *dxePath, const char *resName, char *buf, int32_t bufSize);</code></pre>
<p>Load a text resource from a DXE file into a caller-provided buffer. Null-terminated and truncated to fit bufSize.</p>
<pre> Parameter Description
--------- -----------
dxePath Path to DXE file
resName Resource name
buf Output buffer
bufSize Buffer capacity</pre>
<p>Returns: true on success.</p>
<h4>dvxResLoadData</h4>
<pre><code>void *dvxResLoadData(const char *dxePath, const char *resName, uint32_t *outSize);</code></pre>
<p>Load a raw binary resource from a DXE file. Returns a malloc'd buffer that the caller must free.</p>
<pre> Parameter Description
--------- -----------
dxePath Path to DXE file
resName Resource name
outSize Output: data size in bytes</pre>
<p>Returns: Data buffer, or NULL if not found.</p>
<h3>Utilities</h3>
<h4>dvxTextHash</h4>
<pre><code>uint32_t dvxTextHash(const char *text);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
text Null-terminated string to hash</pre>
<p>Returns: 32-bit hash value.</p>
</div>
<div class="topic" id="api.widget">
<h1>dvxWidget.h -- Widget System</h1>
<h2>dvxWidget.h -- Widget System</h2>
<p>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.</p>
<h3>WidgetT Structure</h3>
<p>Core widget structure. Generic across all widget types; type-specific data lives in the void *data pointer managed by each widget's DXE.</p>
<pre> 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
char accelKey Accelerator character (0 = none)
void *userData, *data Application data and widget-private data
const char *tooltip Tooltip text (NULL = none)
MenuT *contextMenu Right-click menu (NULL = none)</pre>
<p>Universal Callbacks:</p>
<pre> 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 btn, int32_t x, int32_t y) Mouse button pressed
onMouseUp(WidgetT *w, int32_t btn, int32_t x, int32_t y) Mouse button released
onMouseMove(WidgetT *w, int32_t btn, 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</pre>
<h3>Size Specification Macros</h3>
<pre> 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</pre>
<h3>Widget Class Flags</h3>
<pre> 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</pre>
<h3>Window Integration</h3>
<h4>wgtInitWindow</h4>
<pre><code>WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
win Window to initialize</pre>
<p>Returns: Root VBox widget (add children to this).</p>
<h3>Widget Operations</h3>
<h4>wgtGetContext</h4>
<pre><code>AppContextT *wgtGetContext(const WidgetT *w);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
w Any widget in the tree</pre>
<p>Returns: Pointer to the AppContextT.</p>
<h4>wgtInvalidate</h4>
<pre><code>void wgtInvalidate(WidgetT *w);</code></pre>
<p>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).</p>
<pre> Parameter Description
--------- -----------
w Widget to invalidate</pre>
<h4>wgtInvalidatePaint</h4>
<pre><code>void wgtInvalidatePaint(WidgetT *w);</code></pre>
<p>Mark a widget as needing repaint only, without re-layout. Use for visual-only changes (checkbox toggle, selection highlight, cursor blink).</p>
<pre> Parameter Description
--------- -----------
w Widget to repaint</pre>
<h4>wgtSetText</h4>
<pre><code>void wgtSetText(WidgetT *w, const char *text);</code></pre>
<p>Set widget text content (dispatches to the widget class's SET_TEXT handler).</p>
<pre> Parameter Description
--------- -----------
w Widget
text New text</pre>
<h4>wgtGetText</h4>
<pre><code>const char *wgtGetText(const WidgetT *w);</code></pre>
<p>Get the widget's current text content.</p>
<pre> Parameter Description
--------- -----------
w Widget</pre>
<p>Returns: Text string (empty string if no handler).</p>
<h4>wgtSetEnabled</h4>
<pre><code>void wgtSetEnabled(WidgetT *w, bool enabled);</code></pre>
<p>Enable or disable a widget. Disabled widgets are grayed out and do not receive input.</p>
<pre> Parameter Description
--------- -----------
w Widget
enabled true = enabled, false = disabled</pre>
<h4>wgtSetReadOnly</h4>
<pre><code>void wgtSetReadOnly(WidgetT *w, bool readOnly);</code></pre>
<p>Set read-only mode. Allows scrolling and selection but blocks editing.</p>
<pre> Parameter Description
--------- -----------
w Widget
readOnly true = read-only</pre>
<h4>wgtSetFocused</h4>
<pre><code>void wgtSetFocused(WidgetT *w);</code></pre>
<p>Set keyboard focus to a widget.</p>
<pre> Parameter Description
--------- -----------
w Widget to focus</pre>
<h4>wgtGetFocused</h4>
<pre><code>WidgetT *wgtGetFocused(void);</code></pre>
<p>Get the currently focused widget.</p>
<p>Returns: Focused widget, or NULL.</p>
<h4>wgtSetVisible</h4>
<pre><code>void wgtSetVisible(WidgetT *w, bool visible);</code></pre>
<p>Show or hide a widget.</p>
<pre> Parameter Description
--------- -----------
w Widget
visible true = visible, false = hidden</pre>
<h4>wgtSetName</h4>
<pre><code>void wgtSetName(WidgetT *w, const char *name);</code></pre>
<p>Set a widget's name for lookup via wgtFind().</p>
<pre> Parameter Description
--------- -----------
w Widget
name Name string (max MAX_WIDGET_NAME chars)</pre>
<h4>wgtFind</h4>
<pre><code>WidgetT *wgtFind(WidgetT *root, const char *name);</code></pre>
<p>Find a widget by name. Searches the subtree rooted at root.</p>
<pre> Parameter Description
--------- -----------
root Root of subtree to search
name Widget name to find</pre>
<p>Returns: Matching widget, or NULL.</p>
<h4>wgtDestroy</h4>
<pre><code>void wgtDestroy(WidgetT *w);</code></pre>
<p>Destroy a widget and all its children. Removes from parent's child list.</p>
<pre> Parameter Description
--------- -----------
w Widget to destroy</pre>
<h4>wgtSetTooltip</h4>
<pre><code>void wgtSetTooltip(WidgetT *w, const char *text);</code></pre>
<p>Set tooltip text for a widget. Pass NULL to remove. Caller owns the string and it must outlive the widget.</p>
<pre> Parameter Description
--------- -----------
w Widget
text Tooltip text, or NULL</pre>
<h4>widgetOnResize</h4>
<pre><code>void widgetOnResize(WindowT *win, int32_t newW, int32_t newH);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
win Window being resized
newW, newH New content dimensions</pre>
<h3>Layout</h3>
<h4>wgtResolveSize</h4>
<pre><code>int32_t wgtResolveSize(int32_t taggedSize, int32_t parentSize, int32_t charWidth);</code></pre>
<p>Decode a tagged size value (WGT_SIZE_PIXELS/CHARS/PERCENT) into a concrete pixel count. Returns 0 for a raw 0 input (meaning &quot;auto&quot;).</p>
<pre> Parameter Description
--------- -----------
taggedSize Tagged size value
parentSize Parent dimension (for PERCENT mode)
charWidth Font character width (for CHARS mode)</pre>
<p>Returns: Size in pixels.</p>
<h4>wgtLayout</h4>
<pre><code>void wgtLayout(WidgetT *root, int32_t availW, int32_t availH, const BitmapFontT *font);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
root Root widget
availW/H Available space
font Bitmap font (for character-based sizing)</pre>
<h4>wgtPaint</h4>
<pre><code>void wgtPaint(WidgetT *root, DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
root Root widget
d Display context
ops Blit operations vtable
font Bitmap font
colors Color scheme</pre>
<h3>Debug</h3>
<h4>wgtSetDebugLayout</h4>
<pre><code>void wgtSetDebugLayout(AppContextT *ctx, bool enabled);</code></pre>
<p>Draw colored borders around layout containers for debugging.</p>
<pre> Parameter Description
--------- -----------
ctx Application context
enabled true = draw debug borders</pre>
<h3>Dynamic Widget Registration</h3>
<h4>wgtRegisterClass</h4>
<pre><code>int32_t wgtRegisterClass(const WidgetClassT *wclass);</code></pre>
<p>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).</p>
<pre> Parameter Description
--------- -----------
wclass Widget class vtable to register</pre>
<p>Returns: Assigned type ID.</p>
<h4>wgtRegisterApi</h4>
<pre><code>void wgtRegisterApi(const char *name, const void *api);</code></pre>
<p>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.</p>
<pre> Parameter Description
--------- -----------
name Widget type name (e.g. &quot;button&quot;, &quot;listbox&quot;)
api Pointer to the widget's API struct</pre>
<h4>wgtGetApi</h4>
<pre><code>const void *wgtGetApi(const char *name);</code></pre>
<p>Retrieve a registered widget API struct by name.</p>
<pre> Parameter Description
--------- -----------
name Widget type name</pre>
<p>Returns: Pointer to the API struct, or NULL if not found.</p>
<h3>Widget Interface Descriptors</h3>
<h4>wgtRegisterIface</h4>
<pre><code>void wgtRegisterIface(const char *name, const WgtIfaceT *iface);</code></pre>
<p>Register an interface descriptor for a widget type. Used by the BASIC form runtime and IDE for generic property/method dispatch.</p>
<pre> Parameter Description
--------- -----------
name Widget type name
iface Interface descriptor</pre>
<h4>wgtGetIface</h4>
<pre><code>const WgtIfaceT *wgtGetIface(const char *name);</code></pre>
<p>Retrieve an interface descriptor by widget type name.</p>
<pre> Parameter Description
--------- -----------
name Widget type name</pre>
<p>Returns: Interface descriptor, or NULL.</p>
<h4>wgtFindByBasName</h4>
<pre><code>const char *wgtFindByBasName(const char *basName);</code></pre>
<p>Find a widget type name by its VB-style name (e.g. &quot;CommandButton&quot; -&gt; &quot;button&quot;). Case-insensitive search.</p>
<pre> Parameter Description
--------- -----------
basName VB-style widget name</pre>
<p>Returns: Internal type name, or NULL.</p>
<h4>wgtIfaceCount</h4>
<pre><code>int32_t wgtIfaceCount(void);</code></pre>
<p>Return the number of registered widget interfaces.</p>
<p>Returns: Count of registered interfaces.</p>
<h4>wgtIfaceAt</h4>
<pre><code>const WgtIfaceT *wgtIfaceAt(int32_t idx, const char **outName);</code></pre>
<p>Get a registered widget interface by index.</p>
<pre> Parameter Description
--------- -----------
idx Index (0-based)
outName Output: type name</pre>
<p>Returns: Interface descriptor.</p>
<h4>wgtIfaceGetPath</h4>
<pre><code>const char *wgtIfaceGetPath(const char *name);</code></pre>
<p>Get the .wgt DXE file path for a registered widget.</p>
<pre> Parameter Description
--------- -----------
name Widget type name</pre>
<p>Returns: File path string.</p>
<h4>wgtIfaceSetPath</h4>
<pre><code>void wgtIfaceSetPath(const char *name, const char *path);</code></pre>
<p>Set the .wgt DXE file path for a registered widget (called by the loader).</p>
<pre> Parameter Description
--------- -----------
name Widget type name
path DXE file path</pre>
<h4>wgtIfaceGetPathIndex</h4>
<pre><code>int32_t wgtIfaceGetPathIndex(const char *name);</code></pre>
<p>Get the 1-based index of this widget within its .wgt file. Used to construct suffixed resource names (e.g. &quot;name-2&quot;, &quot;icon16-2&quot;).</p>
<pre> Parameter Description
--------- -----------
name Widget type name</pre>
<p>Returns: 1-based index within the DXE file.</p>
<h3>Typed Dispatch Helpers</h3>
<p>The following inline functions provide type-safe dispatch through the WidgetClassT handler table. Each checks for a non-NULL handler before calling.</p>
<pre> 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</pre>
</div>
<div class="topic" id="libtasks">
<h1>libtasks -- Cooperative Task Switching</h1>
<h2>libtasks -- Cooperative Task Switching</h2>
<p>Credit-based cooperative (non-preemptive) multitasking library for DOS protected mode (DJGPP/DPMI). Each task receives (priority + 1) credits per scheduling round. Tasks run round-robin, consuming one credit per turn. When all credits are exhausted, every ready task is refilled. Higher-priority tasks run proportionally more often but never starve lower ones.</p>
<p>Header: tasks/taskswitch.h</p>
<h3>Why Cooperative</h3>
<p>DOS is single-threaded with no kernel scheduler. DPMI provides no preemption primitives. The DVX GUI event model is inherently single-threaded: one compositor, one input queue, one window stack. Cooperative switching lets each task yield at safe points, avoiding synchronization primitives entirely.</p>
<h3>Error Codes</h3>
<pre> Constant Value Description
-------- ----- -----------
TS_OK 0 Success
TS_ERR_INIT -1 Task system not initialized
TS_ERR_PARAM -2 Invalid parameter (bad task ID, etc.)
TS_ERR_FULL -3 Task array full (should not occur; array grows)
TS_ERR_NOMEM -4 Memory allocation failed
TS_ERR_STATE -5 Invalid state transition</pre>
<h3>Constants</h3>
<pre> Constant Value Description
-------- ----- -----------
TS_DEFAULT_STACK_SIZE 32768 Default stack size per task (32 KB)
TS_NAME_MAX 32 Maximum task name length including NUL
TS_PRIORITY_LOW 0 Low priority (1 credit per round)
TS_PRIORITY_NORMAL 5 Normal priority (6 credits per round)
TS_PRIORITY_HIGH 10 High priority (11 credits per round)</pre>
<h3>Types</h3>
<h4>TaskStateE</h4>
<p>Task scheduling state. Only Ready tasks participate in scheduling.</p>
<pre> Value Description
----- -----------
TaskStateReady Eligible for scheduling
TaskStateRunning Currently executing (cosmetic; marks active task)
TaskStatePaused Skipped by scheduler until explicitly resumed
TaskStateTerminated Slot available for reuse</pre>
<h4>TaskEntryT</h4>
<pre><code>typedef void (*TaskEntryT)(void *arg);</code></pre>
<p>Task entry point function signature. The void* argument lets the caller pass arbitrary context (e.g. a shell app descriptor).</p>
<h3>tsInit</h3>
<pre><code>int32_t tsInit(void);</code></pre>
<p>Initialize the task system. The calling context becomes task 0 (the main task). Task 0 is special: it cannot be killed or paused, and tsRecoverToMain() always returns control here. No separate stack is allocated for task 0; it uses the process stack directly.</p>
<p>Returns: TS_OK on success, TS_ERR_INIT if already initialized.</p>
<h3>tsShutdown</h3>
<pre><code>void tsShutdown(void);</code></pre>
<p>Shut down the task system and free all task stacks and internal storage. Safe to call even if tsInit() was never called.</p>
<h3>tsCreate</h3>
<pre><code>int32_t tsCreate(const char *name, TaskEntryT entry, void *arg, uint32_t stackSize, int32_t priority);</code></pre>
<p>Create a new task. Terminated task slots are recycled to avoid unbounded array growth.</p>
<pre> Parameter Description
--------- -----------
name Task name (truncated to TS_NAME_MAX - 1 characters)
entry Task entry point function
arg Opaque argument passed to entry
stackSize Stack size in bytes (pass 0 for TS_DEFAULT_STACK_SIZE)
priority Scheduling priority (0..10; use TS_PRIORITY_* constants)</pre>
<p>Returns: Task ID (&gt;= 0) on success, or a negative error code (TS_ERR_INIT, TS_ERR_PARAM, TS_ERR_NOMEM).</p>
<h3>tsYield</h3>
<pre><code>void tsYield(void);</code></pre>
<p>Yield CPU to the next eligible ready task using credit-based round-robin. This is the sole mechanism for task switching. Every task must call this (or a GUI function that calls it) periodically, or it will monopolize the CPU.</p>
<h3>tsPause</h3>
<pre><code>int32_t tsPause(uint32_t taskId);</code></pre>
<p>Pause a task, removing it from scheduling. Cannot pause the main task (ID 0). If a task pauses itself, an implicit yield occurs.</p>
<pre> Parameter Description
--------- -----------
taskId ID of the task to pause</pre>
<p>Returns: TS_OK on success, TS_ERR_PARAM on invalid ID, TS_ERR_STATE if the task is not in a pausable state.</p>
<h3>tsResume</h3>
<pre><code>int32_t tsResume(uint32_t taskId);</code></pre>
<p>Resume a paused task. Credits are refilled so the task gets a fair share of CPU time immediately rather than waiting for the next scheduling round.</p>
<pre> Parameter Description
--------- -----------
taskId ID of the task to resume</pre>
<p>Returns: TS_OK on success, TS_ERR_PARAM on invalid ID, TS_ERR_STATE if the task is not paused.</p>
<h3>tsSetPriority</h3>
<pre><code>int32_t tsSetPriority(uint32_t taskId, int32_t priority);</code></pre>
<p>Set a task's scheduling priority. Also refills credits so the change takes effect immediately.</p>
<pre> Parameter Description
--------- -----------
taskId ID of the task to modify
priority New priority level (0..10)</pre>
<p>Returns: TS_OK on success, TS_ERR_PARAM on invalid ID or out-of-range priority.</p>
<h3>tsGetPriority</h3>
<pre><code>int32_t tsGetPriority(uint32_t taskId);</code></pre>
<p>Get a task's current scheduling priority.</p>
<pre> Parameter Description
--------- -----------
taskId ID of the task to query</pre>
<p>Returns: Priority value (0..10) on success, TS_ERR_PARAM on invalid ID.</p>
<h3>tsGetState</h3>
<pre><code>TaskStateE tsGetState(uint32_t taskId);</code></pre>
<p>Get a task's current scheduling state.</p>
<pre> Parameter Description
--------- -----------
taskId ID of the task to query</pre>
<p>Returns: TaskStateE value. Returns TaskStateTerminated for invalid IDs.</p>
<h3>tsCurrentId</h3>
<pre><code>uint32_t tsCurrentId(void);</code></pre>
<p>Get the ID of the currently executing task. Always valid while the task system is initialized.</p>
<p>Returns: Current task ID.</p>
<h3>tsGetName</h3>
<pre><code>const char *tsGetName(uint32_t taskId);</code></pre>
<p>Get a task's name string.</p>
<pre> Parameter Description
--------- -----------
taskId ID of the task to query</pre>
<p>Returns: Pointer to the task's name, or NULL on invalid ID. The pointer remains valid until the task slot is reused.</p>
<h3>tsExit</h3>
<pre><code>void tsExit(void);</code></pre>
<p>Terminate the calling task. Must not be called from the main task (ID 0). The stack is freed immediately and the slot is marked for reuse. This function never returns; it performs an internal context switch to the next ready task.</p>
<h3>tsKill</h3>
<pre><code>int32_t tsKill(uint32_t taskId);</code></pre>
<p>Forcibly terminate another task. Cannot kill the main task (ID 0) or the currently running task (use tsExit() for self-termination). Safe because cooperative scheduling guarantees the target is suspended at a yield point.</p>
<pre> Parameter Description
--------- -----------
taskId ID of the task to terminate</pre>
<p>Returns: TS_OK on success, TS_ERR_PARAM on invalid ID or illegal target (main task, self).</p>
<h3>tsRecoverToMain</h3>
<pre><code>void tsRecoverToMain(void);</code></pre>
<p>Crash recovery: force the scheduler back to the main task (ID 0). Call after longjmp from a signal handler that fired in a non-main task. The crashed task is NOT cleaned up by this call; call tsKill() afterward to free its resources. This exists because longjmp unwinds the crashed task's stack but the scheduler state still points to it.</p>
<h3>tsActiveCount</h3>
<pre><code>uint32_t tsActiveCount(void);</code></pre>
<p>Get the number of non-terminated tasks currently in the system.</p>
<p>Returns: Count of tasks in Ready, Running, or Paused state.</p>
</div>
<div class="topic" id="shell.overview">
<h1>DVX Shell Library</h1>
<h2>DVX Shell Library</h2>
<p>The DVX shell library manages the lifecycle of DXE applications: loading, launching, tracking, and reaping. It provides the bridge between the DVX GUI compositor and dynamically loaded DXE3 application modules.</p>
<p>Header: shell/shellApp.h</p>
<h3>App Model</h3>
<p>The shell supports two kinds of DXE apps:</p>
<ul>
<li>Callback-only (hasMainLoop = false) -- appMain() runs in the shell's task 0, creates windows, registers event callbacks, and returns immediately. The app lives through GUI callbacks. Lifecycle ends when the last window is closed. Simpler and cheaper (no extra stack/task).</li>
</ul>
<p>Main-loop (hasMainLoop = true) -- A dedicated cooperative task is created. appMain() runs in that task and can do its own polling loop, calling tsYield() to share CPU. Lifecycle ends when appMain() returns or the task is killed. Needed for terminal emulators, games, or long computations.</p>
<p>Both types use the same DXE interface: an exported appDescriptor and appMain function.</p>
<h3>DXE Interface</h3>
<p>Every .app DXE module must export these symbols (COFF convention uses leading underscore):</p>
<pre> Symbol Type Required
------ ---- --------
_appDescriptor AppDescriptorT Yes
_appMain int32_t (*)(DxeAppContextT *) Yes
_appShutdown void (*)(void) No</pre>
<h3>State Machine</h3>
<p>App slots progress through four states:</p>
<pre><code>Free -&gt; Loaded -&gt; Running -&gt; Terminating -&gt; Free</code></pre>
<p>LoadedE is transient (only during shellLoadApp before the entry point is called). TerminatingE means the app's task has exited but cleanup has not yet occurred. The shell's main loop reaps terminating apps each frame via shellReapApps().</p>
<h3>Contents</h3>
<p><a href="#shell.types">Types and Constants</a></p>
<p><a href="#shell.lifecycle">Lifecycle API</a></p>
<p><a href="#shell.query">Query API</a></p>
<p><a href="#shell.config">Configuration API</a></p>
<p><a href="#shell.desktop">Desktop Callbacks</a></p>
<p><a href="#shell.info">System Information</a></p>
</div>
<div class="topic" id="shell.types">
<h1>Shell Types and Constants</h1>
<h2>Types and Constants</h2>
<h3>Constants</h3>
<pre> Constant Value Description
-------- ----- -----------
SHELL_APP_NAME_MAX 64 Maximum length of an app name string.
SHELL_STACK_DEFAULT 0 Use in AppDescriptorT.stackSize to get the default task stack size.
SHELL_DESKTOP_APP &quot;apps/kpunch/progman/progman.app&quot; Default desktop application path.</pre>
<h3>AppDescriptorT</h3>
<p>Exported by every DXE app as a global named appDescriptor. The shell reads it at load time to determine how to launch the app.</p>
<pre> Field Type Description
----- ---- -----------
name[SHELL_APP_NAME_MAX] char[] Display name of the application.
hasMainLoop bool false = callback-only, true = dedicated task.
multiInstance bool true = allow multiple simultaneous instances via temp copy.
stackSize int32_t SHELL_STACK_DEFAULT or explicit byte count for the task stack.
priority int32_t TS_PRIORITY_* value or custom priority for the task.</pre>
<h3>DxeAppContextT</h3>
<p>Passed as the sole argument to appMain(). Gives the app access to the shell's GUI context and its own identity.</p>
<pre> Field Type Description
----- ---- -----------
shellCtx AppContextT * The shell's GUI context (for creating windows, drawing, etc.).
appId int32_t This app's unique ID (slot index, 1-based).
appPath[DVX_MAX_PATH] char[] Full path to the .app DXE file.
appDir[DVX_MAX_PATH] char[] Directory containing the .app file (for loading resources).
configDir[DVX_MAX_PATH] char[] Writable config directory (e.g. CONFIG/APPS/KPUNCH/DVXBASIC/).
args[1024] char[] Launch arguments (empty string if none).
helpFile[DVX_MAX_PATH] char[] Help file path (for F1 context help).
helpTopic[128] char[] Current help topic ID (updated by the app at runtime).</pre>
<p>The appDir field is derived from the .app file path at load time so apps can find their own resources via relative paths. This is necessary because the working directory is shared by all apps in DOS.</p>
<h3>AppStateE</h3>
<pre> Value Description
----- -----------
AppStateFreeE Slot is available for reuse.
AppStateLoadedE DXE loaded, entry point not yet called (transient).
AppStateRunningE Entry point called, app is active.
AppStateTerminatingE Shutdown in progress, awaiting reap.</pre>
<h3>ShellAppT</h3>
<p>Per-app slot in the shell's app table. Slot 0 is reserved for the shell itself; apps use slots 1 and above.</p>
<pre> Field Type Description
----- ---- -----------
appId int32_t Unique ID (slot index, 1-based; 0 = shell).
name[SHELL_APP_NAME_MAX] char[] Display name from AppDescriptorT.
path[DVX_MAX_PATH] char[] Original DXE file path.
tempPath[DVX_MAX_PATH] char[] Temp copy path for multi-instance (empty if not a copy).
dxeHandle void * dlopen() handle for the DXE module.
state AppStateE Current lifecycle state.
hasMainLoop bool Whether this app has a dedicated task.
mainTaskId uint32_t Task ID if hasMainLoop, else 0.
entryFn int32_t (*)(DxeAppContextT *) Pointer to appMain.
shutdownFn void (*)(void) Pointer to appShutdown (may be NULL).
dxeCtx DxeAppContextT * Heap-allocated context (address stable across realloc).</pre>
</div>
<div class="topic" id="shell.lifecycle">
<h1>App Lifecycle API</h1>
<h2>App Lifecycle API</h2>
<h3>shellAppInit</h3>
<pre><code>void shellAppInit(void);</code></pre>
<p>Initialize the app slot table. Seeds slot 0 (reserved for the shell). Must be called once at startup before any other shell API function.</p>
<h3>shellLoadApp</h3>
<pre><code>int32_t shellLoadApp(AppContextT *ctx, const char *path);</code></pre>
<p>Load and start an app from a DXE file. Returns the app ID (&gt;= 1) on success, or -1 on error.</p>
<p>For callback-only apps, appMain() runs synchronously and returns before shellLoadApp returns. For main-loop apps, a cooperative task is created and the app begins running on the next tsYield().</p>
<p>If multiInstance is false in the app's descriptor and the same DXE is already loaded, the call fails with an error dialog. If multiInstance is true, the DXE is copied to a temp file so dlopen gets an independent code and data image.</p>
<h3>shellLoadAppWithArgs</h3>
<pre><code>int32_t shellLoadAppWithArgs(AppContextT *ctx, const char *path, const char *args);</code></pre>
<p>Load and run an app with arguments. The args string is copied into DxeAppContextT.args before appMain() is called. Otherwise identical to shellLoadApp().</p>
<h3>shellReapApps</h3>
<pre><code>bool shellReapApps(AppContextT *ctx);</code></pre>
<p>Scan for and reap finished apps. Call once per frame from the main loop.</p>
<p>Returns true if any apps were reaped, so the caller can trigger a desktop refresh. For main-loop apps, termination is detected by the AppStateTerminatingE state (set when appMain returns). For callback-only apps, termination is detected when no windows remain for that app.</p>
<h3>shellReapApp</h3>
<pre><code>void shellReapApp(AppContextT *ctx, ShellAppT *app);</code></pre>
<p>Gracefully shut down a single app. Calls the app's shutdownFn (if present), destroys all windows belonging to the app, kills its task (if any), closes the DXE handle, and frees the context. The slot returns to AppStateFreeE.</p>
<h3>shellForceKillApp</h3>
<pre><code>void shellForceKillApp(AppContextT *ctx, ShellAppT *app);</code></pre>
<p>Forcibly kill an app without calling its shutdown hook. Used by the Task Manager &quot;End Task&quot; or when an app has crashed and cannot be trusted to run cleanup code.</p>
<p>Cleanup order: windows first (removes from compositor), then task (frees stack), then DXE handle (unmaps code). Closing the DXE before destroying windows would cause callbacks into unmapped code.</p>
<h3>shellTerminateAllApps</h3>
<pre><code>void shellTerminateAllApps(AppContextT *ctx);</code></pre>
<p>Force-kill all running apps. Called during shell shutdown. Iterates all slots and calls shellForceKillApp() on each active app.</p>
</div>
<div class="topic" id="shell.query">
<h1>Query API</h1>
<h2>Query API</h2>
<h3>shellGetApp</h3>
<pre><code>ShellAppT *shellGetApp(int32_t appId);</code></pre>
<p>Look up an app slot by ID. Returns a pointer to the ShellAppT, or NULL if the ID is out of range or the slot is free. Valid app IDs are 1 through shellAppSlotCount() - 1.</p>
<h3>shellAppSlotCount</h3>
<pre><code>int32_t shellAppSlotCount(void);</code></pre>
<p>Return the total number of app slots (including slot 0). Use as the iteration bound when scanning all slots. Slot 0 is the shell itself; app slots start at 1.</p>
<h3>shellRunningAppCount</h3>
<pre><code>int32_t shellRunningAppCount(void);</code></pre>
<p>Count running apps, not counting the shell itself. Includes apps in both AppStateLoadedE and AppStateRunningE states.</p>
</div>
<div class="topic" id="shell.config">
<h1>Configuration API</h1>
<h2>Configuration API</h2>
<p>Each app has a per-app configuration directory derived from its DXE path, mirrored under CONFIG/. For example, an app at APPS/KPUNCH/DVXBASIC/dvxbasic.app gets the config directory CONFIG/APPS/KPUNCH/DVXBASIC/.</p>
<h3>shellEnsureConfigDir</h3>
<pre><code>int32_t shellEnsureConfigDir(const DxeAppContextT *ctx);</code></pre>
<p>Ensure the app's config directory exists, creating all parent directories as needed. Returns 0 on success, -1 on failure.</p>
<p>Call this before writing any config files. The directory path comes from ctx-&gt;configDir.</p>
<h3>shellConfigPath</h3>
<pre><code>void shellConfigPath(const DxeAppContextT *ctx, const char *filename, char *outPath, int32_t outSize);</code></pre>
<p>Build a full path to a file in the app's config directory by joining ctx-&gt;configDir with the given filename.</p>
<pre><code>// Example:
char path[DVX_MAX_PATH];
shellConfigPath(ctx, &quot;settings.ini&quot;, path, sizeof(path));
// -&gt; &quot;CONFIG/APPS/KPUNCH/PROGMAN/settings.ini&quot;</code></pre>
</div>
<div class="topic" id="shell.desktop">
<h1>Desktop Callbacks</h1>
<h2>Desktop Callbacks</h2>
<p>The shell provides a notification mechanism for app state changes (load, reap, crash). Desktop managers register a callback to refresh their display when apps come and go.</p>
<h3>shellRegisterDesktopUpdate</h3>
<pre><code>void shellRegisterDesktopUpdate(void (*updateFn)(void));</code></pre>
<p>Register a callback for app state change notifications. Multiple callbacks are supported. Apps typically call this during appMain() to receive notifications.</p>
<h3>shellUnregisterDesktopUpdate</h3>
<pre><code>void shellUnregisterDesktopUpdate(void (*updateFn)(void));</code></pre>
<p>Remove a previously registered callback. Call this before app shutdown to avoid dangling function pointers.</p>
<h3>shellDesktopUpdate</h3>
<pre><code>void shellDesktopUpdate(void);</code></pre>
<p>Notify all registered desktop callbacks that app state has changed. Called internally by the shell after loading or reaping an app. Can also be called by apps that need to trigger a desktop refresh.</p>
<h3>shellCtrlEscFn</h3>
<pre><code>extern void (*shellCtrlEscFn)(AppContextT *ctx);</code></pre>
<p>Function pointer set by the taskmgr DXE's constructor. The shell calls this when Ctrl+Esc is pressed. NULL if the task manager is not loaded.</p>
</div>
<div class="topic" id="shell.info">
<h1>System Information</h1>
<h2>System Information</h2>
<p>Header: shell/shellInfo.h</p>
<p>Thin wrapper around the platform layer's hardware detection. Gathers system information at startup, logs it, and caches the result for display in dialogs.</p>
<h3>shellInfoInit</h3>
<pre><code>void shellInfoInit(AppContextT *ctx);</code></pre>
<p>Gather all hardware information via the platform layer, log each line to DVX.LOG, and store the result for later retrieval. Call once after dvxInit().</p>
<h3>shellGetSystemInfo</h3>
<pre><code>const char *shellGetSystemInfo(void);</code></pre>
<p>Return the formatted system information text. The returned pointer is valid for the lifetime of the process (static buffer in the platform layer).</p>
</div>
<div class="topic" id="sql.overview">
<h1>dvxSql -- SQL Database Interface</h1>
<h3>dvxSql -- SQL Database Interface</h3>
<p>High-level wrapper around SQLite3 for DVX applications. Manages database connections and result set cursors via integer handles so BASIC code never touches raw pointers. All handles are 1-based; 0 indicates an error or invalid handle.</p>
<p>Header: sql/dvxSql.h</p>
<h4>Limits</h4>
<pre> Constant Value Description
-------- ----- -----------
MAX_DBS 16 Maximum number of simultaneously open databases.
MAX_CURSORS 64 Maximum number of simultaneously open result set cursors.</pre>
<h4>Handle Model</h4>
<p>Database and cursor handles are int32_t values. A successful open or query returns a handle greater than zero. Handle 0 is reserved as the invalid/error sentinel. Closing a database automatically finalizes all cursors that belong to it.</p>
<p><a href="#sql.db">Database Operations</a></p>
<p><a href="#sql.cursor">Cursor Operations</a></p>
<p><a href="#sql.utility">Utility Functions</a></p>
<p><a href="#sql.example">Example</a></p>
</div>
<div class="topic" id="sql.db">
<h1>Database Operations</h1>
<h3>Database Operations</h3>
<h4>dvxSqlOpen</h4>
<pre><code>int32_t dvxSqlOpen(const char *path);</code></pre>
<p>Open a SQLite database file. Creates the file if it does not exist.</p>
<pre> Parameter Description
--------- -----------
path Path to the database file.</pre>
<p>Returns a database handle greater than 0 on success, or 0 on error (null path, open failure, or no free slots).</p>
<h4>dvxSqlClose</h4>
<pre><code>void dvxSqlClose(int32_t db);</code></pre>
<p>Close a database and free all associated resources. Any open cursors belonging to this database are automatically finalized.</p>
<pre> Parameter Description
--------- -----------
db Database handle returned by dvxSqlOpen.</pre>
<p>Safe to call with an invalid handle (no-op).</p>
<h4>dvxSqlExec</h4>
<pre><code>bool dvxSqlExec(int32_t db, const char *sql);</code></pre>
<p>Execute one or more SQL statements that return no result rows. Suitable for DDL (CREATE TABLE, DROP TABLE, etc.) and DML (INSERT, UPDATE, DELETE).</p>
<pre> Parameter Description
--------- -----------
db Database handle.
sql SQL statement(s) to execute.</pre>
<p>Returns true on success, false on error. On failure, the error message is available via dvxSqlError. On success, the affected row count is available via dvxSqlAffectedRows.</p>
<h4>dvxSqlError</h4>
<pre><code>const char *dvxSqlError(int32_t db);</code></pre>
<p>Return the last error message for a database handle. The returned string is stored internally and valid until the next operation on the same handle.</p>
<pre> Parameter Description
--------- -----------
db Database handle.</pre>
<p>Returns the error string, or &quot;Invalid database handle&quot; if the handle is invalid.</p>
<h4>dvxSqlAffectedRows</h4>
<pre><code>int32_t dvxSqlAffectedRows(int32_t db);</code></pre>
<p>Return the number of rows inserted, updated, or deleted by the last dvxSqlExec call on this handle.</p>
<pre> Parameter Description
--------- -----------
db Database handle.</pre>
<p>Returns the row count, or 0 if the handle is invalid.</p>
</div>
<div class="topic" id="sql.cursor">
<h1>Cursor Operations</h1>
<h3>Cursor Operations</h3>
<p>Result set cursors are created by dvxSqlQuery and must be freed with dvxSqlFreeResult when no longer needed. A new cursor is positioned before the first row; call dvxSqlNext to advance to the first row before reading field values.</p>
<h4>dvxSqlQuery</h4>
<pre><code>int32_t dvxSqlQuery(int32_t db, const char *sql);</code></pre>
<p>Execute a SELECT query and return a cursor handle for iterating the results. The cursor is positioned before the first row.</p>
<pre> Parameter Description
--------- -----------
db Database handle.
sql SQL SELECT statement.</pre>
<p>Returns a cursor handle greater than 0 on success, or 0 on error (invalid handle, null SQL, SQL syntax error, or no free cursor slots). On failure, the error message is available via dvxSqlError on the database handle.</p>
<h4>dvxSqlNext</h4>
<pre><code>bool dvxSqlNext(int32_t rs);</code></pre>
<p>Advance the cursor to the next row.</p>
<pre> Parameter Description
--------- -----------
rs Cursor handle returned by dvxSqlQuery.</pre>
<p>Returns true if a row is now available for reading, false if the cursor has reached the end or the handle is invalid.</p>
<h4>dvxSqlEof</h4>
<pre><code>bool dvxSqlEof(int32_t rs);</code></pre>
<p>Test whether the cursor is past the last row.</p>
<pre> Parameter Description
--------- -----------
rs Cursor handle.</pre>
<p>Returns true if the cursor is exhausted or the handle is invalid, false otherwise.</p>
<h4>dvxSqlFieldCount</h4>
<pre><code>int32_t dvxSqlFieldCount(int32_t rs);</code></pre>
<p>Return the number of columns in the result set.</p>
<pre> Parameter Description
--------- -----------
rs Cursor handle.</pre>
<p>Returns the column count, or 0 if the handle is invalid.</p>
<h4>dvxSqlFieldName</h4>
<pre><code>const char *dvxSqlFieldName(int32_t rs, int32_t col);</code></pre>
<p>Return the name of a column by index.</p>
<pre> Parameter Description
--------- -----------
rs Cursor handle.
col Column index (0-based).</pre>
<p>Returns the column name, or &quot;&quot; if the handle or index is invalid.</p>
<h4>dvxSqlFieldText</h4>
<pre><code>const char *dvxSqlFieldText(int32_t rs, int32_t col);</code></pre>
<p>Return the value of a column as a string.</p>
<pre> Parameter Description
--------- -----------
rs Cursor handle.
col Column index (0-based).</pre>
<p>Returns the text value, or &quot;&quot; if the handle or index is invalid or the value is NULL.</p>
<h4>dvxSqlFieldByName</h4>
<pre><code>const char *dvxSqlFieldByName(int32_t rs, const char *name);</code></pre>
<p>Return the value of a column identified by name as a string. The name match is case-insensitive.</p>
<pre> Parameter Description
--------- -----------
rs Cursor handle.
name Column name (case-insensitive).</pre>
<p>Returns the text value, or &quot;&quot; if the handle is invalid, the name is NULL, or no column with that name exists.</p>
<h4>dvxSqlFieldInt</h4>
<pre><code>int32_t dvxSqlFieldInt(int32_t rs, int32_t col);</code></pre>
<p>Return the value of a column as a 32-bit integer.</p>
<pre> Parameter Description
--------- -----------
rs Cursor handle.
col Column index (0-based).</pre>
<p>Returns the integer value, or 0 if the handle or index is invalid.</p>
<h4>dvxSqlFieldDbl</h4>
<pre><code>double dvxSqlFieldDbl(int32_t rs, int32_t col);</code></pre>
<p>Return the value of a column as a double-precision floating point number.</p>
<pre> Parameter Description
--------- -----------
rs Cursor handle.
col Column index (0-based).</pre>
<p>Returns the double value, or 0.0 if the handle or index is invalid.</p>
<h4>dvxSqlFreeResult</h4>
<pre><code>void dvxSqlFreeResult(int32_t rs);</code></pre>
<p>Close a result set cursor and free its resources. Must be called for every cursor returned by dvxSqlQuery.</p>
<pre> Parameter Description
--------- -----------
rs Cursor handle.</pre>
<p>Safe to call with an invalid handle (no-op).</p>
</div>
<div class="topic" id="sql.utility">
<h1>Utility Functions</h1>
<h3>Utility Functions</h3>
<h4>dvxSqlEscape</h4>
<pre><code>int32_t dvxSqlEscape(const char *src, char *dst, int32_t dstSize);</code></pre>
<p>Escape a string for safe inclusion in SQL string literals. Doubles single quotes so that O'Brien becomes O''Brien.</p>
<pre> Parameter Description
--------- -----------
src Source string to escape.
dst Destination buffer for the escaped string.
dstSize Size of the destination buffer in bytes.</pre>
<p>Returns the length of the escaped string (not including the null terminator), or -1 if the buffer was too small or any parameter is NULL/invalid.</p>
</div>
<div class="topic" id="sql.example">
<h1>Example Usage</h1>
<h3>Example Usage</h3>
<h4>Creating a Table and Inserting Data</h4>
<pre><code>int32_t db = dvxSqlOpen(&quot;mydata.db&quot;);
if (!db) {
// handle error
}
dvxSqlExec(db, &quot;CREATE TABLE IF NOT EXISTS contacts (&quot;
&quot;id INTEGER PRIMARY KEY, &quot;
&quot;name TEXT, &quot;
&quot;phone TEXT)&quot;);
dvxSqlExec(db, &quot;INSERT INTO contacts (name, phone) &quot;
&quot;VALUES ('Alice', '555-0100')&quot;);</code></pre>
<h4>Querying and Iterating Results</h4>
<pre><code>int32_t rs = dvxSqlQuery(db, &quot;SELECT id, name, phone FROM contacts&quot;);
if (!rs) {
printf(&quot;Error: %s\n&quot;, dvxSqlError(db));
}
while (dvxSqlNext(rs)) {
int32_t id = dvxSqlFieldInt(rs, 0);
const char *name = dvxSqlFieldText(rs, 1);
const char *phone = dvxSqlFieldText(rs, 2);
printf(&quot;%d: %s -- %s\n&quot;, id, name, phone);
}
dvxSqlFreeResult(rs);
dvxSqlClose(db);</code></pre>
<h4>Escaping User Input</h4>
<pre><code>char escaped[512];
dvxSqlEscape(userInput, escaped, sizeof(escaped));
char sql[1024];
snprintf(sql, sizeof(sql),
&quot;INSERT INTO notes (text) VALUES ('%s')&quot;, escaped);
dvxSqlExec(db, sql);</code></pre>
</div>
<div class="topic" id="lib.texthelp">
<h1>Text Help Library</h1>
<h2>Text Help Library</h2>
<p>Shared text editing infrastructure library for DVX widget DXEs. Provides cursor blink management, cross-widget selection clearing, word boundary logic, and a complete single-line text editing engine. Used by TextInput, Spinner, ComboBox, AnsiTerm, and other widgets that need text editing behavior.</p>
<p>Header: texthelp/textHelp.h</p>
<h3>Constants</h3>
<pre> Constant Value Description
-------- ----- -----------
TEXT_INPUT_PAD 3 Pixel padding inside text editing fields.</pre>
</div>
<div class="topic" id="lib.texthelp.cursorblink">
<h1>wgtUpdateCursorBlink</h1>
<h3>wgtUpdateCursorBlink</h3>
<p>Advances the cursor blink timer. When the blink interval (250 ms) elapses, toggles the global sCursorBlinkOn flag and invalidates the currently focused widget for repaint. Registered automatically at library load time via a constructor function that sets the sCursorBlinkFn pointer.</p>
<pre><code>void wgtUpdateCursorBlink(void);</code></pre>
<p>Takes no arguments and returns nothing. Called by the core event loop.</p>
</div>
<div class="topic" id="lib.texthelp.clearother">
<h1>clearOtherSelections</h1>
<h3>clearOtherSelections</h3>
<p>Clears the text selection on whichever widget previously had one, unless that widget is the one passed as the argument. Tracks the last selected widget in a static pointer for O(1) lookup instead of walking the widget tree. Validates that the previous widget's window is still in the window stack before touching it, so stale pointers from closed windows are handled safely. If the previous selection was in a different window, that window gets a full repaint to clear the stale highlight.</p>
<pre><code>void clearOtherSelections(WidgetT *except);</code></pre>
<pre> Parameter Type Description
--------- ---- -----------
except WidgetT * The widget that now owns the selection. Its selection is preserved.</pre>
</div>
<div class="topic" id="lib.texthelp.iswordchar">
<h1>isWordChar</h1>
<h3>isWordChar</h3>
<p>Returns true if the character is alphanumeric or underscore. Used by word boundary functions to define what constitutes a &quot;word&quot; for double-click selection and Ctrl+arrow navigation.</p>
<pre><code>bool isWordChar(char c);</code></pre>
<pre> Parameter Type Description
--------- ---- -----------
c char The character to test.</pre>
<p>Returns true if c is alphanumeric (a-z, A-Z, 0-9) or underscore.</p>
</div>
<div class="topic" id="lib.texthelp.wordend">
<h1>wordEnd</h1>
<h3>wordEnd</h3>
<p>Scans forward from the given position, returning the index of the first non-word character. Used to find the right boundary of a word for double-click word selection.</p>
<pre><code>int32_t wordEnd(const char *buf, int32_t len, int32_t pos);</code></pre>
<pre> Parameter Type Description
--------- ---- -----------
buf const char * The text buffer to scan.
len int32_t Length of the text in the buffer.
pos int32_t Starting position (character index).</pre>
<p>Returns the index one past the last word character.</p>
</div>
<div class="topic" id="lib.texthelp.wordstart">
<h1>wordStart</h1>
<h3>wordStart</h3>
<p>Scans backward from the given position, returning the index of the first character of the current word. Used to find the left boundary of a word for double-click word selection.</p>
<pre><code>int32_t wordStart(const char *buf, int32_t pos);</code></pre>
<pre> Parameter Type Description
--------- ---- -----------
buf const char * The text buffer to scan.
pos int32_t Starting position (character index).</pre>
<p>Returns the index of the first character of the word containing pos.</p>
</div>
<div class="topic" id="lib.texthelp.dragupdate">
<h1>widgetTextEditDragUpdateLine</h1>
<h3>widgetTextEditDragUpdateLine</h3>
<p>Called during mouse drag to extend the selection in a single-line text field. Converts a viewport-relative pixel x coordinate to a character position and updates the cursor and selection end accordingly. Auto-scrolls the text when the mouse moves past the left or right visible edge.</p>
<pre><code>void widgetTextEditDragUpdateLine(
int32_t vx, int32_t leftEdge, int32_t maxChars,
const BitmapFontT *font, int32_t len,
int32_t *pCursorPos, int32_t *pScrollOff,
int32_t *pSelEnd);</code></pre>
<pre> Parameter Type Description
--------- ---- -----------
vx int32_t Mouse x position in viewport coordinates.
leftEdge int32_t Pixel x of the left edge of the text area.
maxChars int32_t Maximum visible characters in the field.
font const BitmapFontT * Bitmap font used for character width.
len int32_t Total length of the text buffer.
pCursorPos int32_t * [in/out] Current cursor position.
pScrollOff int32_t * [in/out] Horizontal scroll offset in characters.
pSelEnd int32_t * [out] Updated selection end position.</pre>
</div>
<div class="topic" id="lib.texthelp.mouseclick">
<h1>widgetTextEditMouseClick</h1>
<h3>widgetTextEditMouseClick</h3>
<p>Handles mouse click events for single-line text widgets. Converts pixel coordinates to a character position using the font's character width. Detects multi-click sequences via the core multiClickDetect() function:</p>
<ul>
<li>Single click -- places the cursor and begins a potential drag selection.</li>
<li>Double click -- selects the word under the cursor (if wordSelect is true), or selects all text.</li>
</ul>
<p>Triple click -- selects all text in the field.</p>
<pre><code>void widgetTextEditMouseClick(
WidgetT *w, int32_t vx, int32_t vy,
int32_t textLeftX, const BitmapFontT *font,
const char *buf, int32_t len, int32_t scrollOff,
int32_t *pCursorPos, int32_t *pSelStart,
int32_t *pSelEnd, bool wordSelect,
bool dragSelect);</code></pre>
<pre> Parameter Type Description
--------- ---- -----------
w WidgetT * The widget receiving the click.
vx int32_t Mouse x in viewport coordinates.
vy int32_t Mouse y in viewport coordinates.
textLeftX int32_t Pixel x of the left edge of the text area.
font const BitmapFontT * Bitmap font for character width calculation.
buf const char * Text buffer contents.
len int32_t Length of text in the buffer.
scrollOff int32_t Current horizontal scroll offset.
pCursorPos int32_t * [out] Computed cursor position.
pSelStart int32_t * [out] Selection start.
pSelEnd int32_t * [out] Selection end.
wordSelect bool If true, double-click selects word; if false, selects all.
dragSelect bool If true, single-click begins drag selection.</pre>
</div>
<div class="topic" id="lib.texthelp.onkey">
<h1>widgetTextEditOnKey</h1>
<h3>widgetTextEditOnKey</h3>
<p>The core single-line text editing engine. Processes a single keystroke and updates the buffer, cursor, scroll offset, selection, and undo state. All state is passed by pointer so the function is reusable across TextInput, Spinner, ComboBox, and any other single-line widget.</p>
<pre><code>void widgetTextEditOnKey(
WidgetT *w, int32_t key, int32_t mod,
char *buf, int32_t bufSize,
int32_t *pLen, int32_t *pCursor,
int32_t *pScrollOff,
int32_t *pSelStart, int32_t *pSelEnd,
char *undoBuf, int32_t *pUndoLen,
int32_t *pUndoCursor, int32_t fieldWidth);</code></pre>
<pre> Parameter Type Description
--------- ---- -----------
w WidgetT * The widget receiving the key event.
key int32_t Key code (ASCII for printable, control code or scan|0x100 for extended).
mod int32_t Modifier flags (KEY_MOD_SHIFT, etc.).
buf char * [in/out] The text buffer.
bufSize int32_t Total size of the buffer including null terminator.
pLen int32_t * [in/out] Current text length.
pCursor int32_t * [in/out] Cursor position (character index).
pScrollOff int32_t * [in/out] Horizontal scroll offset.
pSelStart int32_t * [in/out] Selection start (-1 if no selection).
pSelEnd int32_t * [in/out] Selection end (-1 if no selection).
undoBuf char * Undo buffer (same size as buf). NULL to disable undo.
pUndoLen int32_t * [in/out] Length of undo buffer contents.
pUndoCursor int32_t * [in/out] Cursor position saved in undo state.
fieldWidth int32_t Visible field width in pixels. 0 = use widget width.</pre>
<h4>Supported Keys</h4>
<pre> Key Action
--- ------
Printable Insert character at cursor (replaces selection if active).
Backspace Delete character before cursor or delete selection.
Delete Delete character after cursor or delete selection.
Left Move cursor left. With Shift, extend selection.
Right Move cursor right. With Shift, extend selection.
Ctrl+Left Move cursor to previous word boundary. With Shift, extend selection.
Ctrl+Right Move cursor to next word boundary. With Shift, extend selection.
Home Move cursor to start. With Shift, extend selection.
End Move cursor to end. With Shift, extend selection.
Ctrl+A Select all text.
Ctrl+C Copy selection to clipboard.
Ctrl+V Paste from clipboard (newlines stripped).
Ctrl+X Cut selection to clipboard.
Ctrl+Z Undo (swaps current and undo buffers).</pre>
<p>Fires w-&gt;onChange after any mutation (insert, delete, paste, cut, undo). Automatically adjusts scroll offset to keep cursor visible after every operation.</p>
</div>
<div class="topic" id="lib.texthelp.paintline">
<h1>widgetTextEditPaintLine</h1>
<h3>widgetTextEditPaintLine</h3>
<p>Renders a single line of text with optional selection highlighting and a blinking cursor. Splits the visible text into up to three segments (pre-selection, selection, post-selection) and draws each with appropriate colors. The selection highlight uses the menu highlight colors from the color scheme. The cursor is drawn as a one-pixel vertical line when sCursorBlinkOn is true.</p>
<pre><code>void widgetTextEditPaintLine(
DisplayT *d, const BlitOpsT *ops,
const BitmapFontT *font,
const ColorSchemeT *colors,
int32_t textX, int32_t textY,
const char *buf, int32_t visLen,
int32_t scrollOff, int32_t cursorPos,
int32_t selStart, int32_t selEnd,
uint32_t fg, uint32_t bg,
bool showCursor,
int32_t cursorMinX, int32_t cursorMaxX);</code></pre>
<pre> Parameter Type Description
--------- ---- -----------
d DisplayT * Display context for drawing.
ops const BlitOpsT * Blit operations table for the current pixel format.
font const BitmapFontT * Bitmap font for text rendering.
colors const ColorSchemeT * Color scheme (used for selection highlight colors).
textX int32_t Pixel x of the start of visible text.
textY int32_t Pixel y of the text baseline.
buf const char * Visible portion of the text buffer (buf + scrollOff).
visLen int32_t Number of visible characters to draw.
scrollOff int32_t Scroll offset (used to map selection to visible range).
cursorPos int32_t Absolute cursor position in the full buffer.
selStart int32_t Selection start (-1 if no selection).
selEnd int32_t Selection end (-1 if no selection).
fg uint32_t Foreground (text) color.
bg uint32_t Background color.
showCursor bool Whether to draw the cursor (false when widget lacks focus).
cursorMinX int32_t Left clipping bound for cursor drawing.
cursorMaxX int32_t Right clipping bound for cursor drawing.</pre>
</div>
<div class="topic" id="lib.listhelp">
<h1>List Helper Library</h1>
<h2>List Helper Library</h2>
<p>Shared helper routines for dropdown and list-based widget DXEs (ListBox, Dropdown, ComboBox, ListView, TreeView). Provides dropdown arrow rendering, item measurement, keyboard navigation, popup geometry calculation, and popup list painting.</p>
<p>Header: listhelp/listHelp.h</p>
<h3>Constants</h3>
<pre> Constant Value Description
-------- ----- -----------
DROPDOWN_BTN_WIDTH 16 Width of the dropdown arrow button in pixels.
DROPDOWN_MAX_VISIBLE 8 Maximum number of items visible in a popup list.</pre>
<h3>widgetDrawDropdownArrow</h3>
<p>Draw the triangular dropdown arrow glyph centered at a given position.</p>
<pre><code>void widgetDrawDropdownArrow(DisplayT *d, const BlitOpsT *ops,
int32_t centerX, int32_t centerY, uint32_t color);</code></pre>
<pre> Parameter Description
--------- -----------
d Display context.
ops Blit operations vtable for the active pixel depth.
centerX Horizontal center of the arrow in backbuffer coordinates.
centerY Vertical center of the arrow in backbuffer coordinates.
color Pre-packed pixel color for the arrow.</pre>
<h3>widgetMaxItemLen</h3>
<p>Scan an array of strings and return the length (in characters) of the longest item.</p>
<pre><code>int32_t widgetMaxItemLen(const char **items, int32_t count);</code></pre>
<pre> Parameter Description
--------- -----------
items Array of null-terminated string pointers.
count Number of items in the array.</pre>
<p>Returns the character length of the longest item, or 0 if count is zero.</p>
<h3>widgetNavigateIndex</h3>
<p>Compute a new selected index from a navigation key press. Handles Up, Down, Home, End, Page Up, and Page Down.</p>
<pre><code>int32_t widgetNavigateIndex(int32_t key, int32_t current,
int32_t count, int32_t pageSize);</code></pre>
<pre> Parameter Description
--------- -----------
key Keyboard scancode (Up, Down, Home, End, PgUp, PgDn).
current Currently selected index.
count Total number of items in the list.
pageSize Number of visible items (used for PgUp/PgDn step size).</pre>
<p>Returns the new index, clamped to [0, count-1].</p>
<h3>widgetDropdownPopupRect</h3>
<p>Calculate the screen rectangle for a dropdown popup list, positioning it below the owning widget and clamping to screen bounds.</p>
<pre><code>void widgetDropdownPopupRect(WidgetT *w, const BitmapFontT *font,
int32_t contentH, int32_t itemCount,
int32_t *popX, int32_t *popY, int32_t *popW, int32_t *popH);</code></pre>
<pre> Parameter Description
--------- -----------
w The widget that owns the popup (Dropdown, ComboBox, etc.).
font Bitmap font used for item text (determines row height).
contentH Height of the widget's content area in pixels.
itemCount Total number of items in the list.
popX Output: popup X position (screen coordinates).
popY Output: popup Y position (screen coordinates).
popW Output: popup width in pixels.
popH Output: popup height in pixels.</pre>
<p>The popup is sized to show up to DROPDOWN_MAX_VISIBLE items.</p>
<h3>widgetPaintPopupList</h3>
<p>Render a popup item list with highlight, scrolling, and beveled border.</p>
<pre><code>void widgetPaintPopupList(DisplayT *d, const BlitOpsT *ops,
const BitmapFontT *font, const ColorSchemeT *colors,
int32_t popX, int32_t popY, int32_t popW, int32_t popH,
const char **items, int32_t itemCount,
int32_t hoverIdx, int32_t scrollPos);</code></pre>
<pre> Parameter Description
--------- -----------
d Display context.
ops Blit operations vtable.
font Bitmap font for rendering item text.
colors Color scheme for background, text, and highlight colors.
popX Popup X position (from widgetDropdownPopupRect).
popY Popup Y position.
popW Popup width.
popH Popup height.
items Array of null-terminated item strings.
itemCount Total number of items.
hoverIdx Index of the highlighted (hovered/selected) item, or -1 for none.
scrollPos Index of the first visible item (scroll offset).</pre>
</div>
<div class="topic" id="lib.taskmgr">
<h1>Task Manager</h1>
<h2>Task Manager</h2>
<p>System-level task manager for DVX. Displays running applications and per-app memory usage. Always accessible via Ctrl+Esc regardless of which application is focused. Persists independently of the desktop app (Program Manager).</p>
<p>Header: taskmgr/shellTaskMgr.h</p>
<p>Loaded as: bin/libs/taskmgr.lib</p>
<h3>shellTaskMgrOpen</h3>
<p>Open the Task Manager window, or raise it to the front if already open.</p>
<pre><code>void shellTaskMgrOpen(AppContextT *ctx);</code></pre>
<pre> Parameter Description
--------- -----------
ctx Application context (from dvxInit). Required for window creation and event registration.</pre>
<p>Called by the shell's global Ctrl+Esc handler.</p>
<h3>shellTaskMgrRefresh</h3>
<p>Refresh the task list display. Call this when applications are launched or terminated so the Task Manager reflects the current state.</p>
<pre><code>void shellTaskMgrRefresh(void);</code></pre>
<p>Takes no parameters. Safe to call even if the Task Manager window is not currently open (the call is a no-op in that case).</p>
</div>
<div class="topic" id="lib.serial">
<h1>Serial Stack</h1>
<h2>Serial Stack</h2>
<p>The DVX serial/networking stack provides reliable, optionally encrypted communication over RS-232 serial ports. It is composed of four layers, each building on the one below:</p>
<ul>
<li>rs232 -- ISR-driven UART driver with ring buffers and flow control</li>
<li>packet -- HDLC framing, CRC-16, Go-Back-N ARQ (reliable delivery)</li>
<li>security -- 1024-bit Diffie-Hellman key exchange, XTEA-CTR cipher, DRBG RNG</li>
</ul>
<p>secLink -- Convenience wrapper: channel multiplexing, per-packet encryption</p>
<p>Loaded as: bin/libs/kpunch/serial/serial.lib</p>
<p><a href="#lib.serial.rs232">Layer 1: RS-232 UART Driver</a></p>
<p><a href="#lib.serial.packet">Layer 2: Packet Transport</a></p>
<p><a href="#lib.serial.security">Layer 3: Security (DH + XTEA)</a></p>
<p><a href="#lib.serial.seclink">Layer 4: Secure Link</a></p>
</div>
<div class="topic" id="lib.serial.rs232">
<h1>RS-232 UART Driver</h1>
<h2>RS-232 UART Driver</h2>
<p>ISR-driven serial port driver supporting up to 4 simultaneous COM ports. A shared ISR drains UART FIFOs into per-port ring buffers (2048 bytes, power-of-2 for fast index wrapping). Flow control (XON/XOFF, RTS/CTS, DTR/DSR) operates within the ISR using watermark thresholds. All ISR data structures are DPMI-locked to prevent page faults.</p>
<p>Header: rs232/rs232.h</p>
<h3>Port Constants</h3>
<pre> Constant Value Description
-------- ----- -----------
RS232_COM1 0 First serial port.
RS232_COM2 1 Second serial port.
RS232_COM3 2 Third serial port.
RS232_COM4 3 Fourth serial port.</pre>
<h3>Handshake Modes</h3>
<pre> Constant Value Description
-------- ----- -----------
RS232_HANDSHAKE_NONE 0 No flow control.
RS232_HANDSHAKE_XONXOFF 1 Software flow control (XON/XOFF characters).
RS232_HANDSHAKE_RTSCTS 2 Hardware flow control via RTS/CTS lines.
RS232_HANDSHAKE_DTRDSR 3 Hardware flow control via DTR/DSR lines.</pre>
<h3>UART Types</h3>
<p>Detected automatically by probing the scratch register and FIFO capability.</p>
<pre> Constant Value Description
-------- ----- -----------
RS232_UART_UNKNOWN 0 Detection failed.
RS232_UART_8250 1 Original IBM PC UART. No FIFO.
RS232_UART_16450 2 Has scratch register, no FIFO.
RS232_UART_16550 3 Has FIFO but buggy (rare).
RS232_UART_16550A 4 Working 16-byte FIFO. Most common in 486+ hardware.</pre>
<h3>Error Codes</h3>
<pre> Constant Value Description
-------- ----- -----------
RS232_SUCCESS 0 Operation succeeded.
RS232_ERR_UNKNOWN -1 Unknown error.
RS232_ERR_NOT_OPEN -2 Port is not open.
RS232_ERR_ALREADY_OPEN -3 Port is already open.
RS232_ERR_NO_UART -4 No UART detected at port address.
RS232_ERR_INVALID_PORT -5 Invalid port number.
RS232_ERR_INVALID_BASE -6 Invalid base I/O address.
RS232_ERR_INVALID_IRQ -7 Invalid IRQ number.
RS232_ERR_INVALID_BPS -8 Invalid baud rate.
RS232_ERR_INVALID_DATA -9 Invalid data bits value.
RS232_ERR_INVALID_PARITY -10 Invalid parity character.
RS232_ERR_INVALID_STOP -11 Invalid stop bits value.
RS232_ERR_INVALID_HANDSHAKE -12 Invalid handshake mode.
RS232_ERR_INVALID_FIFO -13 Invalid FIFO threshold.
RS232_ERR_NULL_PTR -14 NULL pointer argument.
RS232_ERR_IRQ_NOT_FOUND -15 Could not detect IRQ for port.
RS232_ERR_LOCK_MEM -16 DPMI memory lock failed.</pre>
<h3>rs232Open</h3>
<p>Open a COM port with the specified line parameters.</p>
<pre><code>int rs232Open(int com, int32_t bps, int dataBits,
char parity, int stopBits, int handshake);</code></pre>
<pre> Parameter Description
--------- -----------
com Port index (RS232_COM1..RS232_COM4).
bps Baud rate (e.g. 9600, 19200, 38400, 57600, 115200).
dataBits Data bits per character (5, 6, 7, or 8).
parity Parity mode: 'N' (none), 'O' (odd), 'E' (even), 'M' (mark), 'S' (space).
stopBits Stop bits (1 or 2).
handshake Flow control mode (RS232_HANDSHAKE_*).</pre>
<p>Returns RS232_SUCCESS or a negative error code.</p>
<h3>rs232Close</h3>
<p>Close a COM port and release its ISR resources.</p>
<pre><code>int rs232Close(int com);</code></pre>
<h3>rs232Read</h3>
<p>Non-blocking read from the receive ring buffer.</p>
<pre><code>int rs232Read(int com, char *data, int len);</code></pre>
<pre> Parameter Description
--------- -----------
com Port index.
data Buffer to receive data.
len Maximum bytes to read.</pre>
<p>Returns the number of bytes actually read (may be less than len).</p>
<h3>rs232Write</h3>
<p>Blocking polled write directly to UART transmit holding register. Bypasses the TX ring buffer. Use for small, immediate writes.</p>
<pre><code>int rs232Write(int com, const char *data, int len);</code></pre>
<p>Returns RS232_SUCCESS or a negative error code.</p>
<h3>rs232WriteBuf</h3>
<p>Non-blocking write to the transmit ring buffer. The ISR drains buffered data to the UART asynchronously.</p>
<pre><code>int rs232WriteBuf(int com, const char *data, int len);</code></pre>
<p>Returns the number of bytes actually queued (may be less than len if the buffer is full).</p>
<h3>rs232Set</h3>
<p>Change all line parameters on an open port.</p>
<pre><code>int rs232Set(int com, int32_t bps, int dataBits,
char parity, int stopBits, int handshake);</code></pre>
<h3>Configuration Getters</h3>
<pre> Function Returns
-------- -------
rs232GetBase(com) I/O base address.
rs232GetBps(com) Current baud rate.
rs232GetData(com) Data bits setting.
rs232GetParity(com) Parity character ('N', 'O', 'E', 'M', 'S').
rs232GetStop(com) Stop bits setting.
rs232GetHandshake(com) Handshake mode.
rs232GetIrq(com) IRQ number.
rs232GetUartType(com) Detected UART type (RS232_UART_*).</pre>
<h3>Status Getters</h3>
<pre> Function Returns
-------- -------
rs232GetRxBuffered(com) Bytes waiting in the receive ring buffer.
rs232GetTxBuffered(com) Bytes waiting in the transmit ring buffer.
rs232GetCts(com) CTS line state (0 or 1).
rs232GetDsr(com) DSR line state (0 or 1).
rs232GetDtr(com) DTR line state (0 or 1).
rs232GetRts(com) RTS line state (0 or 1).
rs232GetLsr(com) Line status register value.
rs232GetMcr(com) Modem control register value.
rs232GetMsr(com) Modem status register value.</pre>
<h3>Configuration Setters</h3>
<pre> Function Description
-------- -----------
rs232SetBase(com, base) Set I/O base address (before open).
rs232SetBps(com, bps) Change baud rate.
rs232SetData(com, dataBits) Change data bits.
rs232SetParity(com, parity) Change parity mode.
rs232SetStop(com, stopBits) Change stop bits.
rs232SetHandshake(com, handshake) Change flow control mode.
rs232SetIrq(com, irq) Set IRQ number (before open).
rs232SetMcr(com, mcr) Set modem control register directly.
rs232SetDtr(com, dtr) Set DTR line state.
rs232SetRts(com, rts) Set RTS line state.
rs232SetFifoThreshold(com, thr) Set FIFO trigger level (1, 4, 8, or 14 bytes).</pre>
<h3>Buffer Management</h3>
<pre> Function Description
-------- -----------
rs232ClearRxBuffer(com) Discard all data in the receive ring buffer.
rs232ClearTxBuffer(com) Discard all data in the transmit ring buffer.</pre>
</div>
<div class="topic" id="lib.serial.packet">
<h1>Packet Transport</h1>
<h2>Packet Transport</h2>
<p>Reliable, ordered packet delivery over an RS-232 serial link. Uses HDLC-style byte-stuffed framing for frame delimiting, CRC-16-CCITT for error detection, and Go-Back-N ARQ with a configurable sliding window for retransmission.</p>
<p>Header: packet/packet.h</p>
<h3>Constants</h3>
<pre> Constant Value Description
-------- ----- -----------
PKT_MAX_PAYLOAD 255 Maximum bytes per packet payload.
PKT_DEFAULT_WINDOW 4 Default sliding window size (unacknowledged frames in flight).
PKT_MAX_WINDOW 8 Maximum sliding window size.</pre>
<h3>Error Codes</h3>
<pre> Constant Value Description
-------- ----- -----------
PKT_SUCCESS 0 Operation succeeded.
PKT_ERR_INVALID_PORT -1 Invalid COM port index.
PKT_ERR_NOT_OPEN -2 Connection is not open.
PKT_ERR_ALREADY_OPEN -3 Connection is already open.
PKT_ERR_WOULD_BLOCK -4 Operation would block.
PKT_ERR_OVERFLOW -5 Buffer overflow.
PKT_ERR_INVALID_PARAM -6 Invalid parameter.
PKT_ERR_TX_FULL -7 Transmit window is full.
PKT_ERR_NO_DATA -8 No data available.
PKT_ERR_DISCONNECTED -9 Remote side disconnected.</pre>
<h3>PktRecvCallbackT</h3>
<p>Callback type for received packets.</p>
<pre><code>typedef void (*PktRecvCallbackT)(void *ctx,
const uint8_t *data, int len);</code></pre>
<pre> Parameter Description
--------- -----------
ctx User context pointer (passed to pktOpen).
data Payload bytes (valid only during the callback).
len Payload length.</pre>
<h3>pktOpen</h3>
<p>Open a packetized connection over an already-open COM port.</p>
<pre><code>PktConnT *pktOpen(int com, int windowSize,
PktRecvCallbackT callback, void *callbackCtx);</code></pre>
<pre> Parameter Description
--------- -----------
com COM port index (RS232_COM1..RS232_COM4). Must already be open via rs232Open.
windowSize Sliding window size (1..PKT_MAX_WINDOW). Pass 0 for PKT_DEFAULT_WINDOW.
callback Called when a complete, CRC-verified packet is received.
callbackCtx User pointer passed to the callback.</pre>
<p>Returns an opaque PktConnT handle, or NULL on failure.</p>
<h3>pktClose</h3>
<p>Close a packetized connection. Does not close the underlying COM port.</p>
<pre><code>void pktClose(PktConnT *conn);</code></pre>
<h3>pktSend</h3>
<p>Send a data packet.</p>
<pre><code>int pktSend(PktConnT *conn, const uint8_t *data,
int len, bool block);</code></pre>
<pre> Parameter Description
--------- -----------
conn Connection handle from pktOpen.
data Payload bytes (up to PKT_MAX_PAYLOAD).
len Payload length.
block If true, block until transmit window has space. If false, return PKT_ERR_TX_FULL when the window is full.</pre>
<p>Returns PKT_SUCCESS or a negative error code.</p>
<h3>pktPoll</h3>
<p>Poll for incoming data, process received frames, and handle retransmits. Must be called frequently in the main loop.</p>
<pre><code>int pktPoll(PktConnT *conn);</code></pre>
<p>Returns the number of valid data packets delivered to the callback.</p>
<h3>pktReset</h3>
<p>Reset the connection state (sequence numbers, buffers) and send a RST frame to the remote side.</p>
<pre><code>int pktReset(PktConnT *conn);</code></pre>
<h3>pktCanSend</h3>
<p>Check whether there is room in the transmit window for another packet.</p>
<pre><code>bool pktCanSend(PktConnT *conn);</code></pre>
<h3>pktGetPending</h3>
<p>Get the number of unacknowledged packets currently in the transmit window.</p>
<pre><code>int pktGetPending(PktConnT *conn);</code></pre>
</div>
<div class="topic" id="lib.serial.security">
<h1>Security (DH + XTEA)</h1>
<h2>Security (DH + XTEA)</h2>
<p>Cryptographic primitives for the serial stack: 1024-bit Diffie-Hellman key exchange (RFC 2409 Group 2), XTEA block cipher in CTR mode, and an XTEA-CTR DRBG random number generator.</p>
<p>XTEA requires no lookup tables and compiles to approximately 20 instructions per round, making it suitable for 486-class hardware where AES S-box tables would thrash the 8KB cache.</p>
<p>Header: security/security.h</p>
<h3>Constants</h3>
<pre> Constant Value Description
-------- ----- -----------
SEC_DH_KEY_SIZE 128 Size of a DH public key in bytes (1024 bits).
SEC_XTEA_KEY_SIZE 16 Size of an XTEA key in bytes (128 bits).</pre>
<h3>Error Codes</h3>
<pre> Constant Value Description
-------- ----- -----------
SEC_SUCCESS 0 Operation succeeded.
SEC_ERR_PARAM -1 Invalid parameter.
SEC_ERR_NOT_READY -2 DH context not ready (keys not generated or secret not computed).
SEC_ERR_ALLOC -3 Memory allocation failed.</pre>
<h3>RNG Functions</h3>
<p>The RNG uses XTEA-CTR as a DRBG. Hardware entropy from PIT timer jitter is weak (~20 bits); supplement with keyboard timing or mouse jitter before generating DH keys.</p>
<pre><code>void secRngSeed(const uint8_t *entropy, int len);
int secRngGatherEntropy(uint8_t *buf, int len);
void secRngAddEntropy(const uint8_t *data, int len);
void secRngBytes(uint8_t *buf, int len);</code></pre>
<pre> Function Description
-------- -----------
secRngSeed Seed the DRBG from an entropy buffer.
secRngGatherEntropy Gather hardware entropy (PIT jitter, BIOS tick count) into a buffer.
secRngAddEntropy Mix additional entropy into the DRBG state.
secRngBytes Generate pseudorandom bytes.</pre>
<h3>Diffie-Hellman Key Exchange</h3>
<p>1024-bit DH with 256-bit private exponents using the RFC 2409 Group 2 safe prime.</p>
<pre><code>SecDhT *secDhCreate(void);
int secDhGenerateKeys(SecDhT *dh);
int secDhGetPublicKey(SecDhT *dh, uint8_t *buf, int *len);
int secDhComputeSecret(SecDhT *dh,
const uint8_t *remotePub, int len);
int secDhDeriveKey(SecDhT *dh, uint8_t *key, int keyLen);
void secDhDestroy(SecDhT *dh);</code></pre>
<pre> Function Description
-------- -----------
secDhCreate Allocate a new DH context.
secDhGenerateKeys Generate a private exponent and public key. RNG must be seeded first.
secDhGetPublicKey Copy the local public key into buf. *len receives the key size.
secDhComputeSecret Compute the shared secret from the remote public key.
secDhDeriveKey Derive a symmetric key (XTEA key) from the shared secret via hashing.
secDhDestroy Free the DH context and all associated memory.</pre>
<p>Typical usage order: secDhCreate, secDhGenerateKeys, exchange public keys, secDhComputeSecret, secDhDeriveKey, secDhDestroy.</p>
<h3>XTEA-CTR Cipher</h3>
<p>XTEA in counter mode. Encrypt and decrypt are the same operation (XOR with keystream). The counter must never repeat with the same key.</p>
<pre><code>SecCipherT *secCipherCreate(const uint8_t *key);
void secCipherSetNonce(SecCipherT *c,
uint32_t nonceLo, uint32_t nonceHi);
void secCipherCrypt(SecCipherT *c,
uint8_t *data, int len);
void secCipherDestroy(SecCipherT *c);</code></pre>
<pre> Function Description
-------- -----------
secCipherCreate Allocate a cipher context with a 128-bit key.
secCipherSetNonce Set the initial counter value (nonce). Must be unique per session.
secCipherCrypt Encrypt or decrypt data in place. The counter increments automatically.
secCipherDestroy Free the cipher context.</pre>
</div>
<div class="topic" id="lib.serial.seclink">
<h1>Secure Link</h1>
<h2>Secure Link</h2>
<p>Top-level API composing all three lower layers (rs232, packet, security) into a single interface. Provides channel multiplexing (0-127) and per-packet encryption control over a reliable serial link.</p>
<p>Each packet carries a one-byte header: bit 7 is the encrypted flag, bits 6..0 are the channel number. Unencrypted packets can be sent before the handshake completes (e.g., for version negotiation).</p>
<p>Header: seclink/secLink.h</p>
<h3>Constants</h3>
<pre> Constant Value Description
-------- ----- -----------
SECLINK_MAX_PAYLOAD 254 Maximum plaintext bytes per send (PKT_MAX_PAYLOAD minus 1-byte channel header).
SECLINK_MAX_CHANNEL 127 Highest valid channel number.</pre>
<h3>Error Codes</h3>
<pre> Constant Value Description
-------- ----- -----------
SECLINK_SUCCESS 0 Operation succeeded.
SECLINK_ERR_PARAM -1 Invalid parameter.
SECLINK_ERR_SERIAL -2 RS-232 layer error.
SECLINK_ERR_ALLOC -3 Memory allocation failed.
SECLINK_ERR_HANDSHAKE -4 DH handshake failed.
SECLINK_ERR_NOT_READY -5 Handshake not yet completed (encrypted send attempted).
SECLINK_ERR_SEND -6 Packet send failed.</pre>
<h3>SecLinkRecvT</h3>
<p>Receive callback type. Delivers decrypted plaintext with the channel number.</p>
<pre><code>typedef void (*SecLinkRecvT)(void *ctx,
const uint8_t *data, int len, uint8_t channel);</code></pre>
<h3>secLinkOpen</h3>
<p>Open a secure serial link. Opens the COM port and packet layer internally.</p>
<pre><code>SecLinkT *secLinkOpen(int com, int32_t bps, int dataBits,
char parity, int stopBits, int handshake,
SecLinkRecvT callback, void *ctx);</code></pre>
<pre> Parameter Description
--------- -----------
com COM port index (RS232_COM1..RS232_COM4).
bps Baud rate.
dataBits Data bits per character (5-8).
parity Parity mode ('N', 'O', 'E', 'M', 'S').
stopBits Stop bits (1 or 2).
handshake Flow control mode (RS232_HANDSHAKE_*).
callback Called when a packet is received (plaintext, with channel).
ctx User pointer passed to the callback.</pre>
<p>Returns an opaque SecLinkT handle, or NULL on failure.</p>
<h3>secLinkClose</h3>
<p>Close the link, free all resources, and close the COM port.</p>
<pre><code>void secLinkClose(SecLinkT *link);</code></pre>
<h3>secLinkHandshake</h3>
<p>Perform Diffie-Hellman key exchange. Blocks until both sides complete. The RNG must be seeded before calling this.</p>
<pre><code>int secLinkHandshake(SecLinkT *link);</code></pre>
<p>Returns SECLINK_SUCCESS or SECLINK_ERR_HANDSHAKE.</p>
<h3>secLinkSend</h3>
<p>Send data on a channel, optionally encrypted.</p>
<pre><code>int secLinkSend(SecLinkT *link, const uint8_t *data,
int len, uint8_t channel, bool encrypt, bool block);</code></pre>
<pre> Parameter Description
--------- -----------
link Connection handle from secLinkOpen.
data Plaintext payload (1..SECLINK_MAX_PAYLOAD bytes).
len Payload length.
channel Logical channel number (0..SECLINK_MAX_CHANNEL).
encrypt If true, encrypt before sending (requires completed handshake).
block If true, block until the transmit window has space.</pre>
<p>Returns SECLINK_SUCCESS or a negative error code.</p>
<h3>secLinkSendBuf</h3>
<p>Send an arbitrarily large buffer by splitting into SECLINK_MAX_PAYLOAD chunks. Always blocks until all data is sent.</p>
<pre><code>int secLinkSendBuf(SecLinkT *link, const uint8_t *data,
int len, uint8_t channel, bool encrypt);</code></pre>
<p>Returns SECLINK_SUCCESS or the first error encountered.</p>
<h3>secLinkPoll</h3>
<p>Poll for incoming data. Decrypts encrypted packets and delivers plaintext to the receive callback.</p>
<pre><code>int secLinkPoll(SecLinkT *link);</code></pre>
<p>Returns the number of packets delivered, or a negative error code.</p>
<h3>secLinkIsReady</h3>
<p>Check whether the handshake is complete and the link is ready for encrypted data.</p>
<pre><code>bool secLinkIsReady(SecLinkT *link);</code></pre>
<h3>secLinkGetPending</h3>
<p>Get the number of unacknowledged packets in the transmit window.</p>
<pre><code>int secLinkGetPending(SecLinkT *link);</code></pre>
</div>
<div class="topic" id="lib.basrt">
<h1>BASIC Runtime Library</h1>
<h2>BASIC Runtime Library</h2>
<p>Stack-based p-code virtual machine and value system for DVX BASIC. Embeddable: the host provides I/O and UI callbacks. No DVX GUI dependencies in the core runtime.</p>
<p>Headers: apps/dvxbasic/runtime/vm.h, apps/dvxbasic/runtime/values.h</p>
<p><a href="#lib.basrt.values">Value System (values.h)</a></p>
<p><a href="#lib.basrt.vm">Virtual Machine (vm.h)</a></p>
</div>
<div class="topic" id="lib.basrt.values">
<h1>Value System</h1>
<h2>Value System</h2>
<p>Tagged union value type for the VM evaluation stack, variables, and array elements. Strings, arrays, and UDT instances are reference-counted for automatic memory management without a garbage collector.</p>
<p>Header: apps/dvxbasic/runtime/values.h</p>
<h3>Type Tags</h3>
<pre> Constant Value C Union Field Description
-------- ----- ------------- -----------
BAS_TYPE_INTEGER 0 intVal 16-bit signed integer.
BAS_TYPE_LONG 1 longVal 32-bit signed integer.
BAS_TYPE_SINGLE 2 sngVal 32-bit float.
BAS_TYPE_DOUBLE 3 dblVal 64-bit float.
BAS_TYPE_STRING 4 strVal Reference-counted dynamic string.
BAS_TYPE_BOOLEAN 5 boolVal True (-1) or False (0).
BAS_TYPE_ARRAY 6 arrVal Reference-counted array.
BAS_TYPE_UDT 7 udtVal Reference-counted user-defined type.
BAS_TYPE_OBJECT 8 objVal Opaque host pointer (form, control).
BAS_TYPE_REF 9 refVal ByRef pointer to a BasValueT slot.</pre>
<h3>BasValueT</h3>
<p>Tagged union holding any BASIC value.</p>
<pre><code>struct BasValueTag {
uint8_t type; // BAS_TYPE_*
union {
int16_t intVal;
int32_t longVal;
float sngVal;
double dblVal;
BasStringT *strVal;
int16_t boolVal;
BasArrayT *arrVal;
BasUdtT *udtVal;
void *objVal;
BasValueT *refVal;
};
};</code></pre>
<h3>Value Constructors</h3>
<pre><code>BasValueT basValInteger(int16_t v);
BasValueT basValLong(int32_t v);
BasValueT basValSingle(float v);
BasValueT basValDouble(double v);
BasValueT basValString(BasStringT *s);
BasValueT basValStringFromC(const char *text);
BasValueT basValBool(bool v);
BasValueT basValObject(void *obj);</code></pre>
<p>Each returns a BasValueT with the appropriate type tag set. basValString increments the string's reference count.</p>
<h3>Value Lifetime</h3>
<pre><code>BasValueT basValCopy(BasValueT v);
void basValRelease(BasValueT *v);</code></pre>
<pre> Function Description
-------- -----------
basValCopy Copy a value. Increments reference count for strings, arrays, and UDTs.
basValRelease Release a value. Decrements reference count and frees if it reaches zero.</pre>
<h3>Type Conversion</h3>
<pre><code>BasValueT basValToInteger(BasValueT v);
BasValueT basValToLong(BasValueT v);
BasValueT basValToSingle(BasValueT v);
BasValueT basValToDouble(BasValueT v);
BasValueT basValToString(BasValueT v);
BasValueT basValToBool(BasValueT v);</code></pre>
<p>Each returns a new value of the target type. The original is not released; the caller manages both lifetimes.</p>
<h3>Value Utilities</h3>
<pre> Function Description
-------- -----------
basValToNumber(v) Convert any numeric value to double.
basValFormatString(v) Return a new ref-counted string representation of v.
basValIsTruthy(v) True if non-zero number or non-empty string.
basValCompare(a, b) Compare two values. Returns -1, 0, or 1.
basValCompareCI(a, b) Case-insensitive comparison (OPTION COMPARE TEXT).
basValPromoteType(a, b) Determine common type for binary ops (e.g. Integer + Single -&gt; Single).</pre>
<h3>BasStringT</h3>
<p>Reference-counted string with flexible array member for inline storage.</p>
<pre><code>typedef struct {
int32_t refCount;
int32_t len;
int32_t cap;
char data[];
} BasStringT;</code></pre>
<h4>String Functions</h4>
<pre> Function Description
-------- -----------
basStringNew(text, len) Allocate from a C string. refCount starts at 1.
basStringAlloc(cap) Allocate an empty string with given capacity.
basStringRef(s) Increment reference count. Returns s.
basStringUnref(s) Decrement reference count. Frees when it reaches zero.
basStringConcat(a, b) Concatenate two strings. Returns a new string (refCount 1).
basStringSub(s, start, len) Extract a substring. Returns a new string (refCount 1).
basStringCompare(a, b) Compare. Returns &lt;0, 0, &gt;0 (like strcmp).
basStringCompareCI(a, b) Case-insensitive compare.
basStringSystemInit() Initialize the string system and empty string singleton.
basStringSystemShutdown() Shut down the string system.</pre>
<p>The global basEmptyString is a singleton that is never freed.</p>
<h3>BasArrayT</h3>
<p>Reference-counted multi-dimensional array (up to BAS_ARRAY_MAX_DIMS = 8 dimensions).</p>
<pre><code>typedef struct {
int32_t refCount;
uint8_t elementType;
int32_t dims;
int32_t lbound[BAS_ARRAY_MAX_DIMS];
int32_t ubound[BAS_ARRAY_MAX_DIMS];
int32_t totalElements;
BasValueT *elements;
} BasArrayT;</code></pre>
<h4>Array Functions</h4>
<pre> Function Description
-------- -----------
basArrayNew(dims, lbounds, ubounds, type) Allocate an array. refCount starts at 1.
basArrayFree(arr) Free all elements and release the array.
basArrayRef(arr) Increment reference count.
basArrayUnref(arr) Decrement reference count. Frees at zero.
basArrayIndex(arr, indices, ndims) Compute flat index from multi-dimensional indices. Returns -1 if out of bounds.</pre>
<h3>BasUdtT</h3>
<p>Reference-counted user-defined type instance.</p>
<pre><code>typedef struct {
int32_t refCount;
int32_t typeId;
int32_t fieldCount;
BasValueT *fields;
} BasUdtT;</code></pre>
<h4>UDT Functions</h4>
<pre> Function Description
-------- -----------
basUdtNew(typeId, fieldCount) Allocate a UDT instance. refCount starts at 1.
basUdtFree(udt) Free all fields and release.
basUdtRef(udt) Increment reference count.
basUdtUnref(udt) Decrement reference count. Frees at zero.</pre>
</div>
<div class="topic" id="lib.basrt.vm">
<h1>Virtual Machine</h1>
<h2>Virtual Machine</h2>
<p>Stack-based p-code interpreter. Executes compiled BASIC bytecode modules. The host provides I/O, UI, SQL, and external library callbacks. The VM has no DVX dependencies; it can be embedded in any C program.</p>
<p>Header: apps/dvxbasic/runtime/vm.h</p>
<h3>VM Limits</h3>
<pre> Constant Value Description
-------- ----- -----------
BAS_VM_STACK_SIZE 256 Evaluation stack depth.
BAS_VM_CALL_STACK_SIZE 64 Maximum call nesting depth.
BAS_VM_MAX_GLOBALS 512 Global variable slots.
BAS_VM_MAX_LOCALS 64 Local variables per stack frame.
BAS_VM_MAX_FOR_DEPTH 32 Maximum nested FOR loop depth.
BAS_VM_MAX_FILES 16 Open file channels (1-based).</pre>
<h3>BasVmResultE</h3>
<p>Result codes returned by basVmRun and basVmStep.</p>
<pre> Code Value Description
---- ----- -----------
BAS_VM_OK 0 Program completed normally.
BAS_VM_HALTED 1 HALT instruction reached.
BAS_VM_YIELDED 2 DoEvents yielded control.
BAS_VM_ERROR 3 Runtime error.
BAS_VM_STACK_OVERFLOW 4 Evaluation stack overflow.
BAS_VM_STACK_UNDERFLOW 5 Evaluation stack underflow.
BAS_VM_CALL_OVERFLOW 6 Call stack overflow.
BAS_VM_DIV_BY_ZERO 7 Division by zero.
BAS_VM_TYPE_MISMATCH 8 Type mismatch in operation.
BAS_VM_OUT_OF_MEMORY 9 Memory allocation failed.
BAS_VM_BAD_OPCODE 10 Unknown opcode encountered.
BAS_VM_FILE_ERROR 11 File I/O error.
BAS_VM_SUBSCRIPT_RANGE 12 Array subscript out of range.
BAS_VM_USER_ERROR 13 ON ERROR raised by program.
BAS_VM_STEP_LIMIT 14 Step limit reached (not an error).
BAS_VM_BREAKPOINT 15 Breakpoint or step completed (not an error).</pre>
<h3>Lifecycle</h3>
<pre><code>BasVmT *basVmCreate(void);
void basVmDestroy(BasVmT *vm);
void basVmLoadModule(BasVmT *vm, BasModuleT *module);
void basVmReset(BasVmT *vm);</code></pre>
<pre> Function Description
-------- -----------
basVmCreate Allocate and initialize a new VM instance.
basVmDestroy Destroy the VM and free all resources.
basVmLoadModule Load a compiled module (BasModuleT) into the VM.
basVmReset Reset to initial state (clear stack, globals, PC).</pre>
<h3>Execution</h3>
<pre><code>BasVmResultE basVmRun(BasVmT *vm);
BasVmResultE basVmStep(BasVmT *vm);
void basVmSetStepLimit(BasVmT *vm, int32_t limit);</code></pre>
<pre> Function Description
-------- -----------
basVmRun Execute the loaded module until it ends, halts, yields, errors, or hits a breakpoint/step limit.
basVmStep Execute a single instruction and return. Useful for debugger stepping.
basVmSetStepLimit Set maximum instructions per basVmRun call. 0 = unlimited (default). Returns BAS_VM_STEP_LIMIT when reached.</pre>
<h3>I/O Callbacks</h3>
<p>The host provides these callbacks for PRINT, INPUT, and DoEvents statements.</p>
<pre><code>void basVmSetPrintCallback(BasVmT *vm, BasPrintFnT fn, void *ctx);
void basVmSetInputCallback(BasVmT *vm, BasInputFnT fn, void *ctx);
void basVmSetDoEventsCallback(BasVmT *vm, BasDoEventsFnT fn, void *ctx);</code></pre>
<h4>Callback Types</h4>
<pre><code>typedef void (*BasPrintFnT)(void *ctx, const char *text, bool newline);
typedef bool (*BasInputFnT)(void *ctx, const char *prompt,
char *buf, int32_t bufSize);
typedef bool (*BasDoEventsFnT)(void *ctx);</code></pre>
<pre> Type Description
---- -----------
BasPrintFnT Called for PRINT output. text is null-terminated. newline indicates line advance.
BasInputFnT Called for INPUT. Fill buf (up to bufSize-1 chars). Return true on success, false on cancel.
BasDoEventsFnT Called for DoEvents. Process pending events and return. Return false to stop the program.</pre>
<h3>UI Callbacks</h3>
<p>For form and control integration. The VM resolves all UI operations through these callbacks, keeping it independent of any specific GUI toolkit.</p>
<pre><code>void basVmSetUiCallbacks(BasVmT *vm, const BasUiCallbacksT *ui);</code></pre>
<h4>BasUiCallbacksT</h4>
<pre> Field Signature Description
----- --------- -----------
getProp BasValueT (*)(ctx, ctrlRef, propName) Get a control property value.
setProp void (*)(ctx, ctrlRef, propName, value) Set a control property.
callMethod BasValueT (*)(ctx, ctrlRef, methodName, args, argc) Call a method on a control.
createCtrl void *(*)(ctx, formRef, typeName, ctrlName) Create a control on a form.
findCtrl void *(*)(ctx, formRef, ctrlName) Find a control by name.
findCtrlIdx void *(*)(ctx, formRef, ctrlName, index) Find a control array element.
loadForm void *(*)(ctx, formName) Load a form by name.
unloadForm void (*)(ctx, formRef) Unload a form.
showForm void (*)(ctx, formRef, modal) Show a form (modal or modeless).
hideForm void (*)(ctx, formRef) Hide a form (keep in memory).
msgBox int32_t (*)(ctx, message, flags) Display a message box.
inputBox BasStringT *(*)(ctx, prompt, title, defaultText) Display an input box.
ctx void * User pointer passed to all callbacks.</pre>
<h3>SQL Callbacks</h3>
<p>For database integration.</p>
<pre><code>void basVmSetSqlCallbacks(BasVmT *vm, const BasSqlCallbacksT *sql);</code></pre>
<h4>BasSqlCallbacksT</h4>
<pre> Field Signature Description
----- --------- -----------
sqlOpen int32_t (*)(path) Open a database. Returns handle.
sqlClose void (*)(db) Close a database.
sqlExec bool (*)(db, sql) Execute a non-query SQL statement.
sqlError const char *(*)(db) Get last error message.
sqlQuery int32_t (*)(db, sql) Execute a query. Returns result set handle.
sqlNext bool (*)(rs) Advance to next row.
sqlEof bool (*)(rs) Check if at end of result set.
sqlFieldCount int32_t (*)(rs) Get number of columns.
sqlFieldName const char *(*)(rs, col) Get column name by index.
sqlFieldText const char *(*)(rs, col) Get column value as text by index.
sqlFieldByName const char *(*)(rs, name) Get column value as text by name.
sqlFieldInt int32_t (*)(rs, col) Get column value as integer.
sqlFieldDbl double (*)(rs, col) Get column value as double.
sqlFreeResult void (*)(rs) Free a result set.
sqlAffectedRows int32_t (*)(db) Get number of rows affected by last statement.</pre>
<h3>External Library Callbacks</h3>
<p>For DECLARE LIBRARY support. The VM resolves external functions at runtime via the host.</p>
<pre><code>void basVmSetExternCallbacks(BasVmT *vm,
const BasExternCallbacksT *ext);</code></pre>
<h4>BasExternCallbacksT</h4>
<pre> Field Signature Description
----- --------- -----------
resolveExtern void *(*)(ctx, libName, funcName) Resolve a native function by library and symbol name. Cached after first call.
callExtern BasValueT (*)(ctx, funcPtr, funcName, args, argc, retType) Call a resolved native function, marshalling arguments and return value.
ctx void * User pointer passed to both callbacks.</pre>
<h3>Form Context</h3>
<p>Set the active form context during event dispatch.</p>
<pre><code>void basVmSetCurrentForm(BasVmT *vm, void *formRef);
void basVmSetCurrentFormVars(BasVmT *vm,
BasValueT *vars, int32_t count);</code></pre>
<h3>Stack Access</h3>
<p>Push and pop values on the evaluation stack for host integration.</p>
<pre><code>bool basVmPush(BasVmT *vm, BasValueT val);
bool basVmPop(BasVmT *vm, BasValueT *val);</code></pre>
<p>Both return true on success, false on stack overflow/underflow.</p>
<h3>Error Reporting</h3>
<pre><code>const char *basVmGetError(const BasVmT *vm);</code></pre>
<p>Returns the current error message string. Valid after basVmRun returns BAS_VM_ERROR.</p>
<h3>Sub/Function Calls from Host</h3>
<p>Call a SUB or FUNCTION by its code address from host code.</p>
<pre><code>bool basVmCallSub(BasVmT *vm, int32_t codeAddr);
bool basVmCallSubWithArgs(BasVmT *vm, int32_t codeAddr,
const BasValueT *args, int32_t argCount);
bool basVmCallSubWithArgsOut(BasVmT *vm, int32_t codeAddr,
const BasValueT *args, int32_t argCount,
BasValueT *outArgs, int32_t outCount);</code></pre>
<pre> Function Description
-------- -----------
basVmCallSub Call a SUB with no arguments.
basVmCallSubWithArgs Call a SUB with arguments pushed onto the stack frame.
basVmCallSubWithArgsOut Call a SUB and read back modified argument values after it returns.</pre>
<p>All three push a call frame, execute until the SUB returns, then restore the previous execution state. Return true on normal completion, false on error or if the VM is not idle.</p>
<h3>Debugger API</h3>
<pre><code>void basVmSetBreakpoints(BasVmT *vm,
int32_t *lines, int32_t count);
void basVmStepInto(BasVmT *vm);
void basVmStepOver(BasVmT *vm);
void basVmStepOut(BasVmT *vm);
void basVmRunToCursor(BasVmT *vm, int32_t line);
int32_t basVmGetCurrentLine(const BasVmT *vm);</code></pre>
<pre> Function Description
-------- -----------
basVmSetBreakpoints Set the breakpoint list (sorted array of source line numbers, host-owned memory).
basVmStepInto Break at the next OP_LINE instruction.
basVmStepOver Break when call depth returns to the current level.
basVmStepOut Break when call depth drops below the current level.
basVmRunToCursor Break when execution reaches the specified source line.
basVmGetCurrentLine Get the current source line number (from the last OP_LINE instruction).</pre>
<p>The breakpoint callback notifies the host when a breakpoint fires during nested sub calls:</p>
<pre><code>typedef void (*BasBreakpointFnT)(void *ctx, int32_t line);</code></pre>
<h3>BasModuleT</h3>
<p>Compiled module produced by the BASIC compiler and loaded into the VM.</p>
<pre><code>typedef struct {
uint8_t *code;
int32_t codeLen;
BasStringT **constants;
int32_t constCount;
int32_t globalCount;
int32_t entryPoint;
BasValueT *dataPool;
int32_t dataCount;
BasProcEntryT *procs;
int32_t procCount;
BasFormVarInfoT *formVarInfo;
int32_t formVarInfoCount;
BasDebugVarT *debugVars;
int32_t debugVarCount;
BasDebugUdtDefT *debugUdtDefs;
int32_t debugUdtDefCount;
} BasModuleT;</code></pre>
<pre> Field Description
----- -----------
code P-code bytecode array.
codeLen Length of bytecode in bytes.
constants String constant pool.
constCount Number of string constants.
globalCount Number of global variable slots needed.
entryPoint PC of the first instruction (module-level code).
dataPool DATA statement value pool (for READ).
dataCount Number of values in the data pool.
procs Procedure table (SUBs and FUNCTIONs).
procCount Number of procedures.
formVarInfo Per-form variable counts and init code addresses.
formVarInfoCount Number of forms with form-scoped variables.
debugVars Variable names and metadata for the debugger.
debugVarCount Number of debug variable entries.
debugUdtDefs UDT type definitions for the debugger.
debugUdtDefCount Number of debug UDT definitions.</pre>
</div>
<div class="topic" id="widget.base">
<h1>Base WidgetT (Common Properties, Events, and Operations)</h1>
<h2>DVX Widget System</h2>
<p>Complete reference for the DVX GUI widget toolkit. All widgets are implemented as dynamically loaded DXE modules. They are created via convenience macros that wrap the per-widget API function tables. The base WidgetT structure is defined in core/dvxWidget.h; individual widget headers live in widgets/.</p>
<p>Individual widgets are documented in their own sections. See the table of contents for the full list.</p>
<h3>Base WidgetT (Common Properties, Events, and Operations)</h3>
<p>Every widget inherits from the WidgetT structure defined in core/dvxWidget.h. The fields and callbacks listed here are available on all widget types.</p>
<h4>Common Properties</h4>
<pre> Field Type Description
----- ---- -----------
name char[32] Widget name for lookup via wgtFind().
x, y, w, h int32_t Computed geometry relative to the window content area (set by layout).
minW, minH int32_t (tagged) Minimum size hints. Use wgtPixels(), wgtChars(), or wgtPercent(). 0 = auto.
maxW, maxH int32_t (tagged) Maximum size constraints. 0 = no limit.
prefW, prefH int32_t (tagged) Preferred size. 0 = auto.
weight int32_t Extra-space distribution weight. 0 = fixed, 100 = normal. A widget with weight=200 gets twice the extra space of one with weight=100.
align WidgetAlignE Main-axis alignment for children: AlignStartE, AlignCenterE, AlignEndE.
spacing int32_t (tagged) Spacing between children (containers only). 0 = default.
padding int32_t (tagged) Internal padding (containers only). 0 = default.
fgColor uint32_t Foreground color override. 0 = use color scheme default.
bgColor uint32_t Background color override. 0 = use color scheme default.
visible bool Visibility state.
enabled bool Enabled state. Disabled widgets are grayed out and ignore input.
readOnly bool Read-only mode: allows scrolling/selection but blocks editing.
swallowTab bool When true, Tab key goes to the widget instead of navigating focus.
accelKey char Lowercase accelerator character. 0 if none.
tooltip const char * Tooltip text. NULL = none. Caller owns the string.
contextMenu MenuT * Right-click context menu. NULL = none. Caller owns.
userData void * Application-defined user data pointer.</pre>
<h4>Size Specification Macros</h4>
<pre> Macro Description
----- -----------
wgtPixels(v) Size in pixels.
wgtChars(v) Size in character widths (multiplied by font charWidth).
wgtPercent(v) Size as a percentage of parent dimension.</pre>
<h4>Common Events (Callbacks)</h4>
<p>These callback function pointers are available on every WidgetT. Set them directly on the widget struct.</p>
<pre> Callback Signature Description
-------- --------- -----------
onClick void (*)(WidgetT *w) Fires on mouse click / activation.
onDblClick void (*)(WidgetT *w) Fires on double-click.
onChange void (*)(WidgetT *w) Fires when the widget's value changes (text, selection, check state, etc.).
onFocus void (*)(WidgetT *w) Fires when the widget receives keyboard focus.
onBlur void (*)(WidgetT *w) Fires when the widget loses keyboard focus.
onKeyPress void (*)(WidgetT *w, int32_t keyAscii) Fires on a printable key press (ASCII value).
onKeyDown void (*)(WidgetT *w, int32_t keyCode, int32_t shift) Fires on key down (scan code + shift state).
onKeyUp void (*)(WidgetT *w, int32_t keyCode, int32_t shift) Fires on key up.
onMouseDown void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) Fires on mouse button press.
onMouseUp void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) Fires on mouse button release.
onMouseMove void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) Fires on mouse movement over the widget.
onScroll void (*)(WidgetT *w, int32_t delta) Fires on mouse wheel scroll.
onValidate bool (*)(WidgetT *w) Validation callback. Return false to cancel a pending write.</pre>
<h4>Common Operations</h4>
<pre> Function Description
-------- -----------
WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win) Initialize widgets for a window. Returns the root VBox container.
AppContextT *wgtGetContext(const WidgetT *w) Walk up from any widget to retrieve the AppContextT.
void wgtInvalidate(WidgetT *w) Mark widget for re-layout and repaint. Propagates to ancestors.
void wgtInvalidatePaint(WidgetT *w) Mark widget for repaint only (no layout recalculation).
void wgtSetText(WidgetT *w, const char *text) Set widget text (label, button, textinput, etc.).
const char *wgtGetText(const WidgetT *w) Get widget text.
void wgtSetEnabled(WidgetT *w, bool enabled) Enable or disable a widget.
void wgtSetReadOnly(WidgetT *w, bool readOnly) Set read-only mode.
void wgtSetFocused(WidgetT *w) Set keyboard focus to a widget.
WidgetT *wgtGetFocused(void) Get the currently focused widget.
void wgtSetVisible(WidgetT *w, bool visible) Show or hide a widget.
void wgtSetName(WidgetT *w, const char *name) Set widget name for lookup.
WidgetT *wgtFind(WidgetT *root, const char *name) Find a widget by name in the subtree.
void wgtDestroy(WidgetT *w) Destroy a widget and all its children.
void wgtSetTooltip(WidgetT *w, const char *text) Set tooltip text. Pass NULL to remove.</pre>
</div>
<div class="topic" id="widget.ansiterm">
<h1>AnsiTerm</h1>
<h3>AnsiTerm</h3>
<p>A VT100/ANSI-compatible terminal emulator widget designed for connecting to BBS systems over the serial link. Uses a traditional text-mode cell buffer (character + attribute byte pairs) with the CP437 character set and 16-color CGA palette. Supports cursor movement, screen/line erase, scrolling regions, SGR colors, and scrollback history. Communication is abstracted through read/write function pointers, allowing the terminal to work with raw serial ports, the secLink encrypted channel, or any other byte-oriented transport.</p>
<p>Header: widgets/widgetAnsiTerm.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *term = wgtAnsiTerm(parent, 80, 25);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtAnsiTerm(parent, cols, rows) Create an ANSI terminal widget with the given column and row dimensions.
wgtAnsiTermWrite(w, data, len) Write raw bytes into the terminal's ANSI parser. data is a const uint8_t * buffer, len is the byte count.
wgtAnsiTermClear(w) Clear the terminal screen and reset the cursor to the home position.
wgtAnsiTermSetComm(w, ctx, readFn, writeFn) Attach a communication channel. readFn and writeFn are I/O callbacks; ctx is passed as their first argument.
wgtAnsiTermSetScrollback(w, maxLines) Set the maximum number of scrollback lines. Lines scrolled off the top are saved in a circular buffer.
wgtAnsiTermPoll(w) Poll the communication channel for incoming data and feed it into the ANSI parser.
wgtAnsiTermRepaint(w, outY, outH) Fast repaint path that renders dirty rows directly into the window's content buffer, bypassing the widget pipeline. Returns the dirty region via outY/outH.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
Cols Integer Read-only Number of columns.
Rows Integer Read-only Number of rows.
Scrollback Integer Write-only Maximum scrollback lines.</pre>
<h4>Methods (BASIC Interface)</h4>
<pre> Method Description
------ -----------
Clear Clear the terminal screen.
Write Write a string into the terminal.</pre>
<h4>Events</h4>
<p>AnsiTerm uses the common events only. No widget-specific events are defined.</p>
</div>
<div class="topic" id="widget.box">
<h1>Box (VBox / HBox / Frame)</h1>
<h3>Box (VBox / HBox / Frame)</h3>
<p>Container widgets that arrange their children in a vertical column (VBox), horizontal row (HBox), or a titled group box (Frame). These are the primary layout building blocks. Children are laid out using a flexbox-like algorithm with weight-based extra-space distribution.</p>
<p>Header: widgets/widgetBox.h</p>
<h4>Creation</h4>
<pre> Macro Description
----- -----------
wgtVBox(parent) Create a vertical box container. Children are stacked top to bottom.
wgtHBox(parent) Create a horizontal box container. Children are placed left to right.
wgtFrame(parent, title) Create a titled group box (a VBox with a border and label).</pre>
<h4>Properties</h4>
<p>Box containers use the common WidgetT fields for layout control:</p>
<pre> Property Description
-------- -----------
align Main-axis alignment of children. HBox: Start=left, Center=center, End=right. VBox: Start=top, Center=center, End=bottom.
spacing Gap between children (tagged size).
padding Internal padding around children (tagged size).
weight Controls how the box itself stretches within its parent.</pre>
<h4>Events</h4>
<p>Containers use the common events only. No widget-specific events.</p>
</div>
<div class="topic" id="widget.button">
<h1>Button</h1>
<h3>Button</h3>
<p>A push button with a text label. Fires onClick when pressed and released. Supports keyboard activation via accelerator keys.</p>
<p>Header: widgets/widgetButton.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *btn = wgtButton(parent, &quot;OK&quot;);</code></pre>
<h4>Macro</h4>
<pre> Macro Description
----- -----------
wgtButton(parent, text) Create a push button with the given label text.</pre>
<h4>Properties</h4>
<p>Uses common WidgetT properties. Set accelKey for keyboard shortcut. Use wgtSetText() / wgtGetText() to change the label.</p>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onClick Fires when the button is clicked (press + release).</pre>
</div>
<div class="topic" id="widget.canvas">
<h1>Canvas</h1>
<h3>Canvas</h3>
<p>A freeform drawing surface with a fixed-size pixel buffer. Provides drawing primitives (lines, rectangles, circles, text, individual pixels) and supports save/load to BMP files. Mouse interaction is available via a callback.</p>
<p>Header: widgets/widgetCanvas.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *cv = wgtCanvas(parent, 320, 200);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtCanvas(parent, w, h) Create a canvas with the given pixel dimensions.
wgtCanvasClear(w, color) Fill the entire canvas with a solid color.
wgtCanvasSetPenColor(w, color) Set the drawing pen color.
wgtCanvasSetPenSize(w, size) Set the drawing pen size in pixels.
wgtCanvasDrawLine(w, x0, y0, x1, y1) Draw a line from (x0,y0) to (x1,y1).
wgtCanvasDrawRect(w, x, y, width, height) Draw a rectangle outline.
wgtCanvasFillRect(w, x, y, width, height) Draw a filled rectangle.
wgtCanvasFillCircle(w, cx, cy, radius) Draw a filled circle.
wgtCanvasSetPixel(w, x, y, color) Set a single pixel to the given color.
wgtCanvasGetPixel(w, x, y) Get the color of a single pixel.
wgtCanvasDrawText(w, x, y, text) Draw text at the given position using the current pen color.
wgtCanvasSetMouseCallback(w, cb) Set a mouse interaction callback. Signature: void (*cb)(WidgetT *w, int32_t cx, int32_t cy, bool drag). Receives canvas-relative coordinates and whether the mouse is being dragged.
wgtCanvasSave(w, path) Save the canvas contents to a BMP file.
wgtCanvasLoad(w, path) Load a BMP file into the canvas.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onClick Fires when the canvas is clicked.
Mouse callback (via wgtCanvasSetMouseCallback) Fires on mouse down and drag with canvas-local coordinates.</pre>
<h4>Methods (BASIC Interface)</h4>
<pre> Method Description
------ -----------
Clear Clear the canvas to a given color.</pre>
</div>
<div class="topic" id="widget.checkbox">
<h1>Checkbox</h1>
<h3>Checkbox</h3>
<p>A toggle control with a text label. Clicking toggles between checked and unchecked states.</p>
<p>Header: widgets/widgetCheckbox.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *cb = wgtCheckbox(parent, &quot;Enable logging&quot;);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtCheckbox(parent, text) Create a checkbox with the given label text.
wgtCheckboxIsChecked(w) Returns true if the checkbox is checked.
wgtCheckboxSetChecked(w, checked) Set the checked state programmatically.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onClick Fires when clicked (after toggle).
onChange Fires when the checked state changes.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
Value Boolean Read/Write Whether the checkbox is checked.</pre>
</div>
<div class="topic" id="widget.combobox">
<h1>ComboBox</h1>
<h3>ComboBox</h3>
<p>A combination of a text input and a dropdown list. The user can either type a value or select from a list of predefined options. Unlike Dropdown, the text field is editable.</p>
<p>Header: widgets/widgetComboBox.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *cb = wgtComboBox(parent, 128);
const char *items[] = { &quot;Arial&quot;, &quot;Courier&quot;, &quot;Times&quot; };
wgtComboBoxSetItems(cb, items, 3);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtComboBox(parent, maxLen) Create a combo box. maxLen is the maximum text input length.
wgtComboBoxSetItems(w, items, count) Set the dropdown items.
wgtComboBoxGetSelected(w) Get the index of the selected item (-1 if the text does not match any item).
wgtComboBoxSetSelected(w, idx) Set the selected item by index.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onChange Fires when the text or selection changes.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
ListIndex Integer Read/Write Index of the currently selected item.</pre>
</div>
<div class="topic" id="widget.datactrl">
<h1>DataCtrl</h1>
<h3>DataCtrl</h3>
<p>A VB3-style Data control for database binding. Displays a visible navigation bar that connects to a SQLite database via dvxSql* functions. Reads all rows from the RecordSource query into an in-memory cache for bidirectional navigation. Fires Reposition events when the cursor moves so bound controls can update. Supports master-detail linking between Data controls.</p>
<p>Header: widgets/widgetDataCtrl.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *data = wgtDataCtrl(parent);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtDataCtrl(parent) Create a Data control.
wgtDataCtrlRefresh(w) Re-execute the RecordSource query and rebuild the row cache.
wgtDataCtrlMoveFirst(w) Move the cursor to the first row.
wgtDataCtrlMovePrev(w) Move the cursor to the previous row.
wgtDataCtrlMoveNext(w) Move the cursor to the next row.
wgtDataCtrlMoveLast(w) Move the cursor to the last row.
wgtDataCtrlGetField(w, colName) Get the value of a column in the current row. Returns const char *.
wgtDataCtrlSetField(w, colName, value) Set the value of a column in the current row (marks the row dirty).
wgtDataCtrlUpdateRow(w) Write the current row's pending changes back to the database.
wgtDataCtrlUpdate(w) Flush all pending changes to the database.
wgtDataCtrlAddNew(w) Begin a new row. Sets dirty state; call Update to commit.
wgtDataCtrlDelete(w) Delete the current row from the database.
wgtDataCtrlSetMasterValue(w, val) Set the master-detail filter value for this control.
wgtDataCtrlGetRowCount(w) Get the total number of cached rows.
wgtDataCtrlGetColCount(w) Get the number of columns in the result set.
wgtDataCtrlGetColName(w, col) Get the name of a column by index. Returns const char *.
wgtDataCtrlGetCellText(w, row, col) Get the text of a specific cell by row and column index. Returns const char *.
wgtDataCtrlSetCurrentRow(w, row) Set the current row by index (0-based).</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
DatabaseName String Read/Write Path to the SQLite database file.
RecordSource String Read/Write SQL query or table name for the result set.
KeyColumn String Read/Write Primary key column name (used for UPDATE/DELETE).
MasterSource String Read/Write Name of the master Data control for master-detail linking.
MasterField String Read/Write Column in the master control to read for the filter value.
DetailField String Read/Write Column in this table to filter by the master value.
Caption String Read/Write Text displayed on the navigation bar.
BOF Boolean Read-only True when the cursor is before the first row.
EOF Boolean Read-only True when the cursor is past the last row.</pre>
<h4>Methods (BASIC Interface)</h4>
<pre> Method Description
------ -----------
AddNew Begin a new row.
Delete Delete the current row.
MoveFirst Move to the first row.
MoveLast Move to the last row.
MoveNext Move to the next row.
MovePrevious Move to the previous row.
Refresh Re-execute the query and rebuild the cache.
Update Write pending changes to the database.</pre>
<h4>Events</h4>
<pre> Event Description
----- -----------
Reposition Fires when the current row changes (navigation, refresh, etc.). Default event.
Validate Fires before writing changes. Return false to cancel.</pre>
</div>
<div class="topic" id="widget.dbgrid">
<h1>DbGrid</h1>
<h3>DbGrid</h3>
<p>A database grid widget that displays all records from a Data control in a scrollable, sortable table. Columns auto-populate from the Data control's column names and can be hidden, resized, and renamed by the application. Clicking a column header sorts the display. Selecting a row syncs the Data control's cursor position. The grid reads directly from the Data control's cached rows, so there is no separate copy of the data.</p>
<p>Header: widgets/widgetDbGrid.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *grid = wgtDbGrid(parent);
wgtDbGridSetDataWidget(grid, dataCtrl);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtDbGrid(parent) Create a database grid widget.
wgtDbGridSetDataWidget(w, dataWidget) Bind the grid to a Data control. The grid reads rows from this widget.
wgtDbGridRefresh(w) Re-read the Data control's state and repaint the grid.
wgtDbGridSetColumnVisible(w, fieldName, visible) Show or hide a column by field name.
wgtDbGridSetColumnHeader(w, fieldName, header) Set a display header for a column (overrides the field name).
wgtDbGridSetColumnWidth(w, fieldName, width) Set the width of a column by field name (tagged size, 0 = auto).
wgtDbGridGetSelectedRow(w) Get the index of the currently selected data row (-1 if none).</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
GridLines Boolean Read/Write Whether to draw grid lines between cells.</pre>
<h4>Methods (BASIC Interface)</h4>
<pre> Method Description
------ -----------
Refresh Re-read the Data control and repaint.</pre>
<h4>Events</h4>
<pre> Event Description
----- -----------
Click Fires when a row is clicked.
DblClick Fires when a row is double-clicked. Default event.</pre>
</div>
<div class="topic" id="widget.dropdown">
<h1>Dropdown</h1>
<h3>Dropdown</h3>
<p>A drop-down list that displays a single selected item and expands to show all options when clicked. Read-only selection (the user cannot type into it).</p>
<p>Header: widgets/widgetDropdown.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *dd = wgtDropdown(parent);
const char *items[] = { &quot;Red&quot;, &quot;Green&quot;, &quot;Blue&quot; };
wgtDropdownSetItems(dd, items, 3);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtDropdown(parent) Create a dropdown list.
wgtDropdownSetItems(w, items, count) Set the list of items. items is a const char ** array.
wgtDropdownGetSelected(w) Get the index of the selected item (-1 if none).
wgtDropdownSetSelected(w, idx) Set the selected item by index.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onChange Fires when the selected item changes.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
ListIndex Integer Read/Write Index of the currently selected item.</pre>
</div>
<div class="topic" id="widget.imagebutton">
<h1>ImageButton</h1>
<h3>ImageButton</h3>
<p>A clickable button that displays an image instead of text. Has press/release visual feedback like a regular button. Can be created from raw pixel data or a BMP file.</p>
<p>Header: widgets/widgetImageButton.h</p>
<h4>Creation</h4>
<pre> Macro Description
----- -----------
wgtImageButton(parent, data, w, h, pitch) Create an image button from raw pixel data.
wgtImageButtonFromFile(parent, path) Create an image button by loading a BMP file.</pre>
<h4>Methods</h4>
<pre> Macro Description
----- -----------
wgtImageButtonSetData(w, data, imgW, imgH, pitch) Replace the image with new raw pixel data.
wgtImageButtonLoadFile(w, path) Replace the image by loading a new file.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onClick Fires when the image button is clicked (press + release).</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
Picture String Write-only Load an image from a file path.
ImageWidth Integer Read-only Width of the currently loaded image in pixels.
ImageHeight Integer Read-only Height of the currently loaded image in pixels.</pre>
<hr>
</div>
<div class="topic" id="widget.image">
<h1>Image</h1>
<h3>Image</h3>
<p>Displays a bitmap image. Can be created from raw pixel data or loaded from a BMP file on disk. The image is rendered at its natural size within the widget bounds.</p>
<p>Header: widgets/widgetImage.h</p>
<h4>Creation</h4>
<pre> Macro Description
----- -----------
wgtImage(parent, data, w, h, pitch) Create an image widget from raw pixel data. data is a uint8_t * pixel buffer, w/h are dimensions, pitch is bytes per row.
wgtImageFromFile(parent, path) Create an image widget by loading a BMP file from disk.</pre>
<h4>Methods</h4>
<pre> Macro Description
----- -----------
wgtImageSetData(w, data, imgW, imgH, pitch) Replace the displayed image with new raw pixel data.
wgtImageLoadFile(w, path) Replace the displayed image by loading a new file.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onClick Fires when the image is clicked.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
Picture String Write-only Load an image from a file path.
ImageWidth Integer Read-only Width of the currently loaded image in pixels.
ImageHeight Integer Read-only Height of the currently loaded image in pixels.</pre>
</div>
<div class="topic" id="widget.label">
<h1>Label</h1>
<h3>Label</h3>
<p>A static text label. Does not accept keyboard focus. Typically used to describe other widgets. Supports text alignment and accelerator keys (with WCLASS_FOCUS_FORWARD, the accelerator moves focus to the next focusable sibling).</p>
<p>Header: widgets/widgetLabel.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *lbl = wgtLabel(parent, &quot;Name:&quot;);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtLabel(parent, text) Create a text label.
wgtLabelSetAlign(w, align) Set the text alignment (AlignStartE, AlignCenterE, AlignEndE).</pre>
<h4>Properties</h4>
<p>Use wgtSetText() / wgtGetText() to change the text. Set accelKey for accelerator support (focus forwards to next focusable widget).</p>
<h4>Events</h4>
<p>Labels use the common events only. Typically no callbacks are set on labels.</p>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
Alignment Enum (Left, Center, Right) Read/Write Text alignment within the label.</pre>
<hr>
</div>
<div class="topic" id="widget.listbox">
<h1>ListBox</h1>
<h3>ListBox</h3>
<p>A scrollable list of text items. Supports single and multi-selection modes and drag-to-reorder.</p>
<p>Header: widgets/widgetListBox.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *lb = wgtListBox(parent);
const char *items[] = { &quot;Alpha&quot;, &quot;Beta&quot;, &quot;Gamma&quot; };
wgtListBoxSetItems(lb, items, 3);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtListBox(parent) Create a list box.
wgtListBoxSetItems(w, items, count) Set the list items.
wgtListBoxGetSelected(w) Get the index of the selected item (-1 if none).
wgtListBoxSetSelected(w, idx) Set the selected item by index.
wgtListBoxSetMultiSelect(w, multi) Enable or disable multi-selection mode.
wgtListBoxIsItemSelected(w, idx) Check if a specific item is selected (multi-select mode).
wgtListBoxSetItemSelected(w, idx, selected) Select or deselect a specific item.
wgtListBoxSelectAll(w) Select all items (multi-select mode).
wgtListBoxClearSelection(w) Deselect all items.
wgtListBoxSetReorderable(w, reorderable) Enable drag-to-reorder.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onClick Fires when an item is clicked.
onDblClick Fires when an item is double-clicked.
onChange Fires when the selection changes.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
ListIndex Integer Read/Write Index of the currently selected item.</pre>
<h4>Methods (BASIC Interface)</h4>
<pre> Method Description
------ -----------
SelectAll Select all items.
ClearSelection Deselect all items.
SetMultiSelect Enable or disable multi-selection.
SetReorderable Enable or disable drag-to-reorder.
IsItemSelected Check if a specific item is selected by index.
SetItemSelected Select or deselect a specific item by index.</pre>
<hr>
</div>
<div class="topic" id="widget.listview">
<h1>ListView</h1>
<h3>ListView</h3>
<p>A multi-column list with sortable headers. Supports single and multi-selection, column alignment, header click sorting, and drag-to-reorder. Data is provided as a flat array of strings (row-major order, one string per cell).</p>
<p>Header: widgets/widgetListView.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *lv = wgtListView(parent);
ListViewColT cols[] = {
{ &quot;Name&quot;, wgtChars(20), ListViewAlignLeftE },
{ &quot;Size&quot;, wgtChars(10), ListViewAlignRightE }
};
wgtListViewSetColumns(lv, cols, 2);
const char *cells[] = { &quot;file.txt&quot;, &quot;1234&quot;, &quot;readme.md&quot;, &quot;5678&quot; };
wgtListViewSetData(lv, cells, 2);</code></pre>
<h4>Column Definition</h4>
<pre><code>typedef struct {
const char *title;
int32_t width; // tagged size (wgtPixels/wgtChars/wgtPercent, 0 = auto)
ListViewAlignE align; // ListViewAlignLeftE, ListViewAlignCenterE, ListViewAlignRightE
} ListViewColT;</code></pre>
<h4>Sort Direction</h4>
<pre><code>typedef enum {
ListViewSortNoneE,
ListViewSortAscE,
ListViewSortDescE
} ListViewSortE;</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtListView(parent) Create a list view.
wgtListViewSetColumns(w, cols, count) Define columns from an array of ListViewColT.
wgtListViewSetData(w, cellData, rowCount) Set row data. cellData is a flat const char ** array of size rowCount * colCount.
wgtListViewGetSelected(w) Get the index of the selected row (-1 if none).
wgtListViewSetSelected(w, idx) Set the selected row by index.
wgtListViewSetSort(w, col, dir) Set the sort column and direction.
wgtListViewSetHeaderClickCallback(w, cb) Set a callback for header clicks. Signature: void (*cb)(WidgetT *w, int32_t col, ListViewSortE dir).
wgtListViewSetMultiSelect(w, multi) Enable or disable multi-selection.
wgtListViewIsItemSelected(w, idx) Check if a specific row is selected.
wgtListViewSetItemSelected(w, idx, selected) Select or deselect a specific row.
wgtListViewSelectAll(w) Select all rows.
wgtListViewClearSelection(w) Deselect all rows.
wgtListViewSetReorderable(w, reorderable) Enable drag-to-reorder of rows.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onClick Fires when a row is clicked.
onDblClick Fires when a row is double-clicked.
onChange Fires when the selection changes.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
ListIndex Integer Read/Write Index of the currently selected row.</pre>
<h4>Methods (BASIC Interface)</h4>
<pre> Method Description
------ -----------
SelectAll Select all rows.
ClearSelection Deselect all rows.
SetMultiSelect Enable or disable multi-selection.
SetReorderable Enable or disable drag-to-reorder.
IsItemSelected Check if a specific row is selected by index.
SetItemSelected Select or deselect a specific row by index.</pre>
<hr>
</div>
<div class="topic" id="widget.progressbar">
<h1>ProgressBar</h1>
<h3>ProgressBar</h3>
<p>A visual indicator of progress, displayed as a filled bar. Supports both horizontal and vertical orientations. Value ranges from 0 to 100.</p>
<p>Header: widgets/widgetProgressBar.h</p>
<h4>Creation</h4>
<pre> Macro Description
----- -----------
wgtProgressBar(parent) Create a horizontal progress bar.
wgtProgressBarV(parent) Create a vertical progress bar.</pre>
<h4>Methods</h4>
<pre> Macro Description
----- -----------
wgtProgressBarSetValue(w, value) Set the progress value (0-100).
wgtProgressBarGetValue(w) Get the current progress value.</pre>
<h4>Events</h4>
<p>ProgressBar is a display-only widget. Typically no callbacks are set.</p>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
Value Integer Read/Write Current progress value (0-100).</pre>
<hr>
</div>
<div class="topic" id="widget.radio">
<h1>Radio Button</h1>
<h3>Radio Button</h3>
<p>A mutually exclusive selection control. Radio buttons must be placed inside a radio group container. Only one radio button within a group can be selected at a time.</p>
<p>Header: widgets/widgetRadio.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *grp = wgtRadioGroup(parent);
WidgetT *r1 = wgtRadio(grp, &quot;Option A&quot;);
WidgetT *r2 = wgtRadio(grp, &quot;Option B&quot;);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtRadioGroup(parent) Create a radio group container.
wgtRadio(parent, text) Create a radio button inside a group.
wgtRadioGroupSetSelected(w, idx) Set the selected radio button by index within the group.
wgtRadioGetIndex(w) Get the index of the currently selected radio button.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onClick Fires on the radio button when clicked.
onChange Fires when the selection changes.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
Value Integer Read-only Index of the currently selected radio button in the group.</pre>
<h4>Methods (BASIC Interface)</h4>
<pre> Method Description
------ -----------
SetSelected Set the selected radio button by index.</pre>
<hr>
</div>
<div class="topic" id="widget.scrollpane">
<h1>ScrollPane</h1>
<h3>ScrollPane</h3>
<p>A scrollable container that provides vertical and/or horizontal scrollbars when its content exceeds the visible area. Place a single child (typically a VBox or HBox) inside the scroll pane.</p>
<p>Header: widgets/widgetScrollPane.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *sp = wgtScrollPane(parent);
WidgetT *content = wgtVBox(sp);
// add children to content...</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtScrollPane(parent) Create a scroll pane container.
wgtScrollPaneScrollToChild(sp, child) Scroll so that the given child widget is visible.
wgtScrollPaneSetNoBorder(w, noBorder) When true, removes the border around the scroll pane.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onScroll Fires when the scroll position changes.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
NoBorder Boolean Read/Write Whether the border around the scroll pane is hidden.</pre>
<hr>
</div>
<div class="topic" id="widget.separator">
<h1>Separator</h1>
<h3>Separator</h3>
<p>A visual dividing line used to separate groups of widgets. Available in horizontal and vertical orientations.</p>
<p>Header: widgets/widgetSeparator.h</p>
<h4>Creation</h4>
<pre> Macro Description
----- -----------
wgtHSeparator(parent) Create a horizontal separator line.
wgtVSeparator(parent) Create a vertical separator line.</pre>
<h4>Events</h4>
<p>Separator is a visual-only widget. No events.</p>
<hr>
</div>
<div class="topic" id="widget.slider">
<h1>Slider</h1>
<h3>Slider</h3>
<p>A horizontal slider (track bar) for selecting an integer value within a range. The user drags the thumb or clicks the track to change the value.</p>
<p>Header: widgets/widgetSlider.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *sl = wgtSlider(parent, 0, 100);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtSlider(parent, minVal, maxVal) Create a slider with the given integer range.
wgtSliderSetValue(w, value) Set the slider value programmatically.
wgtSliderGetValue(w) Get the current slider value.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onChange Fires when the slider value changes.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
Value Integer Read/Write Current slider value.</pre>
<hr>
</div>
<div class="topic" id="widget.spacer">
<h1>Spacer</h1>
<h3>Spacer</h3>
<p>An invisible widget used for layout purposes. By default it has weight=100, so it absorbs available extra space. Useful for pushing other widgets apart or aligning them to edges.</p>
<p>Header: widgets/widgetSpacer.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *row = wgtHBox(parent);
wgtButton(row, &quot;OK&quot;);
wgtSpacer(row); // pushes Cancel to the right
wgtButton(row, &quot;Cancel&quot;);</code></pre>
<h4>Macro</h4>
<pre> Macro Description
----- -----------
wgtSpacer(parent) Create an invisible spacer widget.</pre>
<h4>Events</h4>
<p>Spacer is an invisible layout widget. No events.</p>
<hr>
</div>
<div class="topic" id="widget.spinner">
<h1>Spinner</h1>
<h3>Spinner</h3>
<p>A numeric input with up/down buttons for incrementing and decrementing a value within a range. Supports both integer and floating-point (real) modes.</p>
<p>Header: widgets/widgetSpinner.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *sp = wgtSpinner(parent, 0, 100, 1);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtSpinner(parent, minVal, maxVal, step) Create a spinner with the given integer range and step size.
wgtSpinnerSetValue(w, value) Set the integer value.
wgtSpinnerGetValue(w) Get the current integer value.
wgtSpinnerSetRange(w, minVal, maxVal) Set the integer range.
wgtSpinnerSetStep(w, step) Set the integer step size.
wgtSpinnerSetRealMode(w, enable) Switch to floating-point mode.
wgtSpinnerGetRealValue(w) Get the current floating-point value.
wgtSpinnerSetRealValue(w, value) Set the floating-point value.
wgtSpinnerSetRealRange(w, minVal, maxVal) Set the floating-point range.
wgtSpinnerSetRealStep(w, step) Set the floating-point step size.
wgtSpinnerSetDecimals(w, decimals) Set the number of decimal places displayed in real mode.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onChange Fires when the value changes.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
Value Integer Read/Write Current integer value.
RealMode Boolean Read/Write Whether floating-point mode is active.
Decimals Integer Read/Write Number of decimal places displayed in real mode.</pre>
<h4>Methods (BASIC Interface)</h4>
<pre> Method Description
------ -----------
SetRange Set the integer range (min, max).
SetStep Set the integer step size.</pre>
<hr>
</div>
<div class="topic" id="widget.splitter">
<h1>Splitter</h1>
<h3>Splitter</h3>
<p>A two-pane container with a draggable divider. The user drags the splitter bar to resize the two panes. Can be oriented vertically (left/right panes) or horizontally (top/bottom panes). Add exactly two children.</p>
<p>Header: widgets/widgetSplitter.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *sp = wgtSplitter(parent, true); // vertical = left|right
WidgetT *left = wgtVBox(sp);
WidgetT *right = wgtVBox(sp);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtSplitter(parent, vertical) Create a splitter. vertical=true for left/right panes, false for top/bottom.
wgtSplitterSetPos(w, pos) Set the divider position in pixels.
wgtSplitterGetPos(w) Get the current divider position in pixels.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onChange Fires when the divider position changes.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
Position Integer Read/Write Divider position in pixels.</pre>
<hr>
</div>
<div class="topic" id="widget.statusbar">
<h1>StatusBar</h1>
<h3>StatusBar</h3>
<p>A horizontal bar typically placed at the bottom of a window for displaying status text and informational widgets. Children are laid out horizontally.</p>
<p>Header: widgets/widgetStatusBar.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *sb = wgtStatusBar(parent);
wgtLabel(sb, &quot;Ready&quot;);</code></pre>
<h4>Macro</h4>
<pre> Macro Description
----- -----------
wgtStatusBar(parent) Create a status bar container.</pre>
<h4>Properties</h4>
<p>Uses common container properties. Add child widgets (labels, progress bars, etc.) to populate.</p>
<h4>Events</h4>
<p>StatusBar itself has no widget-specific events. Events fire on the child widgets.</p>
<hr>
</div>
<div class="topic" id="widget.tabcontrol">
<h1>TabControl</h1>
<h3>TabControl</h3>
<p>A tabbed container that displays one page at a time with clickable tabs along the top. Each tab page is a container that holds its own child widgets.</p>
<p>Header: widgets/widgetTabControl.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *tabs = wgtTabControl(parent);
WidgetT *page1 = wgtTabPage(tabs, &quot;General&quot;);
WidgetT *page2 = wgtTabPage(tabs, &quot;Advanced&quot;);
// add children to page1, page2...</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtTabControl(parent) Create a tab control.
wgtTabPage(parent, title) Add a tab page with the given title. Returns the page container widget.
wgtTabControlSetActive(w, idx) Set the active tab by index (0-based).
wgtTabControlGetActive(w) Get the index of the active tab.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onChange Fires when the active tab changes.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
TabIndex Integer Read/Write Index of the currently active tab (0-based).</pre>
<h4>Methods (BASIC Interface)</h4>
<pre> Method Description
------ -----------
SetActive Set the active tab by index.</pre>
<hr>
</div>
<div class="topic" id="widget.textinput">
<h1>TextInput / TextArea</h1>
<h3>TextInput / TextArea</h3>
<p>Single-line text input, password input, masked input, and multi-line text area with optional syntax colorization, line numbers, find/replace, and gutter decorators.</p>
<p>Header: widgets/widgetTextInput.h</p>
<h4>Creation</h4>
<pre> Macro Description
----- -----------
wgtTextInput(parent, maxLen) Create a single-line text input. maxLen is the maximum number of characters.
wgtPasswordInput(parent, maxLen) Create a password input (characters displayed as bullets).
wgtMaskedInput(parent, mask) Create a masked input field. The mask string defines the input format.
wgtTextArea(parent, maxLen) Create a multi-line text area.</pre>
<h4>Methods (TextArea-specific)</h4>
<pre> Macro Description
----- -----------
wgtTextAreaSetColorize(w, fn, ctx) Set a syntax colorization callback. The callback receives each line and fills a color index array. Color indices: 0=default, 1=keyword, 2=string, 3=comment, 4=number, 5=operator, 6=type/builtin, 7=reserved.
wgtTextAreaGoToLine(w, line) Scroll to and place the cursor on the given line number.
wgtTextAreaSetAutoIndent(w, enable) Enable or disable automatic indentation on newline.
wgtTextAreaSetShowLineNumbers(w, show) Show or hide line numbers in the gutter.
wgtTextAreaSetCaptureTabs(w, capture) When true, Tab key inserts a tab/spaces instead of moving focus.
wgtTextAreaSetTabWidth(w, width) Set the tab stop width in characters.
wgtTextAreaSetUseTabChar(w, useChar) When true, insert literal tab characters; when false, insert spaces.
wgtTextAreaFindNext(w, needle, caseSens, fwd) Search for the next occurrence. Returns true if found.
wgtTextAreaReplaceAll(w, needle, repl, caseSens) Replace all occurrences. Returns the number of replacements made.
wgtTextAreaSetLineDecorator(w, fn, ctx) Set a gutter line decorator callback. The callback returns a color and receives the line number, a color output pointer, and the user context.
wgtTextAreaGetCursorLine(w) Get the current cursor line number.
wgtTextAreaSetGutterClick(w, fn) Set a callback for gutter clicks (e.g. for breakpoint toggling). Callback receives the widget and line number.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onChange Fires when the text content changes.
onKeyPress Fires on each key press (ASCII value).
onValidate Called before committing a change. Return false to cancel.</pre>
<hr>
</div>
<div class="topic" id="widget.timer">
<h1>Timer</h1>
<h3>Timer</h3>
<p>A non-visual widget that fires its onClick callback at a regular interval. Useful for animations, polling, and periodic updates. Must be explicitly started after creation.</p>
<p>Header: widgets/widgetTimer.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *tmr = wgtTimer(parent, 1000, true); // 1 second, repeating
tmr-&gt;onClick = onTimerTick;
wgtTimerStart(tmr);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtTimer(parent, intervalMs, repeat) Create a timer. intervalMs is the interval in milliseconds. repeat: true for repeating, false for one-shot.
wgtTimerStart(w) Start the timer.
wgtTimerStop(w) Stop the timer.
wgtTimerSetInterval(w, intervalMs) Change the timer interval.
wgtTimerIsRunning(w) Returns true if the timer is currently running.
wgtUpdateTimers() Global tick function. Called by the event loop to advance all active timers.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onClick Fires each time the timer elapses.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
Enabled Boolean Read/Write Whether the timer is running. Reading returns the running state; writing starts or stops it.
Interval Integer Write-only Timer interval in milliseconds.</pre>
<h4>Methods (BASIC Interface)</h4>
<pre> Method Description
------ -----------
Start Start the timer.
Stop Stop the timer.</pre>
<h4>Extra Events (BASIC Interface)</h4>
<pre> Event Description
----- -----------
Timer Fires each time the timer elapses. Default event.</pre>
<hr>
</div>
<div class="topic" id="widget.toolbar">
<h1>Toolbar</h1>
<h3>Toolbar</h3>
<p>A horizontal container for toolbar buttons and controls. Typically placed at the top of a window. Children (usually ImageButtons or Buttons) are laid out horizontally with toolbar-appropriate spacing.</p>
<p>Header: widgets/widgetToolbar.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *tb = wgtToolbar(parent);
wgtImageButtonFromFile(tb, &quot;icons/save.bmp&quot;);
wgtImageButtonFromFile(tb, &quot;icons/open.bmp&quot;);</code></pre>
<h4>Macro</h4>
<pre> Macro Description
----- -----------
wgtToolbar(parent) Create a toolbar container.</pre>
<h4>Properties</h4>
<p>Uses common container properties. Add children (buttons, separators, etc.) to populate the toolbar.</p>
<h4>Events</h4>
<p>Toolbar itself has no widget-specific events. Events fire on the child widgets.</p>
<hr>
</div>
<div class="topic" id="widget.treeview">
<h1>TreeView</h1>
<h3>TreeView</h3>
<p>A hierarchical tree control with expandable/collapsible nodes. Supports single and multi-selection and drag-to-reorder. Tree items are added as children of the TreeView or of other tree items to create nested hierarchies.</p>
<p>Header: widgets/widgetTreeView.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *tv = wgtTreeView(parent);
WidgetT *root = wgtTreeItem(tv, &quot;Root&quot;);
WidgetT *child = wgtTreeItem(root, &quot;Child&quot;);</code></pre>
<h4>Macros</h4>
<pre> Macro Description
----- -----------
wgtTreeView(parent) Create a tree view control.
wgtTreeItem(parent, text) Add a tree item as a child of the tree view or another tree item.
wgtTreeViewGetSelected(w) Get the currently selected tree item (returns WidgetT *, NULL if none).
wgtTreeViewSetSelected(w, item) Set the selected tree item.
wgtTreeViewSetMultiSelect(w, multi) Enable or disable multi-selection.
wgtTreeViewSetReorderable(w, reorderable) Enable drag-to-reorder of items.
wgtTreeItemSetExpanded(w, expanded) Expand or collapse a tree item.
wgtTreeItemIsExpanded(w) Check if a tree item is expanded.
wgtTreeItemIsSelected(w) Check if a tree item is selected (multi-select mode).
wgtTreeItemSetSelected(w, selected) Select or deselect a tree item.</pre>
<h4>Events</h4>
<pre> Callback Description
-------- -----------
onClick Fires when a tree item is clicked.
onDblClick Fires when a tree item is double-clicked.
onChange Fires when the selection changes.</pre>
<h4>Methods (BASIC Interface)</h4>
<pre> Method Description
------ -----------
SetMultiSelect Enable or disable multi-selection.
SetReorderable Enable or disable drag-to-reorder.</pre>
<hr>
</div>
<div class="topic" id="widget.wrapbox">
<h1>WrapBox</h1>
<h3>WrapBox</h3>
<p>A flow/wrap layout container that arranges children left-to-right, wrapping to the next row when the available width is exceeded. Each row's height is the maximum child height in that row. Supports configurable spacing between items and rows, and per-row alignment for short rows.</p>
<p>Header: widgets/widgetWrapBox.h</p>
<h4>Creation</h4>
<pre><code>WidgetT *wrap = wgtWrapBox(parent);
wgtButton(wrap, &quot;Tag 1&quot;);
wgtButton(wrap, &quot;Tag 2&quot;);
wgtButton(wrap, &quot;Tag 3&quot;);</code></pre>
<h4>Macro</h4>
<pre> Macro Description
----- -----------
wgtWrapBox(parent) Create a wrap box container.</pre>
<h4>Properties</h4>
<p>WrapBox uses the common WidgetT container fields for layout control:</p>
<pre> Property Description
-------- -----------
spacing Gap between children in both the horizontal and vertical directions (tagged size). Default is 4 pixels.
padding Internal padding around children (tagged size). Default is 2 pixels.</pre>
<h4>Properties (BASIC Interface)</h4>
<pre> Property Type Access Description
-------- ---- ------ -----------
Alignment Enum (Left, Center, Right) Read/Write Row alignment for rows that do not fill the full width.</pre>
<h4>Events</h4>
<p>WrapBox is a container widget. It uses the common events only. No widget-specific events are defined.</p>
</div>
</main>
</body>
</html>
Reference in a new issue View git blame Copy permalink