AI_Slop/DVX_GUI
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
DVX_GUI/core/apiref.dhs

3500 lines
92 KiB
Text
Raw Blame History

.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 generated from source headers.
The DVX GUI is built as a five-layer architecture. Each layer is defined in its own header file. This reference covers every public function, type, and constant.
.h2 Layers
.list
.item dvxTypes.h -- Shared type definitions
.item dvxCursor.h -- Cursor definitions
.item dvxVideo.h -- Layer 1: VESA VBE Video Backend
.item dvxDraw.h -- Layer 2: 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 dvxWidget.h -- Widget System
.endlist
.link api.types dvxTypes.h -- Shared Type Definitions
.link api.cursor dvxCursor.h -- Cursor Definitions
.link api.video dvxVideo.h -- Layer 1: VESA VBE Video Backend
.link api.draw dvxDraw.h -- Layer 2: Drawing Primitives
.link api.comp dvxComp.h -- Layer 3: Dirty Rectangle Compositor
.link api.wm dvxWm.h -- Layer 4: Window Manager
.link api.app dvxApp.h -- Layer 5: Application API
.link api.widget dvxWidget.h -- Widget System
.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 (14 or 16)
int32_t firstChar ASCII code of first glyph (typically 0)
int32_t numChars Number of glyphs (typically 256)
const uint8_t *glyphData Packed 1bpp data, charHeight bytes per glyph
.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 contentDirty true when contentBuf has changed
bool needsPaint true until first onPaint call
int32_t maxW, maxH Maximum dimensions
int32_t preMaxX, preMaxY, preMaxW, preMaxH Saved geometry before maximize
uint8_t *contentBuf Per-window content backbuffer
int32_t contentPitch Content buffer bytes per row
uint8_t *iconData Icon pixel data, NULL if none
int32_t iconW, iconH, iconPitch Icon image dimensions and pitch
MenuBarT *menuBar Menu bar (NULL if no menus)
ScrollbarT *vScroll, *hScroll Scrollbars (NULL if not present)
struct WidgetT *widgetRoot Widget tree root (NULL if none)
MenuT *contextMenu Right-click context menu
AccelTableT *accelTable Keyboard accelerator table
void *userData Application-defined data pointer
.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 btn) Mouse event (content-relative)
onResize(WindowT *win, int32_t newW, int32_t newH) Window resized
onClose(WindowT *win) Close requested
onMenu(WindowT *win, int32_t menuId) Menu item or accelerator activated
onScroll(WindowT *win, ScrollbarOrientE orient, int32_t val) Scrollbar value changed
onCursorQuery(WindowT *win, int32_t x, int32_t y) Return CURSOR_* for hit position
onFocus(WindowT *win) Window gained focus
onBlur(WindowT *win) Window lost focus
.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 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.subMenu Child menu for cascading (NULL if leaf)
MenuBarT.activeIdx Open popup index (-1 = none)
.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
.endtable
.h3 VideoModeInfoT
Describes an available video mode (enumerated at init).
.table
Field Description
----- -----------
int32_t w, h Resolution
int32_t bpp Bits per pixel
.endtable
.h3 CursorT
Software-rendered 16x16 cursor using AND/XOR mask encoding.
.table
Field Description
----- -----------
int32_t width, height Cursor dimensions (always 16x16)
int32_t hotX, hotY Hot spot coordinates
const uint16_t *andMask AND mask (0 = draw pixel, 1 = transparent)
const uint16_t *xorData XOR data (0 = black, 1 = white where AND = 0)
.endtable
.h2 Bevel Convenience Macros
.table
Macro Description
----- -----------
BEVEL_RAISED(cs, bw) Raised bevel style from ColorSchemeT ptr and border width
BEVEL_SUNKEN(cs, face, bw) Sunken bevel style with explicit face color
BEVEL_TROUGH(cs) 1px sunken trough (for scrollbar tracks)
BEVEL_SB_BUTTON(cs) 1px raised scrollbar button
.endtable
.h2 Chrome Constants
.table
Define Value Description
------ ----- -----------
CHROME_BORDER_WIDTH 4 Outer frame border width
CHROME_TITLE_HEIGHT 20 Title bar height
CHROME_TITLE_PAD 4 Title text padding
CHROME_INNER_BORDER 2 Inner chrome border
CHROME_MENU_HEIGHT 20 Menu bar height
CHROME_TOTAL_TOP 26 Total inset from top of frame to content
CHROME_TOTAL_SIDE 6 Total inset from side of frame to content
CHROME_TOTAL_BOTTOM 6 Total inset from bottom of frame to content
CHROME_CLOSE_BTN_SIZE 16 Close button gadget size
.endtable
.h2 Hit Test Constants
.table
Define Value Description
------ ----- -----------
HIT_CONTENT 0 Content area
HIT_TITLE 1 Title bar
HIT_CLOSE 2 Close gadget
HIT_RESIZE 3 Resize border
HIT_MENU 4 Menu bar
HIT_VSCROLL 5 Vertical scrollbar
HIT_HSCROLL 6 Horizontal scrollbar
HIT_MINIMIZE 7 Minimize gadget
HIT_MAXIMIZE 8 Maximize gadget
HIT_NONE -1 No window hit (desktop)
.endtable
.h2 Mouse Button Flags
.table
Define Value Description
------ ----- -----------
MOUSE_LEFT 1 Left mouse button
MOUSE_RIGHT 2 Right mouse button
MOUSE_MIDDLE 4 Middle mouse button
.endtable
.h2 Accelerator Modifier Flags
.table
Define Value Description
------ ----- -----------
ACCEL_SHIFT 0x03 Shift key (matches BIOS shift state bits)
ACCEL_CTRL 0x04 Ctrl key
ACCEL_ALT 0x08 Alt key
.endtable
.h2 Extended Key Codes
.table
Define Description
------ -----------
KEY_F1 .. KEY_F12 Function keys (scancode | 0x100)
KEY_INSERT Insert key
KEY_DELETE Delete key
KEY_HOME Home key
KEY_END End key
KEY_PGUP Page Up key
KEY_PGDN Page Down key
.endtable
.h2 Resize Edge Flags
.table
Define Value Description
------ ----- -----------
RESIZE_NONE 0 No resize edge
RESIZE_LEFT 1 Left edge
RESIZE_RIGHT 2 Right edge
RESIZE_TOP 4 Top edge
RESIZE_BOTTOM 8 Bottom edge (combinable via OR for corners)
.endtable
.h2 Utility Macros
.table
Macro Description
----- -----------
DVX_MIN(a, b) Return the smaller of two values
DVX_MAX(a, b) Return the larger of two values
.endtable
.topic api.cursor
.title dvxCursor.h -- Cursor Definitions
.toc 1 dvxCursor.h -- Cursor Definitions
.index dvxCursor.h
.index Cursor Shapes
.index CURSOR_ARROW
.index CURSOR_BUSY
.h1 dvxCursor.h -- Cursor Definitions
Embedded 16x16 mouse cursor bitmaps compiled as static const data. No external cursor files. Uses the standard AND/XOR mask encoding from the IBM VGA hardware cursor spec.
.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, dimensions, and hot spot coordinates.
.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 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 drawBevel
.code
void drawBevel(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const BevelStyleT *style);
.endcode
Draw a beveled frame. Top/left edges in highlight color, bottom/right in shadow. Interior filled with face color if non-zero.
.table
Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
x, y, w, h Outer bevel rectangle
style Bevel colors and width
.endtable
.h2 drawChar
.code
int32_t drawChar(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, char ch, uint32_t fg, uint32_t bg, bool opaque);
.endcode
Draw a single character glyph. When opaque is true, the background fills the entire cell; when false, only foreground pixels are drawn (transparent background).
.table
Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
font Bitmap font
x, y Character position
ch Character to draw
fg, bg Foreground and background packed colors
opaque true = fill background, false = transparent
.endtable
Returns: Advance width (always charWidth).
.h2 drawText
.code
void drawText(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque);
.endcode
Draw a null-terminated string. Calls drawChar per character.
.table
Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
font Bitmap font
x, y Start position
text Null-terminated string
fg, bg Foreground and background packed colors
opaque true = fill background, false = transparent
.endtable
.h2 drawTextN
.code
void drawTextN(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, int32_t count, uint32_t fg, uint32_t bg, bool opaque);
.endcode
Optimized batch text rendering for a known character count. Computes clip bounds once, fills background in a single rectFill, then overlays glyph foreground pixels. Significantly faster than per-character drawChar for long runs (terminal rows, list items).
.table
Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
font Bitmap font
x, y Start position
text Character buffer (not required to be null-terminated)
count Number of characters to render
fg, bg Foreground and background packed colors
opaque true = fill background, false = transparent
.endtable
.h2 textWidth
.code
int32_t textWidth(const BitmapFontT *font, const char *text);
.endcode
Return the pixel width of a null-terminated string (strlen(text) * charWidth).
.table
Parameter Description
--------- -----------
font Bitmap font
text Null-terminated string
.endtable
Returns: Width in pixels.
.h2 accelParse
.code
char accelParse(const char *text);
.endcode
Scan text for an & prefix and return the following character as a lowercase accelerator key. "&File" returns 'f', "E&xit" returns 'x'.
.table
Parameter Description
--------- -----------
text Text with optional & accelerator marker
.endtable
Returns: Lowercase accelerator character, or 0 if none.
.h2 drawTextAccel
.code
void drawTextAccel(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque);
.endcode
Draw text with & accelerator markers. The character after & is drawn underlined to indicate the keyboard shortcut. && produces a literal &. Used for menu items and button labels.
.table
Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
font Bitmap font
x, y Start position
text Text with & markers
fg, bg Foreground and background packed colors
opaque true = fill background, false = transparent
.endtable
.h2 textWidthAccel
.code
int32_t textWidthAccel(const BitmapFontT *font, const char *text);
.endcode
Measure text width excluding & markers (so "&File" measures as 4 chars).
.table
Parameter Description
--------- -----------
font Bitmap font
text Text with optional & markers
.endtable
Returns: Width in pixels.
.h2 drawMaskedBitmap
.code
void drawMaskedBitmap(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const uint16_t *andMask, const uint16_t *xorData, uint32_t fgColor, uint32_t bgColor);
.endcode
Draw a 1-bit AND/XOR masked bitmap. Used for software-rendered mouse cursors.
.table
Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
x, y Screen position
w, h Bitmap dimensions
andMask AND transparency mask (one uint16_t per row)
xorData XOR color data
fgColor, bgColor Cursor foreground and background packed colors
.endtable
.h2 drawTermRow
.code
void drawTermRow(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, int32_t cols, const uint8_t *lineData, const uint32_t *palette, bool blinkVisible, int32_t cursorCol);
.endcode
Render an entire row of terminal character cells (ch/attr byte pairs) in a single pass. Colors looked up from a 16-color palette. Attribute bit 7 controls blink.
.table
Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
font Bitmap font
x, y Row start position
cols Number of columns
lineData Packed ch/attr byte pairs (2 bytes per cell)
palette 16-entry packed color palette
blinkVisible false = hide blinking characters
cursorCol Column for inverted text cursor (-1 = none)
.endtable
.h2 drawFocusRect
.code
void drawFocusRect(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);
.endcode
Draw a 1px dotted rectangle (alternating pixels). Used for keyboard focus indicators, matching the Windows 3.x focus rectangle convention.
.table
Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
x, y, w, h Focus rectangle bounds
color Dot color (packed)
.endtable
.h2 drawHLine
.code
void drawHLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, uint32_t color);
.endcode
Draw a horizontal line (1px tall).
.table
Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
x, y Start position
w Width in pixels
color Packed pixel color
.endtable
.h2 drawVLine
.code
void drawVLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t h, uint32_t color);
.endcode
Draw a vertical line (1px wide).
.table
Parameter Description
--------- -----------
d Display context
ops Blit operations vtable
x, y Start position
h Height in pixels
color Packed pixel color
.endtable
.topic api.comp
.title dvxComp.h -- Layer 3: Dirty Rectangle Compositor
.toc 1 dvxComp.h -- Layer 3: Compositor
.index dvxComp.h
.index dirtyListInit
.index dirtyListAdd
.index dirtyListMerge
.index dirtyListClear
.index flushRect
.index rectIntersect
.index rectIsEmpty
.h1 dvxComp.h -- Layer 3: Dirty Rectangle Compositor
Tracks changed screen regions and ensures only dirty regions are redrawn and flushed to video memory. The compositing pipeline: mark dirty, merge overlapping rects, redraw desktop + windows (back-to-front, painter's algorithm), flush to LFB.
.h2 dirtyListInit
.code
void dirtyListInit(DirtyListT *dl);
.endcode
Zero the dirty rect count. Called at the start of each frame.
.table
Parameter Description
--------- -----------
dl Dirty list to initialize
.endtable
.h2 dirtyListAdd
.code
void dirtyListAdd(DirtyListT *dl, int32_t x, int32_t y, int32_t w, int32_t h);
.endcode
Enqueue a dirty rectangle. Grows dynamically; triggers merge at a soft capacity limit.
.table
Parameter Description
--------- -----------
dl Dirty list
x, y, w, h Dirty rectangle in screen coordinates
.endtable
.h2 dirtyListMerge
.code
void dirtyListMerge(DirtyListT *dl);
.endcode
Consolidate the dirty list by merging overlapping and adjacent rects. Uses iterative pairwise merge: if combining two rects does not increase total area beyond a threshold, they are merged. Reduces compositor passes and LFB flush operations.
.table
Parameter Description
--------- -----------
dl Dirty list to merge
.endtable
.h2 dirtyListClear
.code
void dirtyListClear(DirtyListT *dl);
.endcode
Reset the dirty list to empty (sets count to 0).
.table
Parameter Description
--------- -----------
dl Dirty list to clear
.endtable
.h2 flushRect
.code
void flushRect(DisplayT *d, const RectT *r);
.endcode
Copy a rectangle from the system RAM backbuffer to the LFB (video memory). This is the only place the real framebuffer is written. Uses platform-specific fast copy (rep movsd on DOS) for each scanline.
.table
Parameter Description
--------- -----------
d Display context
r Rectangle to flush
.endtable
.h2 rectIntersect
.code
bool rectIntersect(const RectT *a, const RectT *b, RectT *result);
.endcode
Compute the intersection of two rectangles.
.table
Parameter Description
--------- -----------
a, b Input rectangles
result Output: intersection rectangle (valid only when return is true)
.endtable
Returns: true if the rectangles overlap, false if disjoint.
.h2 rectIsEmpty
.code
bool rectIsEmpty(const RectT *r);
.endcode
Test whether a rectangle has zero or negative area.
.table
Parameter Description
--------- -----------
r Rectangle to test
.endtable
Returns: true if w <= 0 or h <= 0.
.topic api.wm
.title dvxWm.h -- Layer 4: Window Manager
.toc 1 dvxWm.h -- Layer 4: Window Manager
.index dvxWm.h
.index wmInit
.index wmCreateWindow
.index wmDestroyWindow
.index wmRaiseWindow
.index wmSetFocus
.index wmUpdateContentRect
.index wmReallocContentBuf
.index wmMinWindowSize
.index wmAddMenuBar
.index wmAddMenu
.index wmAddMenuItem
.index wmAddSubMenu
.index wmCreateMenu
.index wmDrawChrome
.index wmHitTest
.index wmDragBegin
.index wmResizeBegin
.index wmMaximize
.index wmMinimize
.index wmRestore
.h1 dvxWm.h -- Layer 4: Window Manager
Manages the window lifecycle, Z-order stack, chrome drawing, hit testing, and interactive operations (drag, resize, scroll). The WM owns window geometry and chrome; content is owned by the application via callbacks or the widget system.
.h2 Initialization
.h3 wmInit
.code
void wmInit(WindowStackT *stack);
.endcode
Zero the window stack. Must be called before any other WM function.
.table
Parameter Description
--------- -----------
stack Window stack to initialize
.endtable
.h2 Window Lifecycle
.h3 wmCreateWindow
.code
WindowT *wmCreateWindow(WindowStackT *stack, DisplayT *d, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);
.endcode
Allocate a new window, initialize its geometry and content buffer, and push it to the top of the Z-order stack. Returns with all callbacks NULL; the caller should set onPaint/onKey/etc. before the next event loop iteration.
.table
Parameter Description
--------- -----------
stack Window stack
d Display context
title Window title text
x, y Initial position
w, h Initial outer frame dimensions
resizable true = allow user resize
.endtable
Returns: Pointer to new WindowT, or NULL on failure.
.h3 wmDestroyWindow
.code
void wmDestroyWindow(WindowStackT *stack, WindowT *win);
.endcode
Free the window's content buffer and all attached resources (menu bar, scrollbars, widget tree), remove it from the stack, and dirty the vacated region.
.table
Parameter Description
--------- -----------
stack Window stack
win Window to destroy
.endtable
.h2 Z-Order and Focus
.h3 wmRaiseWindow
.code
void wmRaiseWindow(WindowStackT *stack, DirtyListT *dl, int32_t idx);
.endcode
Move window at stack index idx to the top of the Z-order. Dirties both old and new top positions so overlapping windows get repainted.
.table
Parameter Description
--------- -----------
stack Window stack
dl Dirty list for repaint marking
idx Stack index of window to raise
.endtable
.h3 wmSetFocus
.code
void wmSetFocus(WindowStackT *stack, DirtyListT *dl, int32_t idx);
.endcode
Transfer keyboard focus to the window at stack index idx. Unfocuses the previously focused window and dirties both title bars.
.table
Parameter Description
--------- -----------
stack Window stack
dl Dirty list
idx Stack index of window to focus
.endtable
.h2 Geometry
.h3 wmUpdateContentRect
.code
void wmUpdateContentRect(WindowT *win);
.endcode
Recompute contentX/Y/W/H from the window's outer frame dimensions, accounting for chrome borders, title bar, menu bar, and scrollbars. Must be called after any change to frame size or chrome configuration.
.table
Parameter Description
--------- -----------
win Window to update
.endtable
.h3 wmReallocContentBuf
.code
int32_t wmReallocContentBuf(WindowT *win, const DisplayT *d);
.endcode
Reallocate the per-window content backbuffer to match current contentW/H. Old buffer contents are lost; caller should trigger a full repaint via onPaint afterward.
.table
Parameter Description
--------- -----------
win Window to reallocate
d Display context (for bytes-per-pixel)
.endtable
Returns: 0 on success, -1 on allocation failure.
.h3 wmMinWindowSize
.code
void wmMinWindowSize(const WindowT *win, int32_t *minW, int32_t *minH);
.endcode
Get the minimum window size. Accounts for chrome, gadgets, and menu bar.
.table
Parameter Description
--------- -----------
win Window
minW, minH Output: minimum width and height
.endtable
.h2 Menu Bar
.h3 wmAddMenuBar
.code
MenuBarT *wmAddMenuBar(WindowT *win);
.endcode
Allocate and attach a menu bar to a window. Adjusts content area to make room (CHROME_MENU_HEIGHT pixels). One menu bar per window.
.table
Parameter Description
--------- -----------
win Window to add menu bar to
.endtable
Returns: Pointer to the new MenuBarT.
.h3 wmDestroyMenuBar
.code
void wmDestroyMenuBar(WindowT *win);
.endcode
Free the menu bar and reclaim the content area.
.table
Parameter Description
--------- -----------
win Window to remove menu bar from
.endtable
.h3 wmAddMenu
.code
MenuT *wmAddMenu(MenuBarT *bar, const char *label);
.endcode
Append a dropdown menu to the menu bar. The label supports & accelerator markers (e.g. "&File").
.table
Parameter Description
--------- -----------
bar Menu bar
label Menu label text
.endtable
Returns: Pointer to the new MenuT to populate with items.
.h3 wmAddMenuItem
.code
void wmAddMenuItem(MenuT *menu, const char *label, int32_t id);
.endcode
Append a clickable item to a menu. The id is passed to the window's onMenu callback when selected.
.table
Parameter Description
--------- -----------
menu Menu to append to
label Item label (supports & markers)
id Application-defined command ID
.endtable
.h3 wmAddMenuCheckItem
.code
void wmAddMenuCheckItem(MenuT *menu, const char *label, int32_t id, bool checked);
.endcode
Add a checkbox-style menu item. Check state toggles on click; rendered with a checkmark glyph.
.table
Parameter Description
--------- -----------
menu Menu to append to
label Item label
id Command ID
checked Initial checked state
.endtable
.h3 wmAddMenuRadioItem
.code
void wmAddMenuRadioItem(MenuT *menu, const char *label, int32_t id, bool checked);
.endcode
Add a radio-style menu item. Radio groups are defined implicitly by consecutive radio items; selecting one unchecks the others in the group.
.table
Parameter Description
--------- -----------
menu Menu to append to
label Item label
id Command ID
checked Initial checked state
.endtable
.h3 wmAddMenuSeparator
.code
void wmAddMenuSeparator(MenuT *menu);
.endcode
Insert a horizontal separator line. Separators are not interactive.
.table
Parameter Description
--------- -----------
menu Menu to append separator to
.endtable
.h3 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
.h2 Hit Testing
.h3 wmHitTest
.code
int32_t wmHitTest(const WindowStackT *stack, int32_t mx, int32_t my, int32_t *hitPart);
.endcode
Determine which window and chrome region is under the given screen coordinates. Iterates front-to-back (highest Z first) so the topmost window wins.
.table
Parameter Description
--------- -----------
stack Window stack
mx, my Screen coordinates
hitPart Output: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, etc.
.endtable
Returns: Stack index of hit window, or -1 for desktop.
.h3 wmResizeEdgeHit
.code
int32_t wmResizeEdgeHit(const WindowT *win, int32_t mx, int32_t my);
.endcode
Determine which edge(s) of a window's border zone are targeted for resize.
.table
Parameter Description
--------- -----------
win Window
mx, my Screen coordinates
.endtable
Returns: Bitmask of RESIZE_LEFT / RESIZE_RIGHT / RESIZE_TOP / RESIZE_BOTTOM.
.h3 wmMinimizedIconHit
.code
int32_t wmMinimizedIconHit(const WindowStackT *stack, const DisplayT *d, int32_t mx, int32_t my);
.endcode
Hit-test minimized icons at the bottom of the screen.
.table
Parameter Description
--------- -----------
stack Window stack
d Display context
mx, my Screen coordinates
.endtable
Returns: Stack index of the minimized window, or -1.
.h2 Drag and Resize
.h3 wmDragBegin
.code
void wmDragBegin(WindowStackT *stack, int32_t idx, int32_t mouseX, int32_t mouseY);
.endcode
Begin a window drag operation. Records the mouse offset from the window origin.
.table
Parameter Description
--------- -----------
stack Window stack
idx Stack index of window to drag
mouseX/Y Current mouse position
.endtable
.h3 wmDragMove
.code
void wmDragMove(WindowStackT *stack, DirtyListT *dl, int32_t mouseX, int32_t mouseY, int32_t screenW, int32_t screenH);
.endcode
Update window position during an active drag. Dirties both old and new positions.
.table
Parameter Description
--------- -----------
stack Window stack
dl Dirty list
mouseX/Y Current mouse position
screenW/H Screen dimensions (for clamping)
.endtable
.h3 wmDragEnd
.code
void wmDragEnd(WindowStackT *stack);
.endcode
End the current drag operation. Clears dragWindow state.
.table
Parameter Description
--------- -----------
stack Window stack
.endtable
.h3 wmResizeBegin
.code
void wmResizeBegin(WindowStackT *stack, int32_t idx, int32_t edge, int32_t mouseX, int32_t mouseY);
.endcode
Begin a window resize operation. Records which edge(s) are being dragged.
.table
Parameter Description
--------- -----------
stack Window stack
idx Stack index
edge Bitmask of RESIZE_xxx flags
mouseX/Y Current mouse position
.endtable
.h3 wmResizeMove
.code
void wmResizeMove(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, int32_t *mouseX, int32_t *mouseY);
.endcode
Update window dimensions during an active resize. Enforces MIN_WINDOW_W/H and maxW/maxH constraints. Reallocates content buffer and calls onResize if size changed. mouseX/mouseY are in/out: clamped on return for cursor warping.
.table
Parameter Description
--------- -----------
stack Window stack
dl Dirty list
d Display context
mouseX/Y In/out: mouse position (clamped on return)
.endtable
.h3 wmResizeEnd
.code
void wmResizeEnd(WindowStackT *stack);
.endcode
End the current resize operation. Clears resizeWindow state.
.table
Parameter Description
--------- -----------
stack Window stack
.endtable
.h2 Scrollbar Interaction
.h3 wmScrollbarClick
.code
void wmScrollbarClick(WindowStackT *stack, DirtyListT *dl, int32_t idx, int32_t orient, int32_t mx, int32_t my);
.endcode
Handle an initial click on a scrollbar. Determines what was hit (arrows, trough, or thumb) and either adjusts the value immediately or begins a thumb drag.
.table
Parameter Description
--------- -----------
stack Window stack
dl Dirty list
idx Stack index of window
orient SCROLL_VERTICAL or SCROLL_HORIZONTAL
mx, my Click screen coordinates
.endtable
.h3 wmScrollbarDrag
.code
void wmScrollbarDrag(WindowStackT *stack, DirtyListT *dl, int32_t mx, int32_t my);
.endcode
Update the scroll value during an active thumb drag. Maps mouse position along the track to a proportional scroll value.
.table
Parameter Description
--------- -----------
stack Window stack
dl Dirty list
mx, my Current mouse position
.endtable
.h3 wmScrollbarEnd
.code
void wmScrollbarEnd(WindowStackT *stack);
.endcode
End an active scrollbar thumb drag.
.table
Parameter Description
--------- -----------
stack Window stack
.endtable
.h2 Minimize / Maximize / Restore
.h3 wmMaximize
.code
void wmMaximize(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);
.endcode
Maximize a window. Saves current geometry, then expands to screen or maxW/maxH bounds.
.table
Parameter Description
--------- -----------
stack Window stack
dl Dirty list
d Display context
win Window to maximize
.endtable
.h3 wmMinimize
.code
void wmMinimize(WindowStackT *stack, DirtyListT *dl, WindowT *win);
.endcode
Minimize a window. Hides the window and shows an icon at the bottom of the screen.
.table
Parameter Description
--------- -----------
stack Window stack
dl Dirty list
win Window to minimize
.endtable
.h3 wmRestore
.code
void wmRestore(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);
.endcode
Restore a maximized window to its pre-maximize geometry.
.table
Parameter Description
--------- -----------
stack Window stack
dl Dirty list
d Display context
win Maximized window to restore
.endtable
.h3 wmRestoreMinimized
.code
void wmRestoreMinimized(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);
.endcode
Restore a minimized window (show it again and remove the icon).
.table
Parameter Description
--------- -----------
stack Window stack
dl Dirty list
d Display context
win Minimized window to restore
.endtable
.h2 Minimized Icon Layout
.h3 wmMinimizedIconPos
.code
void wmMinimizedIconPos(const DisplayT *d, int32_t index, int32_t *x, int32_t *y);
.endcode
Compute the screen position of a minimized icon by ordinal index. Icons wrap into rows from bottom to top when the screen fills up.
.table
Parameter Description
--------- -----------
d Display context
index Ordinal index of the minimized icon
x, y Output: screen position
.endtable
.h3 wmMinimizedIconRect
.code
void wmMinimizedIconRect(const WindowStackT *stack, const DisplayT *d, int32_t *y, int32_t *h);
.endcode
Compute the screen rect covering all minimized icon rows. Used to dirty the icon area when windows are minimized or restored.
.table
Parameter Description
--------- -----------
stack Window stack
d Display context
y, h Output: vertical extent of icon area
.endtable
.h2 Miscellaneous
.h3 wmSetTitle
.code
void wmSetTitle(WindowT *win, DirtyListT *dl, const char *title);
.endcode
Set the window title and dirty the title bar for repaint.
.table
Parameter Description
--------- -----------
win Window
dl Dirty list
title New title text
.endtable
.h3 wmSetIcon
.code
int32_t wmSetIcon(WindowT *win, const char *path, const DisplayT *d);
.endcode
Load an icon image for a window from a file. Converts to display pixel format.
.table
Parameter Description
--------- -----------
win Window
path Image file path
d Display context
.endtable
Returns: 0 on success, -1 on failure.
.topic api.app
.title dvxApp.h -- Layer 5: Application API
.toc 1 dvxApp.h -- Layer 5: Application API
.index dvxApp.h
.index AppContextT
.index dvxInit
.index dvxShutdown
.index dvxRun
.index dvxUpdate
.index dvxQuit
.index dvxCreateWindow
.index dvxCreateWindowCentered
.index dvxDestroyWindow
.index dvxRaiseWindow
.index dvxFitWindow
.index 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 dvxLoadImage
.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);
.endcode
Configure mouse behavior.
.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)
.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. 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 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 dvxWidget.h -- Widget System
.toc 1 dvxWidget.h -- Widget System
.index dvxWidget.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 dvxWidget.h -- Widget System
Retained-mode widget toolkit layered on the DVX window manager. Widgets form a tree (parent-child) rooted at a per-window VBox container. Layout is automatic: measure minimum sizes bottom-up, then allocate space top-down with flexbox-like weighted distribution. Widget types are registered dynamically at runtime via DXE plugins.
.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
char accelKey Accelerator character (0 = none)
void *userData, *data Application data and widget-private data
const char *tooltip Tooltip text (NULL = none)
MenuT *contextMenu Right-click menu (NULL = none)
.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 btn, int32_t x, int32_t y) Mouse button pressed
onMouseUp(WidgetT *w, int32_t btn, int32_t x, int32_t y) Mouse button released
onMouseMove(WidgetT *w, int32_t btn, int32_t x, int32_t y) Mouse moved
onScroll(WidgetT *w, int32_t delta) Mouse wheel
onValidate(WidgetT *w) Return false to cancel a write
.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);
.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
.endtable
.h2 Debug
.h3 wgtSetDebugLayout
.code
void wgtSetDebugLayout(AppContextT *ctx, bool enabled);
.endcode
Draw colored borders around layout containers for debugging.
.table
Parameter Description
--------- -----------
ctx Application context
enabled true = draw debug borders
.endtable
.h2 Dynamic Widget Registration
.h3 wgtRegisterClass
.code
int32_t wgtRegisterClass(const WidgetClassT *wclass);
.endcode
Register a new widget class at runtime. Appends to widgetClassTable. The WidgetClassT must remain valid for the lifetime of the process (typically static const in a DXE).
.table
Parameter Description
--------- -----------
wclass Widget class vtable to register
.endtable
Returns: Assigned type ID.
.h3 wgtRegisterApi
.code
void wgtRegisterApi(const char *name, const void *api);
.endcode
Register a widget API struct under a name. Each widget DXE registers its API during initialization. Callers retrieve it via wgtGetApi() and cast to the widget-specific type.
.table
Parameter Description
--------- -----------
name Widget type name (e.g. "button", "listbox")
api Pointer to the widget's API struct
.endtable
.h3 wgtGetApi
.code
const void *wgtGetApi(const char *name);
.endcode
Retrieve a registered widget API struct by name.
.table
Parameter Description
--------- -----------
name Widget type name
.endtable
Returns: Pointer to the API struct, or NULL if not found.
.h2 Widget Interface Descriptors
.h3 wgtRegisterIface
.code
void wgtRegisterIface(const char *name, const WgtIfaceT *iface);
.endcode
Register an interface descriptor for a widget type. Used by the BASIC form runtime and IDE for generic property/method dispatch.
.table
Parameter Description
--------- -----------
name Widget type name
iface Interface descriptor
.endtable
.h3 wgtGetIface
.code
const WgtIfaceT *wgtGetIface(const char *name);
.endcode
Retrieve an interface descriptor by widget type name.
.table
Parameter Description
--------- -----------
name Widget type name
.endtable
Returns: Interface descriptor, or NULL.
.h3 wgtFindByBasName
.code
const char *wgtFindByBasName(const char *basName);
.endcode
Find a widget type name by its VB-style name (e.g. "CommandButton" -> "button"). Case-insensitive search.
.table
Parameter Description
--------- -----------
basName VB-style widget name
.endtable
Returns: Internal type name, or NULL.
.h3 wgtIfaceCount
.code
int32_t wgtIfaceCount(void);
.endcode
Return the number of registered widget interfaces.
Returns: Count of registered interfaces.
.h3 wgtIfaceAt
.code
const WgtIfaceT *wgtIfaceAt(int32_t idx, const char **outName);
.endcode
Get a registered widget interface by index.
.table
Parameter Description
--------- -----------
idx Index (0-based)
outName Output: type name
.endtable
Returns: Interface descriptor.
.h3 wgtIfaceGetPath
.code
const char *wgtIfaceGetPath(const char *name);
.endcode
Get the .wgt DXE file path for a registered widget.
.table
Parameter Description
--------- -----------
name Widget type name
.endtable
Returns: File path string.
.h3 wgtIfaceSetPath
.code
void wgtIfaceSetPath(const char *name, const char *path);
.endcode
Set the .wgt DXE file path for a registered widget (called by the loader).
.table
Parameter Description
--------- -----------
name Widget type name
path DXE file path
.endtable
.h3 wgtIfaceGetPathIndex
.code
int32_t wgtIfaceGetPathIndex(const char *name);
.endcode
Get the 1-based index of this widget within its .wgt file. Used to construct suffixed resource names (e.g. "name-2", "icon16-2").
.table
Parameter Description
--------- -----------
name Widget type name
.endtable
Returns: 1-based index within the DXE file.
.h2 Typed Dispatch Helpers
The following inline functions provide type-safe dispatch through the WidgetClassT handler table. Each checks for a non-NULL handler before calling.
.table
Function Method ID Description
-------- --------- -----------
wclsHas(w, methodId) -- Check if handler exists
wclsPaint(w, d, ops, font, colors) WGT_METHOD_PAINT Paint the widget
wclsPaintOverlay(w, d, ops, font, colors) WGT_METHOD_PAINT_OVERLAY Paint overlay (popups)
wclsCalcMinSize(w, font) WGT_METHOD_CALC_MIN_SIZE Compute minimum size
wclsLayout(w, font) WGT_METHOD_LAYOUT Layout children
wclsGetLayoutMetrics(w, font, ...) WGT_METHOD_GET_LAYOUT_METRICS Get pad, gap, extraTop, borderW
wclsOnMouse(w, root, vx, vy) WGT_METHOD_ON_MOUSE Handle mouse event
wclsOnKey(w, key, mod) WGT_METHOD_ON_KEY Handle key event
wclsOnAccelActivate(w, root) WGT_METHOD_ON_ACCEL_ACTIVATE Handle accelerator
wclsDestroy(w) WGT_METHOD_DESTROY Destroy widget data
wclsOnChildChanged(parent, child) WGT_METHOD_ON_CHILD_CHANGED Notify parent of change
wclsGetText(w) WGT_METHOD_GET_TEXT Get widget text
wclsSetText(w, text) WGT_METHOD_SET_TEXT Set widget text
wclsClearSelection(w) WGT_METHOD_CLEAR_SELECTION Clear text selection
wclsClosePopup(w) WGT_METHOD_CLOSE_POPUP Close dropdown popup
wclsGetPopupRect(w, font, ...) WGT_METHOD_GET_POPUP_RECT Get popup screen rect
wclsOnDragUpdate(w, root, x, y) WGT_METHOD_ON_DRAG_UPDATE Update during drag
wclsOnDragEnd(w, root, x, y) WGT_METHOD_ON_DRAG_END End drag operation
wclsGetCursorShape(w, vx, vy) WGT_METHOD_GET_CURSOR_SHAPE Get cursor for position
wclsPoll(w, win) WGT_METHOD_POLL Periodic polling
wclsQuickRepaint(w, outY, outH) WGT_METHOD_QUICK_REPAINT Fast partial repaint
wclsScrollChildIntoView(parent, child) WGT_METHOD_SCROLL_CHILD_INTO_VIEW Scroll child visible
.endtable
Reference in a new issue View git blame Copy permalink