DVX GUI API Reference
DVX GUI API Reference
DOS Visual eXecutive -- Complete public API documentation generated from source headers.
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.
Layers
- dvxTypes.h -- Shared type definitions
- dvxCursor.h -- Cursor definitions
- dvxVideo.h -- Layer 1: VESA VBE Video Backend
- dvxDraw.h -- Layer 2: Drawing Primitives
- dvxComp.h -- Layer 3: Dirty Rectangle Compositor
- dvxWm.h -- Layer 4: Window Manager
- dvxApp.h -- Layer 5: Application API
dvxWidget.h -- Widget System
dvxTypes.h -- Shared Type Definitions
dvxCursor.h -- Cursor Definitions
dvxVideo.h -- Layer 1: VESA VBE Video Backend
dvxDraw.h -- Layer 2: Drawing Primitives
dvxComp.h -- Layer 3: Dirty Rectangle Compositor
dvxWm.h -- Layer 4: Window Manager
dvxTypes.h -- Shared Type Definitions
dvxTypes.h -- Shared Type Definitions
Central type definitions shared across all five layers of the DVX GUI stack. Every header includes this file. Contains no function definitions -- only structs, enums, typedefs, and compile-time constants.
Core Structures
PixelFormatT
Describes the pixel encoding for the active VESA video mode. Populated once at startup from the VBE mode info block, then treated as read-only.
Field Description ----- ----------- int32_t bitsPerPixel 8, 15, 16, or 32 int32_t bytesPerPixel 1, 2, 2, or 4 uint32_t redMask, greenMask, blueMask Bitmasks for each color channel int32_t redShift, greenShift, blueShift Bit position of each color field int32_t redBits, greenBits, blueBits Number of bits per channel
DisplayT
Single display context passed by pointer through every layer. All drawing targets the backBuf; only dirty rects are flushed to lfb.
Field Description ----- ----------- int32_t width, height Screen dimensions in pixels int32_t pitch Bytes per scanline PixelFormatT format Active pixel format uint8_t *lfb Mapped linear framebuffer (VESA LFB) uint8_t *backBuf System RAM backbuffer uint8_t *palette 768 bytes for 8-bit mode, NULL otherwise int32_t clipX, clipY, clipW, clipH Current clip rectangle
RectT
Rectangle in origin + extent form. Used throughout the compositor, window manager, and widget layout engine.
Field Description ----- ----------- int32_t x, y Top-left corner int32_t w, h Width and height
BlitOpsT
Vtable for hot-path span operations. Resolved at init time based on pixel depth. On DOS, these dispatch to hand-written asm (rep stosl / rep movsd).
Field Description ----- ----------- SpanFillFnT spanFill Fill a horizontal span with a solid color SpanCopyFnT spanCopy Copy a horizontal span between buffers int32_t bytesPerPixel Bytes per pixel for the active mode int32_t pitch Bytes per scanline
BevelStyleT
Bevel drawing parameters. Swapping highlight/shadow flips raised vs. sunken appearance.
Field Description ----- ----------- uint32_t highlight Lighter color (top/left edges) uint32_t shadow Darker color (bottom/right edges) uint32_t face Interior fill color (0 = no fill) int32_t width Border thickness in pixels (typically 2)
BitmapFontT
Fixed-width 8-pixel-wide bitmap font descriptor. One size provided: 8x16 (standard VGA ROM font, CP437 encoding).
Field Description ----- ----------- int32_t charWidth Fixed width per glyph (always 8) int32_t charHeight Glyph height (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
ColorSchemeT
All UI colors pre-packed into display pixel format at init time. Theme support is achieved by swapping this struct.
Field Description ----- ----------- uint32_t desktop Desktop background color uint32_t windowFace Window body / chrome face uint32_t windowHighlight Bevel highlight (top/left edge) uint32_t windowShadow Bevel shadow (bottom/right edge) uint32_t activeTitleBg, activeTitleFg Focused window title bar uint32_t inactiveTitleBg, inactiveTitleFg Unfocused window title bar uint32_t contentBg, contentFg Window content area default colors uint32_t menuBg, menuFg Menu bar and popup background/text uint32_t menuHighlightBg, menuHighlightFg Menu item highlight uint32_t buttonFace Button face color uint32_t scrollbarBg, scrollbarFg, scrollbarTrough Scrollbar element colors uint32_t cursorFg, cursorBg Mouse cursor colors
ColorIdE
Enum for addressing individual colors in ColorSchemeT. Order matches struct field order.
Values: ColorDesktopE, ColorWindowFaceE, ColorWindowHighlightE, ColorWindowShadowE, ColorActiveTitleBgE, ColorActiveTitleFgE, ColorInactiveTitleBgE, ColorInactiveTitleFgE, ColorContentBgE, ColorContentFgE, ColorMenuBgE, ColorMenuFgE, ColorMenuHighlightBgE, ColorMenuHighlightFgE, ColorButtonFaceE, ColorScrollbarBgE, ColorScrollbarFgE, ColorScrollbarTroughE, ColorCursorFgE, ColorCursorBgE, ColorCountE.
DirtyListT
Fixed-capacity list of dirty rectangles. Dynamic array, grows on demand.
Field Description ----- ----------- RectT *rects Dynamic array of dirty rectangles int32_t count Current number of dirty rects int32_t cap Allocated capacity
WindowT
Central window object. Each window owns a persistent content backbuffer and receives events through callback function pointers.
Field Description ----- ----------- int32_t id Unique window identifier int32_t appId Shell app ID (0 = shell itself) int32_t x, y, w, h Outer frame position and dimensions int32_t contentX, contentY, contentW, contentH Content area inset from frame char title[MAX_TITLE_LEN] Window title text (max 128 chars) bool visible, focused, minimized, maximized, resizable, modal Window state flags bool 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
Callbacks:
Callback Description -------- ----------- onPaint(WindowT *win, RectT *dirtyArea) Content repaint requested onKey(WindowT *win, int32_t key, int32_t mod) Key press onKeyUp(WindowT *win, int32_t scancode, int32_t mod) Key release onMouse(WindowT *win, int32_t x, int32_t y, int32_t 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
WindowStackT
Z-ordered window stack (front-to-back: index count-1 is topmost). Owns system-wide drag/resize/scroll interaction state.
Field Description ----- ----------- WindowT **windows Dynamic array of window pointers int32_t count, cap Current count and allocated capacity int32_t focusedIdx Stack index of focused window int32_t dragWindow, dragOffX, dragOffY Active drag state int32_t resizeWindow, resizeEdge Active resize state int32_t scrollWindow, scrollOrient, scrollDragOff Active scroll drag state
MenuT / MenuItemT / MenuBarT
Menu system types. Fixed-size label buffers (MAX_MENU_LABEL = 32). Cascading submenus supported via MenuItemT.subMenu pointer.
Field Description ----- ----------- MenuItemT.label Item text (supports & accelerator markers) MenuItemT.id Application-defined command ID MenuItemT.type MenuItemNormalE, MenuItemCheckE, or MenuItemRadioE MenuItemT.separator true = horizontal divider line MenuItemT.enabled, checked Item state MenuItemT.subMenu Child menu for cascading (NULL if leaf) MenuBarT.activeIdx Open popup index (-1 = none)
ScrollbarT
Window-level scrollbar state. Managed by the WM layer, drawn after content.
Field Description ----- ----------- ScrollbarOrientE orient ScrollbarVerticalE or ScrollbarHorizontalE int32_t min, max Scroll range int32_t value Current position int32_t pageSize Visible portion (for proportional thumb sizing) int32_t x, y, length Computed screen position and track length
AccelTableT / AccelEntryT
Per-window keyboard accelerator table. Entries are matched against keystrokes in the event loop and fire onMenu(cmdId) on match.
Field Description ----- ----------- AccelEntryT.key ASCII character or KEY_Fxx constant AccelEntryT.modifiers Bitmask of ACCEL_CTRL, ACCEL_SHIFT, ACCEL_ALT AccelEntryT.cmdId Command ID passed to onMenu
VideoModeInfoT
Describes an available video mode (enumerated at init).
Field Description ----- ----------- int32_t w, h Resolution int32_t bpp Bits per pixel
CursorT
Software-rendered 16x16 cursor using AND/XOR mask encoding.
Field Description ----- ----------- int32_t width, height Cursor dimensions (always 16x16) int32_t hotX, hotY Hot spot coordinates const uint16_t *andMask AND mask (0 = draw pixel, 1 = transparent) const uint16_t *xorData XOR data (0 = black, 1 = white where AND = 0)
Bevel Convenience Macros
Macro Description ----- ----------- BEVEL_RAISED(cs, bw) Raised bevel style from ColorSchemeT ptr and border width BEVEL_SUNKEN(cs, face, bw) Sunken bevel style with explicit face color BEVEL_TROUGH(cs) 1px sunken trough (for scrollbar tracks) BEVEL_SB_BUTTON(cs) 1px raised scrollbar button
Chrome Constants
Define Value Description ------ ----- ----------- CHROME_BORDER_WIDTH 4 Outer frame border width CHROME_TITLE_HEIGHT 20 Title bar height CHROME_TITLE_PAD 4 Title text padding CHROME_INNER_BORDER 2 Inner chrome border CHROME_MENU_HEIGHT 20 Menu bar height CHROME_TOTAL_TOP 26 Total inset from top of frame to content CHROME_TOTAL_SIDE 6 Total inset from side of frame to content CHROME_TOTAL_BOTTOM 6 Total inset from bottom of frame to content CHROME_CLOSE_BTN_SIZE 16 Close button gadget size
Hit Test Constants
Define Value Description ------ ----- ----------- HIT_CONTENT 0 Content area HIT_TITLE 1 Title bar HIT_CLOSE 2 Close gadget HIT_RESIZE 3 Resize border HIT_MENU 4 Menu bar HIT_VSCROLL 5 Vertical scrollbar HIT_HSCROLL 6 Horizontal scrollbar HIT_MINIMIZE 7 Minimize gadget HIT_MAXIMIZE 8 Maximize gadget HIT_NONE -1 No window hit (desktop)
Mouse Button Flags
Define Value Description ------ ----- ----------- MOUSE_LEFT 1 Left mouse button MOUSE_RIGHT 2 Right mouse button MOUSE_MIDDLE 4 Middle mouse button
Accelerator Modifier Flags
Define Value Description ------ ----- ----------- ACCEL_SHIFT 0x03 Shift key (matches BIOS shift state bits) ACCEL_CTRL 0x04 Ctrl key ACCEL_ALT 0x08 Alt key
Extended Key Codes
Define Description ------ ----------- KEY_F1 .. KEY_F12 Function keys (scancode | 0x100) KEY_INSERT Insert key KEY_DELETE Delete key KEY_HOME Home key KEY_END End key KEY_PGUP Page Up key KEY_PGDN Page Down key
Resize Edge Flags
Define Value Description ------ ----- ----------- RESIZE_NONE 0 No resize edge RESIZE_LEFT 1 Left edge RESIZE_RIGHT 2 Right edge RESIZE_TOP 4 Top edge RESIZE_BOTTOM 8 Bottom edge (combinable via OR for corners)
Utility Macros
Macro Description ----- ----------- DVX_MIN(a, b) Return the smaller of two values DVX_MAX(a, b) Return the larger of two values
dvxCursor.h -- Cursor Definitions
dvxCursor.h -- Cursor Definitions
Embedded 16x16 mouse cursor bitmaps compiled as static const data. No external cursor files. Uses the standard AND/XOR mask encoding from the IBM VGA hardware cursor spec.
Cursor Shape IDs
Define Value Description ------ ----- ----------- CURSOR_ARROW 0 Standard arrow (hot spot at tip) CURSOR_RESIZE_H 1 Horizontal resize (left/right arrows) CURSOR_RESIZE_V 2 Vertical resize (up/down arrows) CURSOR_RESIZE_DIAG_NWSE 3 NW-SE diagonal resize CURSOR_RESIZE_DIAG_NESW 4 NE-SW diagonal resize CURSOR_BUSY 5 Hourglass (wait) CURSOR_CROSSHAIR 6 Crosshair for placement CURSOR_COUNT 7 Total number of cursor shapes
Data
dvxCursors[CURSOR_COUNT]
Static const array of CursorT structs, indexed by CURSOR_xxx constants. Each entry includes the AND mask, XOR data, dimensions, and hot spot coordinates.
dvxVideo.h -- Layer 1: VESA VBE Video Backend
dvxVideo.h -- Layer 1: VESA VBE Video Backend
The lowest layer. Responsible for VESA VBE mode negotiation, LFB mapping via DPMI, system RAM backbuffer allocation, pixel format discovery, and color packing. LFB-only design: bank switching is deliberately unsupported.
videoInit
int32_t videoInit(DisplayT *d, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);Probe VBE for a mode matching the requested resolution and depth, enable it, map the LFB into DPMI linear address space, and allocate a system RAM backbuffer. preferredBpp is a hint; the closest available depth is used if an exact match is not found.
Parameter Description --------- ----------- d Display context to initialize requestedW/H Desired screen resolution preferredBpp Preferred bits per pixel (8, 15, 16, or 32)
Returns: 0 on success, negative on failure.
videoShutdown
void videoShutdown(DisplayT *d);Restore VGA text mode (mode 3), unmap the LFB, and free the backbuffer. Safe to call even if videoInit() failed.
Parameter Description --------- ----------- d Display context to shut down
packColor
uint32_t packColor(const DisplayT *d, uint8_t r, uint8_t g, uint8_t b);Pack an RGB triplet into the display's native pixel format. For direct-color modes (15/16/32 bpp), returns a packed pixel value using shift/mask fields. For 8-bit mode, returns the nearest palette index via Euclidean distance in RGB space.
Parameter Description --------- ----------- d Display context (provides pixel format) r, g, b Color components (0-255)
Returns: Native pixel value suitable for direct framebuffer write.
setClipRect
void setClipRect(DisplayT *d, int32_t x, int32_t y, int32_t w, int32_t h);Set the clip rectangle on the display. All subsequent draw operations clip to this rectangle. The caller must save and restore the clip rect around scoped operations.
Parameter Description --------- ----------- d Display context x, y, w, h Clip rectangle in screen coordinates
resetClipRect
void resetClipRect(DisplayT *d);Reset the clip rectangle to the full display dimensions.
Parameter Description --------- ----------- d Display context
dvxDraw.h -- Layer 2: Drawing Primitives
dvxDraw.h -- Layer 2: Drawing Primitives
All 2D drawing operations: rectangle fills, bitmap blits, text rendering, bevels, lines, and cursor rendering. Every function draws into the display's backbuffer and clips to the current clip rectangle. This layer is stateless beyond the clip rect on DisplayT.
drawInit
void drawInit(BlitOpsT *ops, const DisplayT *d);Populate a BlitOpsT with the correct span functions for the display's pixel depth. Must be called once after videoInit().
Parameter Description --------- ----------- ops BlitOpsT to populate d Initialized display context
rectFill
void rectFill(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);Fill a rectangle with a solid color. Clips to the display clip rect. Workhorse for backgrounds, window fills, and clear operations.
Parameter Description --------- ----------- d Display context ops Blit operations vtable x, y, w, h Rectangle to fill color Packed pixel color
rectCopy
void rectCopy(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h);Copy a rectangle from an arbitrary source buffer into the backbuffer. Used to blit per-window content buffers during compositing.
Parameter Description --------- ----------- d Display context ops Blit operations vtable dstX, dstY Destination position in backbuffer srcBuf Source pixel buffer srcPitch Source buffer bytes per row srcX, srcY Origin within source buffer w, h Rectangle dimensions to copy
rectCopyGrayscale
void rectCopyGrayscale(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h);Copy a rectangle with grayscale conversion. Each pixel's RGB is converted to luminance (0.299R + 0.587G + 0.114B) for a disabled/grayed appearance.
Parameter Description --------- ----------- d Display context ops Blit operations vtable dstX, dstY Destination position srcBuf, srcPitch Source buffer and pitch srcX, srcY Source origin w, h Rectangle dimensions
drawBevel
void drawBevel(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const BevelStyleT *style);Draw a beveled frame. Top/left edges in highlight color, bottom/right in shadow. Interior filled with face color if non-zero.
Parameter Description --------- ----------- d Display context ops Blit operations vtable x, y, w, h Outer bevel rectangle style Bevel colors and width
drawChar
int32_t drawChar(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, char ch, uint32_t fg, uint32_t bg, bool opaque);Draw a single character glyph. When opaque is true, the background fills the entire cell; when false, only foreground pixels are drawn (transparent background).
Parameter Description --------- ----------- d Display context ops Blit operations vtable font Bitmap font x, y Character position ch Character to draw fg, bg Foreground and background packed colors opaque true = fill background, false = transparent
Returns: Advance width (always charWidth).
drawText
void drawText(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque);Draw a null-terminated string. Calls drawChar per character.
Parameter Description --------- ----------- d Display context ops Blit operations vtable font Bitmap font x, y Start position text Null-terminated string fg, bg Foreground and background packed colors opaque true = fill background, false = transparent
drawTextN
void drawTextN(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, int32_t count, uint32_t fg, uint32_t bg, bool opaque);Optimized batch text rendering for a known character count. Computes clip bounds once, fills background in a single rectFill, then overlays glyph foreground pixels. Significantly faster than per-character drawChar for long runs (terminal rows, list items).
Parameter Description --------- ----------- d Display context ops Blit operations vtable font Bitmap font x, y Start position text Character buffer (not required to be null-terminated) count Number of characters to render fg, bg Foreground and background packed colors opaque true = fill background, false = transparent
textWidth
int32_t textWidth(const BitmapFontT *font, const char *text);Return the pixel width of a null-terminated string (strlen(text) * charWidth).
Parameter Description --------- ----------- font Bitmap font text Null-terminated string
Returns: Width in pixels.
accelParse
char accelParse(const char *text);Scan text for an & prefix and return the following character as a lowercase accelerator key. "&File" returns 'f', "E&xit" returns 'x'.
Parameter Description --------- ----------- text Text with optional & accelerator marker
Returns: Lowercase accelerator character, or 0 if none.
drawTextAccel
void drawTextAccel(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque);Draw text with & accelerator markers. The character after & is drawn underlined to indicate the keyboard shortcut. && produces a literal &. Used for menu items and button labels.
Parameter Description --------- ----------- d Display context ops Blit operations vtable font Bitmap font x, y Start position text Text with & markers fg, bg Foreground and background packed colors opaque true = fill background, false = transparent
textWidthAccel
int32_t textWidthAccel(const BitmapFontT *font, const char *text);Measure text width excluding & markers (so "&File" measures as 4 chars).
Parameter Description --------- ----------- font Bitmap font text Text with optional & markers
Returns: Width in pixels.
drawMaskedBitmap
void drawMaskedBitmap(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const uint16_t *andMask, const uint16_t *xorData, uint32_t fgColor, uint32_t bgColor);Draw a 1-bit AND/XOR masked bitmap. Used for software-rendered mouse cursors.
Parameter Description --------- ----------- d Display context ops Blit operations vtable x, y Screen position w, h Bitmap dimensions andMask AND transparency mask (one uint16_t per row) xorData XOR color data fgColor, bgColor Cursor foreground and background packed colors
drawTermRow
void drawTermRow(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, int32_t cols, const uint8_t *lineData, const uint32_t *palette, bool blinkVisible, int32_t cursorCol);Render an entire row of terminal character cells (ch/attr byte pairs) in a single pass. Colors looked up from a 16-color palette. Attribute bit 7 controls blink.
Parameter Description --------- ----------- d Display context ops Blit operations vtable font Bitmap font x, y Row start position cols Number of columns lineData Packed ch/attr byte pairs (2 bytes per cell) palette 16-entry packed color palette blinkVisible false = hide blinking characters cursorCol Column for inverted text cursor (-1 = none)
drawFocusRect
void drawFocusRect(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);Draw a 1px dotted rectangle (alternating pixels). Used for keyboard focus indicators, matching the Windows 3.x focus rectangle convention.
Parameter Description --------- ----------- d Display context ops Blit operations vtable x, y, w, h Focus rectangle bounds color Dot color (packed)
drawHLine
void drawHLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, uint32_t color);Draw a horizontal line (1px tall).
Parameter Description --------- ----------- d Display context ops Blit operations vtable x, y Start position w Width in pixels color Packed pixel color
drawVLine
void drawVLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t h, uint32_t color);Draw a vertical line (1px wide).
Parameter Description --------- ----------- d Display context ops Blit operations vtable x, y Start position h Height in pixels color Packed pixel color
dvxComp.h -- Layer 3: Dirty Rectangle Compositor
dvxComp.h -- Layer 3: Dirty Rectangle Compositor
Tracks changed screen regions and ensures only dirty regions are redrawn and flushed to video memory. The compositing pipeline: mark dirty, merge overlapping rects, redraw desktop + windows (back-to-front, painter's algorithm), flush to LFB.
dirtyListInit
void dirtyListInit(DirtyListT *dl);Zero the dirty rect count. Called at the start of each frame.
Parameter Description --------- ----------- dl Dirty list to initialize
dirtyListAdd
void dirtyListAdd(DirtyListT *dl, int32_t x, int32_t y, int32_t w, int32_t h);Enqueue a dirty rectangle. Grows dynamically; triggers merge at a soft capacity limit.
Parameter Description --------- ----------- dl Dirty list x, y, w, h Dirty rectangle in screen coordinates
dirtyListMerge
void dirtyListMerge(DirtyListT *dl);Consolidate the dirty list by merging overlapping and adjacent rects. Uses iterative pairwise merge: if combining two rects does not increase total area beyond a threshold, they are merged. Reduces compositor passes and LFB flush operations.
Parameter Description --------- ----------- dl Dirty list to merge
dirtyListClear
void dirtyListClear(DirtyListT *dl);Reset the dirty list to empty (sets count to 0).
Parameter Description --------- ----------- dl Dirty list to clear
flushRect
void flushRect(DisplayT *d, const RectT *r);Copy a rectangle from the system RAM backbuffer to the LFB (video memory). This is the only place the real framebuffer is written. Uses platform-specific fast copy (rep movsd on DOS) for each scanline.
Parameter Description --------- ----------- d Display context r Rectangle to flush
rectIntersect
bool rectIntersect(const RectT *a, const RectT *b, RectT *result);Compute the intersection of two rectangles.
Parameter Description --------- ----------- a, b Input rectangles result Output: intersection rectangle (valid only when return is true)
Returns: true if the rectangles overlap, false if disjoint.
rectIsEmpty
bool rectIsEmpty(const RectT *r);Test whether a rectangle has zero or negative area.
Parameter Description --------- ----------- r Rectangle to test
Returns: true if w <= 0 or h <= 0.
dvxWm.h -- Layer 4: Window Manager
dvxWm.h -- Layer 4: Window Manager
Manages the window lifecycle, Z-order stack, chrome drawing, hit testing, and interactive operations (drag, resize, scroll). The WM owns window geometry and chrome; content is owned by the application via callbacks or the widget system.
Initialization
wmInit
void wmInit(WindowStackT *stack);Zero the window stack. Must be called before any other WM function.
Parameter Description --------- ----------- stack Window stack to initialize
Window Lifecycle
wmCreateWindow
WindowT *wmCreateWindow(WindowStackT *stack, DisplayT *d, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);Allocate a new window, initialize its geometry and content buffer, and push it to the top of the Z-order stack. Returns with all callbacks NULL; the caller should set onPaint/onKey/etc. before the next event loop iteration.
Parameter Description --------- ----------- stack Window stack d Display context title Window title text x, y Initial position w, h Initial outer frame dimensions resizable true = allow user resize
Returns: Pointer to new WindowT, or NULL on failure.
wmDestroyWindow
void wmDestroyWindow(WindowStackT *stack, WindowT *win);Free the window's content buffer and all attached resources (menu bar, scrollbars, widget tree), remove it from the stack, and dirty the vacated region.
Parameter Description --------- ----------- stack Window stack win Window to destroy
Z-Order and Focus
wmRaiseWindow
void wmRaiseWindow(WindowStackT *stack, DirtyListT *dl, int32_t idx);Move window at stack index idx to the top of the Z-order. Dirties both old and new top positions so overlapping windows get repainted.
Parameter Description --------- ----------- stack Window stack dl Dirty list for repaint marking idx Stack index of window to raise
wmSetFocus
void wmSetFocus(WindowStackT *stack, DirtyListT *dl, int32_t idx);Transfer keyboard focus to the window at stack index idx. Unfocuses the previously focused window and dirties both title bars.
Parameter Description --------- ----------- stack Window stack dl Dirty list idx Stack index of window to focus
Geometry
wmUpdateContentRect
void wmUpdateContentRect(WindowT *win);Recompute contentX/Y/W/H from the window's outer frame dimensions, accounting for chrome borders, title bar, menu bar, and scrollbars. Must be called after any change to frame size or chrome configuration.
Parameter Description --------- ----------- win Window to update
wmReallocContentBuf
int32_t wmReallocContentBuf(WindowT *win, const DisplayT *d);Reallocate the per-window content backbuffer to match current contentW/H. Old buffer contents are lost; caller should trigger a full repaint via onPaint afterward.
Parameter Description --------- ----------- win Window to reallocate d Display context (for bytes-per-pixel)
Returns: 0 on success, -1 on allocation failure.
wmMinWindowSize
void wmMinWindowSize(const WindowT *win, int32_t *minW, int32_t *minH);Get the minimum window size. Accounts for chrome, gadgets, and menu bar.
Parameter Description --------- ----------- win Window minW, minH Output: minimum width and height
Menu Bar
wmAddMenuBar
MenuBarT *wmAddMenuBar(WindowT *win);Allocate and attach a menu bar to a window. Adjusts content area to make room (CHROME_MENU_HEIGHT pixels). One menu bar per window.
Parameter Description --------- ----------- win Window to add menu bar to
Returns: Pointer to the new MenuBarT.
wmDestroyMenuBar
void wmDestroyMenuBar(WindowT *win);Free the menu bar and reclaim the content area.
Parameter Description --------- ----------- win Window to remove menu bar from
wmAddMenu
MenuT *wmAddMenu(MenuBarT *bar, const char *label);Append a dropdown menu to the menu bar. The label supports & accelerator markers (e.g. "&File").
Parameter Description --------- ----------- bar Menu bar label Menu label text
Returns: Pointer to the new MenuT to populate with items.
wmAddMenuItem
void wmAddMenuItem(MenuT *menu, const char *label, int32_t id);Append a clickable item to a menu. The id is passed to the window's onMenu callback when selected.
Parameter Description --------- ----------- menu Menu to append to label Item label (supports & markers) id Application-defined command ID
wmAddMenuCheckItem
void wmAddMenuCheckItem(MenuT *menu, const char *label, int32_t id, bool checked);Add a checkbox-style menu item. Check state toggles on click; rendered with a checkmark glyph.
Parameter Description --------- ----------- menu Menu to append to label Item label id Command ID checked Initial checked state
wmAddMenuRadioItem
void wmAddMenuRadioItem(MenuT *menu, const char *label, int32_t id, bool checked);Add a radio-style menu item. Radio groups are defined implicitly by consecutive radio items; selecting one unchecks the others in the group.
Parameter Description --------- ----------- menu Menu to append to label Item label id Command ID checked Initial checked state
wmAddMenuSeparator
void wmAddMenuSeparator(MenuT *menu);Insert a horizontal separator line. Separators are not interactive.
Parameter Description --------- ----------- menu Menu to append separator to
wmMenuItemIsChecked
bool wmMenuItemIsChecked(MenuBarT *bar, int32_t id);Query the checked state of a menu item by command ID. Searches all menus in the bar.
Parameter Description --------- ----------- bar Menu bar id Command ID to query
Returns: true if checked.
wmMenuItemSetChecked
void wmMenuItemSetChecked(MenuBarT *bar, int32_t id, bool checked);Set the checked state of a menu item by command ID. For radio items, setting checked=true also unchecks other radio items in the same group.
Parameter Description --------- ----------- bar Menu bar id Command ID checked New checked state
wmMenuItemSetEnabled
void wmMenuItemSetEnabled(MenuBarT *bar, int32_t id, bool enabled);Enable or disable a menu item by command ID.
Parameter Description --------- ----------- bar Menu bar id Command ID enabled true = enabled, false = grayed out
wmAddSubMenu
MenuT *wmAddSubMenu(MenuT *parentMenu, const char *label);Create a cascading submenu attached to a parent menu. The child MenuT is heap-allocated and freed when the parent window is destroyed.
Parameter Description --------- ----------- parentMenu Parent menu to attach submenu to label Submenu label text
Returns: Pointer to the child MenuT, or NULL on allocation failure.
wmCreateMenu
MenuT *wmCreateMenu(void);Allocate a heap-resident MenuT for use as a context menu (right-click). Unlike menu bar menus, context menus are standalone allocations. Free with wmFreeMenu().
Returns: Pointer to the new MenuT.
wmFreeMenu
void wmFreeMenu(MenuT *menu);Free a standalone menu allocated with wmCreateMenu(). Also frees any heap-allocated submenu children recursively.
Parameter Description --------- ----------- menu Menu to free
Scrollbars
wmAddVScrollbar
ScrollbarT *wmAddVScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize);Attach a vertical scrollbar to the right edge of the window's content area. Shrinks contentW by SCROLLBAR_WIDTH pixels.
Parameter Description --------- ----------- win Window min, max Scroll value range pageSize Visible portion (controls thumb size)
Returns: Pointer to the new ScrollbarT.
wmAddHScrollbar
ScrollbarT *wmAddHScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize);Attach a horizontal scrollbar to the bottom edge. Shrinks contentH by SCROLLBAR_WIDTH pixels.
Parameter Description --------- ----------- win Window min, max Scroll value range pageSize Visible portion
Returns: Pointer to the new ScrollbarT.
Drawing
wmDrawChrome
void wmDrawChrome(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo);Draw the window frame: outer bevel, title bar with text, close/minimize/maximize gadgets, and menu bar if present. Drawing is clipped to the intersection with clipTo.
Parameter Description --------- ----------- d Display context ops Blit operations vtable font Bitmap font for title text colors Color scheme win Window to draw chrome for clipTo Dirty rectangle to clip drawing to
wmDrawContent
void wmDrawContent(DisplayT *d, const BlitOpsT *ops, WindowT *win, const RectT *clipTo);Blit the window's content backbuffer into the display backbuffer, clipped to the dirty rect. Pure copy operation (no drawing).
Parameter Description --------- ----------- d Display context ops Blit operations vtable win Window clipTo Dirty rectangle
wmDrawScrollbars
void wmDrawScrollbars(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo);Draw scrollbars (track, arrows, proportional thumb) for a window. Drawn after content so scrollbars overlay the content area edge.
Parameter Description --------- ----------- d Display context ops Blit operations vtable colors Color scheme win Window clipTo Dirty rectangle
wmDrawMinimizedIcons
void wmDrawMinimizedIcons(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, const WindowStackT *stack, const RectT *clipTo);Draw icons for all minimized windows along the bottom of the screen. Each icon shows a scaled preview of the window's content with a beveled border.
Parameter Description --------- ----------- d Display context ops Blit operations vtable colors Color scheme stack Window stack clipTo Dirty rectangle
Hit Testing
wmHitTest
int32_t wmHitTest(const WindowStackT *stack, int32_t mx, int32_t my, int32_t *hitPart);Determine which window and chrome region is under the given screen coordinates. Iterates front-to-back (highest Z first) so the topmost window wins.
Parameter Description --------- ----------- stack Window stack mx, my Screen coordinates hitPart Output: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, etc.
Returns: Stack index of hit window, or -1 for desktop.
wmResizeEdgeHit
int32_t wmResizeEdgeHit(const WindowT *win, int32_t mx, int32_t my);Determine which edge(s) of a window's border zone are targeted for resize.
Parameter Description --------- ----------- win Window mx, my Screen coordinates
Returns: Bitmask of RESIZE_LEFT / RESIZE_RIGHT / RESIZE_TOP / RESIZE_BOTTOM.
wmMinimizedIconHit
int32_t wmMinimizedIconHit(const WindowStackT *stack, const DisplayT *d, int32_t mx, int32_t my);Hit-test minimized icons at the bottom of the screen.
Parameter Description --------- ----------- stack Window stack d Display context mx, my Screen coordinates
Returns: Stack index of the minimized window, or -1.
Drag and Resize
wmDragBegin
void wmDragBegin(WindowStackT *stack, int32_t idx, int32_t mouseX, int32_t mouseY);Begin a window drag operation. Records the mouse offset from the window origin.
Parameter Description --------- ----------- stack Window stack idx Stack index of window to drag mouseX/Y Current mouse position
wmDragMove
void wmDragMove(WindowStackT *stack, DirtyListT *dl, int32_t mouseX, int32_t mouseY, int32_t screenW, int32_t screenH);Update window position during an active drag. Dirties both old and new positions.
Parameter Description --------- ----------- stack Window stack dl Dirty list mouseX/Y Current mouse position screenW/H Screen dimensions (for clamping)
wmDragEnd
void wmDragEnd(WindowStackT *stack);End the current drag operation. Clears dragWindow state.
Parameter Description --------- ----------- stack Window stack
wmResizeBegin
void wmResizeBegin(WindowStackT *stack, int32_t idx, int32_t edge, int32_t mouseX, int32_t mouseY);Begin a window resize operation. Records which edge(s) are being dragged.
Parameter Description --------- ----------- stack Window stack idx Stack index edge Bitmask of RESIZE_xxx flags mouseX/Y Current mouse position
wmResizeMove
void wmResizeMove(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, int32_t *mouseX, int32_t *mouseY);Update window dimensions during an active resize. Enforces MIN_WINDOW_W/H and maxW/maxH constraints. Reallocates content buffer and calls onResize if size changed. mouseX/mouseY are in/out: clamped on return for cursor warping.
Parameter Description --------- ----------- stack Window stack dl Dirty list d Display context mouseX/Y In/out: mouse position (clamped on return)
wmResizeEnd
void wmResizeEnd(WindowStackT *stack);End the current resize operation. Clears resizeWindow state.
Parameter Description --------- ----------- stack Window stack
Scrollbar Interaction
wmScrollbarClick
void wmScrollbarClick(WindowStackT *stack, DirtyListT *dl, int32_t idx, int32_t orient, int32_t mx, int32_t my);Handle an initial click on a scrollbar. Determines what was hit (arrows, trough, or thumb) and either adjusts the value immediately or begins a thumb drag.
Parameter Description --------- ----------- stack Window stack dl Dirty list idx Stack index of window orient SCROLL_VERTICAL or SCROLL_HORIZONTAL mx, my Click screen coordinates
wmScrollbarDrag
void wmScrollbarDrag(WindowStackT *stack, DirtyListT *dl, int32_t mx, int32_t my);Update the scroll value during an active thumb drag. Maps mouse position along the track to a proportional scroll value.
Parameter Description --------- ----------- stack Window stack dl Dirty list mx, my Current mouse position
wmScrollbarEnd
void wmScrollbarEnd(WindowStackT *stack);End an active scrollbar thumb drag.
Parameter Description --------- ----------- stack Window stack
Minimize / Maximize / Restore
wmMaximize
void wmMaximize(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);Maximize a window. Saves current geometry, then expands to screen or maxW/maxH bounds.
Parameter Description --------- ----------- stack Window stack dl Dirty list d Display context win Window to maximize
wmMinimize
void wmMinimize(WindowStackT *stack, DirtyListT *dl, WindowT *win);Minimize a window. Hides the window and shows an icon at the bottom of the screen.
Parameter Description --------- ----------- stack Window stack dl Dirty list win Window to minimize
wmRestore
void wmRestore(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);Restore a maximized window to its pre-maximize geometry.
Parameter Description --------- ----------- stack Window stack dl Dirty list d Display context win Maximized window to restore
wmRestoreMinimized
void wmRestoreMinimized(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);Restore a minimized window (show it again and remove the icon).
Parameter Description --------- ----------- stack Window stack dl Dirty list d Display context win Minimized window to restore
Minimized Icon Layout
wmMinimizedIconPos
void wmMinimizedIconPos(const DisplayT *d, int32_t index, int32_t *x, int32_t *y);Compute the screen position of a minimized icon by ordinal index. Icons wrap into rows from bottom to top when the screen fills up.
Parameter Description --------- ----------- d Display context index Ordinal index of the minimized icon x, y Output: screen position
wmMinimizedIconRect
void wmMinimizedIconRect(const WindowStackT *stack, const DisplayT *d, int32_t *y, int32_t *h);Compute the screen rect covering all minimized icon rows. Used to dirty the icon area when windows are minimized or restored.
Parameter Description --------- ----------- stack Window stack d Display context y, h Output: vertical extent of icon area
Miscellaneous
wmSetTitle
void wmSetTitle(WindowT *win, DirtyListT *dl, const char *title);Set the window title and dirty the title bar for repaint.
Parameter Description --------- ----------- win Window dl Dirty list title New title text
wmSetIcon
int32_t wmSetIcon(WindowT *win, const char *path, const DisplayT *d);Load an icon image for a window from a file. Converts to display pixel format.
Parameter Description --------- ----------- win Window path Image file path d Display context
Returns: 0 on success, -1 on failure.
dvxApp.h -- Layer 5: Application API
dvxApp.h -- Layer 5: Application API
The topmost layer and the public-facing API. Aggregates all lower layers into a single AppContextT. Applications interact exclusively through dvx*() functions and window callbacks. The event loop follows a cooperative model: poll, dispatch, composite, yield.
AppContextT
Single monolithic context that owns all GUI state. Contains the display, window stack, dirty list, blit ops, font, color scheme, popup state, cursor state, mouse/keyboard state, tooltip state, wallpaper buffer, video mode list, and various configuration fields. Allocated on the caller's stack or statically.
Initialization and Shutdown
dvxInit
int32_t dvxInit(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);Initialize the entire GUI stack: video mode, input devices, font, color scheme, cursor shapes, and internal state. Single entry point for starting a DVX application.
Parameter Description --------- ----------- ctx Application context to initialize requestedW/H Desired screen resolution preferredBpp Preferred bits per pixel
Returns: 0 on success, negative on failure.
dvxShutdown
void dvxShutdown(AppContextT *ctx);Tear down the GUI stack in reverse order: destroy all windows, restore text mode, release input devices. Safe to call after a failed dvxInit().
Parameter Description --------- ----------- ctx Application context
dvxChangeVideoMode
int32_t dvxChangeVideoMode(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);Switch to a new video mode live. Reallocates the backbuffer, all window content buffers, repacks colors, rescales wallpaper, and repositions off-screen windows.
Parameter Description --------- ----------- ctx Application context requestedW/H New resolution preferredBpp New bits per pixel
Returns: 0 on success, -1 on failure (old mode restored).
Event Loop
dvxRun
void dvxRun(AppContextT *ctx);Enter the main event loop. Polls input, dispatches events, composites dirty regions, and yields on each iteration. Returns when ctx->running becomes false.
Parameter Description --------- ----------- ctx Application context
dvxUpdate
bool dvxUpdate(AppContextT *ctx);Process exactly one frame of the event loop. For applications that integrate the GUI into their own main loop (e.g. polling serial ports between frames).
Parameter Description --------- ----------- ctx Application context
Returns: false when the GUI wants to exit.
dvxQuit
void dvxQuit(AppContextT *ctx);Request exit from the main event loop (sets ctx->running = false).
Parameter Description --------- ----------- ctx Application context
Window Management
dvxCreateWindow
WindowT *dvxCreateWindow(AppContextT *ctx, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);Create a window at an explicit screen position. The window is raised to the top, focused, and its entire region is dirtied.
Parameter Description --------- ----------- ctx Application context title Window title x, y Screen position w, h Outer frame dimensions resizable true = allow user resize
Returns: Pointer to new WindowT.
dvxCreateWindowCentered
WindowT *dvxCreateWindowCentered(AppContextT *ctx, const char *title, int32_t w, int32_t h, bool resizable);Convenience wrapper that centers the window on screen.
Parameter Description --------- ----------- ctx Application context title Window title w, h Outer frame dimensions resizable true = allow user resize
Returns: Pointer to new WindowT.
dvxDestroyWindow
void dvxDestroyWindow(AppContextT *ctx, WindowT *win);Destroy a window, free all its resources, and dirty its former region.
Parameter Description --------- ----------- ctx Application context win Window to destroy
dvxRaiseWindow
void dvxRaiseWindow(AppContextT *ctx, WindowT *win);Raise a window to the top of the Z-order and give it focus.
Parameter Description --------- ----------- ctx Application context win Window to raise
dvxFitWindow
void dvxFitWindow(AppContextT *ctx, WindowT *win);Resize a window to exactly fit its widget tree's computed minimum size (plus chrome). Used for dialog boxes and fixed-layout windows.
Parameter Description --------- ----------- ctx Application context win Window to fit
dvxFitWindowW
void dvxFitWindowW(AppContextT *ctx, WindowT *win);Resize window width only to fit widget tree's minimum width (plus chrome).
Parameter Description --------- ----------- ctx Application context win Window to fit
dvxFitWindowH
void dvxFitWindowH(AppContextT *ctx, WindowT *win);Resize window height only to fit widget tree's minimum height (plus chrome).
Parameter Description --------- ----------- ctx Application context win Window to fit
dvxResizeWindow
void dvxResizeWindow(AppContextT *ctx, WindowT *win, int32_t newW, int32_t newH);Programmatically resize a window to the specified outer dimensions.
Parameter Description --------- ----------- ctx Application context win Window to resize newW, newH New outer frame dimensions
dvxMinimizeWindow
void dvxMinimizeWindow(AppContextT *ctx, WindowT *win);Minimize a window (show as icon at bottom of screen).
Parameter Description --------- ----------- ctx Application context win Window to minimize
dvxMaximizeWindow
void dvxMaximizeWindow(AppContextT *ctx, WindowT *win);Maximize a window (expand to fill screen or maxW/maxH).
Parameter Description --------- ----------- ctx Application context win Window to maximize
dvxHideWindow
void dvxHideWindow(AppContextT *ctx, WindowT *win);Hide a window without destroying it. Marks the exposed region dirty.
Parameter Description --------- ----------- ctx Application context win Window to hide
dvxShowWindow
void dvxShowWindow(AppContextT *ctx, WindowT *win);Show a previously hidden window. Marks its region dirty for repaint.
Parameter Description --------- ----------- ctx Application context win Window to show
Invalidation
dvxInvalidateRect
void dvxInvalidateRect(AppContextT *ctx, WindowT *win, int32_t x, int32_t y, int32_t w, int32_t h);Mark a sub-region of a window's content area as needing repaint. Coordinates are relative to the content area, not the screen. Triggers onPaint during the next composite pass.
Parameter Description --------- ----------- ctx Application context win Window x, y, w, h Dirty rectangle in content-relative coordinates
dvxInvalidateWindow
void dvxInvalidateWindow(AppContextT *ctx, WindowT *win);Mark the entire window content area as dirty.
Parameter Description --------- ----------- ctx Application context win Window to invalidate
Window Properties
dvxSetTitle
void dvxSetTitle(AppContextT *ctx, WindowT *win, const char *title);Set a window's title text and dirty the title bar.
Parameter Description --------- ----------- ctx Application context win Window title New title text
dvxSetWindowIcon
int32_t dvxSetWindowIcon(AppContextT *ctx, WindowT *win, const char *path);Load an icon for a window from an image file.
Parameter Description --------- ----------- ctx Application context win Window path Image file path
Returns: 0 on success, -1 on failure.
dvxSetBusy
void dvxSetBusy(AppContextT *ctx, bool busy);Set or clear busy state. While busy, the hourglass cursor is shown and input is blocked.
Parameter Description --------- ----------- ctx Application context busy true = show hourglass, false = normal
Accessors
dvxGetFont
const BitmapFontT *dvxGetFont(const AppContextT *ctx);Get a pointer to the default font.
Parameter Description --------- ----------- ctx Application context
Returns: Pointer to the active BitmapFontT.
dvxGetColors
const ColorSchemeT *dvxGetColors(const AppContextT *ctx);Get a pointer to the current color scheme.
Parameter Description --------- ----------- ctx Application context
Returns: Pointer to the active ColorSchemeT.
dvxGetDisplay
DisplayT *dvxGetDisplay(AppContextT *ctx);Get a pointer to the display context.
Parameter Description --------- ----------- ctx Application context
Returns: Pointer to the DisplayT.
dvxGetBlitOps
const BlitOpsT *dvxGetBlitOps(const AppContextT *ctx);Get a pointer to the blit operations vtable.
Parameter Description --------- ----------- ctx Application context
Returns: Pointer to the active BlitOpsT.
dvxGetVideoModes
const VideoModeInfoT *dvxGetVideoModes(const AppContextT *ctx, int32_t *count);Return the list of available video modes enumerated at init time.
Parameter Description --------- ----------- ctx Application context count Output: number of mode entries
Returns: Pointer to the VideoModeInfoT array.
Color Scheme
dvxSetColor
void dvxSetColor(AppContextT *ctx, ColorIdE id, uint8_t r, uint8_t g, uint8_t b);Set a single color by ID. Repacks to native pixel format and invalidates the entire screen.
Parameter Description --------- ----------- ctx Application context id Color ID (ColorIdE) r, g, b RGB values (0-255)
dvxGetColor
void dvxGetColor(const AppContextT *ctx, ColorIdE id, uint8_t *r, uint8_t *g, uint8_t *b);Get a color's RGB values by ID.
Parameter Description --------- ----------- ctx Application context id Color ID (ColorIdE) r, g, b Output: RGB values
dvxApplyColorScheme
void dvxApplyColorScheme(AppContextT *ctx);Apply all colors from ctx->colorRgb[] at once (repack + full repaint).
Parameter Description --------- ----------- ctx Application context
dvxResetColorScheme
void dvxResetColorScheme(AppContextT *ctx);Reset all colors to the built-in defaults and repaint.
Parameter Description --------- ----------- ctx Application context
dvxLoadTheme
bool dvxLoadTheme(AppContextT *ctx, const char *filename);Load a theme file (INI format with [colors] section) and apply it.
Parameter Description --------- ----------- ctx Application context filename Path to theme INI file
Returns: true on success.
dvxSaveTheme
bool dvxSaveTheme(const AppContextT *ctx, const char *filename);Save the current color scheme to a theme file.
Parameter Description --------- ----------- ctx Application context filename Output file path
Returns: true on success.
dvxColorName
const char *dvxColorName(ColorIdE id);Return the INI key name for a color ID (e.g. "desktop", "windowFace").
Parameter Description --------- ----------- id Color ID
Returns: Static string.
dvxColorLabel
const char *dvxColorLabel(ColorIdE id);Return a human-readable display label (e.g. "Desktop", "Cursor Color").
Parameter Description --------- ----------- id Color ID
Returns: Static string.
Wallpaper
dvxSetWallpaper
bool dvxSetWallpaper(AppContextT *ctx, const char *path);Load and apply a wallpaper image using the current wallpaperMode (stretch/tile/center). Pass NULL to clear the wallpaper.
Parameter Description --------- ----------- ctx Application context path Image file path, or NULL to clear
Returns: true on success.
dvxSetWallpaperMode
void dvxSetWallpaperMode(AppContextT *ctx, WallpaperModeE mode);Change the wallpaper display mode and re-render. No effect if no wallpaper is loaded.
Parameter Description --------- ----------- ctx Application context mode WallpaperStretchE, WallpaperTileE, or WallpaperCenterE
Mouse Configuration
dvxSetMouseConfig
void dvxSetMouseConfig(AppContextT *ctx, int32_t wheelDir, int32_t dblClickMs, int32_t accelThreshold);Configure mouse behavior.
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)
Accelerators
dvxCreateAccelTable
AccelTableT *dvxCreateAccelTable(void);Allocate a new accelerator table. Attach to a window via win->accelTable.
Returns: Pointer to new AccelTableT.
dvxFreeAccelTable
void dvxFreeAccelTable(AccelTableT *table);Free an accelerator table and its entries.
Parameter Description --------- ----------- table Table to free
dvxAddAccel
void dvxAddAccel(AccelTableT *table, int32_t key, int32_t modifiers, int32_t cmdId);Register a keyboard shortcut. On match, fires the window's onMenu callback with cmdId.
Parameter Description --------- ----------- table Accelerator table key ASCII character or KEY_Fxx constant modifiers Bitmask of ACCEL_CTRL / ACCEL_SHIFT / ACCEL_ALT cmdId Command ID passed to onMenu
Window Arrangement
dvxCascadeWindows
void dvxCascadeWindows(AppContextT *ctx);Cascade all visible, non-minimized windows. Each is offset diagonally by the title bar height.
Parameter Description --------- ----------- ctx Application context
dvxTileWindows
void dvxTileWindows(AppContextT *ctx);Arrange visible windows in an NxM grid filling the screen.
Parameter Description --------- ----------- ctx Application context
dvxTileWindowsH
void dvxTileWindowsH(AppContextT *ctx);Tile windows horizontally (side by side, equal width, full height).
Parameter Description --------- ----------- ctx Application context
dvxTileWindowsV
void dvxTileWindowsV(AppContextT *ctx);Tile windows vertically (stacked, full width, equal height).
Parameter Description --------- ----------- ctx Application context
Image I/O
dvxLoadImage
uint8_t *dvxLoadImage(const AppContextT *ctx, const char *path, int32_t *outW, int32_t *outH, int32_t *outPitch);Load an image file (BMP, PNG, JPEG, GIF) and convert to the display's native pixel format. Caller must free with dvxFreeImage().
Parameter Description --------- ----------- ctx Application context path Image file path outW, outH Output: image dimensions outPitch Output: row pitch in bytes
Returns: Pixel buffer, or NULL on failure.
dvxLoadImageFromMemory
uint8_t *dvxLoadImageFromMemory(const AppContextT *ctx, const uint8_t *data, int32_t dataLen, int32_t *outW, int32_t *outH, int32_t *outPitch);Load an image from a memory buffer. Same output format as dvxLoadImage(). Caller must free with dvxFreeImage().
Parameter Description --------- ----------- ctx Application context data Image data buffer dataLen Buffer size in bytes outW, outH Output: image dimensions outPitch Output: row pitch in bytes
Returns: Pixel buffer, or NULL on failure.
dvxFreeImage
void dvxFreeImage(uint8_t *data);Free a pixel buffer returned by dvxLoadImage() or dvxLoadImageFromMemory().
Parameter Description --------- ----------- data Buffer to free
dvxImageInfo
bool dvxImageInfo(const char *path, int32_t *outW, int32_t *outH);Query image dimensions without decoding the full file.
Parameter Description --------- ----------- path Image file path outW, outH Output: image dimensions
Returns: true on success.
dvxSaveImage
int32_t dvxSaveImage(const AppContextT *ctx, const uint8_t *data, int32_t w, int32_t h, int32_t pitch, const char *path);Save native-format pixel data to a PNG file.
Parameter Description --------- ----------- ctx Application context data Pixel data in display native format w, h Image dimensions pitch Row pitch in bytes path Output file path
Returns: 0 on success, -1 on failure.
Screenshots
dvxScreenshot
int32_t dvxScreenshot(AppContextT *ctx, const char *path);Save the entire screen (backbuffer contents) to a PNG file. Converts from native pixel format to RGB.
Parameter Description --------- ----------- ctx Application context path Output PNG file path
Returns: 0 on success, -1 on failure.
dvxWindowScreenshot
int32_t dvxWindowScreenshot(AppContextT *ctx, WindowT *win, const char *path);Save a window's content to a PNG file.
Parameter Description --------- ----------- ctx Application context win Window path Output PNG file path
Returns: 0 on success, -1 on failure.
Clipboard
dvxClipboardCopy
void dvxClipboardCopy(const char *text, int32_t len);Copy text to the process-wide clipboard buffer. Simple static buffer (not inter-process).
Parameter Description --------- ----------- text Text to copy len Length in bytes
dvxClipboardGet
const char *dvxClipboardGet(int32_t *outLen);Retrieve the current clipboard contents. Returns a pointer to the internal buffer (valid until the next dvxClipboardCopy), or NULL if empty.
Parameter Description --------- ----------- outLen Output: length of clipboard text
Returns: Clipboard text, or NULL.
Resource Loading
dvxResLoadIcon
uint8_t *dvxResLoadIcon(AppContextT *ctx, const char *dxePath, const char *resName, int32_t *outW, int32_t *outH, int32_t *outPitch);Load an icon/image resource from a DXE file and decode to native pixel format. Caller must free with dvxFreeImage().
Parameter Description --------- ----------- ctx Application context dxePath Path to DXE file resName Resource name within the DXE outW, outH Output: image dimensions outPitch Output: row pitch
Returns: Pixel buffer, or NULL if not found.
dvxResLoadText
bool dvxResLoadText(const char *dxePath, const char *resName, char *buf, int32_t bufSize);Load a text resource from a DXE file into a caller-provided buffer. Null-terminated and truncated to fit bufSize.
Parameter Description --------- ----------- dxePath Path to DXE file resName Resource name buf Output buffer bufSize Buffer capacity
Returns: true on success.
dvxResLoadData
void *dvxResLoadData(const char *dxePath, const char *resName, uint32_t *outSize);Load a raw binary resource from a DXE file. Returns a malloc'd buffer that the caller must free.
Parameter Description --------- ----------- dxePath Path to DXE file resName Resource name outSize Output: data size in bytes
Returns: Data buffer, or NULL if not found.
Utilities
dvxTextHash
uint32_t dvxTextHash(const char *text);Compute a djb2-xor hash for cheap dirty detection. Compare at save time with the current hash to detect changes without a shadow copy. Not cryptographic.
Parameter Description --------- ----------- text Null-terminated string to hash
Returns: 32-bit hash value.
dvxWidget.h -- Widget System
dvxWidget.h -- Widget System
Retained-mode widget toolkit layered on the DVX window manager. Widgets form a tree (parent-child) rooted at a per-window VBox container. Layout is automatic: measure minimum sizes bottom-up, then allocate space top-down with flexbox-like weighted distribution. Widget types are registered dynamically at runtime via DXE plugins.
WidgetT Structure
Core widget structure. Generic across all widget types; type-specific data lives in the void *data pointer managed by each widget's DXE.
Field Description ----- ----------- int32_t type Widget type ID (assigned by wgtRegisterClass) const WidgetClassT *wclass Vtable for this widget type char name[MAX_WIDGET_NAME] Widget name for lookup via wgtFind parent, firstChild, lastChild, nextSibling Tree linkage pointers WindowT *window Owning window int32_t x, y, w, h Computed geometry (relative to content area) int32_t calcMinW, calcMinH Computed minimum size (from layout pass) int32_t minW, minH, maxW, maxH, prefW, prefH Size hints (tagged sizes) int32_t weight Extra-space distribution weight (0=fixed, 100=normal) WidgetAlignE align Main-axis alignment for children int32_t spacing, padding Tagged sizes for child spacing and padding uint32_t fgColor, bgColor Custom colors (0 = use scheme defaults) bool visible, enabled, readOnly State flags bool swallowTab Tab key goes to widget, not focus navigation 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)
Universal Callbacks:
Callback Description -------- ----------- onClick(WidgetT *w) Widget clicked onDblClick(WidgetT *w) Widget double-clicked onChange(WidgetT *w) Value changed onFocus(WidgetT *w) Widget gained focus onBlur(WidgetT *w) Widget lost focus onKeyPress(WidgetT *w, int32_t keyAscii) ASCII key press onKeyDown(WidgetT *w, int32_t keyCode, int32_t shift) Key down onKeyUp(WidgetT *w, int32_t keyCode, int32_t shift) Key up onMouseDown(WidgetT *w, int32_t 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
Size Specification Macros
Macro Description ----- ----------- wgtPixels(v) Size in pixels wgtChars(v) Size in character widths (multiplied by charWidth at layout) wgtPercent(v) Size as percentage of parent dimension
Widget Class Flags
Flag Description ---- ----------- WCLASS_FOCUSABLE Can receive keyboard focus (Tab navigation) WCLASS_HORIZ_CONTAINER Lays out children horizontally (vs. vertical) WCLASS_PAINTS_CHILDREN Widget handles child rendering itself WCLASS_NO_HIT_RECURSE Hit testing stops here, no child recursion WCLASS_FOCUS_FORWARD Accel hit forwards focus to next focusable sibling WCLASS_HAS_POPUP Has dropdown popup overlay WCLASS_SCROLLABLE Accepts mouse wheel events WCLASS_SCROLL_CONTAINER Scroll container (ScrollPane) WCLASS_NEEDS_POLL Needs periodic polling WCLASS_SWALLOWS_TAB Tab key goes to widget, not focus navigation WCLASS_RELAYOUT_ON_SCROLL Full relayout on scrollbar drag WCLASS_PRESS_RELEASE Click = press + release (Button, ImageButton) WCLASS_ACCEL_WHEN_HIDDEN Accelerator matching works even when invisible
Window Integration
wgtInitWindow
WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win);Initialize the widget system for a window. Creates a root VBox container that fills the content area, and installs callback handlers (onPaint, onMouse, onKey, onResize) for widget-based event dispatch. The window's userData is set to the AppContextT pointer.
Parameter Description --------- ----------- ctx Application context win Window to initialize
Returns: Root VBox widget (add children to this).
Widget Operations
wgtGetContext
AppContextT *wgtGetContext(const WidgetT *w);Walk from any widget up the tree to the root, then retrieve the AppContextT stored in the window's userData. Lets any widget access the full application context.
Parameter Description --------- ----------- w Any widget in the tree
Returns: Pointer to the AppContextT.
wgtInvalidate
void wgtInvalidate(WidgetT *w);Mark a widget as needing both re-layout (measure + position) and repaint. Propagates upward to ancestors. Use after structural changes (adding/removing children, text changes that affect size).
Parameter Description --------- ----------- w Widget to invalidate
wgtInvalidatePaint
void wgtInvalidatePaint(WidgetT *w);Mark a widget as needing repaint only, without re-layout. Use for visual-only changes (checkbox toggle, selection highlight, cursor blink).
Parameter Description --------- ----------- w Widget to repaint
wgtSetText
void wgtSetText(WidgetT *w, const char *text);Set widget text content (dispatches to the widget class's SET_TEXT handler).
Parameter Description --------- ----------- w Widget text New text
wgtGetText
const char *wgtGetText(const WidgetT *w);Get the widget's current text content.
Parameter Description --------- ----------- w Widget
Returns: Text string (empty string if no handler).
wgtSetEnabled
void wgtSetEnabled(WidgetT *w, bool enabled);Enable or disable a widget. Disabled widgets are grayed out and do not receive input.
Parameter Description --------- ----------- w Widget enabled true = enabled, false = disabled
wgtSetReadOnly
void wgtSetReadOnly(WidgetT *w, bool readOnly);Set read-only mode. Allows scrolling and selection but blocks editing.
Parameter Description --------- ----------- w Widget readOnly true = read-only
wgtSetFocused
void wgtSetFocused(WidgetT *w);Set keyboard focus to a widget.
Parameter Description --------- ----------- w Widget to focus
wgtGetFocused
WidgetT *wgtGetFocused(void);Get the currently focused widget.
Returns: Focused widget, or NULL.
wgtSetVisible
void wgtSetVisible(WidgetT *w, bool visible);Show or hide a widget.
Parameter Description --------- ----------- w Widget visible true = visible, false = hidden
wgtSetName
void wgtSetName(WidgetT *w, const char *name);Set a widget's name for lookup via wgtFind().
Parameter Description --------- ----------- w Widget name Name string (max MAX_WIDGET_NAME chars)
wgtFind
WidgetT *wgtFind(WidgetT *root, const char *name);Find a widget by name. Searches the subtree rooted at root.
Parameter Description --------- ----------- root Root of subtree to search name Widget name to find
Returns: Matching widget, or NULL.
wgtDestroy
void wgtDestroy(WidgetT *w);Destroy a widget and all its children. Removes from parent's child list.
Parameter Description --------- ----------- w Widget to destroy
wgtSetTooltip
void wgtSetTooltip(WidgetT *w, const char *text);Set tooltip text for a widget. Pass NULL to remove. Caller owns the string and it must outlive the widget.
Parameter Description --------- ----------- w Widget text Tooltip text, or NULL
widgetOnResize
void widgetOnResize(WindowT *win, int32_t newW, int32_t newH);Default window resize handler installed by wgtInitWindow(). Re-evaluates scrollbars and relayouts the widget tree. Call from custom onResize handlers to chain to the widget system.
Parameter Description --------- ----------- win Window being resized newW, newH New content dimensions
Layout
wgtResolveSize
int32_t wgtResolveSize(int32_t taggedSize, int32_t parentSize, int32_t charWidth);Decode a tagged size value (WGT_SIZE_PIXELS/CHARS/PERCENT) into a concrete pixel count. Returns 0 for a raw 0 input (meaning "auto").
Parameter Description --------- ----------- taggedSize Tagged size value parentSize Parent dimension (for PERCENT mode) charWidth Font character width (for CHARS mode)
Returns: Size in pixels.
wgtLayout
void wgtLayout(WidgetT *root, int32_t availW, int32_t availH, const BitmapFontT *font);Execute the full two-pass layout algorithm. Pass 1 (bottom-up): compute minimum sizes. Pass 2 (top-down): allocate space with weighted distribution. Normally called automatically; exposed for cases where layout must be forced before the next paint.
Parameter Description --------- ----------- root Root widget availW/H Available space font Bitmap font (for character-based sizing)
wgtPaint
void wgtPaint(WidgetT *root, DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors);Paint the entire widget tree by depth-first traversal. Each widget's clip rect is set to its bounds. Overlays (popups, tooltips) are painted in a second pass on top.
Parameter Description --------- ----------- root Root widget d Display context ops Blit operations vtable font Bitmap font colors Color scheme
Debug
wgtSetDebugLayout
void wgtSetDebugLayout(AppContextT *ctx, bool enabled);Draw colored borders around layout containers for debugging.
Parameter Description --------- ----------- ctx Application context enabled true = draw debug borders
Dynamic Widget Registration
wgtRegisterClass
int32_t wgtRegisterClass(const WidgetClassT *wclass);Register a new widget class at runtime. Appends to widgetClassTable. The WidgetClassT must remain valid for the lifetime of the process (typically static const in a DXE).
Parameter Description --------- ----------- wclass Widget class vtable to register
Returns: Assigned type ID.
wgtRegisterApi
void wgtRegisterApi(const char *name, const void *api);Register a widget API struct under a name. Each widget DXE registers its API during initialization. Callers retrieve it via wgtGetApi() and cast to the widget-specific type.
Parameter Description --------- ----------- name Widget type name (e.g. "button", "listbox") api Pointer to the widget's API struct
wgtGetApi
const void *wgtGetApi(const char *name);Retrieve a registered widget API struct by name.
Parameter Description --------- ----------- name Widget type name
Returns: Pointer to the API struct, or NULL if not found.
Widget Interface Descriptors
wgtRegisterIface
void wgtRegisterIface(const char *name, const WgtIfaceT *iface);Register an interface descriptor for a widget type. Used by the BASIC form runtime and IDE for generic property/method dispatch.
Parameter Description --------- ----------- name Widget type name iface Interface descriptor
wgtGetIface
const WgtIfaceT *wgtGetIface(const char *name);Retrieve an interface descriptor by widget type name.
Parameter Description --------- ----------- name Widget type name
Returns: Interface descriptor, or NULL.
wgtFindByBasName
const char *wgtFindByBasName(const char *basName);Find a widget type name by its VB-style name (e.g. "CommandButton" -> "button"). Case-insensitive search.
Parameter Description --------- ----------- basName VB-style widget name
Returns: Internal type name, or NULL.
wgtIfaceCount
int32_t wgtIfaceCount(void);Return the number of registered widget interfaces.
Returns: Count of registered interfaces.
wgtIfaceAt
const WgtIfaceT *wgtIfaceAt(int32_t idx, const char **outName);Get a registered widget interface by index.
Parameter Description --------- ----------- idx Index (0-based) outName Output: type name
Returns: Interface descriptor.
wgtIfaceGetPath
const char *wgtIfaceGetPath(const char *name);Get the .wgt DXE file path for a registered widget.
Parameter Description --------- ----------- name Widget type name
Returns: File path string.
wgtIfaceSetPath
void wgtIfaceSetPath(const char *name, const char *path);Set the .wgt DXE file path for a registered widget (called by the loader).
Parameter Description --------- ----------- name Widget type name path DXE file path
wgtIfaceGetPathIndex
int32_t wgtIfaceGetPathIndex(const char *name);Get the 1-based index of this widget within its .wgt file. Used to construct suffixed resource names (e.g. "name-2", "icon16-2").
Parameter Description --------- ----------- name Widget type name
Returns: 1-based index within the DXE file.
Typed Dispatch Helpers
The following inline functions provide type-safe dispatch through the WidgetClassT handler table. Each checks for a non-NULL handler before calling.
Function Method ID Description -------- --------- ----------- wclsHas(w, methodId) -- Check if handler exists wclsPaint(w, d, ops, font, colors) WGT_METHOD_PAINT Paint the widget wclsPaintOverlay(w, d, ops, font, colors) WGT_METHOD_PAINT_OVERLAY Paint overlay (popups) wclsCalcMinSize(w, font) WGT_METHOD_CALC_MIN_SIZE Compute minimum size wclsLayout(w, font) WGT_METHOD_LAYOUT Layout children wclsGetLayoutMetrics(w, font, ...) WGT_METHOD_GET_LAYOUT_METRICS Get pad, gap, extraTop, borderW wclsOnMouse(w, root, vx, vy) WGT_METHOD_ON_MOUSE Handle mouse event wclsOnKey(w, key, mod) WGT_METHOD_ON_KEY Handle key event wclsOnAccelActivate(w, root) WGT_METHOD_ON_ACCEL_ACTIVATE Handle accelerator wclsDestroy(w) WGT_METHOD_DESTROY Destroy widget data wclsOnChildChanged(parent, child) WGT_METHOD_ON_CHILD_CHANGED Notify parent of change wclsGetText(w) WGT_METHOD_GET_TEXT Get widget text wclsSetText(w, text) WGT_METHOD_SET_TEXT Set widget text wclsClearSelection(w) WGT_METHOD_CLEAR_SELECTION Clear text selection wclsClosePopup(w) WGT_METHOD_CLOSE_POPUP Close dropdown popup wclsGetPopupRect(w, font, ...) WGT_METHOD_GET_POPUP_RECT Get popup screen rect wclsOnDragUpdate(w, root, x, y) WGT_METHOD_ON_DRAG_UPDATE Update during drag wclsOnDragEnd(w, root, x, y) WGT_METHOD_ON_DRAG_END End drag operation wclsGetCursorShape(w, vx, vy) WGT_METHOD_GET_CURSOR_SHAPE Get cursor for position wclsPoll(w, win) WGT_METHOD_POLL Periodic polling wclsQuickRepaint(w, outY, outH) WGT_METHOD_QUICK_REPAINT Fast partial repaint wclsScrollChildIntoView(parent, child) WGT_METHOD_SCROLL_CHILD_INTO_VIEW Scroll child visible