# The MIT License (MIT) # # Copyright (C) 2026 Scott Duensing # # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to # deal in the Software without restriction, including without limitation the # rights to use, copy, modify, merge, publish, distribute, sublicense, and/or # sell copies of the Software, and to permit persons to whom the Software is # furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included in # all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS # IN THE SOFTWARE. .section Architecture .topic api.overview .title DVX GUI API Reference .toc 0 DVX GUI API Reference .default .index DVX API .index API Reference .h1 DVX GUI API Reference DOS Visual eXecutive -- Complete public API documentation covering every public function, type, and constant in the libdvx headers. The DVX GUI is built as a five-layer architecture. Each layer is defined in its own header file. Additional headers cover dialogs, resources, preferences, memory tracking, the platform abstraction, and the widget system. .h2 Headers .list .item dvxTypes.h -- Shared type definitions and constants .item dvxCur.h -- Embedded mouse cursor bitmaps .item dvxFont.h -- Embedded 8x16 CP437 bitmap font .item dvxPal.h -- 8-bit mode 256-color palette .item dvxVideo.h -- Layer 1: VESA VBE video backend .item dvxDraw.h -- Layer 2: 2D drawing primitives .item dvxComp.h -- Layer 3: Dirty rectangle compositor .item dvxWm.h -- Layer 4: Window manager .item dvxApp.h -- Layer 5: Application API .item dvxDlg.h -- Modal dialog boxes .item dvxRes.h -- DXE-embedded resource system .item dvxPrefs.h -- INI preferences system .item dvxMem.h -- Per-app memory tracking .item dvxWgt.h -- Widget system public API .item dvxWgtP.h -- Widget plugin API .item platform/dvxPlat.h -- Platform abstraction layer .endlist .link api.types dvxTypes.h -- Shared Type Definitions .link api.cursor dvxCur.h -- Cursor Definitions .link api.font dvxFont.h -- Bitmap Font Data .link api.palette dvxPal.h -- 8-bit Palette .link api.video dvxVideo.h -- Layer 1: Video Backend .link api.draw dvxDraw.h -- Layer 2: Drawing Primitives .link api.comp dvxComp.h -- Layer 3: Compositor .link api.wm dvxWm.h -- Layer 4: Window Manager .link api.app dvxApp.h -- Layer 5: Application API .link api.dialog dvxDlg.h -- Modal Dialogs .link api.resource dvxRes.h -- Resource System .link api.prefs dvxPrefs.h -- Preferences .link api.mem dvxMem.h -- Memory Tracking .link api.widget dvxWgt.h -- Widget System .link api.widgetplugin dvxWgtP.h -- Widget Plugin API .link api.platform platform/dvxPlat.h -- Platform Layer .topic api.types .title dvxTypes.h -- Shared Type Definitions .toc 1 dvxTypes.h -- Shared Type Definitions .index dvxTypes.h .index PixelFormatT .index DisplayT .index RectT .index BlitOpsT .index BevelStyleT .index BitmapFontT .index ColorSchemeT .index ColorIdE .index DirtyListT .index WindowT .index WindowStackT .index MenuT .index MenuItemT .index MenuBarT .index ScrollbarT .index AccelTableT .index AccelEntryT .index VideoModeInfoT .index CursorT .h1 dvxTypes.h -- Shared Type Definitions Central type definitions shared across all five layers of the DVX GUI stack. Every header includes this file. Contains no function definitions -- only structs, enums, typedefs, and compile-time constants. .h2 Core Structures .h3 PixelFormatT Describes the pixel encoding for the active VESA video mode. Populated once at startup from the VBE mode info block, then treated as read-only. .table Field Description ----- ----------- int32_t bitsPerPixel 8, 15, 16, or 32 int32_t bytesPerPixel 1, 2, 2, or 4 uint32_t redMask, greenMask, blueMask Bitmasks for each color channel int32_t redShift, greenShift, blueShift Bit position of each color field int32_t redBits, greenBits, blueBits Number of bits per channel .endtable .h3 DisplayT Single display context passed by pointer through every layer. All drawing targets the backBuf; only dirty rects are flushed to lfb. .table Field Description ----- ----------- int32_t width, height Screen dimensions in pixels int32_t pitch Bytes per scanline PixelFormatT format Active pixel format uint8_t *lfb Mapped linear framebuffer (VESA LFB) uint8_t *backBuf System RAM backbuffer uint8_t *palette 768 bytes for 8-bit mode, NULL otherwise int32_t clipX, clipY, clipW, clipH Current clip rectangle .endtable .h3 RectT Rectangle in origin + extent form. Used throughout the compositor, window manager, and widget layout engine. .table Field Description ----- ----------- int32_t x, y Top-left corner int32_t w, h Width and height .endtable .h3 BlitOpsT Vtable for hot-path span operations. Resolved at init time based on pixel depth. On DOS, these dispatch to hand-written asm (rep stosl / rep movsd). .table Field Description ----- ----------- SpanFillFnT spanFill Fill a horizontal span with a solid color SpanCopyFnT spanCopy Copy a horizontal span between buffers int32_t bytesPerPixel Bytes per pixel for the active mode int32_t pitch Bytes per scanline .endtable .h3 BevelStyleT Bevel drawing parameters. Swapping highlight/shadow flips raised vs. sunken appearance. .table Field Description ----- ----------- uint32_t highlight Lighter color (top/left edges) uint32_t shadow Darker color (bottom/right edges) uint32_t face Interior fill color (0 = no fill) int32_t width Border thickness in pixels (typically 2) .endtable .h3 BitmapFontT Fixed-width 8-pixel-wide bitmap font descriptor. One size provided: 8x16 (standard VGA ROM font, CP437 encoding). .table Field Description ----- ----------- int32_t charWidth Fixed width per glyph (always 8) int32_t charHeight Glyph height (16 in the bundled font) int32_t firstChar ASCII code of first glyph (typically 0) int32_t numChars Number of glyphs (typically 256) const uint8_t *glyphData Packed 1bpp data, charHeight bytes per glyph .endtable .h3 ColorSchemeT All UI colors pre-packed into display pixel format at init time. Theme support is achieved by swapping this struct. .table Field Description ----- ----------- uint32_t desktop Desktop background color uint32_t windowFace Window body / chrome face uint32_t windowHighlight Bevel highlight (top/left edge) uint32_t windowShadow Bevel shadow (bottom/right edge) uint32_t activeTitleBg, activeTitleFg Focused window title bar uint32_t inactiveTitleBg, inactiveTitleFg Unfocused window title bar uint32_t contentBg, contentFg Window content area default colors uint32_t menuBg, menuFg Menu bar and popup background/text uint32_t menuHighlightBg, menuHighlightFg Menu item highlight uint32_t buttonFace Button face color uint32_t scrollbarBg, scrollbarFg, scrollbarTrough Scrollbar element colors uint32_t cursorFg, cursorBg Mouse cursor colors .endtable .h3 ColorIdE Enum for addressing individual colors in ColorSchemeT. Order matches struct field order. Values: ColorDesktopE, ColorWindowFaceE, ColorWindowHighlightE, ColorWindowShadowE, ColorActiveTitleBgE, ColorActiveTitleFgE, ColorInactiveTitleBgE, ColorInactiveTitleFgE, ColorContentBgE, ColorContentFgE, ColorMenuBgE, ColorMenuFgE, ColorMenuHighlightBgE, ColorMenuHighlightFgE, ColorButtonFaceE, ColorScrollbarBgE, ColorScrollbarFgE, ColorScrollbarTroughE, ColorCursorFgE, ColorCursorBgE, ColorCountE. .h3 DirtyListT Fixed-capacity list of dirty rectangles. Dynamic array, grows on demand. .table Field Description ----- ----------- RectT *rects Dynamic array of dirty rectangles int32_t count Current number of dirty rects int32_t cap Allocated capacity .endtable .h3 WindowT Central window object. Each window owns a persistent content backbuffer and receives events through callback function pointers. .table Field Description ----- ----------- int32_t id Unique window identifier int32_t appId Shell app ID (0 = shell itself) int32_t x, y, w, h Outer frame position and dimensions int32_t contentX, contentY, contentW, contentH Content area inset from frame char title[MAX_TITLE_LEN] Window title text (max 128 chars) bool visible, focused, minimized, maximized, resizable, modal Window state flags bool iconNeedsRefresh true when contentBuf changed (for minimized icon refresh) uint8_t paintNeeded PAINT_NONE / PAINT_PARTIAL / PAINT_FULL int32_t maxW, maxH Maximum dimensions int32_t preMaxX, preMaxY, preMaxW, preMaxH Saved geometry before maximize uint8_t *contentBuf Per-window content backbuffer int32_t contentPitch Content buffer bytes per row uint8_t *iconData Icon pixel data, NULL if none int32_t iconW, iconH, iconPitch Icon image dimensions and pitch MenuBarT *menuBar Menu bar (NULL if no menus) ScrollbarT *vScroll, *hScroll Scrollbars (NULL if not present) struct WidgetT *widgetRoot Widget tree root (NULL if none) MenuT *contextMenu Right-click context menu AccelTableT *accelTable Keyboard accelerator table void *userData Application-defined data pointer .endtable Callbacks: .table Callback Description -------- ----------- onPaint(WindowT *win, RectT *dirtyArea) Content repaint requested onKey(WindowT *win, int32_t key, int32_t mod) Key press onKeyUp(WindowT *win, int32_t scancode, int32_t mod) Key release onMouse(WindowT *win, int32_t x, int32_t y, int32_t buttons) Mouse event (content-relative) onResize(WindowT *win, int32_t newW, int32_t newH) Window resized onClose(WindowT *win) Close requested onMenu(WindowT *win, int32_t menuId) Menu item or accelerator activated onScroll(WindowT *win, ScrollbarOrientE orient, int32_t value) Scrollbar value changed int32_t onCursorQuery(WindowT *win, int32_t x, int32_t y) Return CURSOR_* for hit position onFocus(WindowT *win) Window gained focus onBlur(WindowT *win) Window lost focus .endtable .h3 WindowStackT Z-ordered window stack (front-to-back: index count-1 is topmost). Owns system-wide drag/resize/scroll interaction state. .table Field Description ----- ----------- WindowT **windows Dynamic array of window pointers int32_t count, cap Current count and allocated capacity int32_t focusedIdx Stack index of focused window int32_t dragWindow, dragOffX, dragOffY Active drag state int32_t dragStartX, dragStartY Mouse position at drag begin (for deadzone) bool dragActive True once mouse moved past deadzone int32_t resizeWindow, resizeEdge Active resize state int32_t scrollWindow, scrollOrient, scrollDragOff Active scroll drag state .endtable .h3 MenuT / MenuItemT / MenuBarT Menu system types. Fixed-size label buffers (MAX_MENU_LABEL = 32). Cascading submenus supported via MenuItemT.subMenu pointer. .table Field Description ----- ----------- MenuItemT.label Item text (supports & accelerator markers) MenuItemT.id Application-defined command ID MenuItemT.type MenuItemNormalE, MenuItemCheckE, or MenuItemRadioE MenuItemT.separator true = horizontal divider line MenuItemT.enabled, checked Item state MenuItemT.accelKey Lowercase accelerator character (0 = none) MenuItemT.subMenu Child menu for cascading (NULL if leaf) MenuT.label Menu bar label (e.g. "File") MenuT.items Dynamic array of MenuItemT MenuT.itemCount, itemCap Current count and allocated capacity MenuT.barX, barW Computed position/width on the menu bar MenuT.accelKey Lowercase accelerator character (0 = none) MenuBarT.menus Dynamic array of MenuT MenuBarT.menuCount, menuCap Current count and allocated capacity MenuBarT.activeIdx Open popup index (-1 = none) MenuBarT.positionsDirty True when barX/barW need recomputation .endtable .h3 ScrollbarT Window-level scrollbar state. Managed by the WM layer, drawn after content. .table Field Description ----- ----------- ScrollbarOrientE orient ScrollbarVerticalE or ScrollbarHorizontalE int32_t min, max Scroll range int32_t value Current position int32_t pageSize Visible portion (for proportional thumb sizing) int32_t x, y, length Computed screen position and track length .endtable .h3 AccelTableT / AccelEntryT Per-window keyboard accelerator table. Entries are matched against keystrokes in the event loop and fire onMenu(cmdId) on match. .table Field Description ----- ----------- AccelEntryT.key ASCII character or KEY_Fxx constant AccelEntryT.modifiers Bitmask of ACCEL_CTRL, ACCEL_SHIFT, ACCEL_ALT AccelEntryT.cmdId Command ID passed to onMenu AccelEntryT.normKey Pre-normalized key (uppercased) for fast matching AccelEntryT.normMods Pre-masked modifiers (CTRL|ALT only) for fast matching AccelTableT.entries Dynamic array of AccelEntryT AccelTableT.count, cap Current count and allocated capacity .endtable .h3 VideoModeInfoT Describes an available video mode (enumerated at init). .table Field Description ----- ----------- int32_t w, h Resolution int32_t bpp Bits per pixel .endtable .h3 CursorT Software-rendered 16x16 cursor using AND/XOR mask encoding. .table Field Description ----- ----------- int32_t width, height Cursor dimensions (always 16x16) int32_t hotX, hotY Hot spot coordinates const uint16_t *andMask AND mask (0 = draw pixel, 1 = transparent) const uint16_t *xorData XOR data (0 = black, 1 = white where AND = 0) .endtable .h2 Bevel Convenience Macros .table Macro Description ----- ----------- BEVEL_RAISED(cs, bw) Raised bevel style from ColorSchemeT ptr and border width BEVEL_SUNKEN(cs, face, bw) Sunken bevel style with explicit face color BEVEL_TROUGH(cs) 1px sunken trough (for scrollbar tracks) BEVEL_SB_BUTTON(cs) 1px raised scrollbar button .endtable .h2 Chrome Constants .table Define Value Description ------ ----- ----------- CHROME_BORDER_WIDTH 4 Outer frame border width CHROME_TITLE_HEIGHT 20 Title bar height CHROME_TITLE_PAD 4 Title text padding CHROME_INNER_BORDER 2 Inner chrome border CHROME_MENU_HEIGHT 20 Menu bar height CHROME_TOTAL_TOP 26 Total inset from top of frame to content CHROME_TOTAL_SIDE 6 Total inset from side of frame to content CHROME_TOTAL_BOTTOM 6 Total inset from bottom of frame to content .endtable .h2 Hit Test Constants .table Define Value Description ------ ----- ----------- HIT_CONTENT 0 Content area HIT_TITLE 1 Title bar HIT_CLOSE 2 Close gadget HIT_RESIZE 3 Resize border HIT_MENU 4 Menu bar HIT_VSCROLL 5 Vertical scrollbar HIT_HSCROLL 6 Horizontal scrollbar HIT_MINIMIZE 7 Minimize gadget HIT_MAXIMIZE 8 Maximize gadget HIT_NONE -1 No window hit (desktop) .endtable .h2 Mouse Button Flags .table Define Value Description ------ ----- ----------- MOUSE_LEFT 1 Left mouse button MOUSE_RIGHT 2 Right mouse button MOUSE_MIDDLE 4 Middle mouse button .endtable .h2 Accelerator Modifier Flags .table Define Value Description ------ ----- ----------- ACCEL_SHIFT 0x03 Shift key (matches BIOS shift state bits) ACCEL_CTRL 0x04 Ctrl key ACCEL_ALT 0x08 Alt key .endtable .h2 Extended Key Codes .table Define Description ------ ----------- KEY_F1 .. KEY_F12 Function keys (scancode | 0x100) KEY_INSERT Insert key KEY_DELETE Delete key KEY_HOME Home key KEY_END End key KEY_PGUP Page Up key KEY_PGDN Page Down key .endtable .h2 Resize Edge Flags .table Define Value Description ------ ----- ----------- RESIZE_NONE 0 No resize edge RESIZE_LEFT 1 Left edge RESIZE_RIGHT 2 Right edge RESIZE_TOP 4 Top edge RESIZE_BOTTOM 8 Bottom edge (combinable via OR for corners) .endtable .h2 Utility Macros .table Macro Description ----- ----------- DVX_MIN(a, b) Return the smaller of two values DVX_MAX(a, b) Return the larger of two values .endtable .topic api.cursor .title dvxCur.h -- Cursor Definitions .toc 1 dvxCur.h -- Cursor Definitions .index dvxCur.h .index Cursor Shapes .index CURSOR_ARROW .index CURSOR_BUSY .h1 dvxCur.h -- Cursor Definitions Embedded 16x16 mouse cursor bitmaps compiled as static const data. No external cursor files. Uses the standard AND/XOR mask encoding from the IBM VGA hardware cursor spec. The AND mask selects transparency (1 = transparent, 0 = opaque) and the XOR data selects black vs. white for opaque pixels. .h2 Cursor Shape IDs .table Define Value Description ------ ----- ----------- CURSOR_ARROW 0 Standard arrow (hot spot at tip) CURSOR_RESIZE_H 1 Horizontal resize (left/right arrows) CURSOR_RESIZE_V 2 Vertical resize (up/down arrows) CURSOR_RESIZE_DIAG_NWSE 3 NW-SE diagonal resize CURSOR_RESIZE_DIAG_NESW 4 NE-SW diagonal resize CURSOR_BUSY 5 Hourglass (wait) CURSOR_CROSSHAIR 6 Crosshair for placement CURSOR_COUNT 7 Total number of cursor shapes .endtable .h2 Data .h3 dvxCursors[CURSOR_COUNT] Static const array of CursorT structs, indexed by CURSOR_xxx constants. Each entry includes the AND mask, XOR data (both as 16-element uint16_t arrays), dimensions (16x16), and hot spot coordinates. .h3 dvxCursor Legacy alias for backward compatibility with code that predates multi-cursor support. Equivalent to dvxCursors[CURSOR_ARROW]. .topic api.font .title dvxFont.h -- Bitmap Font Data .toc 1 dvxFont.h -- Bitmap Font Data .index dvxFont.h .index Font .index CP437 .index BitmapFontT .h1 dvxFont.h -- Embedded Bitmap Font Data Raw glyph bitmaps for the standard 8x16 VGA ROM font covering the full IBM Code Page 437 character set (256 glyphs). Compiled in as a static const array, avoiding a real-mode INT 10h call at startup. Glyph format: 1 bit per pixel, 8 pixels wide, MSB = leftmost pixel. Each glyph occupies 16 consecutive bytes (one byte per scanline). The 8-pixel width means per-scanline rendering never needs bit shifting across byte boundaries. CP437 covers: .list .item 0-31 -- Smiley, card suits, arrows, notes (classic extended ASCII glyphs) .item 32-126 -- Printable ASCII .item 127 -- House glyph .item 128-175 -- Accented Latin letters, currency, fractions .item 176-223 -- Box-drawing characters (essential for chrome gadgets) .item 224-254 -- Greek letters, math symbols, super/subscripts .item 255 -- Non-breaking space .endlist .h2 Data .h3 font8x16 Static const uint8_t array of 256 * 16 = 4096 bytes containing the packed 1bpp glyph bitmaps, in ASCII code order. .h3 dvxFont8x16 Static const BitmapFontT struct describing the 8x16 font, ready to pass to drawText/drawTextN/drawChar. Use this as the default font for all text rendering. .h2 Constants .table Define Value Description ------ ----- ----------- FONT_CHAR_WIDTH 8 Fixed glyph width in pixels (defined in dvxTypes.h) .endtable .topic api.palette .title dvxPal.h -- 8-bit Palette .toc 1 dvxPal.h -- 8-bit Palette .index dvxPal.h .index Palette .index 8-bit mode .h1 dvxPal.h -- 256-Color Palette for 8-bit Mode Defines the 256-color VGA/VESA palette used in 8-bit video modes. Layout: .table Range Purpose ----- ------- 0-215 6x6x6 color cube -- uniformly distributed RGB (6 levels per channel: 0, 51, 102, 153, 204, 255). Index = r*36 + g*6 + b. 216-231 16-step grey ramp for smooth gradients 232-239 Dedicated UI chrome colors (highlight, shadow, title bar, desktop) 240-255 Reserved (black) .endtable The cube layout enables O(1) color lookup: snapping an RGB triplet to the nearest cube vertex is integer division by 51. The grey ramp and chrome slots hold colors that need exact values not available in the cube. .h2 Chrome Color Indices .table Define Value Description ------ ----- ----------- PAL_CHROME_HIGHLIGHT 232 White (bevel highlight) PAL_CHROME_SHADOW 233 Dark grey (bevel shadow) PAL_CHROME_ACTIVE_BG 234 Navy (focused title bar) PAL_CHROME_INACTIVE_BG 235 Grey (unfocused title bar) PAL_CHROME_DESKTOP 236 Steel blue (desktop) PAL_CHROME_SELECTION 237 Navy (selection highlight) PAL_CHROME_TEXT 238 Black (text) PAL_CHROME_WHITE 239 Bright white .endtable .h2 Inline Functions .h3 dvxGeneratePalette .code static inline void dvxGeneratePalette(uint8_t *pal); .endcode Populate a 768-byte (256 * 3) RGB buffer with the default DVX 8-bit palette. Called once at init in 8-bit mode to program the DAC. .table Parameter Description --------- ----------- pal Output RGB buffer (768 bytes) .endtable .h3 dvxNearestPalEntry .code static inline uint8_t dvxNearestPalEntry(const uint8_t *pal, uint8_t r, uint8_t g, uint8_t b); .endcode Find the nearest palette entry for an RGB color using minimum Euclidean distance. Two-phase: snap to color cube vertex (O(1)), then scan grey ramp and chrome entries (216-239) for a closer match. Called by packColor() in 8-bit mode. .table Parameter Description --------- ----------- pal Active 768-byte RGB palette r, g, b Color components (0-255) .endtable Returns: Palette index (0-239) of the nearest match. .topic api.video .title dvxVideo.h -- Layer 1: VESA VBE Video Backend .toc 1 dvxVideo.h -- Layer 1: Video Backend .index dvxVideo.h .index videoInit .index videoShutdown .index packColor .index setClipRect .index resetClipRect .index VESA .index LFB .h1 dvxVideo.h -- Layer 1: VESA VBE Video Backend The lowest layer. Responsible for VESA VBE mode negotiation, LFB mapping via DPMI, system RAM backbuffer allocation, pixel format discovery, and color packing. LFB-only design: bank switching is deliberately unsupported. .h2 videoInit .code int32_t videoInit(DisplayT *d, int32_t requestedW, int32_t requestedH, int32_t preferredBpp); .endcode Probe VBE for a mode matching the requested resolution and depth, enable it, map the LFB into DPMI linear address space, and allocate a system RAM backbuffer. preferredBpp is a hint; the closest available depth is used if an exact match is not found. .table Parameter Description --------- ----------- d Display context to initialize requestedW/H Desired screen resolution preferredBpp Preferred bits per pixel (8, 15, 16, or 32) .endtable Returns: 0 on success, negative on failure. .h2 videoShutdown .code void videoShutdown(DisplayT *d); .endcode Restore VGA text mode (mode 3), unmap the LFB, and free the backbuffer. Safe to call even if videoInit() failed. .table Parameter Description --------- ----------- d Display context to shut down .endtable .h2 packColor .code uint32_t packColor(const DisplayT *d, uint8_t r, uint8_t g, uint8_t b); .endcode Pack an RGB triplet into the display's native pixel format. For direct-color modes (15/16/32 bpp), returns a packed pixel value using shift/mask fields. For 8-bit mode, returns the nearest palette index via Euclidean distance in RGB space. .table Parameter Description --------- ----------- d Display context (provides pixel format) r, g, b Color components (0-255) .endtable Returns: Native pixel value suitable for direct framebuffer write. .h2 unpackColor .code void unpackColor(const DisplayT *d, uint32_t color, uint8_t *r, uint8_t *g, uint8_t *b); .endcode Reverse of packColor -- decode a native pixel value to 8-bit RGB components. For direct-color modes, reverses the shift/mask arithmetic. For 8-bit mode, looks up the palette entry at the given index. .table Parameter Description --------- ----------- d Display context color Packed native pixel value r, g, b Output: color components (0-255) .endtable .h2 setClipRect .code void setClipRect(DisplayT *d, int32_t x, int32_t y, int32_t w, int32_t h); .endcode Set the clip rectangle on the display. All subsequent draw operations clip to this rectangle. The caller must save and restore the clip rect around scoped operations. .table Parameter Description --------- ----------- d Display context x, y, w, h Clip rectangle in screen coordinates .endtable .h2 resetClipRect .code void resetClipRect(DisplayT *d); .endcode Reset the clip rectangle to the full display dimensions. .table Parameter Description --------- ----------- d Display context .endtable .topic api.draw .title dvxDraw.h -- Layer 2: Drawing Primitives .toc 1 dvxDraw.h -- Layer 2: Drawing Primitives .index dvxDraw.h .index drawInit .index rectFill .index rectCopy .index rectCopyGrayscale .index drawBevel .index drawChar .index drawText .index drawTextN .index textWidth .index accelParse .index drawTextAccel .index textWidthAccel .index drawMaskedBitmap .index drawTermRow .index drawFocusRect .index drawHLine .index drawVLine .h1 dvxDraw.h -- Layer 2: Drawing Primitives All 2D drawing operations: rectangle fills, bitmap blits, text rendering, bevels, lines, and cursor rendering. Every function draws into the display's backbuffer and clips to the current clip rectangle. This layer is stateless beyond the clip rect on DisplayT. .h2 drawInit .code void drawInit(BlitOpsT *ops, const DisplayT *d); .endcode Populate a BlitOpsT with the correct span functions for the display's pixel depth. Must be called once after videoInit(). .table Parameter Description --------- ----------- ops BlitOpsT to populate d Initialized display context .endtable .h2 rectFill .code void rectFill(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color); .endcode Fill a rectangle with a solid color. Clips to the display clip rect. Workhorse for backgrounds, window fills, and clear operations. .table Parameter Description --------- ----------- d Display context ops Blit operations vtable x, y, w, h Rectangle to fill color Packed pixel color .endtable .h2 rectCopy .code void rectCopy(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h); .endcode Copy a rectangle from an arbitrary source buffer into the backbuffer. Used to blit per-window content buffers during compositing. .table Parameter Description --------- ----------- d Display context ops Blit operations vtable dstX, dstY Destination position in backbuffer srcBuf Source pixel buffer srcPitch Source buffer bytes per row srcX, srcY Origin within source buffer w, h Rectangle dimensions to copy .endtable .h2 rectCopyGrayscale .code void rectCopyGrayscale(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h); .endcode Copy a rectangle with grayscale conversion. Each pixel's RGB is converted to luminance (0.299R + 0.587G + 0.114B) for a disabled/grayed appearance. .table Parameter Description --------- ----------- d Display context ops Blit operations vtable dstX, dstY Destination position srcBuf, srcPitch Source buffer and pitch srcX, srcY Source origin w, h Rectangle dimensions .endtable .h2 rectCopyTransparent .code void rectCopyTransparent(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h, uint32_t keyColor); .endcode Copy with color-key transparency. Pixels matching keyColor are skipped, letting the destination show through. Used to draw image buttons and icons with transparent backgrounds. .table Parameter Description --------- ----------- d Display context ops Blit operations vtable dstX, dstY Destination position srcBuf, srcPitch Source buffer and pitch srcX, srcY Source origin w, h Rectangle dimensions keyColor Packed color treated as transparent .endtable .h2 drawBevel .code void drawBevel(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const BevelStyleT *style); .endcode Draw a beveled frame. Top/left edges in highlight color, bottom/right in shadow. Interior filled with face color if non-zero. .table Parameter Description --------- ----------- d Display context ops Blit operations vtable x, y, w, h Outer bevel rectangle style Bevel colors and width .endtable .h2 drawChar .code int32_t drawChar(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, char ch, uint32_t fg, uint32_t bg, bool opaque); .endcode Draw a single character glyph. When opaque is true, the background fills the entire cell; when false, only foreground pixels are drawn (transparent background). .table Parameter Description --------- ----------- d Display context ops Blit operations vtable font Bitmap font x, y Character position ch Character to draw fg, bg Foreground and background packed colors opaque true = fill background, false = transparent .endtable Returns: Advance width (always charWidth). .h2 drawText .code void drawText(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque); .endcode Draw a null-terminated string. Calls drawChar per character. .table Parameter Description --------- ----------- d Display context ops Blit operations vtable font Bitmap font x, y Start position text Null-terminated string fg, bg Foreground and background packed colors opaque true = fill background, false = transparent .endtable .h2 drawTextN .code void drawTextN(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, int32_t count, uint32_t fg, uint32_t bg, bool opaque); .endcode Optimized batch text rendering for a known character count. Computes clip bounds once, fills background in a single rectFill, then overlays glyph foreground pixels. Significantly faster than per-character drawChar for long runs (terminal rows, list items). .table Parameter Description --------- ----------- d Display context ops Blit operations vtable font Bitmap font x, y Start position text Character buffer (not required to be null-terminated) count Number of characters to render fg, bg Foreground and background packed colors opaque true = fill background, false = transparent .endtable .h2 textWidth .code int32_t textWidth(const BitmapFontT *font, const char *text); .endcode Return the pixel width of a null-terminated string (strlen(text) * charWidth). .table Parameter Description --------- ----------- font Bitmap font text Null-terminated string .endtable Returns: Width in pixels. .h2 accelParse .code char accelParse(const char *text); .endcode Scan text for an & prefix and return the following character as a lowercase accelerator key. "&File" returns 'f', "E&xit" returns 'x'. .table Parameter Description --------- ----------- text Text with optional & accelerator marker .endtable Returns: Lowercase accelerator character, or 0 if none. .h2 drawTextAccel .code void drawTextAccel(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque); .endcode Draw text with & accelerator markers. The character after & is drawn underlined to indicate the keyboard shortcut. && produces a literal &. Used for menu items and button labels. .table Parameter Description --------- ----------- d Display context ops Blit operations vtable font Bitmap font x, y Start position text Text with & markers fg, bg Foreground and background packed colors opaque true = fill background, false = transparent .endtable .h2 textWidthAccel .code int32_t textWidthAccel(const BitmapFontT *font, const char *text); .endcode Measure text width excluding & markers (so "&File" measures as 4 chars). .table Parameter Description --------- ----------- font Bitmap font text Text with optional & markers .endtable Returns: Width in pixels. .h2 drawMaskedBitmap .code void drawMaskedBitmap(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const uint16_t *andMask, const uint16_t *xorData, uint32_t fgColor, uint32_t bgColor); .endcode Draw a 1-bit AND/XOR masked bitmap. Used for software-rendered mouse cursors. .table Parameter Description --------- ----------- d Display context ops Blit operations vtable x, y Screen position w, h Bitmap dimensions andMask AND transparency mask (one uint16_t per row) xorData XOR color data fgColor, bgColor Cursor foreground and background packed colors .endtable .h2 drawTermRow .code void drawTermRow(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, int32_t cols, const uint8_t *lineData, const uint32_t *palette, bool blinkVisible, int32_t cursorCol); .endcode Render an entire row of terminal character cells (ch/attr byte pairs) in a single pass. Colors looked up from a 16-color palette. Attribute bit 7 controls blink. .table Parameter Description --------- ----------- d Display context ops Blit operations vtable font Bitmap font x, y Row start position cols Number of columns lineData Packed ch/attr byte pairs (2 bytes per cell) palette 16-entry packed color palette blinkVisible false = hide blinking characters cursorCol Column for inverted text cursor (-1 = none) .endtable .h2 drawFocusRect .code void drawFocusRect(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color); .endcode Draw a 1px dotted rectangle (alternating pixels). Used for keyboard focus indicators, matching the Windows 3.x focus rectangle convention. .table Parameter Description --------- ----------- d Display context ops Blit operations vtable x, y, w, h Focus rectangle bounds color Dot color (packed) .endtable .h2 drawHLine .code void drawHLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, uint32_t color); .endcode Draw a horizontal line (1px tall). .table Parameter Description --------- ----------- d Display context ops Blit operations vtable x, y Start position w Width in pixels color Packed pixel color .endtable .h2 drawVLine .code void drawVLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t h, uint32_t color); .endcode Draw a vertical line (1px wide). .table Parameter Description --------- ----------- d Display context ops Blit operations vtable x, y Start position h Height in pixels color Packed pixel color .endtable .topic api.comp .title dvxComp.h -- Layer 3: Dirty Rectangle Compositor .toc 1 dvxComp.h -- Layer 3: Compositor .index dvxComp.h .index dirtyListInit .index dirtyListAdd .index dirtyListMerge .index dirtyListClear .index flushRect .index rectIntersect .h1 dvxComp.h -- Layer 3: Dirty Rectangle Compositor Tracks changed screen regions and ensures only dirty regions are redrawn and flushed to video memory. The compositing pipeline: mark dirty, merge overlapping rects, redraw desktop + windows (back-to-front, painter's algorithm), flush to LFB. .h2 dirtyListInit .code void dirtyListInit(DirtyListT *dl); .endcode Zero the dirty rect count. Called at the start of each frame. .table Parameter Description --------- ----------- dl Dirty list to initialize .endtable .h2 dirtyListAdd .code void dirtyListAdd(DirtyListT *dl, int32_t x, int32_t y, int32_t w, int32_t h); .endcode Enqueue a dirty rectangle. Grows dynamically; triggers merge at a soft capacity limit. .table Parameter Description --------- ----------- dl Dirty list x, y, w, h Dirty rectangle in screen coordinates .endtable .h2 dirtyListMerge .code void dirtyListMerge(DirtyListT *dl); .endcode Consolidate the dirty list by merging overlapping and adjacent rects. Uses iterative pairwise merge: if combining two rects does not increase total area beyond a threshold, they are merged. Reduces compositor passes and LFB flush operations. .table Parameter Description --------- ----------- dl Dirty list to merge .endtable .h2 dirtyListClear .code void dirtyListClear(DirtyListT *dl); .endcode Reset the dirty list to empty (sets count to 0). .table Parameter Description --------- ----------- dl Dirty list to clear .endtable .h2 flushRect .code void flushRect(DisplayT *d, const RectT *r); .endcode Copy a rectangle from the system RAM backbuffer to the LFB (video memory). This is the only place the real framebuffer is written. Uses platform-specific fast copy (rep movsd on DOS) for each scanline. .table Parameter Description --------- ----------- d Display context r Rectangle to flush .endtable .h2 rectIntersect .code bool rectIntersect(const RectT *a, const RectT *b, RectT *result); .endcode Compute the intersection of two rectangles. .table Parameter Description --------- ----------- a, b Input rectangles result Output: intersection rectangle (valid only when return is true) .endtable Returns: true if the rectangles overlap, false if disjoint. .topic api.wm .title dvxWm.h -- Layer 4: Window Manager .toc 1 dvxWm.h -- Layer 4: Window Manager .index dvxWm.h .index wmInit .index wmCreateWindow .index wmDestroyWindow .index wmRaiseWindow .index wmSetFocus .index wmUpdateContentRect .index wmReallocContentBuf .index wmMinWindowSize .index wmAddMenuBar .index wmAddMenu .index wmAddMenuItem .index wmAddSubMenu .index wmCreateMenu .index wmDrawChrome .index wmHitTest .index wmDragBegin .index wmResizeBegin .index wmMaximize .index wmMinimize .index wmRestore .h1 dvxWm.h -- Layer 4: Window Manager Manages the window lifecycle, Z-order stack, chrome drawing, hit testing, and interactive operations (drag, resize, scroll). The WM owns window geometry and chrome; content is owned by the application via callbacks or the widget system. .h2 Initialization .h3 wmInit .code void wmInit(WindowStackT *stack); .endcode Zero the window stack. Must be called before any other WM function. .table Parameter Description --------- ----------- stack Window stack to initialize .endtable .h2 Window Lifecycle .h3 wmCreateWindow .code WindowT *wmCreateWindow(WindowStackT *stack, DisplayT *d, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable); .endcode Allocate a new window, initialize its geometry and content buffer, and push it to the top of the Z-order stack. Returns with all callbacks NULL; the caller should set onPaint/onKey/etc. before the next event loop iteration. .table Parameter Description --------- ----------- stack Window stack d Display context title Window title text x, y Initial position w, h Initial outer frame dimensions resizable true = allow user resize .endtable Returns: Pointer to new WindowT, or NULL on failure. .h3 wmDestroyWindow .code void wmDestroyWindow(WindowStackT *stack, WindowT *win); .endcode Free the window's content buffer and all attached resources (menu bar, scrollbars, widget tree), remove it from the stack, and dirty the vacated region. .table Parameter Description --------- ----------- stack Window stack win Window to destroy .endtable .h2 Z-Order and Focus .h3 wmRaiseWindow .code void wmRaiseWindow(WindowStackT *stack, DirtyListT *dl, int32_t idx); .endcode Move window at stack index idx to the top of the Z-order. Dirties both old and new top positions so overlapping windows get repainted. .table Parameter Description --------- ----------- stack Window stack dl Dirty list for repaint marking idx Stack index of window to raise .endtable .h3 wmSetFocus .code void wmSetFocus(WindowStackT *stack, DirtyListT *dl, int32_t idx); .endcode Transfer keyboard focus to the window at stack index idx. Unfocuses the previously focused window and dirties both title bars. .table Parameter Description --------- ----------- stack Window stack dl Dirty list idx Stack index of window to focus .endtable .h2 Geometry .h3 wmUpdateContentRect .code void wmUpdateContentRect(WindowT *win); .endcode Recompute contentX/Y/W/H from the window's outer frame dimensions, accounting for chrome borders, title bar, menu bar, and scrollbars. Must be called after any change to frame size or chrome configuration. .table Parameter Description --------- ----------- win Window to update .endtable .h3 wmReallocContentBuf .code int32_t wmReallocContentBuf(WindowT *win, const DisplayT *d); .endcode Reallocate the per-window content backbuffer to match current contentW/H. Old buffer contents are lost; caller should trigger a full repaint via onPaint afterward. .table Parameter Description --------- ----------- win Window to reallocate d Display context (for bytes-per-pixel) .endtable Returns: 0 on success, -1 on allocation failure. .h3 wmMinWindowSize .code void wmMinWindowSize(const WindowT *win, int32_t *minW, int32_t *minH); .endcode Get the minimum window size. Accounts for chrome, gadgets, and menu bar. .table Parameter Description --------- ----------- win Window minW, minH Output: minimum width and height .endtable .h2 Menu Bar .h3 wmAddMenuBar .code MenuBarT *wmAddMenuBar(WindowT *win); .endcode Allocate and attach a menu bar to a window. Adjusts content area to make room (CHROME_MENU_HEIGHT pixels). One menu bar per window. .table Parameter Description --------- ----------- win Window to add menu bar to .endtable Returns: Pointer to the new MenuBarT. .h3 wmDestroyMenuBar .code void wmDestroyMenuBar(WindowT *win, const DisplayT *d); .endcode Free the menu bar and reclaim the content area. The content buffer is reallocated to fit the grown content area. .table Parameter Description --------- ----------- win Window to remove menu bar from d Display context; pass NULL only during window teardown .endtable .h3 wmAddMenu .code MenuT *wmAddMenu(MenuBarT *bar, const char *label); .endcode Append a dropdown menu to the menu bar. The label supports & accelerator markers (e.g. "&File"). .table Parameter Description --------- ----------- bar Menu bar label Menu label text .endtable Returns: Pointer to the new MenuT to populate with items. .h3 wmAddMenuItem .code void wmAddMenuItem(MenuT *menu, const char *label, int32_t id); .endcode Append a clickable item to a menu. The id is passed to the window's onMenu callback when selected. .table Parameter Description --------- ----------- menu Menu to append to label Item label (supports & markers) id Application-defined command ID .endtable .h3 wmAddMenuCheckItem .code void wmAddMenuCheckItem(MenuT *menu, const char *label, int32_t id, bool checked); .endcode Add a checkbox-style menu item. Check state toggles on click; rendered with a checkmark glyph. .table Parameter Description --------- ----------- menu Menu to append to label Item label id Command ID checked Initial checked state .endtable .h3 wmAddMenuRadioItem .code void wmAddMenuRadioItem(MenuT *menu, const char *label, int32_t id, bool checked); .endcode Add a radio-style menu item. Radio groups are defined implicitly by consecutive radio items; selecting one unchecks the others in the group. .table Parameter Description --------- ----------- menu Menu to append to label Item label id Command ID checked Initial checked state .endtable .h3 wmAddMenuSeparator .code void wmAddMenuSeparator(MenuT *menu); .endcode Insert a horizontal separator line. Separators are not interactive. .table Parameter Description --------- ----------- menu Menu to append separator to .endtable .h3 wmRemoveMenuItem .code bool wmRemoveMenuItem(MenuT *menu, int32_t id); .endcode Remove a menu item by command ID. Searches the menu's items array and shifts remaining items down to close the gap. .table Parameter Description --------- ----------- menu Menu to remove item from id Command ID to remove .endtable Returns: true if a matching item was found and removed. .h3 wmClearMenuItems .code void wmClearMenuItems(MenuT *menu); .endcode Remove all items from a menu while preserving the menu itself on the menu bar. Use when rebuilding a menu's contents dynamically (e.g. a recent-files submenu). .table Parameter Description --------- ----------- menu Menu to empty .endtable .h3 wmMenuItemIsChecked .code bool wmMenuItemIsChecked(MenuBarT *bar, int32_t id); .endcode Query the checked state of a menu item by command ID. Searches all menus in the bar. .table Parameter Description --------- ----------- bar Menu bar id Command ID to query .endtable Returns: true if checked. .h3 wmMenuItemSetChecked .code void wmMenuItemSetChecked(MenuBarT *bar, int32_t id, bool checked); .endcode Set the checked state of a menu item by command ID. For radio items, setting checked=true also unchecks other radio items in the same group. .table Parameter Description --------- ----------- bar Menu bar id Command ID checked New checked state .endtable .h3 wmMenuItemSetEnabled .code void wmMenuItemSetEnabled(MenuBarT *bar, int32_t id, bool enabled); .endcode Enable or disable a menu item by command ID. .table Parameter Description --------- ----------- bar Menu bar id Command ID enabled true = enabled, false = grayed out .endtable .h3 wmAddSubMenu .code MenuT *wmAddSubMenu(MenuT *parentMenu, const char *label); .endcode Create a cascading submenu attached to a parent menu. The child MenuT is heap-allocated and freed when the parent window is destroyed. .table Parameter Description --------- ----------- parentMenu Parent menu to attach submenu to label Submenu label text .endtable Returns: Pointer to the child MenuT, or NULL on allocation failure. .h3 wmCreateMenu .code MenuT *wmCreateMenu(void); .endcode Allocate a heap-resident MenuT for use as a context menu (right-click). Unlike menu bar menus, context menus are standalone allocations. Free with wmFreeMenu(). Returns: Pointer to the new MenuT. .h3 wmFreeMenu .code void wmFreeMenu(MenuT *menu); .endcode Free a standalone menu allocated with wmCreateMenu(). Also frees any heap-allocated submenu children recursively. .table Parameter Description --------- ----------- menu Menu to free .endtable .h2 Scrollbars .h3 wmAddVScrollbar .code ScrollbarT *wmAddVScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize); .endcode Attach a vertical scrollbar to the right edge of the window's content area. Shrinks contentW by SCROLLBAR_WIDTH pixels. .table Parameter Description --------- ----------- win Window min, max Scroll value range pageSize Visible portion (controls thumb size) .endtable Returns: Pointer to the new ScrollbarT. .h3 wmAddHScrollbar .code ScrollbarT *wmAddHScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize); .endcode Attach a horizontal scrollbar to the bottom edge. Shrinks contentH by SCROLLBAR_WIDTH pixels. .table Parameter Description --------- ----------- win Window min, max Scroll value range pageSize Visible portion .endtable Returns: Pointer to the new ScrollbarT. .h2 Drawing .h3 wmDrawChrome .code void wmDrawChrome(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo); .endcode Draw the window frame: outer bevel, title bar with text, close/minimize/maximize gadgets, and menu bar if present. Drawing is clipped to the intersection with clipTo. .table Parameter Description --------- ----------- d Display context ops Blit operations vtable font Bitmap font for title text colors Color scheme win Window to draw chrome for clipTo Dirty rectangle to clip drawing to .endtable .h3 wmDrawContent .code void wmDrawContent(DisplayT *d, const BlitOpsT *ops, WindowT *win, const RectT *clipTo); .endcode Blit the window's content backbuffer into the display backbuffer, clipped to the dirty rect. Pure copy operation (no drawing). .table Parameter Description --------- ----------- d Display context ops Blit operations vtable win Window clipTo Dirty rectangle .endtable .h3 wmDrawScrollbars .code void wmDrawScrollbars(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo); .endcode Draw scrollbars (track, arrows, proportional thumb) for a window. Drawn after content so scrollbars overlay the content area edge. .table Parameter Description --------- ----------- d Display context ops Blit operations vtable colors Color scheme win Window clipTo Dirty rectangle .endtable .h3 wmDrawMinimizedIcons .code void wmDrawMinimizedIcons(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, const WindowStackT *stack, const RectT *clipTo); .endcode Draw icons for all minimized windows along the bottom of the screen. Each icon shows a scaled preview of the window's content with a beveled border. .table Parameter Description --------- ----------- d Display context ops Blit operations vtable colors Color scheme stack Window stack clipTo Dirty rectangle .endtable .h3 wmDrawVScrollbarAt .code void wmDrawVScrollbarAt(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t x, int32_t y, int32_t h, int32_t scrollPos, int32_t visibleItems, int32_t totalItems); .endcode Draw a standalone vertical scrollbar at the given screen coordinates, without a ScrollbarT struct. Used by popup lists (dropdown, combobox) that need a scrollbar inline within a popup overlay. Thumb size and position are computed from scrollPos / visibleItems / totalItems. .table Parameter Description --------- ----------- d Display context ops Blit operations vtable colors Color scheme x, y Screen position (top of scrollbar) h Track height in pixels scrollPos Current top visible item index visibleItems Visible item count (for thumb size) totalItems Total item count .endtable .h2 Hit Testing .h3 wmHitTest .code int32_t wmHitTest(const WindowStackT *stack, int32_t mx, int32_t my, int32_t *hitPart); .endcode Determine which window and chrome region is under the given screen coordinates. Iterates front-to-back (highest Z first) so the topmost window wins. .table Parameter Description --------- ----------- stack Window stack mx, my Screen coordinates hitPart Output: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, etc. .endtable Returns: Stack index of hit window, or -1 for desktop. .h3 wmResizeEdgeHit .code int32_t wmResizeEdgeHit(const WindowT *win, int32_t mx, int32_t my); .endcode Determine which edge(s) of a window's border zone are targeted for resize. .table Parameter Description --------- ----------- win Window mx, my Screen coordinates .endtable Returns: Bitmask of RESIZE_LEFT / RESIZE_RIGHT / RESIZE_TOP / RESIZE_BOTTOM. .h3 wmMinimizedIconHit .code int32_t wmMinimizedIconHit(const WindowStackT *stack, const DisplayT *d, int32_t mx, int32_t my); .endcode Hit-test minimized icons at the bottom of the screen. .table Parameter Description --------- ----------- stack Window stack d Display context mx, my Screen coordinates .endtable Returns: Stack index of the minimized window, or -1. .h2 Drag and Resize .h3 wmDragBegin .code void wmDragBegin(WindowStackT *stack, int32_t idx, int32_t mouseX, int32_t mouseY); .endcode Begin a window drag operation. Records the mouse offset from the window origin. .table Parameter Description --------- ----------- stack Window stack idx Stack index of window to drag mouseX/Y Current mouse position .endtable .h3 wmDragMove .code void wmDragMove(WindowStackT *stack, DirtyListT *dl, int32_t mouseX, int32_t mouseY, int32_t screenW, int32_t screenH); .endcode Update window position during an active drag. Dirties both old and new positions. .table Parameter Description --------- ----------- stack Window stack dl Dirty list mouseX/Y Current mouse position screenW/H Screen dimensions (for clamping) .endtable .h3 wmDragEnd .code void wmDragEnd(WindowStackT *stack); .endcode End the current drag operation. Clears dragWindow state. .table Parameter Description --------- ----------- stack Window stack .endtable .h3 wmResizeBegin .code void wmResizeBegin(WindowStackT *stack, int32_t idx, int32_t edge, int32_t mouseX, int32_t mouseY); .endcode Begin a window resize operation. Records which edge(s) are being dragged. .table Parameter Description --------- ----------- stack Window stack idx Stack index edge Bitmask of RESIZE_xxx flags mouseX/Y Current mouse position .endtable .h3 wmResizeMove .code void wmResizeMove(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, int32_t *mouseX, int32_t *mouseY); .endcode Update window dimensions during an active resize. Enforces MIN_WINDOW_W/H and maxW/maxH constraints. Reallocates content buffer and calls onResize if size changed. mouseX/mouseY are in/out: clamped on return for cursor warping. .table Parameter Description --------- ----------- stack Window stack dl Dirty list d Display context mouseX/Y In/out: mouse position (clamped on return) .endtable .h3 wmResizeEnd .code void wmResizeEnd(WindowStackT *stack); .endcode End the current resize operation. Clears resizeWindow state. .table Parameter Description --------- ----------- stack Window stack .endtable .h2 Scrollbar Interaction .h3 wmScrollbarClick .code void wmScrollbarClick(WindowStackT *stack, DirtyListT *dl, int32_t idx, ScrollbarOrientE orient, int32_t mx, int32_t my); .endcode Handle an initial click on a scrollbar. Determines what was hit (arrows, trough, or thumb) and either adjusts the value immediately or begins a thumb drag. .table Parameter Description --------- ----------- stack Window stack dl Dirty list idx Stack index of window orient ScrollbarVerticalE or ScrollbarHorizontalE mx, my Click screen coordinates .endtable .h3 wmScrollbarDrag .code void wmScrollbarDrag(WindowStackT *stack, DirtyListT *dl, int32_t mx, int32_t my); .endcode Update the scroll value during an active thumb drag. Maps mouse position along the track to a proportional scroll value. .table Parameter Description --------- ----------- stack Window stack dl Dirty list mx, my Current mouse position .endtable .h3 wmScrollbarEnd .code void wmScrollbarEnd(WindowStackT *stack); .endcode End an active scrollbar thumb drag. .table Parameter Description --------- ----------- stack Window stack .endtable .h2 Minimize / Maximize / Restore .h3 wmMaximize .code void wmMaximize(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win); .endcode Maximize a window. Saves current geometry, then expands to screen or maxW/maxH bounds. .table Parameter Description --------- ----------- stack Window stack dl Dirty list d Display context win Window to maximize .endtable .h3 wmMinimize .code void wmMinimize(WindowStackT *stack, DirtyListT *dl, WindowT *win); .endcode Minimize a window. Hides the window and shows an icon at the bottom of the screen. .table Parameter Description --------- ----------- stack Window stack dl Dirty list win Window to minimize .endtable .h3 wmRestore .code void wmRestore(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win); .endcode Restore a maximized window to its pre-maximize geometry. .table Parameter Description --------- ----------- stack Window stack dl Dirty list d Display context win Maximized window to restore .endtable .h3 wmRestoreMinimized .code void wmRestoreMinimized(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win); .endcode Restore a minimized window (show it again and remove the icon). .table Parameter Description --------- ----------- stack Window stack dl Dirty list d Display context win Minimized window to restore .endtable .h2 Minimized Icon Layout .h3 wmMinimizedIconPos .code void wmMinimizedIconPos(const DisplayT *d, int32_t index, int32_t *x, int32_t *y); .endcode Compute the screen position of a minimized icon by ordinal index. Icons wrap into rows from bottom to top when the screen fills up. .table Parameter Description --------- ----------- d Display context index Ordinal index of the minimized icon x, y Output: screen position .endtable .h3 wmMinimizedIconRect .code void wmMinimizedIconRect(const WindowStackT *stack, const DisplayT *d, int32_t *y, int32_t *h); .endcode Compute the screen rect covering all minimized icon rows. Used to dirty the icon area when windows are minimized or restored. .table Parameter Description --------- ----------- stack Window stack d Display context y, h Output: vertical extent of icon area .endtable .h2 Miscellaneous .h3 wmSetTitle .code void wmSetTitle(WindowT *win, DirtyListT *dl, const char *title); .endcode Set the window title and dirty the title bar for repaint. .table Parameter Description --------- ----------- win Window dl Dirty list title New title text .endtable .h3 wmSetIcon .code int32_t wmSetIcon(WindowT *win, const char *path, const DisplayT *d); .endcode Load an icon image for a window from a file. Converts to display pixel format. .table Parameter Description --------- ----------- win Window path Image file path d Display context .endtable Returns: 0 on success, -1 on failure. .topic api.app .title dvxApp.h -- Layer 5: Application API .toc 1 dvxApp.h -- Layer 5: Application API .index dvxApp.h .index AppContextT .index dvxInit .index dvxShutdown .index dvxRun .index dvxUpdate .index dvxQuit .index dvxCreateWindow .index dvxCreateWindowCentered .index dvxDestroyWindow .index dvxRaiseWindow .index dvxFitWindow .index dvxFitWindowH .index dvxFitWindowW .index dvxResizeWindow .index dvxMinimizeWindow .index dvxMaximizeWindow .index dvxHideWindow .index dvxShowWindow .index dvxInvalidateRect .index dvxInvalidateWindow .index dvxSetTitle .index dvxSetWindowIcon .index dvxSetBusy .index dvxGetFont .index dvxGetColors .index dvxGetDisplay .index dvxGetBlitOps .index dvxGetVideoModes .index dvxSetColor .index dvxGetColor .index dvxApplyColorScheme .index dvxResetColorScheme .index dvxLoadTheme .index dvxSaveTheme .index dvxColorName .index dvxColorLabel .index dvxSetWallpaper .index dvxSetWallpaperMode .index dvxSetMouseConfig .index dvxCreateAccelTable .index dvxFreeAccelTable .index dvxAddAccel .index dvxCascadeWindows .index dvxTileWindows .index dvxTileWindowsH .index dvxTileWindowsV .index dvxLoadImage .index dvxLoadImageAlpha .index dvxLoadImageFromMemory .index dvxFreeImage .index dvxImageInfo .index dvxSaveImage .index dvxScreenshot .index dvxWindowScreenshot .index dvxClipboardCopy .index dvxClipboardGet .index dvxResLoadIcon .index dvxResLoadText .index dvxResLoadData .index dvxTextHash .index dvxChangeVideoMode .h1 dvxApp.h -- Layer 5: Application API The topmost layer and the public-facing API. Aggregates all lower layers into a single AppContextT. Applications interact exclusively through dvx*() functions and window callbacks. The event loop follows a cooperative model: poll, dispatch, composite, yield. .h2 AppContextT Single monolithic context that owns all GUI state. Contains the display, window stack, dirty list, blit ops, font, color scheme, popup state, cursor state, mouse/keyboard state, tooltip state, wallpaper buffer, video mode list, and various configuration fields. Allocated on the caller's stack or statically. .h2 Initialization and Shutdown .h3 dvxInit .code int32_t dvxInit(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp); .endcode Initialize the entire GUI stack: video mode, input devices, font, color scheme, cursor shapes, and internal state. Single entry point for starting a DVX application. .table Parameter Description --------- ----------- ctx Application context to initialize requestedW/H Desired screen resolution preferredBpp Preferred bits per pixel .endtable Returns: 0 on success, negative on failure. .h3 dvxShutdown .code void dvxShutdown(AppContextT *ctx); .endcode Tear down the GUI stack in reverse order: destroy all windows, restore text mode, release input devices. Safe to call after a failed dvxInit(). .table Parameter Description --------- ----------- ctx Application context .endtable .h3 dvxChangeVideoMode .code int32_t dvxChangeVideoMode(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp); .endcode Switch to a new video mode live. Reallocates the backbuffer, all window content buffers, repacks colors, rescales wallpaper, and repositions off-screen windows. .table Parameter Description --------- ----------- ctx Application context requestedW/H New resolution preferredBpp New bits per pixel .endtable Returns: 0 on success, -1 on failure (old mode restored). .h2 Event Loop .h3 dvxRun .code void dvxRun(AppContextT *ctx); .endcode Enter the main event loop. Polls input, dispatches events, composites dirty regions, and yields on each iteration. Returns when ctx->running becomes false. .table Parameter Description --------- ----------- ctx Application context .endtable .h3 dvxUpdate .code bool dvxUpdate(AppContextT *ctx); .endcode Process exactly one frame of the event loop. For applications that integrate the GUI into their own main loop (e.g. polling serial ports between frames). .table Parameter Description --------- ----------- ctx Application context .endtable Returns: false when the GUI wants to exit. .h3 dvxQuit .code void dvxQuit(AppContextT *ctx); .endcode Request exit from the main event loop (sets ctx->running = false). .table Parameter Description --------- ----------- ctx Application context .endtable .h2 Window Management .h3 dvxCreateWindow .code WindowT *dvxCreateWindow(AppContextT *ctx, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable); .endcode Create a window at an explicit screen position. The window is raised to the top, focused, and its entire region is dirtied. .table Parameter Description --------- ----------- ctx Application context title Window title x, y Screen position w, h Outer frame dimensions resizable true = allow user resize .endtable Returns: Pointer to new WindowT. .h3 dvxCreateWindowCentered .code WindowT *dvxCreateWindowCentered(AppContextT *ctx, const char *title, int32_t w, int32_t h, bool resizable); .endcode Convenience wrapper that centers the window on screen. .table Parameter Description --------- ----------- ctx Application context title Window title w, h Outer frame dimensions resizable true = allow user resize .endtable Returns: Pointer to new WindowT. .h3 dvxDestroyWindow .code void dvxDestroyWindow(AppContextT *ctx, WindowT *win); .endcode Destroy a window, free all its resources, and dirty its former region. .table Parameter Description --------- ----------- ctx Application context win Window to destroy .endtable .h3 dvxRaiseWindow .code void dvxRaiseWindow(AppContextT *ctx, WindowT *win); .endcode Raise a window to the top of the Z-order and give it focus. .table Parameter Description --------- ----------- ctx Application context win Window to raise .endtable .h3 dvxFitWindow .code void dvxFitWindow(AppContextT *ctx, WindowT *win); .endcode Resize a window to exactly fit its widget tree's computed minimum size (plus chrome). Used for dialog boxes and fixed-layout windows. .table Parameter Description --------- ----------- ctx Application context win Window to fit .endtable .h3 dvxFitWindowW .code void dvxFitWindowW(AppContextT *ctx, WindowT *win); .endcode Resize window width only to fit widget tree's minimum width (plus chrome). .table Parameter Description --------- ----------- ctx Application context win Window to fit .endtable .h3 dvxFitWindowH .code void dvxFitWindowH(AppContextT *ctx, WindowT *win); .endcode Resize window height only to fit widget tree's minimum height (plus chrome). .table Parameter Description --------- ----------- ctx Application context win Window to fit .endtable .h3 dvxResizeWindow .code void dvxResizeWindow(AppContextT *ctx, WindowT *win, int32_t newW, int32_t newH); .endcode Programmatically resize a window to the specified outer dimensions. .table Parameter Description --------- ----------- ctx Application context win Window to resize newW, newH New outer frame dimensions .endtable .h3 dvxMinimizeWindow .code void dvxMinimizeWindow(AppContextT *ctx, WindowT *win); .endcode Minimize a window (show as icon at bottom of screen). .table Parameter Description --------- ----------- ctx Application context win Window to minimize .endtable .h3 dvxMaximizeWindow .code void dvxMaximizeWindow(AppContextT *ctx, WindowT *win); .endcode Maximize a window (expand to fill screen or maxW/maxH). .table Parameter Description --------- ----------- ctx Application context win Window to maximize .endtable .h3 dvxHideWindow .code void dvxHideWindow(AppContextT *ctx, WindowT *win); .endcode Hide a window without destroying it. Marks the exposed region dirty. .table Parameter Description --------- ----------- ctx Application context win Window to hide .endtable .h3 dvxShowWindow .code void dvxShowWindow(AppContextT *ctx, WindowT *win); .endcode Show a previously hidden window. Marks its region dirty for repaint. .table Parameter Description --------- ----------- ctx Application context win Window to show .endtable .h2 Invalidation .h3 dvxInvalidateRect .code void dvxInvalidateRect(AppContextT *ctx, WindowT *win, int32_t x, int32_t y, int32_t w, int32_t h); .endcode Mark a sub-region of a window's content area as needing repaint. Coordinates are relative to the content area, not the screen. Triggers onPaint during the next composite pass. .table Parameter Description --------- ----------- ctx Application context win Window x, y, w, h Dirty rectangle in content-relative coordinates .endtable .h3 dvxInvalidateWindow .code void dvxInvalidateWindow(AppContextT *ctx, WindowT *win); .endcode Mark the entire window content area as dirty. .table Parameter Description --------- ----------- ctx Application context win Window to invalidate .endtable .h2 Window Properties .h3 dvxSetTitle .code void dvxSetTitle(AppContextT *ctx, WindowT *win, const char *title); .endcode Set a window's title text and dirty the title bar. .table Parameter Description --------- ----------- ctx Application context win Window title New title text .endtable .h3 dvxSetWindowIcon .code int32_t dvxSetWindowIcon(AppContextT *ctx, WindowT *win, const char *path); .endcode Load an icon for a window from an image file. .table Parameter Description --------- ----------- ctx Application context win Window path Image file path .endtable Returns: 0 on success, -1 on failure. .h3 dvxSetBusy .code void dvxSetBusy(AppContextT *ctx, bool busy); .endcode Set or clear busy state. While busy, the hourglass cursor is shown and input is blocked. .table Parameter Description --------- ----------- ctx Application context busy true = show hourglass, false = normal .endtable .h2 Accessors .h3 dvxGetFont .code const BitmapFontT *dvxGetFont(const AppContextT *ctx); .endcode Get a pointer to the default font. .table Parameter Description --------- ----------- ctx Application context .endtable Returns: Pointer to the active BitmapFontT. .h3 dvxGetColors .code const ColorSchemeT *dvxGetColors(const AppContextT *ctx); .endcode Get a pointer to the current color scheme. .table Parameter Description --------- ----------- ctx Application context .endtable Returns: Pointer to the active ColorSchemeT. .h3 dvxGetDisplay .code DisplayT *dvxGetDisplay(AppContextT *ctx); .endcode Get a pointer to the display context. .table Parameter Description --------- ----------- ctx Application context .endtable Returns: Pointer to the DisplayT. .h3 dvxGetBlitOps .code const BlitOpsT *dvxGetBlitOps(const AppContextT *ctx); .endcode Get a pointer to the blit operations vtable. .table Parameter Description --------- ----------- ctx Application context .endtable Returns: Pointer to the active BlitOpsT. .h3 dvxGetVideoModes .code const VideoModeInfoT *dvxGetVideoModes(const AppContextT *ctx, int32_t *count); .endcode Return the list of available video modes enumerated at init time. .table Parameter Description --------- ----------- ctx Application context count Output: number of mode entries .endtable Returns: Pointer to the VideoModeInfoT array. .h2 Color Scheme .h3 dvxSetColor .code void dvxSetColor(AppContextT *ctx, ColorIdE id, uint8_t r, uint8_t g, uint8_t b); .endcode Set a single color by ID. Repacks to native pixel format and invalidates the entire screen. .table Parameter Description --------- ----------- ctx Application context id Color ID (ColorIdE) r, g, b RGB values (0-255) .endtable .h3 dvxGetColor .code void dvxGetColor(const AppContextT *ctx, ColorIdE id, uint8_t *r, uint8_t *g, uint8_t *b); .endcode Get a color's RGB values by ID. .table Parameter Description --------- ----------- ctx Application context id Color ID (ColorIdE) r, g, b Output: RGB values .endtable .h3 dvxApplyColorScheme .code void dvxApplyColorScheme(AppContextT *ctx); .endcode Apply all colors from ctx->colorRgb[] at once (repack + full repaint). .table Parameter Description --------- ----------- ctx Application context .endtable .h3 dvxResetColorScheme .code void dvxResetColorScheme(AppContextT *ctx); .endcode Reset all colors to the built-in defaults and repaint. .table Parameter Description --------- ----------- ctx Application context .endtable .h3 dvxLoadTheme .code bool dvxLoadTheme(AppContextT *ctx, const char *filename); .endcode Load a theme file (INI format with [colors] section) and apply it. .table Parameter Description --------- ----------- ctx Application context filename Path to theme INI file .endtable Returns: true on success. .h3 dvxSaveTheme .code bool dvxSaveTheme(const AppContextT *ctx, const char *filename); .endcode Save the current color scheme to a theme file. .table Parameter Description --------- ----------- ctx Application context filename Output file path .endtable Returns: true on success. .h3 dvxColorName .code const char *dvxColorName(ColorIdE id); .endcode Return the INI key name for a color ID (e.g. "desktop", "windowFace"). .table Parameter Description --------- ----------- id Color ID .endtable Returns: Static string. .h3 dvxColorLabel .code const char *dvxColorLabel(ColorIdE id); .endcode Return a human-readable display label (e.g. "Desktop", "Cursor Color"). .table Parameter Description --------- ----------- id Color ID .endtable Returns: Static string. .h2 Wallpaper .h3 dvxSetWallpaper .code bool dvxSetWallpaper(AppContextT *ctx, const char *path); .endcode Load and apply a wallpaper image using the current wallpaperMode (stretch/tile/center). Pass NULL to clear the wallpaper. .table Parameter Description --------- ----------- ctx Application context path Image file path, or NULL to clear .endtable Returns: true on success. .h3 dvxSetWallpaperMode .code void dvxSetWallpaperMode(AppContextT *ctx, WallpaperModeE mode); .endcode Change the wallpaper display mode and re-render. No effect if no wallpaper is loaded. .table Parameter Description --------- ----------- ctx Application context mode WallpaperStretchE, WallpaperTileE, or WallpaperCenterE .endtable .h2 Mouse Configuration .h3 dvxSetMouseConfig .code void dvxSetMouseConfig(AppContextT *ctx, int32_t wheelDir, int32_t dblClickMs, int32_t accelThreshold, int32_t mickeyRatio, int32_t wheelStep); .endcode Configure mouse behavior. Updates the in-memory AppContextT fields and programs any INT 33h settings that need driver-side adjustment. .table Parameter Description --------- ----------- ctx Application context wheelDir 1 = normal, -1 = reversed dblClickMs Double-click speed in milliseconds (e.g. 500) accelThreshold Double-speed threshold in mickeys/sec (0 = don't change) mickeyRatio Mickeys per 8 pixels (0 = don't change, 8 = default speed) wheelStep Lines to scroll per wheel notch (1-10, default 3) .endtable .h2 Accelerators .h3 dvxCreateAccelTable .code AccelTableT *dvxCreateAccelTable(void); .endcode Allocate a new accelerator table. Attach to a window via win->accelTable. Returns: Pointer to new AccelTableT. .h3 dvxFreeAccelTable .code void dvxFreeAccelTable(AccelTableT *table); .endcode Free an accelerator table and its entries. .table Parameter Description --------- ----------- table Table to free .endtable .h3 dvxAddAccel .code void dvxAddAccel(AccelTableT *table, int32_t key, int32_t modifiers, int32_t cmdId); .endcode Register a keyboard shortcut. On match, fires the window's onMenu callback with cmdId. .table Parameter Description --------- ----------- table Accelerator table key ASCII character or KEY_Fxx constant modifiers Bitmask of ACCEL_CTRL / ACCEL_SHIFT / ACCEL_ALT cmdId Command ID passed to onMenu .endtable .h2 Window Arrangement .h3 dvxCascadeWindows .code void dvxCascadeWindows(AppContextT *ctx); .endcode Cascade all visible, non-minimized windows. Each is offset diagonally by the title bar height. .table Parameter Description --------- ----------- ctx Application context .endtable .h3 dvxTileWindows .code void dvxTileWindows(AppContextT *ctx); .endcode Arrange visible windows in an NxM grid filling the screen. .table Parameter Description --------- ----------- ctx Application context .endtable .h3 dvxTileWindowsH .code void dvxTileWindowsH(AppContextT *ctx); .endcode Tile windows horizontally (side by side, equal width, full height). .table Parameter Description --------- ----------- ctx Application context .endtable .h3 dvxTileWindowsV .code void dvxTileWindowsV(AppContextT *ctx); .endcode Tile windows vertically (stacked, full width, equal height). .table Parameter Description --------- ----------- ctx Application context .endtable .h2 Image I/O .h3 dvxLoadImage .code uint8_t *dvxLoadImage(const AppContextT *ctx, const char *path, int32_t *outW, int32_t *outH, int32_t *outPitch); .endcode Load an image file (BMP, PNG, JPEG, GIF) and convert to the display's native pixel format. Caller must free with dvxFreeImage(). .table Parameter Description --------- ----------- ctx Application context path Image file path outW, outH Output: image dimensions outPitch Output: row pitch in bytes .endtable Returns: Pixel buffer, or NULL on failure. .h3 dvxLoadImageFromMemory .code uint8_t *dvxLoadImageFromMemory(const AppContextT *ctx, const uint8_t *data, int32_t dataLen, int32_t *outW, int32_t *outH, int32_t *outPitch); .endcode Load an image from a memory buffer (typically resource data). Same output format as dvxLoadImage(). Caller must free with dvxFreeImage(). .table Parameter Description --------- ----------- ctx Application context data Image data buffer dataLen Buffer size in bytes outW, outH Output: image dimensions outPitch Output: row pitch in bytes .endtable Returns: Pixel buffer, or NULL on failure. .h3 dvxLoadImageAlpha .code uint8_t *dvxLoadImageAlpha(const AppContextT *ctx, const uint8_t *data, int32_t dataLen, int32_t *outW, int32_t *outH, int32_t *outPitch, bool *outHasAlpha, uint32_t *outKeyColor); .endcode Load an image from memory with alpha transparency. Pixels with alpha < 128 are replaced with a packed magenta key color. If any transparent pixels are found, *outHasAlpha is set to true and *outKeyColor receives the packed key color for use with rectCopyTransparent. Caller must free with dvxFreeImage. .table Parameter Description --------- ----------- ctx Application context data Image data buffer dataLen Buffer size in bytes outW, outH Output: image dimensions outPitch Output: row pitch outHasAlpha Output: true if any transparent pixels found outKeyColor Output: packed key color (valid when outHasAlpha is true) .endtable Returns: Pixel buffer, or NULL on failure. .h3 dvxFreeImage .code void dvxFreeImage(uint8_t *data); .endcode Free a pixel buffer returned by dvxLoadImage() or dvxLoadImageFromMemory(). .table Parameter Description --------- ----------- data Buffer to free .endtable .h3 dvxImageInfo .code bool dvxImageInfo(const char *path, int32_t *outW, int32_t *outH); .endcode Query image dimensions without decoding the full file. .table Parameter Description --------- ----------- path Image file path outW, outH Output: image dimensions .endtable Returns: true on success. .h3 dvxSaveImage .code int32_t dvxSaveImage(const AppContextT *ctx, const uint8_t *data, int32_t w, int32_t h, int32_t pitch, const char *path); .endcode Save native-format pixel data to a PNG file. .table Parameter Description --------- ----------- ctx Application context data Pixel data in display native format w, h Image dimensions pitch Row pitch in bytes path Output file path .endtable Returns: 0 on success, -1 on failure. .h2 Screenshots .h3 dvxScreenshot .code int32_t dvxScreenshot(AppContextT *ctx, const char *path); .endcode Save the entire screen (backbuffer contents) to a PNG file. Converts from native pixel format to RGB. .table Parameter Description --------- ----------- ctx Application context path Output PNG file path .endtable Returns: 0 on success, -1 on failure. .h3 dvxWindowScreenshot .code int32_t dvxWindowScreenshot(AppContextT *ctx, WindowT *win, const char *path); .endcode Save a window's content to a PNG file. .table Parameter Description --------- ----------- ctx Application context win Window path Output PNG file path .endtable Returns: 0 on success, -1 on failure. .h2 Clipboard .h3 dvxClipboardCopy .code void dvxClipboardCopy(const char *text, int32_t len); .endcode Copy text to the process-wide clipboard buffer. Simple static buffer (not inter-process). .table Parameter Description --------- ----------- text Text to copy len Length in bytes .endtable .h3 dvxClipboardGet .code const char *dvxClipboardGet(int32_t *outLen); .endcode Retrieve the current clipboard contents. Returns a pointer to the internal buffer (valid until the next dvxClipboardCopy), or NULL if empty. .table Parameter Description --------- ----------- outLen Output: length of clipboard text .endtable Returns: Clipboard text, or NULL. .h2 Resource Loading .h3 dvxResLoadIcon .code uint8_t *dvxResLoadIcon(AppContextT *ctx, const char *dxePath, const char *resName, int32_t *outW, int32_t *outH, int32_t *outPitch); .endcode Load an icon/image resource from a DXE file and decode to native pixel format. Caller must free with dvxFreeImage(). .table Parameter Description --------- ----------- ctx Application context dxePath Path to DXE file resName Resource name within the DXE outW, outH Output: image dimensions outPitch Output: row pitch .endtable Returns: Pixel buffer, or NULL if not found. .h3 dvxResLoadText .code bool dvxResLoadText(const char *dxePath, const char *resName, char *buf, int32_t bufSize); .endcode Load a text resource from a DXE file into a caller-provided buffer. Null-terminated and truncated to fit bufSize. .table Parameter Description --------- ----------- dxePath Path to DXE file resName Resource name buf Output buffer bufSize Buffer capacity .endtable Returns: true on success. .h3 dvxResLoadData .code void *dvxResLoadData(const char *dxePath, const char *resName, uint32_t *outSize); .endcode Load a raw binary resource from a DXE file. Returns a malloc'd buffer that the caller must free. .table Parameter Description --------- ----------- dxePath Path to DXE file resName Resource name outSize Output: data size in bytes .endtable Returns: Data buffer, or NULL if not found. .h2 Utilities .h3 dvxTextHash .code uint32_t dvxTextHash(const char *text); .endcode Compute a djb2-xor hash for cheap dirty detection. Compare at save time with the current hash to detect changes without a shadow copy. Not cryptographic. .table Parameter Description --------- ----------- text Null-terminated string to hash .endtable Returns: 32-bit hash value. .topic api.widget .title dvxWgt.h -- Widget System .toc 1 dvxWgt.h -- Widget System .index dvxWgt.h .index WidgetT .index WidgetClassT .index wgtInitWindow .index wgtGetContext .index wgtInvalidate .index wgtInvalidatePaint .index wgtSetText .index wgtGetText .index wgtSetEnabled .index wgtSetReadOnly .index wgtSetFocused .index wgtGetFocused .index wgtSetVisible .index wgtSetName .index wgtFind .index wgtDestroy .index wgtSetTooltip .index wgtResolveSize .index wgtLayout .index wgtPaint .index wgtSetDebugLayout .index wgtRegisterClass .index wgtRegisterApi .index wgtGetApi .index wgtRegisterIface .index wgtGetIface .index wgtFindByBasName .index wgtPixels .index wgtChars .index wgtPercent .h1 dvxWgt.h -- Widget System Retained-mode widget toolkit layered on the DVX window manager. Widgets form a tree (parent-child) rooted at a per-window VBox container. Layout is automatic: measure minimum sizes bottom-up, then allocate space top-down with flexbox-like weighted distribution. Widget types are registered dynamically at runtime via DXE plugins. .h2 WidgetT Structure Core widget structure. Generic across all widget types; type-specific data lives in the void *data pointer managed by each widget's DXE. .table Field Description ----- ----------- int32_t type Widget type ID (assigned by wgtRegisterClass) const WidgetClassT *wclass Vtable for this widget type char name[MAX_WIDGET_NAME] Widget name for lookup via wgtFind parent, firstChild, lastChild, nextSibling Tree linkage pointers WindowT *window Owning window int32_t x, y, w, h Computed geometry (relative to content area) int32_t calcMinW, calcMinH Computed minimum size (from layout pass) int32_t minW, minH, maxW, maxH, prefW, prefH Size hints (tagged sizes) int32_t weight Extra-space distribution weight (0=fixed, 100=normal) WidgetAlignE align Main-axis alignment for children int32_t spacing, padding Tagged sizes for child spacing and padding uint32_t fgColor, bgColor Custom colors (0 = use scheme defaults) bool visible, enabled, readOnly State flags bool swallowTab Tab key goes to widget, not focus navigation bool paintDirty Needs repaint (set by wgtInvalidatePaint) bool childDirty A descendant needs repaint (for WCLASS_PAINTS_CHILDREN) bool pressed WCLASS_PRESS_RELEASE: set while button is pressed char accelKey Accelerator character (0 = none) int32_t contentOffX, contentOffY Content offset for mouse event coordinates void *userData, *data Application data and widget-private data const char *tooltip Tooltip text (NULL = none) MenuT *contextMenu Right-click menu (NULL = none) .endtable Universal Callbacks: .table Callback Description -------- ----------- onClick(WidgetT *w) Widget clicked onDblClick(WidgetT *w) Widget double-clicked onChange(WidgetT *w) Value changed onFocus(WidgetT *w) Widget gained focus onBlur(WidgetT *w) Widget lost focus onKeyPress(WidgetT *w, int32_t keyAscii) ASCII key press onKeyDown(WidgetT *w, int32_t keyCode, int32_t shift) Key down onKeyUp(WidgetT *w, int32_t keyCode, int32_t shift) Key up onMouseDown(WidgetT *w, int32_t button, int32_t x, int32_t y) Mouse button pressed onMouseUp(WidgetT *w, int32_t button, int32_t x, int32_t y) Mouse button released onMouseMove(WidgetT *w, int32_t button, int32_t x, int32_t y) Mouse moved onScroll(WidgetT *w, int32_t delta) Mouse wheel onValidate(WidgetT *w) Return false to cancel a write .endtable .h2 Size Specification Macros .table Macro Description ----- ----------- wgtPixels(v) Size in pixels wgtChars(v) Size in character widths (multiplied by charWidth at layout) wgtPercent(v) Size as percentage of parent dimension .endtable .h2 Widget Class Flags .table Flag Description ---- ----------- WCLASS_FOCUSABLE Can receive keyboard focus (Tab navigation) WCLASS_HORIZ_CONTAINER Lays out children horizontally (vs. vertical) WCLASS_PAINTS_CHILDREN Widget handles child rendering itself WCLASS_NO_HIT_RECURSE Hit testing stops here, no child recursion WCLASS_FOCUS_FORWARD Accel hit forwards focus to next focusable sibling WCLASS_HAS_POPUP Has dropdown popup overlay WCLASS_SCROLLABLE Accepts mouse wheel events WCLASS_SCROLL_CONTAINER Scroll container (ScrollPane) WCLASS_NEEDS_POLL Needs periodic polling WCLASS_SWALLOWS_TAB Tab key goes to widget, not focus navigation WCLASS_RELAYOUT_ON_SCROLL Full relayout on scrollbar drag WCLASS_PRESS_RELEASE Click = press + release (Button, ImageButton) WCLASS_ACCEL_WHEN_HIDDEN Accelerator matching works even when invisible .endtable .h2 Window Integration .h3 wgtInitWindow .code WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win); .endcode Initialize the widget system for a window. Creates a root VBox container that fills the content area, and installs callback handlers (onPaint, onMouse, onKey, onResize) for widget-based event dispatch. The window's userData is set to the AppContextT pointer. .table Parameter Description --------- ----------- ctx Application context win Window to initialize .endtable Returns: Root VBox widget (add children to this). .h2 Widget Operations .h3 wgtGetContext .code AppContextT *wgtGetContext(const WidgetT *w); .endcode Walk from any widget up the tree to the root, then retrieve the AppContextT stored in the window's userData. Lets any widget access the full application context. .table Parameter Description --------- ----------- w Any widget in the tree .endtable Returns: Pointer to the AppContextT. .h3 wgtInvalidate .code void wgtInvalidate(WidgetT *w); .endcode Mark a widget as needing both re-layout (measure + position) and repaint. Propagates upward to ancestors. Use after structural changes (adding/removing children, text changes that affect size). .table Parameter Description --------- ----------- w Widget to invalidate .endtable .h3 wgtInvalidatePaint .code void wgtInvalidatePaint(WidgetT *w); .endcode Mark a widget as needing repaint only, without re-layout. Use for visual-only changes (checkbox toggle, selection highlight, cursor blink). .table Parameter Description --------- ----------- w Widget to repaint .endtable .h3 wgtSetText .code void wgtSetText(WidgetT *w, const char *text); .endcode Set widget text content (dispatches to the widget class's SET_TEXT handler). .table Parameter Description --------- ----------- w Widget text New text .endtable .h3 wgtGetText .code const char *wgtGetText(const WidgetT *w); .endcode Get the widget's current text content. .table Parameter Description --------- ----------- w Widget .endtable Returns: Text string (empty string if no handler). .h3 wgtSetEnabled .code void wgtSetEnabled(WidgetT *w, bool enabled); .endcode Enable or disable a widget. Disabled widgets are grayed out and do not receive input. .table Parameter Description --------- ----------- w Widget enabled true = enabled, false = disabled .endtable .h3 wgtSetReadOnly .code void wgtSetReadOnly(WidgetT *w, bool readOnly); .endcode Set read-only mode. Allows scrolling and selection but blocks editing. .table Parameter Description --------- ----------- w Widget readOnly true = read-only .endtable .h3 wgtSetFocused .code void wgtSetFocused(WidgetT *w); .endcode Set keyboard focus to a widget. .table Parameter Description --------- ----------- w Widget to focus .endtable .h3 wgtGetFocused .code WidgetT *wgtGetFocused(void); .endcode Get the currently focused widget. Returns: Focused widget, or NULL. .h3 wgtSetVisible .code void wgtSetVisible(WidgetT *w, bool visible); .endcode Show or hide a widget. .table Parameter Description --------- ----------- w Widget visible true = visible, false = hidden .endtable .h3 wgtSetName .code void wgtSetName(WidgetT *w, const char *name); .endcode Set a widget's name for lookup via wgtFind(). .table Parameter Description --------- ----------- w Widget name Name string (max MAX_WIDGET_NAME chars) .endtable .h3 wgtFind .code WidgetT *wgtFind(WidgetT *root, const char *name); .endcode Find a widget by name. Searches the subtree rooted at root. .table Parameter Description --------- ----------- root Root of subtree to search name Widget name to find .endtable Returns: Matching widget, or NULL. .h3 wgtDestroy .code void wgtDestroy(WidgetT *w); .endcode Destroy a widget and all its children. Removes from parent's child list. .table Parameter Description --------- ----------- w Widget to destroy .endtable .h3 wgtSetTooltip .code void wgtSetTooltip(WidgetT *w, const char *text); .endcode Set tooltip text for a widget. Pass NULL to remove. Caller owns the string and it must outlive the widget. .table Parameter Description --------- ----------- w Widget text Tooltip text, or NULL .endtable .h3 widgetOnResize .code void widgetOnResize(WindowT *win, int32_t newW, int32_t newH); .endcode Default window resize handler installed by wgtInitWindow(). Re-evaluates scrollbars and relayouts the widget tree. Call from custom onResize handlers to chain to the widget system. .table Parameter Description --------- ----------- win Window being resized newW, newH New content dimensions .endtable .h2 Layout .h3 wgtResolveSize .code int32_t wgtResolveSize(int32_t taggedSize, int32_t parentSize, int32_t charWidth); .endcode Decode a tagged size value (WGT_SIZE_PIXELS/CHARS/PERCENT) into a concrete pixel count. Returns 0 for a raw 0 input (meaning "auto"). .table Parameter Description --------- ----------- taggedSize Tagged size value parentSize Parent dimension (for PERCENT mode) charWidth Font character width (for CHARS mode) .endtable Returns: Size in pixels. .h3 wgtLayout .code void wgtLayout(WidgetT *root, int32_t availW, int32_t availH, const BitmapFontT *font); .endcode Execute the full two-pass layout algorithm. Pass 1 (bottom-up): compute minimum sizes. Pass 2 (top-down): allocate space with weighted distribution. Normally called automatically; exposed for cases where layout must be forced before the next paint. .table Parameter Description --------- ----------- root Root widget availW/H Available space font Bitmap font (for character-based sizing) .endtable .h3 wgtPaint .code void wgtPaint(WidgetT *root, DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors, bool fullRepaint); .endcode Paint the entire widget tree by depth-first traversal. Each widget's clip rect is set to its bounds. Overlays (popups, tooltips) are painted in a second pass on top. .table Parameter Description --------- ----------- root Root widget d Display context ops Blit operations vtable font Bitmap font colors Color scheme fullRepaint true = repaint every widget; false = only paintDirty widgets .endtable .h2 Debug .h3 wgtSetDebugLayout .code void wgtSetDebugLayout(AppContextT *ctx, bool enabled); .endcode Draw colored borders around layout containers for debugging. .table Parameter Description --------- ----------- ctx Application context enabled true = draw debug borders .endtable .h2 Dynamic Widget Registration .h3 wgtRegisterClass .code int32_t wgtRegisterClass(const WidgetClassT *wclass); .endcode Register a new widget class at runtime. Appends to widgetClassTable. The WidgetClassT must remain valid for the lifetime of the process (typically static const in a DXE). .table Parameter Description --------- ----------- wclass Widget class vtable to register .endtable Returns: Assigned type ID. .h3 wgtRegisterApi .code void wgtRegisterApi(const char *name, const void *api); .endcode Register a widget API struct under a name. Each widget DXE registers its API during initialization. Callers retrieve it via wgtGetApi() and cast to the widget-specific type. .table Parameter Description --------- ----------- name Widget type name (e.g. "button", "listbox") api Pointer to the widget's API struct .endtable .note warning The create function must be the first field of the API struct. BASIC's form runtime instantiates widgets by dereferencing the api pointer as a pointer-to-function-pointer (see createWidgetByIface), so whichever field is first is what gets invoked. If the struct has multiple constructor variants, the one matching createSig must come first; put helper constructors, index accessors, and other entry points after it. .endnote .h3 wgtGetApi .code const void *wgtGetApi(const char *name); .endcode Retrieve a registered widget API struct by name. .table Parameter Description --------- ----------- name Widget type name .endtable Returns: Pointer to the API struct, or NULL if not found. .h2 Widget Interface Descriptors .h3 wgtRegisterIface .code void wgtRegisterIface(const char *name, const WgtIfaceT *iface); .endcode Register an interface descriptor for a widget type. Used by the BASIC form runtime and IDE for generic property/method dispatch. .table Parameter Description --------- ----------- name Widget type name iface Interface descriptor .endtable .h3 wgtGetIface .code const WgtIfaceT *wgtGetIface(const char *name); .endcode Retrieve an interface descriptor by widget type name. .table Parameter Description --------- ----------- name Widget type name .endtable Returns: Interface descriptor, or NULL. .h3 wgtFindByBasName .code const char *wgtFindByBasName(const char *basName); .endcode Find a widget type name by its VB-style name (e.g. "CommandButton" -> "button"). Case-insensitive search. .table Parameter Description --------- ----------- basName VB-style widget name .endtable Returns: Internal type name, or NULL. .h3 wgtIfaceCount .code int32_t wgtIfaceCount(void); .endcode Return the number of registered widget interfaces. Returns: Count of registered interfaces. .h3 wgtIfaceAt .code const WgtIfaceT *wgtIfaceAt(int32_t idx, const char **outName); .endcode Get a registered widget interface by index. .table Parameter Description --------- ----------- idx Index (0-based) outName Output: type name .endtable Returns: Interface descriptor. .h3 wgtIfaceGetPath .code const char *wgtIfaceGetPath(const char *name); .endcode Get the .wgt DXE file path for a registered widget. .table Parameter Description --------- ----------- name Widget type name .endtable Returns: File path string. .h3 wgtIfaceSetPath .code void wgtIfaceSetPath(const char *name, const char *path); .endcode Set the .wgt DXE file path for a registered widget (called by the loader). .table Parameter Description --------- ----------- name Widget type name path DXE file path .endtable .h3 wgtIfaceGetPathIndex .code int32_t wgtIfaceGetPathIndex(const char *name); .endcode Get the 1-based index of this widget within its .wgt file. Used to construct suffixed resource names (e.g. "name-2", "icon16-2"). .table Parameter Description --------- ----------- name Widget type name .endtable Returns: 1-based index within the DXE file. .h2 Typed Dispatch Helpers The following inline functions provide type-safe dispatch through the WidgetClassT handler table. Each checks for a non-NULL handler before calling. .table Function Method ID Description -------- --------- ----------- wclsHas(w, methodId) -- Check if handler exists wclsPaint(w, d, ops, font, colors) WGT_METHOD_PAINT Paint the widget wclsPaintOverlay(w, d, ops, font, colors) WGT_METHOD_PAINT_OVERLAY Paint overlay (popups) wclsCalcMinSize(w, font) WGT_METHOD_CALC_MIN_SIZE Compute minimum size wclsLayout(w, font) WGT_METHOD_LAYOUT Layout children wclsGetLayoutMetrics(w, font, ...) WGT_METHOD_GET_LAYOUT_METRICS Get pad, gap, extraTop, borderW wclsOnMouse(w, root, vx, vy) WGT_METHOD_ON_MOUSE Handle mouse event wclsOnKey(w, key, mod) WGT_METHOD_ON_KEY Handle key event wclsOnAccelActivate(w, root) WGT_METHOD_ON_ACCEL_ACTIVATE Handle accelerator wclsDestroy(w) WGT_METHOD_DESTROY Destroy widget data wclsOnChildChanged(parent, child) WGT_METHOD_ON_CHILD_CHANGED Notify parent of change wclsGetText(w) WGT_METHOD_GET_TEXT Get widget text wclsSetText(w, text) WGT_METHOD_SET_TEXT Set widget text wclsClearSelection(w) WGT_METHOD_CLEAR_SELECTION Clear text selection wclsClosePopup(w) WGT_METHOD_CLOSE_POPUP Close dropdown popup wclsGetPopupRect(w, font, ...) WGT_METHOD_GET_POPUP_RECT Get popup screen rect wclsOnDragUpdate(w, root, x, y) WGT_METHOD_ON_DRAG_UPDATE Update during drag wclsOnDragEnd(w, root, x, y) WGT_METHOD_ON_DRAG_END End drag operation wclsGetCursorShape(w, vx, vy) WGT_METHOD_GET_CURSOR_SHAPE Get cursor for position wclsPoll(w, win) WGT_METHOD_POLL Periodic polling wclsQuickRepaint(w, outY, outH) WGT_METHOD_QUICK_REPAINT Fast partial repaint wclsScrollChildIntoView(parent, child) WGT_METHOD_SCROLL_CHILD_INTO_VIEW Scroll child visible .endtable .h2 Method IDs Fixed constants used to index into WidgetClassT.handlers[]. Method IDs are stable ABI -- new methods are appended at the next sequential ID, never reordered or reused. .table ID Symbol Signature -- ------ --------- 0 WGT_METHOD_PAINT void (w, d, ops, font, colors) 1 WGT_METHOD_PAINT_OVERLAY void (w, d, ops, font, colors) 2 WGT_METHOD_CALC_MIN_SIZE void (w, font) 3 WGT_METHOD_LAYOUT void (w, font) 4 WGT_METHOD_GET_LAYOUT_METRICS void (w, font, pad, gap, extraTop, borderW) 5 WGT_METHOD_ON_MOUSE void (w, root, vx, vy) 6 WGT_METHOD_ON_KEY void (w, key, mod) 7 WGT_METHOD_ON_ACCEL_ACTIVATE void (w, root) 8 WGT_METHOD_DESTROY void (w) 9 WGT_METHOD_ON_CHILD_CHANGED void (parent, child) 10 WGT_METHOD_GET_TEXT const char *(w) 11 WGT_METHOD_SET_TEXT void (w, text) 12 WGT_METHOD_CLEAR_SELECTION bool (w) 13 WGT_METHOD_CLOSE_POPUP void (w) 14 WGT_METHOD_GET_POPUP_RECT void (w, font, contentH, popX, popY, popW, popH) 15 WGT_METHOD_ON_DRAG_UPDATE void (w, root, x, y) 16 WGT_METHOD_ON_DRAG_END void (w, root, x, y) 17 WGT_METHOD_GET_CURSOR_SHAPE int32_t (w, vx, vy) 18 WGT_METHOD_POLL void (w, win) 19 WGT_METHOD_QUICK_REPAINT int32_t (w, outY, outH) 20 WGT_METHOD_SCROLL_CHILD_INTO_VIEW void (parent, child) -- WGT_METHOD_COUNT = 21, WGT_METHOD_MAX = 32 .endtable WGT_CLASS_VERSION is bumped on breaking ABI changes. The framework rejects WidgetClassT structs whose version does not match. .h2 Widget Class Dispatch Table .h3 WidgetClassT .code typedef struct WidgetClassT { uint32_t version; uint32_t flags; void *handlers[WGT_METHOD_MAX]; } WidgetClassT; .endcode .table Field Description ----- ----------- version Must equal WGT_CLASS_VERSION at registration flags Bitmask of WCLASS_xxx flags handlers Array of 32 function pointers indexed by WGT_METHOD_xxx .endtable .h2 Size Encoding Constants .table Define Value Description ------ ----- ----------- WGT_SIZE_TYPE_MASK 0xC0000000 Top 2 bits: unit type selector WGT_SIZE_VAL_MASK 0x3FFFFFFF Bottom 30 bits: numeric value WGT_SIZE_PIXELS 0x00000000 Unit tag: pixels WGT_SIZE_CHARS 0x40000000 Unit tag: character widths WGT_SIZE_PERCENT 0x80000000 Unit tag: percentage of parent WGT_WEIGHT_FILL 100 Default "flexible" weight value .endtable .h2 Widget Interface Descriptors .h3 WgtPropDescT Describes a BASIC-exposed property on a widget type. Used by the form runtime and IDE for generic get/set dispatch. .table Field Description ----- ----------- name BASIC property name (e.g. "Caption", "Value") type Data type: WGT_IFACE_STRING, WGT_IFACE_INT, WGT_IFACE_BOOL, WGT_IFACE_FLOAT, or WGT_IFACE_ENUM getFn Getter function pointer (NULL if write-only) setFn Setter function pointer (NULL if read-only) enumNames For WGT_IFACE_ENUM: NULL-terminated array of value names .endtable .h3 WgtMethodDescT Describes an invokable method on a widget type. .table Field Description ----- ----------- name BASIC method name (e.g. "Clear", "SetFocus") sig Calling convention ID (WGT_SIG_xxx) fn Function pointer .endtable .h3 WgtEventDescT Describes an event beyond the standard common set (Click, DblClick, Change, GotFocus, LostFocus). .table Field Description ----- ----------- name Event name (e.g. "Change", "Timer") .endtable .h3 WgtIfaceT Top-level interface descriptor registered by each widget DXE. .table Field Description ----- ----------- basName VB-style name (e.g. "CommandButton"), or NULL props Array of WgtPropDescT propCount Length of props array methods Array of WgtMethodDescT methodCount Length of methods array events Array of WgtEventDescT (extras beyond common set) eventCount Length of events array createSig How to call the widget's create() function (WgtCreateSigE) createArgs Default numeric args for design-time instantiation isContainer true = widget can hold child widgets defaultEvent Default event name for form designer namePrefix Auto-name prefix (NULL = derive from basName) .endtable .h2 Property Data Type Constants .table Define Value Description ------ ----- ----------- WGT_IFACE_STRING 0 const char * WGT_IFACE_INT 1 int32_t WGT_IFACE_BOOL 2 bool WGT_IFACE_FLOAT 3 float WGT_IFACE_ENUM 4 int32_t with named values .endtable .h2 Create Function Signature Constants .table Define Value Form ------ ----- ---- WGT_CREATE_PARENT 0 fn(parent) WGT_CREATE_PARENT_TEXT 1 fn(parent, const char *text) WGT_CREATE_PARENT_INT 2 fn(parent, int32_t) WGT_CREATE_PARENT_INT_INT 3 fn(parent, int32_t, int32_t) WGT_CREATE_PARENT_INT_INT_INT 4 fn(parent, int32_t, int32_t, int32_t) WGT_CREATE_PARENT_INT_BOOL 5 fn(parent, int32_t, bool) WGT_CREATE_PARENT_BOOL 6 fn(parent, bool) WGT_CREATE_PARENT_DATA 7 fn(parent, data, w, h, pitch) -- not auto-creatable .endtable WGT_MAX_CREATE_ARGS is 3. .topic api.dialog .title dvxDlg.h -- Modal Dialogs .toc 1 dvxDlg.h -- Modal Dialogs .index dvxDlg.h .index dvxMessageBox .index dvxFileDialog .index dvxInputBox .index dvxIntInputBox .index dvxChoiceDialog .index dvxPromptSave .index dvxErrorBox .index dvxInfoBox .h1 dvxDlg.h -- Modal Dialogs Pre-built modal dialog boxes that block the caller and run their own event loop via dvxUpdate() until the user dismisses them. Modal dialogs set ctx->modalWindow to prevent input from reaching other windows for the dialog's lifetime. .h2 Message Box Flags Button configurations (low nibble): .table Define Value Description ------ ----- ----------- MB_OK 0x0000 OK button only (default) MB_OKCANCEL 0x0001 OK and Cancel MB_YESNO 0x0002 Yes and No MB_YESNOCANCEL 0x0003 Yes, No, and Cancel MB_RETRYCANCEL 0x0004 Retry and Cancel .endtable Icon types (high nibble, OR with button flags): .table Define Value Description ------ ----- ----------- MB_ICONINFO 0x0010 Information icon MB_ICONWARNING 0x0020 Warning icon MB_ICONERROR 0x0030 Error icon MB_ICONQUESTION 0x0040 Question mark icon .endtable Return values: .table Define Value Button pressed ------ ----- -------------- ID_OK 1 OK ID_CANCEL 2 Cancel or dialog closed ID_YES 3 Yes ID_NO 4 No ID_RETRY 5 Retry .endtable .h2 dvxMessageBox .code int32_t dvxMessageBox(AppContextT *ctx, const char *title, const char *message, int32_t flags); .endcode Display a modal message box. Blocks the caller by running dvxUpdate() in a loop until a button is pressed or the dialog is closed. The window is automatically destroyed on return. .table Parameter Description --------- ----------- ctx Application context title Window title (NULL falls back to a generic default) message Body text flags MB_xxx button + icon flags, OR'd together .endtable Returns: ID_xxx of the button that was pressed. .code // Example: yes/no confirmation int32_t r = dvxMessageBox(ctx, "Save", "Save changes before closing?", MB_YESNOCANCEL | MB_ICONQUESTION); if (r == ID_YES) { saveFile(); } .endcode .h2 dvxErrorBox .code int32_t dvxErrorBox(AppContextT *ctx, const char *title, const char *message); .endcode Convenience wrapper for MB_OK | MB_ICONERROR. Title defaults to "Error" when NULL. .table Parameter Description --------- ----------- ctx Application context title Dialog title, or NULL for "Error" message Error message .endtable Returns: ID_OK. .h2 dvxInfoBox .code int32_t dvxInfoBox(AppContextT *ctx, const char *title, const char *message); .endcode Convenience wrapper for MB_OK | MB_ICONINFO. .table Parameter Description --------- ----------- ctx Application context title Dialog title message Informational message .endtable Returns: ID_OK. .h2 File Dialog .h3 FileFilterT Describes a filter entry in the file dialog's format dropdown. The glob pattern is extracted from inside the parentheses. .table Field Description ----- ----------- label e.g. "Text Files (*.txt)" or "Images (*.bmp;*.png;*.jpg;*.gif)" .endtable .h3 File Dialog Flags .table Define Value Description ------ ----- ----------- FD_OPEN 0x0000 File open dialog (default) FD_SAVE 0x0001 File save dialog (with overwrite prompt) .endtable .h3 dvxFileDialog .code bool dvxFileDialog(AppContextT *ctx, const char *title, int32_t flags, const char *initialDir, const FileFilterT *filters, int32_t filterCount, char *outPath, int32_t outPathSize); .endcode Display a modal file open/save dialog. Shows a directory listing with parent/drive-letter navigation, a filename input, and an optional filter dropdown. .table Parameter Description --------- ----------- ctx Application context title Window title flags FD_OPEN or FD_SAVE initialDir Starting directory (NULL = current working directory) filters Array of FileFilterT, or NULL filterCount Number of filter entries outPath Output buffer for selected path outPathSize Capacity of outPath buffer .endtable Returns: true if the user selected a file, false if cancelled or closed. .h2 Input Boxes .h3 dvxInputBox .code bool dvxInputBox(AppContextT *ctx, const char *title, const char *prompt, const char *defaultText, char *outBuf, int32_t outBufSize); .endcode Display a modal input box with a prompt label, text field, and OK/Cancel buttons. .table Parameter Description --------- ----------- ctx Application context title Window title prompt Prompt label above the input field defaultText Initial text (NULL = empty) outBuf Output buffer outBufSize Capacity of outBuf .endtable Returns: true if OK was pressed, false if cancelled. .h3 dvxIntInputBox .code bool dvxIntInputBox(AppContextT *ctx, const char *title, const char *prompt, int32_t defaultVal, int32_t minVal, int32_t maxVal, int32_t step, int32_t *outVal); .endcode Display a modal integer input box with a spinner (up/down arrows) for clamped numeric input. .table Parameter Description --------- ----------- ctx Application context title Window title prompt Prompt label defaultVal Initial value minVal Minimum allowed value maxVal Maximum allowed value step Increment per arrow click outVal Output: entered value .endtable Returns: true if OK pressed, false if cancelled. .h2 Choice Dialog .h3 dvxChoiceDialog .code bool dvxChoiceDialog(AppContextT *ctx, const char *title, const char *prompt, const char **items, int32_t itemCount, int32_t defaultIdx, int32_t *outIdx); .endcode Display a modal dialog with a listbox of choices. The user picks one item and clicks OK, or cancels. .table Parameter Description --------- ----------- ctx Application context title Window title prompt Prompt label above the list items Array of choice strings itemCount Number of items defaultIdx Initially highlighted item (-1 = none) outIdx Output: selected index .endtable Returns: true if a choice was made, false if cancelled. .h2 Save Prompt Return codes for dvxPromptSave: .table Define Value Action ------ ----- ------ DVX_SAVE_YES 1 Save, then proceed DVX_SAVE_NO 2 Discard, then proceed DVX_SAVE_CANCEL 3 Abort the operation .endtable .h3 dvxPromptSave .code int32_t dvxPromptSave(AppContextT *ctx, const char *title); .endcode Display a canonical "Save changes?" dialog with Yes/No/Cancel buttons and an appropriate question icon. .table Parameter Description --------- ----------- ctx Application context title Document name for message context .endtable Returns: DVX_SAVE_YES, DVX_SAVE_NO, or DVX_SAVE_CANCEL. .topic api.resource .title dvxRes.h -- Resource System .toc 1 dvxRes.h -- Resource System .index dvxRes.h .index Resources .index DvxResHandleT .index dvxResOpen .index dvxResRead .index dvxResFind .index dvxResClose .index dvxResAppend .index dvxResRemove .h1 dvxRes.h -- DXE-Embedded Resource System Resources are appended to DXE3 files (.app, .wgt, .lib) after the normal DXE content. The DXE loader never reads past its own header-specified sections, so the appended resource block is invisible to dlopen. This lets each DXE carry its own icons, localized text, help content, and binary data without separate resource files. .h2 File Layout .code [DXE3 content] -- untouched, loaded by dlopen [resource data entries] -- sequential, variable length [resource directory] -- fixed-size entries (48 bytes each) [footer] -- magic + directory offset + entry count (16 bytes) .endcode Reading starts from the end: seek to EOF - sizeof(footer), verify the magic, then seek to the directory. .h2 Constants .table Define Value Description ------ ----- ----------- DVX_RES_ICON 1 Image data (BMP, PNG, etc.) DVX_RES_TEXT 2 Null-terminated string DVX_RES_BINARY 3 Arbitrary binary data (app-specific) DVX_RES_MAGIC 0x52585644 Footer signature ("DVXR" little-endian) DVX_RES_NAME_MAX 32 Max resource name length including null .endtable .h2 Structures .h3 DvxResDirEntryT Directory entry describing one resource (48 bytes on disk). .table Field Description ----- ----------- name Resource name (up to 32 chars, null-terminated) type DVX_RES_ICON, DVX_RES_TEXT, or DVX_RES_BINARY offset Absolute file offset of the data size Data size in bytes reserved Padding (must be zero) .endtable .h3 DvxResFooterT Footer at the very end of a DXE file with appended resources (16 bytes). .table Field Description ----- ----------- magic DVX_RES_MAGIC dirOffset Absolute file offset of the resource directory entryCount Number of directory entries reserved Padding (must be zero) .endtable .h3 DvxResHandleT Opaque runtime handle representing an open resource block. .table Field Description ----- ----------- path Source file path entries Directory entries (sorted by name for bsearch) entryCount Number of entries .endtable .h2 Runtime API .h3 dvxResOpen .code DvxResHandleT *dvxResOpen(const char *path); .endcode Open a resource handle by reading the footer and directory. Returns NULL if the file has no resource block or cannot be read. Entries are sorted on open for O(log n) name lookup via bsearch. .table Parameter Description --------- ----------- path Path to the DXE (or any file) with appended resources .endtable Returns: Handle pointer, or NULL. .h3 dvxResRead .code void *dvxResRead(DvxResHandleT *h, const char *name, uint32_t *outSize); .endcode Find a resource by name and read its data into a freshly malloc'd buffer. Caller must free the returned buffer. .table Parameter Description --------- ----------- h Resource handle name Resource name outSize Output: data size in bytes .endtable Returns: Data buffer, or NULL if not found or I/O failed. .h3 dvxResFind .code const DvxResDirEntryT *dvxResFind(DvxResHandleT *h, const char *name); .endcode Look up a resource's directory entry by name. The returned pointer is valid until dvxResClose. .table Parameter Description --------- ----------- h Resource handle name Resource name .endtable Returns: Pointer to directory entry, or NULL if not found. .h3 dvxResClose .code void dvxResClose(DvxResHandleT *h); .endcode Close a resource handle and free its memory. .table Parameter Description --------- ----------- h Handle to close .endtable .h3 dvxResAppend .code int32_t dvxResAppend(const char *path, const char *name, uint32_t type, const void *data, uint32_t dataSize); .endcode Append a resource to an existing DXE file. Preserves existing resources and adds the new one. Thin wrapper over the resource writer in tools/dvxResWrite.h. .table Parameter Description --------- ----------- path Target DXE path name Resource name (up to DVX_RES_NAME_MAX - 1 chars) type DVX_RES_ICON, DVX_RES_TEXT, or DVX_RES_BINARY data Resource payload dataSize Payload size in bytes .endtable Returns: 0 on success, -1 on failure. .h3 dvxResRemove .code int32_t dvxResRemove(const char *path, const char *name); .endcode Remove a resource from a DXE file by name. If this was the last resource, the file is truncated back to the original DXE content. .table Parameter Description --------- ----------- path Target DXE path name Resource name to remove .endtable Returns: 0 on success, -1 if not found or I/O failed. .h2 See Also .link api.app dvxResLoadIcon / dvxResLoadText / dvxResLoadData -- higher-level helpers on top of this API .topic api.prefs .title dvxPrefs.h -- Preferences System .toc 1 dvxPrefs.h -- Preferences System .index dvxPrefs.h .index Preferences .index PrefsHandleT .index prefsLoad .index prefsSave .index prefsGetString .index prefsGetInt .index prefsGetBool .index prefsSetString .index prefsSetInt .index prefsSetBool .h1 dvxPrefs.h -- INI Preferences System Handle-based API over classic INI files. Each prefsLoad/prefsCreate returns a PrefsHandleT that must be passed to all subsequent calls and freed with prefsClose when done. Multiple INI files can be open simultaneously. .h2 Constants .table Define Value Description ------ ----- ----------- DVX_INI_PATH "CONFIG" DVX_PATH_SEP "DVX.INI" Canonical system INI path .endtable .h2 Types .h3 PrefsHandleT Opaque handle representing an in-memory INI file. Fields are not exposed. .h2 Lifecycle .h3 prefsCreate .code PrefsHandleT *prefsCreate(void); .endcode Create an empty preferences handle with no associated file. Use this when building an INI from scratch before calling prefsSaveAs. Returns: New handle, or NULL on allocation failure. .h3 prefsLoad .code PrefsHandleT *prefsLoad(const char *filename); .endcode Load an INI file into a new handle. If the file does not exist, returns a valid empty handle with the path stored so prefsSave can write a new file later. .table Parameter Description --------- ----------- filename Path to INI file .endtable Returns: Handle, or NULL on allocation failure. .h3 prefsSave .code bool prefsSave(PrefsHandleT *h); .endcode Save the in-memory state back to the file that was loaded (or captured by prefsLoad for a non-existent file). .table Parameter Description --------- ----------- h Preferences handle .endtable Returns: true on success. .h3 prefsSaveAs .code bool prefsSaveAs(PrefsHandleT *h, const char *filename); .endcode Save to a specific file, overriding the handle's stored path. .table Parameter Description --------- ----------- h Preferences handle filename Output file path .endtable Returns: true on success. .h3 prefsClose .code void prefsClose(PrefsHandleT *h); .endcode Release all memory held by the handle. Does not save -- call prefsSave first if needed. .table Parameter Description --------- ----------- h Handle to close .endtable .h2 Getters .h3 prefsGetString .code const char *prefsGetString(PrefsHandleT *h, const char *section, const char *key, const char *defaultVal); .endcode Retrieve a string value from [section]/key. The returned pointer is valid until the key is modified or the handle is closed. .table Parameter Description --------- ----------- h Preferences handle section Section name (without brackets) key Key name defaultVal Returned if the key is not present .endtable Returns: Key value or defaultVal. .h3 prefsGetInt .code int32_t prefsGetInt(PrefsHandleT *h, const char *section, const char *key, int32_t defaultVal); .endcode Retrieve an integer value. Supports decimal and negative numbers. .table Parameter Description --------- ----------- h Preferences handle section Section name key Key name defaultVal Returned if the key is absent or non-numeric .endtable Returns: Parsed int, or defaultVal. .h3 prefsGetBool .code bool prefsGetBool(PrefsHandleT *h, const char *section, const char *key, bool defaultVal); .endcode Retrieve a boolean value. Recognises "true"/"yes"/"1" as true and "false"/"no"/"0" as false (case-insensitive). .table Parameter Description --------- ----------- h Preferences handle section Section name key Key name defaultVal Returned if the key is absent or unrecognised .endtable Returns: Parsed bool, or defaultVal. .h2 Setters .h3 prefsSetString .code void prefsSetString(PrefsHandleT *h, const char *section, const char *key, const char *value); .endcode Set a string value. Creates the section and key if they do not already exist. .h3 prefsSetInt .code void prefsSetInt(PrefsHandleT *h, const char *section, const char *key, int32_t value); .endcode Set an integer value (stored in decimal). .h3 prefsSetBool .code void prefsSetBool(PrefsHandleT *h, const char *section, const char *key, bool value); .endcode Set a boolean value (stored as "true"/"false"). .h3 prefsRemove .code void prefsRemove(PrefsHandleT *h, const char *section, const char *key); .endcode Remove a key from a section. No-op if the key does not exist. .topic api.mem .title dvxMem.h -- Memory Tracking .toc 1 dvxMem.h -- Memory Tracking .index dvxMem.h .index dvxMalloc .index dvxFree .index dvxCalloc .index dvxRealloc .index dvxStrdup .index dvxMemGetAppUsage .index dvxMemResetApp .h1 dvxMem.h -- Per-App Memory Tracking Wraps malloc/free/calloc/realloc/strdup with a 16-byte header that records the owning app ID and allocation size. The Task Manager displays per-app memory usage, and leaks are detected when an app is terminated. DXE code does NOT need to include this header for tracking to work. The DXE export table maps malloc/free/calloc/realloc/strdup to these wrappers transparently. Call sites that need the explicit dvxXxx names (e.g. dvxMemGetAppUsage) or the dvxMemAppIdPtr declaration should include dvxMem.h directly. .h2 Globals .h3 dvxMemAppIdPtr .code extern int32_t *dvxMemAppIdPtr; .endcode Pointer to the current owning app ID. The shell points this at its currentAppId field during init so every allocation is charged to the running app. When dvxMemAppIdPtr is NULL or points to zero, allocations are charged to the shell. .h2 Allocation Wrappers .h3 dvxMalloc .code void *dvxMalloc(size_t size); .endcode Tracked malloc. Returns a pointer to user memory (header is hidden in front of it). .h3 dvxCalloc .code void *dvxCalloc(size_t nmemb, size_t size); .endcode Tracked calloc. .h3 dvxRealloc .code void *dvxRealloc(void *ptr, size_t size); .endcode Tracked realloc. Works correctly with tracked pointers only -- the magic header identifies them. .h3 dvxFree .code void dvxFree(void *ptr); .endcode Tracked free. Falls through to the real free() if the pointer's header magic does not match, so mixing tracked and untracked pointers is safe. .h3 dvxStrdup .code char *dvxStrdup(const char *s); .endcode Tracked strdup. .h2 Accounting .h3 dvxMemGetAppUsage .code uint32_t dvxMemGetAppUsage(int32_t appId); .endcode Return the total bytes currently charged to the given app ID. .table Parameter Description --------- ----------- appId App ID to query .endtable Returns: Bytes allocated for this app. .h3 dvxMemResetApp .code void dvxMemResetApp(int32_t appId); .endcode Free every tracked allocation charged to the given app. Called by the shell after an app exits or crashes to reclaim its memory. .table Parameter Description --------- ----------- appId App ID to flush .endtable .topic api.widgetplugin .title dvxWgtP.h -- Widget Plugin API .toc 1 dvxWgtP.h -- Widget Plugin API .index dvxWgtP.h .index widgetAlloc .index widgetAddChild .index widgetDestroyChildren .index widgetHitTest .index widgetFindNextFocusable .index widgetFindPrevFocusable .index widgetFindByAccel .index widgetDrawScrollbarH .index widgetDrawScrollbarV .h1 dvxWgtP.h -- Widget Plugin API Included by widget .c files (DXE modules) to access core infrastructure for tree manipulation, focus management, scrollbar drawing, layout helpers, and shared interaction state. This header is NOT intended for application code -- use dvxWgt.h for the public widget API. .h2 Validation Macros .h3 VALIDATE_WIDGET / VALIDATE_WIDGET_VOID .code VALIDATE_WIDGET(w, wtype, retval); // returns retval on mismatch VALIDATE_WIDGET_VOID(w, wtype); // returns void on mismatch .endcode Bail out of a widget method if the widget pointer is NULL or its type does not match the expected wtype. Use at the top of every widget-specific API function. .h2 Core Constants .table Define Value Description ------ ----- ----------- DEFAULT_SPACING 4 Default pixel spacing between VBox/HBox children DEFAULT_PADDING 4 Default internal padding for containers SB_MIN_THUMB 14 Minimum scrollbar thumb size in pixels WGT_SB_W 14 Widget-internal scrollbar width KEY_MOD_SHIFT 0x03 Shift modifier bits KEY_MOD_CTRL 0x04 Ctrl modifier bit KEY_MOD_ALT 0x08 Alt modifier bit .endtable .h2 Inline Helpers .h3 clampInt .code static inline int32_t clampInt(int32_t val, int32_t lo, int32_t hi); .endcode Clamp val into the [lo, hi] range. .h3 drawTextEmbossed .code static inline void drawTextEmbossed(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, const ColorSchemeT *colors); .endcode Draw text twice -- once offset by (1,1) in highlight color, then overlaid in shadow color at (x,y) -- for a classic Motif-style embossed look used on disabled labels. .h3 drawTextAccelEmbossed .code static inline void drawTextAccelEmbossed(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, const ColorSchemeT *colors); .endcode Embossed text with & accelerator markers. Same offset logic as drawTextEmbossed, but processes & markers. .h2 Shared Interaction State Extern variables defined in widgetCore.c. These hold system-wide widget state: only one focused widget, one open popup, one pressed button at a time. .table Variable Type Purpose -------- ---- ------- sCursorBlinkOn bool Current state of the text cursor blink sDblClickTicks clock_t Double-click interval in clock() ticks sDebugLayout bool When true, draw colored debug borders around containers sClosedPopup WidgetT* Widget whose popup just closed (suppresses re-open) sFocusedWidget WidgetT* Currently focused widget sKeyPressedBtn WidgetT* Button being pressed via keyboard (for release tracking) sOpenPopup WidgetT* Currently open popup (dropdown/combo list) sDragWidget WidgetT* Widget being dragged (any drag type) sPollWidgets WidgetT** Dynamic array of poll widgets (stb_ds) sCursorBlinkFn fn ptr Callback invoked when the blink flips (repaints focused text) .endtable .h2 Core Widget Functions .h3 widgetAlloc .code WidgetT *widgetAlloc(WidgetT *parent, int32_t type); .endcode Allocate a new WidgetT, initialize its fields to defaults, link it as the last child of parent (if non-NULL), and assign its class pointer from widgetClassTable[type]. .h3 widgetAddChild .code void widgetAddChild(WidgetT *parent, WidgetT *child); .endcode Append child to parent's child list. Updates parent's firstChild/lastChild and child's nextSibling pointers. .h3 widgetRemoveChild .code void widgetRemoveChild(WidgetT *parent, WidgetT *child); .endcode Unlink child from parent's child list. Does not destroy the child. .h3 widgetDestroyChildren .code void widgetDestroyChildren(WidgetT *w); .endcode Recursively destroy all descendants of w, calling each one's wclsDestroy handler. .h2 Focus Management .h3 widgetFindNextFocusable .code WidgetT *widgetFindNextFocusable(WidgetT *root, WidgetT *after); .endcode Find the next focusable widget in tab order after the given widget. Wraps to the beginning at the end of the tree. .h3 widgetFindPrevFocusable .code WidgetT *widgetFindPrevFocusable(WidgetT *root, WidgetT *before); .endcode Find the previous focusable widget in tab order. Wraps to the end at the beginning of the tree. .h3 widgetFindByAccel .code WidgetT *widgetFindByAccel(WidgetT *root, char key); .endcode Find a focusable widget whose accelKey (lowercase) matches the given character. Used for Alt+letter hotkeys on buttons and labels. .h2 Hit Testing .h3 widgetHitTest .code WidgetT *widgetHitTest(WidgetT *w, int32_t x, int32_t y); .endcode Find the deepest widget at (x, y) within w's subtree. Respects WCLASS_NO_HIT_RECURSE so certain widget types can prevent children from being hit-tested. .h2 Utility Queries .h3 widgetCountVisibleChildren .code int32_t widgetCountVisibleChildren(const WidgetT *w); .endcode Count children whose visible flag is true. .h3 widgetFrameBorderWidth .code int32_t widgetFrameBorderWidth(const WidgetT *w); .endcode Return the effective border width for a container widget (used to inset child layout). .h3 widgetIsFocusable .code bool widgetIsFocusable(int32_t type); .endcode True if the widget class with this type ID has the WCLASS_FOCUSABLE flag. .h3 widgetIsHorizContainer .code bool widgetIsHorizContainer(int32_t type); .endcode True if the widget class lays out children horizontally (WCLASS_HORIZ_CONTAINER). .h3 multiClickDetect .code int32_t multiClickDetect(int32_t vx, int32_t vy); .endcode Track consecutive clicks at roughly the same position within sDblClickTicks. Returns the current click count (1 for single, 2 for double, etc.). .h2 Clipboard .h3 clipboardCopy .code void clipboardCopy(const char *text, int32_t len); .endcode Copy text to the process-wide clipboard buffer. Same underlying storage as dvxClipboardCopy. .h3 clipboardGet .code const char *clipboardGet(int32_t *outLen); .endcode Retrieve clipboard text. .h2 Scrollbar Helpers .h3 ScrollHitE Scrollbar hit-test result. .table Value Description ----- ----------- ScrollHitNoneE Click fell outside the scrollbar ScrollHitArrowDecE Up/left arrow ScrollHitArrowIncE Down/right arrow ScrollHitPageDecE Trough above/before the thumb ScrollHitPageIncE Trough below/after the thumb ScrollHitThumbE The draggable thumb .endtable .h3 widgetScrollbarThumb .code void widgetScrollbarThumb(int32_t trackLen, int32_t totalSize, int32_t visibleSize, int32_t scrollPos, int32_t *thumbPos, int32_t *thumbSize); .endcode Compute thumb position and size for a scrollbar with the given geometry. Enforces SB_MIN_THUMB. .h3 widgetDrawScrollbarV / widgetDrawScrollbarVEx .code void widgetDrawScrollbarV(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t sbX, int32_t sbY, int32_t sbH, int32_t totalSize, int32_t visibleSize, int32_t scrollPos); void widgetDrawScrollbarVEx(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t sbX, int32_t sbY, int32_t sbH, int32_t totalSize, int32_t visibleSize, int32_t scrollPos, int32_t barW); .endcode Draw a vertical scrollbar inside a widget. The Ex variant lets the caller specify bar width for non-standard scrollbars (e.g. combo popups). Standard variant uses WGT_SB_W. .h3 widgetDrawScrollbarH / widgetDrawScrollbarHEx .code void widgetDrawScrollbarH(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t sbX, int32_t sbY, int32_t sbW, int32_t totalSize, int32_t visibleSize, int32_t scrollPos); void widgetDrawScrollbarHEx(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, int32_t sbX, int32_t sbY, int32_t sbW, int32_t totalSize, int32_t visibleSize, int32_t scrollPos, int32_t barW); .endcode Draw a horizontal scrollbar inside a widget. Standard variant uses WGT_SB_W. .h3 widgetScrollbarHitTest .code ScrollHitE widgetScrollbarHitTest(int32_t sbLen, int32_t relPos, int32_t totalSize, int32_t visibleSize, int32_t scrollPos); .endcode Classify a click position along a scrollbar into ScrollHitE. sbLen is the scrollbar length, relPos is the click position along the bar. .h2 Layout Functions .h3 widgetCalcMinSizeBox / widgetCalcMinSizeTree .code void widgetCalcMinSizeBox(WidgetT *w, const BitmapFontT *font); void widgetCalcMinSizeTree(WidgetT *w, const BitmapFontT *font); .endcode Generic box-container min-size calculation (bottom-up layout pass). widgetCalcMinSizeBox handles a single VBox/HBox; widgetCalcMinSizeTree recurses through the whole subtree. .h3 widgetLayoutBox / widgetLayoutChildren .code void widgetLayoutBox(WidgetT *w, const BitmapFontT *font); void widgetLayoutChildren(WidgetT *w, const BitmapFontT *font); .endcode Generic box-container layout (top-down pass). widgetLayoutBox lays out a single container; widgetLayoutChildren processes each child's layout handler. .h2 Event Dispatch .h3 widgetOnPaint / widgetOnMouse / widgetOnKey / etc. .code void widgetOnPaint(WindowT *win, RectT *dirtyArea); void widgetOnMouse(WindowT *win, int32_t x, int32_t y, int32_t buttons); void widgetOnKey(WindowT *win, int32_t key, int32_t mod); void widgetOnKeyUp(WindowT *win, int32_t scancode, int32_t mod); void widgetOnResize(WindowT *win, int32_t newW, int32_t newH); void widgetOnScroll(WindowT *win, ScrollbarOrientE orient, int32_t value); void widgetOnFocus(WindowT *win); void widgetOnBlur(WindowT *win); .endcode Window-level event handlers that dispatch to individual widgets in the tree. wgtInitWindow installs these as the window's onPaint/onMouse/onKey/etc. callbacks. .h3 widgetManageScrollbars .code void widgetManageScrollbars(WindowT *win, AppContextT *ctx); .endcode Add, remove, or resize window scrollbars based on the widget tree's current min-size vs. the window content area. .h2 Paint Helpers .h3 widgetPaintOne .code void widgetPaintOne(WidgetT *w, DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors); .endcode Paint a single widget (sets clip rect, calls the widget's PAINT handler). Does not recurse. .h3 widgetPaintOverlays .code void widgetPaintOverlays(WidgetT *root, DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors); .endcode Paint the overlay pass: dropdown popups and tooltips drawn on top of the main tree. .h2 Pressable Button Helpers Shared state machine for WCLASS_PRESS_RELEASE widgets (Button, ImageButton). The w->pressed flag tracks the visual state; these helpers fire the widget's onClick callback on release-within-bounds. .h3 widgetPressableOnMouse / widgetPressableOnKey / widgetPressableOnDragUpdate / widgetPressableOnDragEnd / widgetPressableOnAccelActivate .code void widgetPressableOnMouse(WidgetT *w, WidgetT *root, int32_t vx, int32_t vy); void widgetPressableOnKey(WidgetT *w, int32_t key, int32_t mod); void widgetPressableOnDragUpdate(WidgetT *w, WidgetT *root, int32_t x, int32_t y); void widgetPressableOnDragEnd(WidgetT *w, WidgetT *root, int32_t x, int32_t y); void widgetPressableOnAccelActivate(WidgetT *w, WidgetT *root); .endcode Register these directly as the widget class's handlers for WGT_METHOD_ON_MOUSE, WGT_METHOD_ON_KEY, WGT_METHOD_ON_DRAG_UPDATE, WGT_METHOD_ON_DRAG_END, and WGT_METHOD_ON_ACCEL_ACTIVATE. .h2 Generic Text Handlers For widgets whose data struct has a (const char *) as its first field and the WCLASS_HAS_TEXT flag set, these implement GET_TEXT / SET_TEXT directly. .h3 widgetTextGet / widgetTextSet .code const char *widgetTextGet(const WidgetT *w); void widgetTextSet(WidgetT *w, const char *text); .endcode Register these directly as the widget class's handlers for WGT_METHOD_GET_TEXT and WGT_METHOD_SET_TEXT. The text is strdup'd on set and freed automatically on destroy. .h2 Class Table .h3 widgetClassTable .code extern const WidgetClassT **widgetClassTable; .endcode stb_ds dynamic array. Each widget DXE appends its class pointer via wgtRegisterClass() during wgtRegister(). Indexed by the runtime type ID assigned at registration. .topic api.platform .title platform/dvxPlat.h -- Platform Layer .toc 1 platform/dvxPlat.h -- Platform Layer .index dvxPlat.h .index Platform Layer .index PlatformKeyEventT .index platformVideoInit .index platformFlushRect .index platformMousePoll .index platformKeyboardRead .index dvxLog .h1 platform/dvxPlat.h -- Platform Abstraction Layer All OS-specific and CPU-specific code is isolated behind this interface. Port DVX to a new platform by implementing a new dvxPlatformXxx.c against this header. Currently the only implementation is dvxPlatformDos.c for DJGPP/DPMI. Platform functions must be stateless (or manage their own internal state) and must not reference AppContextT or any layer above dvxTypes.h. .h2 Constants .table Define Value Description ------ ----- ----------- DVX_MAX_PATH 260 Maximum file path length PLATFORM_SYSINFO_MAX 4096 Maximum size of formatted system info text DVX_PATH_SEP "\\" Native directory separator on DOS .endtable .h2 Types .h3 PlatformKeyEventT Keyboard event with ASCII and scancode separated. Extended keys (arrows, F-keys) have ascii == 0 and a non-zero scancode. .table Field Description ----- ----------- ascii ASCII value, 0 for extended/function keys scancode PC scancode (e.g. 0x48 = Up, 0x50 = Down) .endtable .h3 PlatformLogFnT .code typedef void (*PlatformLogFnT)(const char *fmt, ...); .endcode Log function signature used by the crash handler. .h3 PlatformSymOverrideT Name/function-pointer pair for registering symbol overrides with the DXE loader. .table Field Description ----- ----------- name Symbol name as seen by DXEs func Function pointer to use instead of the default .endtable .h2 Lifecycle .h3 dvxLog .code void dvxLog(const char *fmt, ...); .endcode Append a formatted line to dvx.log. Implemented in dvx.exe and exported to every DXE via the loader. .h3 platformInit .code void platformInit(void); .endcode One-time platform initialization. On DOS this installs signal handlers for clean shutdown on Ctrl+C/Ctrl+Break. .h3 platformYield .code void platformYield(void); .endcode Cooperative CPU yield, used between frames when the event loop has nothing to do. On DOS this calls __dpmi_yield() to be friendly to multitaskers. .h2 Video .h3 platformVideoInit / platformVideoShutdown .code int32_t platformVideoInit(DisplayT *d, int32_t requestedW, int32_t requestedH, int32_t preferredBpp); void platformVideoShutdown(DisplayT *d); .endcode Low-level video mode setup and teardown. Called by videoInit / videoShutdown. .h3 platformVideoEnumModes .code void platformVideoEnumModes(void (*cb)(int32_t w, int32_t h, int32_t bpp, void *userData), void *userData); .endcode Enumerate LFB-capable graphics modes. Invokes cb once per available mode. .h3 platformVideoSetPalette .code void platformVideoSetPalette(const uint8_t *pal, int32_t firstEntry, int32_t count); .endcode Program the VGA/VESA DAC palette registers (8-bit mode only). .h3 platformVideoFreeBuffers .code void platformVideoFreeBuffers(DisplayT *d); .endcode Free the backbuffer and palette without restoring text mode. Used when switching between graphics modes live. .h2 Framebuffer Flush .h3 platformFlushRect .code void platformFlushRect(const DisplayT *d, const RectT *r); .endcode Copy a rectangle from the system RAM backbuffer to the LFB. The single critical path where PCI bus write speed matters. On DOS, each scanline uses rep movsd for aligned 32-bit writes. .h2 Span Operations .h3 platformSpanFill8/16/32 .code void platformSpanFill8(uint8_t *dst, uint32_t color, int32_t count); void platformSpanFill16(uint8_t *dst, uint32_t color, int32_t count); void platformSpanFill32(uint8_t *dst, uint32_t color, int32_t count); .endcode Fill count pixels at dst with color. Three depth variants because the fill instruction differs by size. On DOS these use inline rep stosl / rep stosw / rep stosb asm. .h3 platformSpanCopy8/16/32 .code void platformSpanCopy8(uint8_t *dst, const uint8_t *src, int32_t count); void platformSpanCopy16(uint8_t *dst, const uint8_t *src, int32_t count); void platformSpanCopy32(uint8_t *dst, const uint8_t *src, int32_t count); .endcode Copy count pixels from src to dst. On DOS these use rep movsd. .h2 Mouse Input .h3 platformMouseInit .code void platformMouseInit(int32_t screenW, int32_t screenH); .endcode Initialize the mouse driver and constrain movement to the screen bounds. .h3 platformMousePoll .code void platformMousePoll(int32_t *mx, int32_t *my, int32_t *buttons); .endcode Poll current mouse state. Buttons is a bitmask: bit 0 = left, bit 1 = right, bit 2 = middle. .h3 platformMouseWheelInit / platformMouseWheelPoll .code bool platformMouseWheelInit(void); int32_t platformMouseWheelPoll(void); .endcode Detect and activate the CuteMouse Wheel API. platformMouseWheelPoll returns the accumulated delta (positive = scroll down) since the last poll. .h3 platformMouseSetAccel / platformMouseSetMickeys .code void platformMouseSetAccel(int32_t threshold); void platformMouseSetMickeys(int32_t horizMickeys, int32_t vertMickeys); .endcode Set the double-speed threshold and mickey-to-pixel ratio. See dvxSetMouseConfig for a higher-level interface. .h3 platformMouseWarp .code void platformMouseWarp(int32_t x, int32_t y); .endcode Move the mouse cursor to an absolute screen position. Used to clamp the cursor to window edges during resize. .h2 Keyboard Input .h3 platformKeyboardGetModifiers .code int32_t platformKeyboardGetModifiers(void); .endcode Return the current modifier key state in BIOS shift-state format. .h3 platformKeyboardRead .code bool platformKeyboardRead(PlatformKeyEventT *evt); .endcode Non-blocking read of the next key from the keyboard buffer. Returns true if a key was available. .h3 platformKeyUpInit / platformKeyUpShutdown / platformKeyUpRead .code void platformKeyUpInit(void); void platformKeyUpShutdown(void); bool platformKeyUpRead(PlatformKeyEventT *evt); .endcode Key-up event detection. Install/uninstall the INT 9 hook around process lifetime. platformKeyUpRead returns true if a key release was detected since the last call. .h3 platformAltScanToChar .code char platformAltScanToChar(int32_t scancode); .endcode Translate an Alt+key scancode to its corresponding ASCII character. Returns 0 for non-printable scancodes. .h2 System Information .h3 platformGetSystemInfo .code const char *platformGetSystemInfo(const DisplayT *display); .endcode Return a pre-formatted text string with hardware/OS information (CPU, clock, memory, video, mouse, disks). Valid for the lifetime of the process. .h3 platformGetMemoryInfo .code bool platformGetMemoryInfo(uint32_t *totalKb, uint32_t *freeKb); .endcode Query total and free physical memory. .h2 File System .h3 platformValidateFilename .code const char *platformValidateFilename(const char *name); .endcode Validate a filename against platform-specific rules (8.3 on DOS). Returns NULL if valid, or a human-readable error string. .h3 platformMkdirRecursive .code int32_t platformMkdirRecursive(const char *path); .endcode Create a directory and all parent directories (like mkdir -p). Existing directories are not an error. .h3 platformChdir .code int32_t platformChdir(const char *path); .endcode Change the working directory, including drive letter on DOS (calls setdisk() first when the path starts with "X:"). .h3 platformPathDirEnd .code char *platformPathDirEnd(const char *path); .endcode Return a pointer to the last directory separator in path, or NULL. On DOS accepts both "/" and "\\". .h3 platformPathBaseName .code const char *platformPathBaseName(const char *path); .endcode Return a pointer to the leaf (basename) portion of path. .h3 platformCopyFile .code bool platformCopyFile(const char *srcPath, const char *dstPath); .endcode Byte-for-byte file copy. Returns false on any open, read, or write failure; a partially written destination is removed so no truncated copy is left behind. .h3 platformReadFile .code char *platformReadFile(const char *path, int32_t *outLen); .endcode Slurp a whole file into a freshly malloc'd, NUL-terminated buffer. Caller frees. Binary-safe: the NUL is past the end of the reported length. .h3 platformGlobMatch .code bool platformGlobMatch(const char *pattern, const char *name); .endcode Simple glob pattern match. Case-insensitive. Supports * (zero or more chars) and ? (single char). .h3 platformLineEnding / platformStripLineEndings .code const char *platformLineEnding(void); int32_t platformStripLineEndings(char *buf, int32_t len); .endcode Return the native line ending string, or strip line-ending characters from a buffer in place. .h2 String Helpers .h3 dvxSkipWs .code const char *dvxSkipWs(const char *s); .endcode Advance past leading spaces and tabs. Returns s unchanged if NULL or already non-whitespace. .h3 dvxTrimRight .code int32_t dvxTrimRight(char *buf); .endcode Strip trailing spaces, tabs, carriage returns, and newlines from buf in place. Returns the new length. .h2 DXE Module Support .h3 platformRegisterDxeExports .code void platformRegisterDxeExports(void); .endcode Register platform and C runtime symbols with the dynamic module loader so DXE modules can resolve them at load time. .h3 platformRegisterSymOverrides .code void platformRegisterSymOverrides(const PlatformSymOverrideT *entries); .endcode Register function pointer overrides for subsequently loaded modules. entries is terminated by {NULL, NULL}. .h2 Crash Recovery .h3 platformInstallCrashHandler .code void platformInstallCrashHandler(jmp_buf *recoveryBuf, volatile int *crashSignal, PlatformLogFnT logFn); .endcode Install signal handlers for SIGSEGV, SIGFPE, SIGILL. On crash, logs platform-specific diagnostics via logFn, stores the signal in *crashSignal, then longjmps to recoveryBuf. .h3 platformLogCrashDetail .code void platformLogCrashDetail(int sig, PlatformLogFnT logFn); .endcode Log platform-specific crash diagnostics. Called internally from the crash handler and exposed for manual invocation. .h2 VGA Splash Screen .h3 platformSplashInit / platformSplashShutdown .code void platformSplashInit(void); void platformSplashShutdown(void); .endcode Enter/leave VGA mode 13h (320x200x256) used for the boot splash. .h3 platformSplashLoadRaw .code bool platformSplashLoadRaw(const char *path); .endcode Load and display a raw splash file (768-byte palette + 64000-byte pixel data). .h3 platformSplashFillRect .code void platformSplashFillRect(int32_t x, int32_t y, int32_t w, int32_t h, uint8_t color); .endcode Fill a rectangle on the mode 13h screen with a palette index. Used to draw the progress bar during module loading.