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

2136 lines
101 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>DVX GUI API Reference</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="#api.overview">DVX GUI API Reference</a></li>
<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>
<h3>Index</h3>
<ul>
<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>
</ul>
</nav>
<main>
<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>
</main>
</body>
</html>
Reference in a new issue View git blame Copy permalink