-
-
-
dvxTypes.h -- Shared Type Definitions
-
dvxTypes.h -- Shared Type Definitions
-
Central type definitions shared across all five layers of the DVX GUI stack. Every header includes this file. Contains no function definitions -- only structs, enums, typedefs, and compile-time constants.
-
Core Structures
-
PixelFormatT
-
Describes the pixel encoding for the active VESA video mode. Populated once at startup from the VBE mode info block, then treated as read-only.
-
Field Description
- ----- -----------
- int32_t bitsPerPixel 8, 15, 16, or 32
- int32_t bytesPerPixel 1, 2, 2, or 4
- uint32_t redMask, greenMask, blueMask Bitmasks for each color channel
- int32_t redShift, greenShift, blueShift Bit position of each color field
- int32_t redBits, greenBits, blueBits Number of bits per channel
-
DisplayT
-
Single display context passed by pointer through every layer. All drawing targets the backBuf; only dirty rects are flushed to lfb.
-
Field Description
- ----- -----------
- int32_t width, height Screen dimensions in pixels
- int32_t pitch Bytes per scanline
- PixelFormatT format Active pixel format
- uint8_t *lfb Mapped linear framebuffer (VESA LFB)
- uint8_t *backBuf System RAM backbuffer
- uint8_t *palette 768 bytes for 8-bit mode, NULL otherwise
- int32_t clipX, clipY, clipW, clipH Current clip rectangle
-
RectT
-
Rectangle in origin + extent form. Used throughout the compositor, window manager, and widget layout engine.
-
Field Description
- ----- -----------
- int32_t x, y Top-left corner
- int32_t w, h Width and height
-
BlitOpsT
-
Vtable for hot-path span operations. Resolved at init time based on pixel depth. On DOS, these dispatch to hand-written asm (rep stosl / rep movsd).
-
Field Description
- ----- -----------
- SpanFillFnT spanFill Fill a horizontal span with a solid color
- SpanCopyFnT spanCopy Copy a horizontal span between buffers
- int32_t bytesPerPixel Bytes per pixel for the active mode
- int32_t pitch Bytes per scanline
-
BevelStyleT
-
Bevel drawing parameters. Swapping highlight/shadow flips raised vs. sunken appearance.
-
Field Description
- ----- -----------
- uint32_t highlight Lighter color (top/left edges)
- uint32_t shadow Darker color (bottom/right edges)
- uint32_t face Interior fill color (0 = no fill)
- int32_t width Border thickness in pixels (typically 2)
-
BitmapFontT
-
Fixed-width 8-pixel-wide bitmap font descriptor. One size provided: 8x16 (standard VGA ROM font, CP437 encoding).
-
Field Description
- ----- -----------
- int32_t charWidth Fixed width per glyph (always 8)
- int32_t charHeight Glyph height (14 or 16)
- int32_t firstChar ASCII code of first glyph (typically 0)
- int32_t numChars Number of glyphs (typically 256)
- const uint8_t *glyphData Packed 1bpp data, charHeight bytes per glyph
-
ColorSchemeT
-
All UI colors pre-packed into display pixel format at init time. Theme support is achieved by swapping this struct.
-
Field Description
- ----- -----------
- uint32_t desktop Desktop background color
- uint32_t windowFace Window body / chrome face
- uint32_t windowHighlight Bevel highlight (top/left edge)
- uint32_t windowShadow Bevel shadow (bottom/right edge)
- uint32_t activeTitleBg, activeTitleFg Focused window title bar
- uint32_t inactiveTitleBg, inactiveTitleFg Unfocused window title bar
- uint32_t contentBg, contentFg Window content area default colors
- uint32_t menuBg, menuFg Menu bar and popup background/text
- uint32_t menuHighlightBg, menuHighlightFg Menu item highlight
- uint32_t buttonFace Button face color
- uint32_t scrollbarBg, scrollbarFg, scrollbarTrough Scrollbar element colors
- uint32_t cursorFg, cursorBg Mouse cursor colors
-
ColorIdE
-
Enum for addressing individual colors in ColorSchemeT. Order matches struct field order.
-
Values: ColorDesktopE, ColorWindowFaceE, ColorWindowHighlightE, ColorWindowShadowE, ColorActiveTitleBgE, ColorActiveTitleFgE, ColorInactiveTitleBgE, ColorInactiveTitleFgE, ColorContentBgE, ColorContentFgE, ColorMenuBgE, ColorMenuFgE, ColorMenuHighlightBgE, ColorMenuHighlightFgE, ColorButtonFaceE, ColorScrollbarBgE, ColorScrollbarFgE, ColorScrollbarTroughE, ColorCursorFgE, ColorCursorBgE, ColorCountE.
-
DirtyListT
-
Fixed-capacity list of dirty rectangles. Dynamic array, grows on demand.
-
Field Description
- ----- -----------
- RectT *rects Dynamic array of dirty rectangles
- int32_t count Current number of dirty rects
- int32_t cap Allocated capacity
-
WindowT
-
Central window object. Each window owns a persistent content backbuffer and receives events through callback function pointers.
-
Field Description
- ----- -----------
- int32_t id Unique window identifier
- int32_t appId Shell app ID (0 = shell itself)
- int32_t x, y, w, h Outer frame position and dimensions
- int32_t contentX, contentY, contentW, contentH Content area inset from frame
- char title[MAX_TITLE_LEN] Window title text (max 128 chars)
- bool visible, focused, minimized, maximized, resizable, modal Window state flags
- bool contentDirty true when contentBuf has changed
- bool needsPaint true until first onPaint call
- int32_t maxW, maxH Maximum dimensions
- int32_t preMaxX, preMaxY, preMaxW, preMaxH Saved geometry before maximize
- uint8_t *contentBuf Per-window content backbuffer
- int32_t contentPitch Content buffer bytes per row
- uint8_t *iconData Icon pixel data, NULL if none
- int32_t iconW, iconH, iconPitch Icon image dimensions and pitch
- MenuBarT *menuBar Menu bar (NULL if no menus)
- ScrollbarT *vScroll, *hScroll Scrollbars (NULL if not present)
- struct WidgetT *widgetRoot Widget tree root (NULL if none)
- MenuT *contextMenu Right-click context menu
- AccelTableT *accelTable Keyboard accelerator table
- void *userData Application-defined data pointer
-
Callbacks:
-
Callback Description
- -------- -----------
- onPaint(WindowT *win, RectT *dirtyArea) Content repaint requested
- onKey(WindowT *win, int32_t key, int32_t mod) Key press
- onKeyUp(WindowT *win, int32_t scancode, int32_t mod) Key release
- onMouse(WindowT *win, int32_t x, int32_t y, int32_t btn) Mouse event (content-relative)
- onResize(WindowT *win, int32_t newW, int32_t newH) Window resized
- onClose(WindowT *win) Close requested
- onMenu(WindowT *win, int32_t menuId) Menu item or accelerator activated
- onScroll(WindowT *win, ScrollbarOrientE orient, int32_t val) Scrollbar value changed
- onCursorQuery(WindowT *win, int32_t x, int32_t y) Return CURSOR_* for hit position
- onFocus(WindowT *win) Window gained focus
- onBlur(WindowT *win) Window lost focus
-
WindowStackT
-
Z-ordered window stack (front-to-back: index count-1 is topmost). Owns system-wide drag/resize/scroll interaction state.
-
Field Description
- ----- -----------
- WindowT **windows Dynamic array of window pointers
- int32_t count, cap Current count and allocated capacity
- int32_t focusedIdx Stack index of focused window
- int32_t dragWindow, dragOffX, dragOffY Active drag state
- int32_t resizeWindow, resizeEdge Active resize state
- int32_t scrollWindow, scrollOrient, scrollDragOff Active scroll drag state
-
MenuT / MenuItemT / MenuBarT
-
Menu system types. Fixed-size label buffers (MAX_MENU_LABEL = 32). Cascading submenus supported via MenuItemT.subMenu pointer.
-
Field Description
- ----- -----------
- MenuItemT.label Item text (supports & accelerator markers)
- MenuItemT.id Application-defined command ID
- MenuItemT.type MenuItemNormalE, MenuItemCheckE, or MenuItemRadioE
- MenuItemT.separator true = horizontal divider line
- MenuItemT.enabled, checked Item state
- MenuItemT.subMenu Child menu for cascading (NULL if leaf)
- MenuBarT.activeIdx Open popup index (-1 = none)
-
ScrollbarT
-
Window-level scrollbar state. Managed by the WM layer, drawn after content.
-
Field Description
- ----- -----------
- ScrollbarOrientE orient ScrollbarVerticalE or ScrollbarHorizontalE
- int32_t min, max Scroll range
- int32_t value Current position
- int32_t pageSize Visible portion (for proportional thumb sizing)
- int32_t x, y, length Computed screen position and track length
-
AccelTableT / AccelEntryT
-
Per-window keyboard accelerator table. Entries are matched against keystrokes in the event loop and fire onMenu(cmdId) on match.
-
Field Description
- ----- -----------
- AccelEntryT.key ASCII character or KEY_Fxx constant
- AccelEntryT.modifiers Bitmask of ACCEL_CTRL, ACCEL_SHIFT, ACCEL_ALT
- AccelEntryT.cmdId Command ID passed to onMenu
-
VideoModeInfoT
-
Describes an available video mode (enumerated at init).
-
Field Description
- ----- -----------
- int32_t w, h Resolution
- int32_t bpp Bits per pixel
-
CursorT
-
Software-rendered 16x16 cursor using AND/XOR mask encoding.
-
Field Description
- ----- -----------
- int32_t width, height Cursor dimensions (always 16x16)
- int32_t hotX, hotY Hot spot coordinates
- const uint16_t *andMask AND mask (0 = draw pixel, 1 = transparent)
- const uint16_t *xorData XOR data (0 = black, 1 = white where AND = 0)
-
Bevel Convenience Macros
-
Macro Description
- ----- -----------
- BEVEL_RAISED(cs, bw) Raised bevel style from ColorSchemeT ptr and border width
- BEVEL_SUNKEN(cs, face, bw) Sunken bevel style with explicit face color
- BEVEL_TROUGH(cs) 1px sunken trough (for scrollbar tracks)
- BEVEL_SB_BUTTON(cs) 1px raised scrollbar button
-
Chrome Constants
-
Define Value Description
- ------ ----- -----------
- CHROME_BORDER_WIDTH 4 Outer frame border width
- CHROME_TITLE_HEIGHT 20 Title bar height
- CHROME_TITLE_PAD 4 Title text padding
- CHROME_INNER_BORDER 2 Inner chrome border
- CHROME_MENU_HEIGHT 20 Menu bar height
- CHROME_TOTAL_TOP 26 Total inset from top of frame to content
- CHROME_TOTAL_SIDE 6 Total inset from side of frame to content
- CHROME_TOTAL_BOTTOM 6 Total inset from bottom of frame to content
- CHROME_CLOSE_BTN_SIZE 16 Close button gadget size
-
Hit Test Constants
-
Define Value Description
- ------ ----- -----------
- HIT_CONTENT 0 Content area
- HIT_TITLE 1 Title bar
- HIT_CLOSE 2 Close gadget
- HIT_RESIZE 3 Resize border
- HIT_MENU 4 Menu bar
- HIT_VSCROLL 5 Vertical scrollbar
- HIT_HSCROLL 6 Horizontal scrollbar
- HIT_MINIMIZE 7 Minimize gadget
- HIT_MAXIMIZE 8 Maximize gadget
- HIT_NONE -1 No window hit (desktop)
-
Mouse Button Flags
-
Define Value Description
- ------ ----- -----------
- MOUSE_LEFT 1 Left mouse button
- MOUSE_RIGHT 2 Right mouse button
- MOUSE_MIDDLE 4 Middle mouse button
-
Accelerator Modifier Flags
-
Define Value Description
- ------ ----- -----------
- ACCEL_SHIFT 0x03 Shift key (matches BIOS shift state bits)
- ACCEL_CTRL 0x04 Ctrl key
- ACCEL_ALT 0x08 Alt key
-
Extended Key Codes
-
Define Description
- ------ -----------
- KEY_F1 .. KEY_F12 Function keys (scancode | 0x100)
- KEY_INSERT Insert key
- KEY_DELETE Delete key
- KEY_HOME Home key
- KEY_END End key
- KEY_PGUP Page Up key
- KEY_PGDN Page Down key
-
Resize Edge Flags
-
Define Value Description
- ------ ----- -----------
- RESIZE_NONE 0 No resize edge
- RESIZE_LEFT 1 Left edge
- RESIZE_RIGHT 2 Right edge
- RESIZE_TOP 4 Top edge
- RESIZE_BOTTOM 8 Bottom edge (combinable via OR for corners)
-
Utility Macros
-
Macro Description
- ----- -----------
- DVX_MIN(a, b) Return the smaller of two values
- DVX_MAX(a, b) Return the larger of two values
-
-
dvxCursor.h -- Cursor Definitions
-
dvxCursor.h -- Cursor Definitions
-
Embedded 16x16 mouse cursor bitmaps compiled as static const data. No external cursor files. Uses the standard AND/XOR mask encoding from the IBM VGA hardware cursor spec.
-
Cursor Shape IDs
-
Define Value Description
- ------ ----- -----------
- CURSOR_ARROW 0 Standard arrow (hot spot at tip)
- CURSOR_RESIZE_H 1 Horizontal resize (left/right arrows)
- CURSOR_RESIZE_V 2 Vertical resize (up/down arrows)
- CURSOR_RESIZE_DIAG_NWSE 3 NW-SE diagonal resize
- CURSOR_RESIZE_DIAG_NESW 4 NE-SW diagonal resize
- CURSOR_BUSY 5 Hourglass (wait)
- CURSOR_CROSSHAIR 6 Crosshair for placement
- CURSOR_COUNT 7 Total number of cursor shapes
-
Data
-
dvxCursors[CURSOR_COUNT]
-
Static const array of CursorT structs, indexed by CURSOR_xxx constants. Each entry includes the AND mask, XOR data, dimensions, and hot spot coordinates.
-
-
dvxVideo.h -- Layer 1: VESA VBE Video Backend
-
dvxVideo.h -- Layer 1: VESA VBE Video Backend
-
The lowest layer. Responsible for VESA VBE mode negotiation, LFB mapping via DPMI, system RAM backbuffer allocation, pixel format discovery, and color packing. LFB-only design: bank switching is deliberately unsupported.
-
videoInit
-
int32_t videoInit(DisplayT *d, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);
-
Probe VBE for a mode matching the requested resolution and depth, enable it, map the LFB into DPMI linear address space, and allocate a system RAM backbuffer. preferredBpp is a hint; the closest available depth is used if an exact match is not found.
-
Parameter Description
- --------- -----------
- d Display context to initialize
- requestedW/H Desired screen resolution
- preferredBpp Preferred bits per pixel (8, 15, 16, or 32)
-
Returns: 0 on success, negative on failure.
-
videoShutdown
-
void videoShutdown(DisplayT *d);
-
Restore VGA text mode (mode 3), unmap the LFB, and free the backbuffer. Safe to call even if videoInit() failed.
-
Parameter Description
- --------- -----------
- d Display context to shut down
-
packColor
-
uint32_t packColor(const DisplayT *d, uint8_t r, uint8_t g, uint8_t b);
-
Pack an RGB triplet into the display's native pixel format. For direct-color modes (15/16/32 bpp), returns a packed pixel value using shift/mask fields. For 8-bit mode, returns the nearest palette index via Euclidean distance in RGB space.
-
Parameter Description
- --------- -----------
- d Display context (provides pixel format)
- r, g, b Color components (0-255)
-
Returns: Native pixel value suitable for direct framebuffer write.
-
setClipRect
-
void setClipRect(DisplayT *d, int32_t x, int32_t y, int32_t w, int32_t h);
-
Set the clip rectangle on the display. All subsequent draw operations clip to this rectangle. The caller must save and restore the clip rect around scoped operations.
-
Parameter Description
- --------- -----------
- d Display context
- x, y, w, h Clip rectangle in screen coordinates
-
resetClipRect
-
void resetClipRect(DisplayT *d);
-
Reset the clip rectangle to the full display dimensions.
-
Parameter Description
- --------- -----------
- d Display context
-
-
dvxDraw.h -- Layer 2: Drawing Primitives
-
dvxDraw.h -- Layer 2: Drawing Primitives
-
All 2D drawing operations: rectangle fills, bitmap blits, text rendering, bevels, lines, and cursor rendering. Every function draws into the display's backbuffer and clips to the current clip rectangle. This layer is stateless beyond the clip rect on DisplayT.
-
drawInit
-
void drawInit(BlitOpsT *ops, const DisplayT *d);
-
Populate a BlitOpsT with the correct span functions for the display's pixel depth. Must be called once after videoInit().
-
Parameter Description
- --------- -----------
- ops BlitOpsT to populate
- d Initialized display context
-
rectFill
-
void rectFill(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);
-
Fill a rectangle with a solid color. Clips to the display clip rect. Workhorse for backgrounds, window fills, and clear operations.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- x, y, w, h Rectangle to fill
- color Packed pixel color
-
rectCopy
-
void rectCopy(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h);
-
Copy a rectangle from an arbitrary source buffer into the backbuffer. Used to blit per-window content buffers during compositing.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- dstX, dstY Destination position in backbuffer
- srcBuf Source pixel buffer
- srcPitch Source buffer bytes per row
- srcX, srcY Origin within source buffer
- w, h Rectangle dimensions to copy
-
rectCopyGrayscale
-
void rectCopyGrayscale(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h);
-
Copy a rectangle with grayscale conversion. Each pixel's RGB is converted to luminance (0.299R + 0.587G + 0.114B) for a disabled/grayed appearance.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- dstX, dstY Destination position
- srcBuf, srcPitch Source buffer and pitch
- srcX, srcY Source origin
- w, h Rectangle dimensions
-
drawBevel
-
void drawBevel(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const BevelStyleT *style);
-
Draw a beveled frame. Top/left edges in highlight color, bottom/right in shadow. Interior filled with face color if non-zero.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- x, y, w, h Outer bevel rectangle
- style Bevel colors and width
-
drawChar
-
int32_t drawChar(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, char ch, uint32_t fg, uint32_t bg, bool opaque);
-
Draw a single character glyph. When opaque is true, the background fills the entire cell; when false, only foreground pixels are drawn (transparent background).
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- font Bitmap font
- x, y Character position
- ch Character to draw
- fg, bg Foreground and background packed colors
- opaque true = fill background, false = transparent
-
Returns: Advance width (always charWidth).
-
drawText
-
void drawText(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque);
-
Draw a null-terminated string. Calls drawChar per character.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- font Bitmap font
- x, y Start position
- text Null-terminated string
- fg, bg Foreground and background packed colors
- opaque true = fill background, false = transparent
-
drawTextN
-
void drawTextN(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, int32_t count, uint32_t fg, uint32_t bg, bool opaque);
-
Optimized batch text rendering for a known character count. Computes clip bounds once, fills background in a single rectFill, then overlays glyph foreground pixels. Significantly faster than per-character drawChar for long runs (terminal rows, list items).
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- font Bitmap font
- x, y Start position
- text Character buffer (not required to be null-terminated)
- count Number of characters to render
- fg, bg Foreground and background packed colors
- opaque true = fill background, false = transparent
-
textWidth
-
int32_t textWidth(const BitmapFontT *font, const char *text);
-
Return the pixel width of a null-terminated string (strlen(text) * charWidth).
-
Parameter Description
- --------- -----------
- font Bitmap font
- text Null-terminated string
-
Returns: Width in pixels.
-
accelParse
-
char accelParse(const char *text);
-
Scan text for an & prefix and return the following character as a lowercase accelerator key. "&File" returns 'f', "E&xit" returns 'x'.
-
Parameter Description
- --------- -----------
- text Text with optional & accelerator marker
-
Returns: Lowercase accelerator character, or 0 if none.
-
drawTextAccel
-
void drawTextAccel(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque);
-
Draw text with & accelerator markers. The character after & is drawn underlined to indicate the keyboard shortcut. && produces a literal &. Used for menu items and button labels.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- font Bitmap font
- x, y Start position
- text Text with & markers
- fg, bg Foreground and background packed colors
- opaque true = fill background, false = transparent
-
textWidthAccel
-
int32_t textWidthAccel(const BitmapFontT *font, const char *text);
-
Measure text width excluding & markers (so "&File" measures as 4 chars).
-
Parameter Description
- --------- -----------
- font Bitmap font
- text Text with optional & markers
-
Returns: Width in pixels.
-
drawMaskedBitmap
-
void drawMaskedBitmap(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const uint16_t *andMask, const uint16_t *xorData, uint32_t fgColor, uint32_t bgColor);
-
Draw a 1-bit AND/XOR masked bitmap. Used for software-rendered mouse cursors.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- x, y Screen position
- w, h Bitmap dimensions
- andMask AND transparency mask (one uint16_t per row)
- xorData XOR color data
- fgColor, bgColor Cursor foreground and background packed colors
-
drawTermRow
-
void drawTermRow(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, int32_t cols, const uint8_t *lineData, const uint32_t *palette, bool blinkVisible, int32_t cursorCol);
-
Render an entire row of terminal character cells (ch/attr byte pairs) in a single pass. Colors looked up from a 16-color palette. Attribute bit 7 controls blink.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- font Bitmap font
- x, y Row start position
- cols Number of columns
- lineData Packed ch/attr byte pairs (2 bytes per cell)
- palette 16-entry packed color palette
- blinkVisible false = hide blinking characters
- cursorCol Column for inverted text cursor (-1 = none)
-
drawFocusRect
-
void drawFocusRect(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);
-
Draw a 1px dotted rectangle (alternating pixels). Used for keyboard focus indicators, matching the Windows 3.x focus rectangle convention.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- x, y, w, h Focus rectangle bounds
- color Dot color (packed)
-
drawHLine
-
void drawHLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, uint32_t color);
-
Draw a horizontal line (1px tall).
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- x, y Start position
- w Width in pixels
- color Packed pixel color
-
drawVLine
-
void drawVLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t h, uint32_t color);
-
Draw a vertical line (1px wide).
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- x, y Start position
- h Height in pixels
- color Packed pixel color
-
-
dvxComp.h -- Layer 3: Dirty Rectangle Compositor
-
dvxComp.h -- Layer 3: Dirty Rectangle Compositor
-
Tracks changed screen regions and ensures only dirty regions are redrawn and flushed to video memory. The compositing pipeline: mark dirty, merge overlapping rects, redraw desktop + windows (back-to-front, painter's algorithm), flush to LFB.
-
dirtyListInit
-
void dirtyListInit(DirtyListT *dl);
-
Zero the dirty rect count. Called at the start of each frame.
-
Parameter Description
- --------- -----------
- dl Dirty list to initialize
-
dirtyListAdd
-
void dirtyListAdd(DirtyListT *dl, int32_t x, int32_t y, int32_t w, int32_t h);
-
Enqueue a dirty rectangle. Grows dynamically; triggers merge at a soft capacity limit.
-
Parameter Description
- --------- -----------
- dl Dirty list
- x, y, w, h Dirty rectangle in screen coordinates
-
dirtyListMerge
-
void dirtyListMerge(DirtyListT *dl);
-
Consolidate the dirty list by merging overlapping and adjacent rects. Uses iterative pairwise merge: if combining two rects does not increase total area beyond a threshold, they are merged. Reduces compositor passes and LFB flush operations.
-
Parameter Description
- --------- -----------
- dl Dirty list to merge
-
dirtyListClear
-
void dirtyListClear(DirtyListT *dl);
-
Reset the dirty list to empty (sets count to 0).
-
Parameter Description
- --------- -----------
- dl Dirty list to clear
-
flushRect
-
void flushRect(DisplayT *d, const RectT *r);
-
Copy a rectangle from the system RAM backbuffer to the LFB (video memory). This is the only place the real framebuffer is written. Uses platform-specific fast copy (rep movsd on DOS) for each scanline.
-
Parameter Description
- --------- -----------
- d Display context
- r Rectangle to flush
-
rectIntersect
-
bool rectIntersect(const RectT *a, const RectT *b, RectT *result);
-
Compute the intersection of two rectangles.
-
Parameter Description
- --------- -----------
- a, b Input rectangles
- result Output: intersection rectangle (valid only when return is true)
-
Returns: true if the rectangles overlap, false if disjoint.
-
rectIsEmpty
-
bool rectIsEmpty(const RectT *r);
-
Test whether a rectangle has zero or negative area.
-
Parameter Description
- --------- -----------
- r Rectangle to test
-
Returns: true if w <= 0 or h <= 0.
-
-
dvxWm.h -- Layer 4: Window Manager
-
dvxWm.h -- Layer 4: Window Manager
-
Manages the window lifecycle, Z-order stack, chrome drawing, hit testing, and interactive operations (drag, resize, scroll). The WM owns window geometry and chrome; content is owned by the application via callbacks or the widget system.
-
Initialization
-
wmInit
-
void wmInit(WindowStackT *stack);
-
Zero the window stack. Must be called before any other WM function.
-
Parameter Description
- --------- -----------
- stack Window stack to initialize
-
Window Lifecycle
-
wmCreateWindow
-
WindowT *wmCreateWindow(WindowStackT *stack, DisplayT *d, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);
-
Allocate a new window, initialize its geometry and content buffer, and push it to the top of the Z-order stack. Returns with all callbacks NULL; the caller should set onPaint/onKey/etc. before the next event loop iteration.
-
Parameter Description
- --------- -----------
- stack Window stack
- d Display context
- title Window title text
- x, y Initial position
- w, h Initial outer frame dimensions
- resizable true = allow user resize
-
Returns: Pointer to new WindowT, or NULL on failure.
-
wmDestroyWindow
-
void wmDestroyWindow(WindowStackT *stack, WindowT *win);
-
Free the window's content buffer and all attached resources (menu bar, scrollbars, widget tree), remove it from the stack, and dirty the vacated region.
-
Parameter Description
- --------- -----------
- stack Window stack
- win Window to destroy
-
Z-Order and Focus
-
wmRaiseWindow
-
void wmRaiseWindow(WindowStackT *stack, DirtyListT *dl, int32_t idx);
-
Move window at stack index idx to the top of the Z-order. Dirties both old and new top positions so overlapping windows get repainted.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list for repaint marking
- idx Stack index of window to raise
-
wmSetFocus
-
void wmSetFocus(WindowStackT *stack, DirtyListT *dl, int32_t idx);
-
Transfer keyboard focus to the window at stack index idx. Unfocuses the previously focused window and dirties both title bars.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- idx Stack index of window to focus
-
Geometry
-
wmUpdateContentRect
-
void wmUpdateContentRect(WindowT *win);
-
Recompute contentX/Y/W/H from the window's outer frame dimensions, accounting for chrome borders, title bar, menu bar, and scrollbars. Must be called after any change to frame size or chrome configuration.
-
Parameter Description
- --------- -----------
- win Window to update
-
wmReallocContentBuf
-
int32_t wmReallocContentBuf(WindowT *win, const DisplayT *d);
-
Reallocate the per-window content backbuffer to match current contentW/H. Old buffer contents are lost; caller should trigger a full repaint via onPaint afterward.
-
Parameter Description
- --------- -----------
- win Window to reallocate
- d Display context (for bytes-per-pixel)
-
Returns: 0 on success, -1 on allocation failure.
-
wmMinWindowSize
-
void wmMinWindowSize(const WindowT *win, int32_t *minW, int32_t *minH);
-
Get the minimum window size. Accounts for chrome, gadgets, and menu bar.
-
Parameter Description
- --------- -----------
- win Window
- minW, minH Output: minimum width and height
-
Menu Bar
-
wmAddMenuBar
-
MenuBarT *wmAddMenuBar(WindowT *win);
-
Allocate and attach a menu bar to a window. Adjusts content area to make room (CHROME_MENU_HEIGHT pixels). One menu bar per window.
-
Parameter Description
- --------- -----------
- win Window to add menu bar to
-
Returns: Pointer to the new MenuBarT.
-
wmDestroyMenuBar
-
void wmDestroyMenuBar(WindowT *win);
-
Free the menu bar and reclaim the content area.
-
Parameter Description
- --------- -----------
- win Window to remove menu bar from
-
wmAddMenu
-
MenuT *wmAddMenu(MenuBarT *bar, const char *label);
-
Append a dropdown menu to the menu bar. The label supports & accelerator markers (e.g. "&File").
-
Parameter Description
- --------- -----------
- bar Menu bar
- label Menu label text
-
Returns: Pointer to the new MenuT to populate with items.
-
wmAddMenuItem
-
void wmAddMenuItem(MenuT *menu, const char *label, int32_t id);
-
Append a clickable item to a menu. The id is passed to the window's onMenu callback when selected.
-
Parameter Description
- --------- -----------
- menu Menu to append to
- label Item label (supports & markers)
- id Application-defined command ID
-
wmAddMenuCheckItem
-
void wmAddMenuCheckItem(MenuT *menu, const char *label, int32_t id, bool checked);
-
Add a checkbox-style menu item. Check state toggles on click; rendered with a checkmark glyph.
-
Parameter Description
- --------- -----------
- menu Menu to append to
- label Item label
- id Command ID
- checked Initial checked state
-
wmAddMenuRadioItem
-
void wmAddMenuRadioItem(MenuT *menu, const char *label, int32_t id, bool checked);
-
Add a radio-style menu item. Radio groups are defined implicitly by consecutive radio items; selecting one unchecks the others in the group.
-
Parameter Description
- --------- -----------
- menu Menu to append to
- label Item label
- id Command ID
- checked Initial checked state
-
wmAddMenuSeparator
-
void wmAddMenuSeparator(MenuT *menu);
-
Insert a horizontal separator line. Separators are not interactive.
-
Parameter Description
- --------- -----------
- menu Menu to append separator to
-
wmMenuItemIsChecked
-
bool wmMenuItemIsChecked(MenuBarT *bar, int32_t id);
-
Query the checked state of a menu item by command ID. Searches all menus in the bar.
-
Parameter Description
- --------- -----------
- bar Menu bar
- id Command ID to query
-
Returns: true if checked.
-
wmMenuItemSetChecked
-
void wmMenuItemSetChecked(MenuBarT *bar, int32_t id, bool checked);
-
Set the checked state of a menu item by command ID. For radio items, setting checked=true also unchecks other radio items in the same group.
-
Parameter Description
- --------- -----------
- bar Menu bar
- id Command ID
- checked New checked state
-
wmMenuItemSetEnabled
-
void wmMenuItemSetEnabled(MenuBarT *bar, int32_t id, bool enabled);
-
Enable or disable a menu item by command ID.
-
Parameter Description
- --------- -----------
- bar Menu bar
- id Command ID
- enabled true = enabled, false = grayed out
-
wmAddSubMenu
-
MenuT *wmAddSubMenu(MenuT *parentMenu, const char *label);
-
Create a cascading submenu attached to a parent menu. The child MenuT is heap-allocated and freed when the parent window is destroyed.
-
Parameter Description
- --------- -----------
- parentMenu Parent menu to attach submenu to
- label Submenu label text
-
Returns: Pointer to the child MenuT, or NULL on allocation failure.
-
wmCreateMenu
-
MenuT *wmCreateMenu(void);
-
Allocate a heap-resident MenuT for use as a context menu (right-click). Unlike menu bar menus, context menus are standalone allocations. Free with wmFreeMenu().
-
Returns: Pointer to the new MenuT.
-
wmFreeMenu
-
void wmFreeMenu(MenuT *menu);
-
Free a standalone menu allocated with wmCreateMenu(). Also frees any heap-allocated submenu children recursively.
-
Parameter Description
- --------- -----------
- menu Menu to free
-
Scrollbars
-
wmAddVScrollbar
-
ScrollbarT *wmAddVScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize);
-
Attach a vertical scrollbar to the right edge of the window's content area. Shrinks contentW by SCROLLBAR_WIDTH pixels.
-
Parameter Description
- --------- -----------
- win Window
- min, max Scroll value range
- pageSize Visible portion (controls thumb size)
-
Returns: Pointer to the new ScrollbarT.
-
wmAddHScrollbar
-
ScrollbarT *wmAddHScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize);
-
Attach a horizontal scrollbar to the bottom edge. Shrinks contentH by SCROLLBAR_WIDTH pixels.
-
Parameter Description
- --------- -----------
- win Window
- min, max Scroll value range
- pageSize Visible portion
-
Returns: Pointer to the new ScrollbarT.
-
Drawing
-
wmDrawChrome
-
void wmDrawChrome(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo);
-
Draw the window frame: outer bevel, title bar with text, close/minimize/maximize gadgets, and menu bar if present. Drawing is clipped to the intersection with clipTo.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- font Bitmap font for title text
- colors Color scheme
- win Window to draw chrome for
- clipTo Dirty rectangle to clip drawing to
-
wmDrawContent
-
void wmDrawContent(DisplayT *d, const BlitOpsT *ops, WindowT *win, const RectT *clipTo);
-
Blit the window's content backbuffer into the display backbuffer, clipped to the dirty rect. Pure copy operation (no drawing).
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- win Window
- clipTo Dirty rectangle
-
wmDrawScrollbars
-
void wmDrawScrollbars(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo);
-
Draw scrollbars (track, arrows, proportional thumb) for a window. Drawn after content so scrollbars overlay the content area edge.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- colors Color scheme
- win Window
- clipTo Dirty rectangle
-
wmDrawMinimizedIcons
-
void wmDrawMinimizedIcons(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, const WindowStackT *stack, const RectT *clipTo);
-
Draw icons for all minimized windows along the bottom of the screen. Each icon shows a scaled preview of the window's content with a beveled border.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- colors Color scheme
- stack Window stack
- clipTo Dirty rectangle
-
Hit Testing
-
wmHitTest
-
int32_t wmHitTest(const WindowStackT *stack, int32_t mx, int32_t my, int32_t *hitPart);
-
Determine which window and chrome region is under the given screen coordinates. Iterates front-to-back (highest Z first) so the topmost window wins.
-
Parameter Description
- --------- -----------
- stack Window stack
- mx, my Screen coordinates
- hitPart Output: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, etc.
-
Returns: Stack index of hit window, or -1 for desktop.
-
wmResizeEdgeHit
-
int32_t wmResizeEdgeHit(const WindowT *win, int32_t mx, int32_t my);
-
Determine which edge(s) of a window's border zone are targeted for resize.
-
Parameter Description
- --------- -----------
- win Window
- mx, my Screen coordinates
-
Returns: Bitmask of RESIZE_LEFT / RESIZE_RIGHT / RESIZE_TOP / RESIZE_BOTTOM.
-
wmMinimizedIconHit
-
int32_t wmMinimizedIconHit(const WindowStackT *stack, const DisplayT *d, int32_t mx, int32_t my);
-
Hit-test minimized icons at the bottom of the screen.
-
Parameter Description
- --------- -----------
- stack Window stack
- d Display context
- mx, my Screen coordinates
-
Returns: Stack index of the minimized window, or -1.
-
Drag and Resize
-
wmDragBegin
-
void wmDragBegin(WindowStackT *stack, int32_t idx, int32_t mouseX, int32_t mouseY);
-
Begin a window drag operation. Records the mouse offset from the window origin.
-
Parameter Description
- --------- -----------
- stack Window stack
- idx Stack index of window to drag
- mouseX/Y Current mouse position
-
wmDragMove
-
void wmDragMove(WindowStackT *stack, DirtyListT *dl, int32_t mouseX, int32_t mouseY, int32_t screenW, int32_t screenH);
-
Update window position during an active drag. Dirties both old and new positions.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- mouseX/Y Current mouse position
- screenW/H Screen dimensions (for clamping)
-
wmDragEnd
-
void wmDragEnd(WindowStackT *stack);
-
End the current drag operation. Clears dragWindow state.
-
Parameter Description
- --------- -----------
- stack Window stack
-
wmResizeBegin
-
void wmResizeBegin(WindowStackT *stack, int32_t idx, int32_t edge, int32_t mouseX, int32_t mouseY);
-
Begin a window resize operation. Records which edge(s) are being dragged.
-
Parameter Description
- --------- -----------
- stack Window stack
- idx Stack index
- edge Bitmask of RESIZE_xxx flags
- mouseX/Y Current mouse position
-
wmResizeMove
-
void wmResizeMove(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, int32_t *mouseX, int32_t *mouseY);
-
Update window dimensions during an active resize. Enforces MIN_WINDOW_W/H and maxW/maxH constraints. Reallocates content buffer and calls onResize if size changed. mouseX/mouseY are in/out: clamped on return for cursor warping.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- d Display context
- mouseX/Y In/out: mouse position (clamped on return)
-
wmResizeEnd
-
void wmResizeEnd(WindowStackT *stack);
-
End the current resize operation. Clears resizeWindow state.
-
Parameter Description
- --------- -----------
- stack Window stack
-
Scrollbar Interaction
-
wmScrollbarClick
-
void wmScrollbarClick(WindowStackT *stack, DirtyListT *dl, int32_t idx, int32_t orient, int32_t mx, int32_t my);
-
Handle an initial click on a scrollbar. Determines what was hit (arrows, trough, or thumb) and either adjusts the value immediately or begins a thumb drag.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- idx Stack index of window
- orient SCROLL_VERTICAL or SCROLL_HORIZONTAL
- mx, my Click screen coordinates
-
wmScrollbarDrag
-
void wmScrollbarDrag(WindowStackT *stack, DirtyListT *dl, int32_t mx, int32_t my);
-
Update the scroll value during an active thumb drag. Maps mouse position along the track to a proportional scroll value.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- mx, my Current mouse position
-
wmScrollbarEnd
-
void wmScrollbarEnd(WindowStackT *stack);
-
End an active scrollbar thumb drag.
-
Parameter Description
- --------- -----------
- stack Window stack
-
Minimize / Maximize / Restore
-
wmMaximize
-
void wmMaximize(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);
-
Maximize a window. Saves current geometry, then expands to screen or maxW/maxH bounds.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- d Display context
- win Window to maximize
-
wmMinimize
-
void wmMinimize(WindowStackT *stack, DirtyListT *dl, WindowT *win);
-
Minimize a window. Hides the window and shows an icon at the bottom of the screen.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- win Window to minimize
-
wmRestore
-
void wmRestore(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);
-
Restore a maximized window to its pre-maximize geometry.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- d Display context
- win Maximized window to restore
-
wmRestoreMinimized
-
void wmRestoreMinimized(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);
-
Restore a minimized window (show it again and remove the icon).
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- d Display context
- win Minimized window to restore
-
Minimized Icon Layout
-
wmMinimizedIconPos
-
void wmMinimizedIconPos(const DisplayT *d, int32_t index, int32_t *x, int32_t *y);
-
Compute the screen position of a minimized icon by ordinal index. Icons wrap into rows from bottom to top when the screen fills up.
-
Parameter Description
- --------- -----------
- d Display context
- index Ordinal index of the minimized icon
- x, y Output: screen position
-
wmMinimizedIconRect
-
void wmMinimizedIconRect(const WindowStackT *stack, const DisplayT *d, int32_t *y, int32_t *h);
-
Compute the screen rect covering all minimized icon rows. Used to dirty the icon area when windows are minimized or restored.
-
Parameter Description
- --------- -----------
- stack Window stack
- d Display context
- y, h Output: vertical extent of icon area
-
Miscellaneous
-
wmSetTitle
-
void wmSetTitle(WindowT *win, DirtyListT *dl, const char *title);
-
Set the window title and dirty the title bar for repaint.
-
Parameter Description
- --------- -----------
- win Window
- dl Dirty list
- title New title text
-
wmSetIcon
-
int32_t wmSetIcon(WindowT *win, const char *path, const DisplayT *d);
-
Load an icon image for a window from a file. Converts to display pixel format.
-
Parameter Description
- --------- -----------
- win Window
- path Image file path
- d Display context
-
Returns: 0 on success, -1 on failure.
-
-
dvxApp.h -- Layer 5: Application API
-
dvxApp.h -- Layer 5: Application API
-
The topmost layer and the public-facing API. Aggregates all lower layers into a single AppContextT. Applications interact exclusively through dvx*() functions and window callbacks. The event loop follows a cooperative model: poll, dispatch, composite, yield.
-
AppContextT
-
Single monolithic context that owns all GUI state. Contains the display, window stack, dirty list, blit ops, font, color scheme, popup state, cursor state, mouse/keyboard state, tooltip state, wallpaper buffer, video mode list, and various configuration fields. Allocated on the caller's stack or statically.
-
Initialization and Shutdown
-
dvxInit
-
int32_t dvxInit(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);
-
Initialize the entire GUI stack: video mode, input devices, font, color scheme, cursor shapes, and internal state. Single entry point for starting a DVX application.
-
Parameter Description
- --------- -----------
- ctx Application context to initialize
- requestedW/H Desired screen resolution
- preferredBpp Preferred bits per pixel
-
Returns: 0 on success, negative on failure.
-
dvxShutdown
-
void dvxShutdown(AppContextT *ctx);
-
Tear down the GUI stack in reverse order: destroy all windows, restore text mode, release input devices. Safe to call after a failed dvxInit().
-
Parameter Description
- --------- -----------
- ctx Application context
-
dvxChangeVideoMode
-
int32_t dvxChangeVideoMode(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);
-
Switch to a new video mode live. Reallocates the backbuffer, all window content buffers, repacks colors, rescales wallpaper, and repositions off-screen windows.
-
Parameter Description
- --------- -----------
- ctx Application context
- requestedW/H New resolution
- preferredBpp New bits per pixel
-
Returns: 0 on success, -1 on failure (old mode restored).
-
Event Loop
-
dvxRun
-
void dvxRun(AppContextT *ctx);
-
Enter the main event loop. Polls input, dispatches events, composites dirty regions, and yields on each iteration. Returns when ctx->running becomes false.
-
Parameter Description
- --------- -----------
- ctx Application context
-
dvxUpdate
-
bool dvxUpdate(AppContextT *ctx);
-
Process exactly one frame of the event loop. For applications that integrate the GUI into their own main loop (e.g. polling serial ports between frames).
-
Parameter Description
- --------- -----------
- ctx Application context
-
Returns: false when the GUI wants to exit.
-
dvxQuit
-
void dvxQuit(AppContextT *ctx);
-
Request exit from the main event loop (sets ctx->running = false).
-
Parameter Description
- --------- -----------
- ctx Application context
-
Window Management
-
dvxCreateWindow
-
WindowT *dvxCreateWindow(AppContextT *ctx, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);
-
Create a window at an explicit screen position. The window is raised to the top, focused, and its entire region is dirtied.
-
Parameter Description
- --------- -----------
- ctx Application context
- title Window title
- x, y Screen position
- w, h Outer frame dimensions
- resizable true = allow user resize
-
Returns: Pointer to new WindowT.
-
dvxCreateWindowCentered
-
WindowT *dvxCreateWindowCentered(AppContextT *ctx, const char *title, int32_t w, int32_t h, bool resizable);
-
Convenience wrapper that centers the window on screen.
-
Parameter Description
- --------- -----------
- ctx Application context
- title Window title
- w, h Outer frame dimensions
- resizable true = allow user resize
-
Returns: Pointer to new WindowT.
-
dvxDestroyWindow
-
void dvxDestroyWindow(AppContextT *ctx, WindowT *win);
-
Destroy a window, free all its resources, and dirty its former region.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to destroy
-
dvxRaiseWindow
-
void dvxRaiseWindow(AppContextT *ctx, WindowT *win);
-
Raise a window to the top of the Z-order and give it focus.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to raise
-
dvxFitWindow
-
void dvxFitWindow(AppContextT *ctx, WindowT *win);
-
Resize a window to exactly fit its widget tree's computed minimum size (plus chrome). Used for dialog boxes and fixed-layout windows.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to fit
-
dvxFitWindowW
-
void dvxFitWindowW(AppContextT *ctx, WindowT *win);
-
Resize window width only to fit widget tree's minimum width (plus chrome).
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to fit
-
dvxFitWindowH
-
void dvxFitWindowH(AppContextT *ctx, WindowT *win);
-
Resize window height only to fit widget tree's minimum height (plus chrome).
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to fit
-
dvxResizeWindow
-
void dvxResizeWindow(AppContextT *ctx, WindowT *win, int32_t newW, int32_t newH);
-
Programmatically resize a window to the specified outer dimensions.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to resize
- newW, newH New outer frame dimensions
-
dvxMinimizeWindow
-
void dvxMinimizeWindow(AppContextT *ctx, WindowT *win);
-
Minimize a window (show as icon at bottom of screen).
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to minimize
-
dvxMaximizeWindow
-
void dvxMaximizeWindow(AppContextT *ctx, WindowT *win);
-
Maximize a window (expand to fill screen or maxW/maxH).
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to maximize
-
dvxHideWindow
-
void dvxHideWindow(AppContextT *ctx, WindowT *win);
-
Hide a window without destroying it. Marks the exposed region dirty.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to hide
-
dvxShowWindow
-
void dvxShowWindow(AppContextT *ctx, WindowT *win);
-
Show a previously hidden window. Marks its region dirty for repaint.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to show
-
Invalidation
-
dvxInvalidateRect
-
void dvxInvalidateRect(AppContextT *ctx, WindowT *win, int32_t x, int32_t y, int32_t w, int32_t h);
-
Mark a sub-region of a window's content area as needing repaint. Coordinates are relative to the content area, not the screen. Triggers onPaint during the next composite pass.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window
- x, y, w, h Dirty rectangle in content-relative coordinates
-
dvxInvalidateWindow
-
void dvxInvalidateWindow(AppContextT *ctx, WindowT *win);
-
Mark the entire window content area as dirty.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to invalidate
-
Window Properties
-
dvxSetTitle
-
void dvxSetTitle(AppContextT *ctx, WindowT *win, const char *title);
-
Set a window's title text and dirty the title bar.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window
- title New title text
-
dvxSetWindowIcon
-
int32_t dvxSetWindowIcon(AppContextT *ctx, WindowT *win, const char *path);
-
Load an icon for a window from an image file.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window
- path Image file path
-
Returns: 0 on success, -1 on failure.
-
dvxSetBusy
-
void dvxSetBusy(AppContextT *ctx, bool busy);
-
Set or clear busy state. While busy, the hourglass cursor is shown and input is blocked.
-
Parameter Description
- --------- -----------
- ctx Application context
- busy true = show hourglass, false = normal
-
Accessors
-
dvxGetFont
-
const BitmapFontT *dvxGetFont(const AppContextT *ctx);
-
Get a pointer to the default font.
-
Parameter Description
- --------- -----------
- ctx Application context
-
Returns: Pointer to the active BitmapFontT.
-
dvxGetColors
-
const ColorSchemeT *dvxGetColors(const AppContextT *ctx);
-
Get a pointer to the current color scheme.
-
Parameter Description
- --------- -----------
- ctx Application context
-
Returns: Pointer to the active ColorSchemeT.
-
dvxGetDisplay
-
DisplayT *dvxGetDisplay(AppContextT *ctx);
-
Get a pointer to the display context.
-
Parameter Description
- --------- -----------
- ctx Application context
-
Returns: Pointer to the DisplayT.
-
dvxGetBlitOps
-
const BlitOpsT *dvxGetBlitOps(const AppContextT *ctx);
-
Get a pointer to the blit operations vtable.
-
Parameter Description
- --------- -----------
- ctx Application context
-
Returns: Pointer to the active BlitOpsT.
-
dvxGetVideoModes
-
const VideoModeInfoT *dvxGetVideoModes(const AppContextT *ctx, int32_t *count);
-
Return the list of available video modes enumerated at init time.
-
Parameter Description
- --------- -----------
- ctx Application context
- count Output: number of mode entries
-
Returns: Pointer to the VideoModeInfoT array.
-
Color Scheme
-
dvxSetColor
-
void dvxSetColor(AppContextT *ctx, ColorIdE id, uint8_t r, uint8_t g, uint8_t b);
-
Set a single color by ID. Repacks to native pixel format and invalidates the entire screen.
-
Parameter Description
- --------- -----------
- ctx Application context
- id Color ID (ColorIdE)
- r, g, b RGB values (0-255)
-
dvxGetColor
-
void dvxGetColor(const AppContextT *ctx, ColorIdE id, uint8_t *r, uint8_t *g, uint8_t *b);
-
Get a color's RGB values by ID.
-
Parameter Description
- --------- -----------
- ctx Application context
- id Color ID (ColorIdE)
- r, g, b Output: RGB values
-
dvxApplyColorScheme
-
void dvxApplyColorScheme(AppContextT *ctx);
-
Apply all colors from ctx->colorRgb[] at once (repack + full repaint).
-
Parameter Description
- --------- -----------
- ctx Application context
-
dvxResetColorScheme
-
void dvxResetColorScheme(AppContextT *ctx);
-
Reset all colors to the built-in defaults and repaint.
-
Parameter Description
- --------- -----------
- ctx Application context
-
dvxLoadTheme
-
bool dvxLoadTheme(AppContextT *ctx, const char *filename);
-
Load a theme file (INI format with [colors] section) and apply it.
-
Parameter Description
- --------- -----------
- ctx Application context
- filename Path to theme INI file
-
Returns: true on success.
-
dvxSaveTheme
-
bool dvxSaveTheme(const AppContextT *ctx, const char *filename);
-
Save the current color scheme to a theme file.
-
Parameter Description
- --------- -----------
- ctx Application context
- filename Output file path
-
Returns: true on success.
-
dvxColorName
-
const char *dvxColorName(ColorIdE id);
-
Return the INI key name for a color ID (e.g. "desktop", "windowFace").
-
Parameter Description
- --------- -----------
- id Color ID
-
Returns: Static string.
-
dvxColorLabel
-
const char *dvxColorLabel(ColorIdE id);
-
Return a human-readable display label (e.g. "Desktop", "Cursor Color").
-
Parameter Description
- --------- -----------
- id Color ID
-
Returns: Static string.
-
Wallpaper
-
dvxSetWallpaper
-
bool dvxSetWallpaper(AppContextT *ctx, const char *path);
-
Load and apply a wallpaper image using the current wallpaperMode (stretch/tile/center). Pass NULL to clear the wallpaper.
-
Parameter Description
- --------- -----------
- ctx Application context
- path Image file path, or NULL to clear
-
Returns: true on success.
-
dvxSetWallpaperMode
-
void dvxSetWallpaperMode(AppContextT *ctx, WallpaperModeE mode);
-
Change the wallpaper display mode and re-render. No effect if no wallpaper is loaded.
-
Parameter Description
- --------- -----------
- ctx Application context
- mode WallpaperStretchE, WallpaperTileE, or WallpaperCenterE
-
Mouse Configuration
-
dvxSetMouseConfig
-
void dvxSetMouseConfig(AppContextT *ctx, int32_t wheelDir, int32_t dblClickMs, int32_t accelThreshold);
-
Configure mouse behavior.
-
Parameter Description
- --------- -----------
- ctx Application context
- wheelDir 1 = normal, -1 = reversed
- dblClickMs Double-click speed in milliseconds (e.g. 500)
- accelThreshold Double-speed threshold in mickeys/sec (0 = don't change)
-
Accelerators
-
dvxCreateAccelTable
-
AccelTableT *dvxCreateAccelTable(void);
-
Allocate a new accelerator table. Attach to a window via win->accelTable.
-
Returns: Pointer to new AccelTableT.
-
dvxFreeAccelTable
-
void dvxFreeAccelTable(AccelTableT *table);
-
Free an accelerator table and its entries.
-
Parameter Description
- --------- -----------
- table Table to free
-
dvxAddAccel
-
void dvxAddAccel(AccelTableT *table, int32_t key, int32_t modifiers, int32_t cmdId);
-
Register a keyboard shortcut. On match, fires the window's onMenu callback with cmdId.
-
Parameter Description
- --------- -----------
- table Accelerator table
- key ASCII character or KEY_Fxx constant
- modifiers Bitmask of ACCEL_CTRL / ACCEL_SHIFT / ACCEL_ALT
- cmdId Command ID passed to onMenu
-
Window Arrangement
-
dvxCascadeWindows
-
void dvxCascadeWindows(AppContextT *ctx);
-
Cascade all visible, non-minimized windows. Each is offset diagonally by the title bar height.
-
Parameter Description
- --------- -----------
- ctx Application context
-
dvxTileWindows
-
void dvxTileWindows(AppContextT *ctx);
-
Arrange visible windows in an NxM grid filling the screen.
-
Parameter Description
- --------- -----------
- ctx Application context
-
dvxTileWindowsH
-
void dvxTileWindowsH(AppContextT *ctx);
-
Tile windows horizontally (side by side, equal width, full height).
-
Parameter Description
- --------- -----------
- ctx Application context
-
dvxTileWindowsV
-
void dvxTileWindowsV(AppContextT *ctx);
-
Tile windows vertically (stacked, full width, equal height).
-
Parameter Description
- --------- -----------
- ctx Application context
-
Image I/O
-
dvxLoadImage
-
uint8_t *dvxLoadImage(const AppContextT *ctx, const char *path, int32_t *outW, int32_t *outH, int32_t *outPitch);
-
Load an image file (BMP, PNG, JPEG, GIF) and convert to the display's native pixel format. Caller must free with dvxFreeImage().
-
Parameter Description
- --------- -----------
- ctx Application context
- path Image file path
- outW, outH Output: image dimensions
- outPitch Output: row pitch in bytes
-
Returns: Pixel buffer, or NULL on failure.
-
dvxLoadImageFromMemory
-
uint8_t *dvxLoadImageFromMemory(const AppContextT *ctx, const uint8_t *data, int32_t dataLen, int32_t *outW, int32_t *outH, int32_t *outPitch);
-
Load an image from a memory buffer. Same output format as dvxLoadImage(). Caller must free with dvxFreeImage().
-
Parameter Description
- --------- -----------
- ctx Application context
- data Image data buffer
- dataLen Buffer size in bytes
- outW, outH Output: image dimensions
- outPitch Output: row pitch in bytes
-
Returns: Pixel buffer, or NULL on failure.
-
dvxFreeImage
-
void dvxFreeImage(uint8_t *data);
-
Free a pixel buffer returned by dvxLoadImage() or dvxLoadImageFromMemory().
-
Parameter Description
- --------- -----------
- data Buffer to free
-
dvxImageInfo
-
bool dvxImageInfo(const char *path, int32_t *outW, int32_t *outH);
-
Query image dimensions without decoding the full file.
-
Parameter Description
- --------- -----------
- path Image file path
- outW, outH Output: image dimensions
-
Returns: true on success.
-
dvxSaveImage
-
int32_t dvxSaveImage(const AppContextT *ctx, const uint8_t *data, int32_t w, int32_t h, int32_t pitch, const char *path);
-
Save native-format pixel data to a PNG file.
-
Parameter Description
- --------- -----------
- ctx Application context
- data Pixel data in display native format
- w, h Image dimensions
- pitch Row pitch in bytes
- path Output file path
-
Returns: 0 on success, -1 on failure.
-
Screenshots
-
dvxScreenshot
-
int32_t dvxScreenshot(AppContextT *ctx, const char *path);
-
Save the entire screen (backbuffer contents) to a PNG file. Converts from native pixel format to RGB.
-
Parameter Description
- --------- -----------
- ctx Application context
- path Output PNG file path
-
Returns: 0 on success, -1 on failure.
-
dvxWindowScreenshot
-
int32_t dvxWindowScreenshot(AppContextT *ctx, WindowT *win, const char *path);
-
Save a window's content to a PNG file.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window
- path Output PNG file path
-
Returns: 0 on success, -1 on failure.
-
Clipboard
-
dvxClipboardCopy
-
void dvxClipboardCopy(const char *text, int32_t len);
-
Copy text to the process-wide clipboard buffer. Simple static buffer (not inter-process).
-
Parameter Description
- --------- -----------
- text Text to copy
- len Length in bytes
-
dvxClipboardGet
-
const char *dvxClipboardGet(int32_t *outLen);
-
Retrieve the current clipboard contents. Returns a pointer to the internal buffer (valid until the next dvxClipboardCopy), or NULL if empty.
-
Parameter Description
- --------- -----------
- outLen Output: length of clipboard text
-
Returns: Clipboard text, or NULL.
-
Resource Loading
-
dvxResLoadIcon
-
uint8_t *dvxResLoadIcon(AppContextT *ctx, const char *dxePath, const char *resName, int32_t *outW, int32_t *outH, int32_t *outPitch);
-
Load an icon/image resource from a DXE file and decode to native pixel format. Caller must free with dvxFreeImage().
-
Parameter Description
- --------- -----------
- ctx Application context
- dxePath Path to DXE file
- resName Resource name within the DXE
- outW, outH Output: image dimensions
- outPitch Output: row pitch
-
Returns: Pixel buffer, or NULL if not found.
-
dvxResLoadText
-
bool dvxResLoadText(const char *dxePath, const char *resName, char *buf, int32_t bufSize);
-
Load a text resource from a DXE file into a caller-provided buffer. Null-terminated and truncated to fit bufSize.
-
Parameter Description
- --------- -----------
- dxePath Path to DXE file
- resName Resource name
- buf Output buffer
- bufSize Buffer capacity
-
Returns: true on success.
-
dvxResLoadData
-
void *dvxResLoadData(const char *dxePath, const char *resName, uint32_t *outSize);
-
Load a raw binary resource from a DXE file. Returns a malloc'd buffer that the caller must free.
-
Parameter Description
- --------- -----------
- dxePath Path to DXE file
- resName Resource name
- outSize Output: data size in bytes
-
Returns: Data buffer, or NULL if not found.
-
Utilities
-
dvxTextHash
-
uint32_t dvxTextHash(const char *text);
-
Compute a djb2-xor hash for cheap dirty detection. Compare at save time with the current hash to detect changes without a shadow copy. Not cryptographic.
-
Parameter Description
- --------- -----------
- text Null-terminated string to hash
-
Returns: 32-bit hash value.
-
-
dvxWidget.h -- Widget System
-
dvxWidget.h -- Widget System
-
Retained-mode widget toolkit layered on the DVX window manager. Widgets form a tree (parent-child) rooted at a per-window VBox container. Layout is automatic: measure minimum sizes bottom-up, then allocate space top-down with flexbox-like weighted distribution. Widget types are registered dynamically at runtime via DXE plugins.
-
WidgetT Structure
-
Core widget structure. Generic across all widget types; type-specific data lives in the void *data pointer managed by each widget's DXE.
-
Field Description
- ----- -----------
- int32_t type Widget type ID (assigned by wgtRegisterClass)
- const WidgetClassT *wclass Vtable for this widget type
- char name[MAX_WIDGET_NAME] Widget name for lookup via wgtFind
- parent, firstChild, lastChild, nextSibling Tree linkage pointers
- WindowT *window Owning window
- int32_t x, y, w, h Computed geometry (relative to content area)
- int32_t calcMinW, calcMinH Computed minimum size (from layout pass)
- int32_t minW, minH, maxW, maxH, prefW, prefH Size hints (tagged sizes)
- int32_t weight Extra-space distribution weight (0=fixed, 100=normal)
- WidgetAlignE align Main-axis alignment for children
- int32_t spacing, padding Tagged sizes for child spacing and padding
- uint32_t fgColor, bgColor Custom colors (0 = use scheme defaults)
- bool visible, enabled, readOnly State flags
- bool swallowTab Tab key goes to widget, not focus navigation
- char accelKey Accelerator character (0 = none)
- void *userData, *data Application data and widget-private data
- const char *tooltip Tooltip text (NULL = none)
- MenuT *contextMenu Right-click menu (NULL = none)
-
Universal Callbacks:
-
Callback Description
- -------- -----------
- onClick(WidgetT *w) Widget clicked
- onDblClick(WidgetT *w) Widget double-clicked
- onChange(WidgetT *w) Value changed
- onFocus(WidgetT *w) Widget gained focus
- onBlur(WidgetT *w) Widget lost focus
- onKeyPress(WidgetT *w, int32_t keyAscii) ASCII key press
- onKeyDown(WidgetT *w, int32_t keyCode, int32_t shift) Key down
- onKeyUp(WidgetT *w, int32_t keyCode, int32_t shift) Key up
- onMouseDown(WidgetT *w, int32_t btn, int32_t x, int32_t y) Mouse button pressed
- onMouseUp(WidgetT *w, int32_t btn, int32_t x, int32_t y) Mouse button released
- onMouseMove(WidgetT *w, int32_t btn, int32_t x, int32_t y) Mouse moved
- onScroll(WidgetT *w, int32_t delta) Mouse wheel
- onValidate(WidgetT *w) Return false to cancel a write
-
Size Specification Macros
-
Macro Description
- ----- -----------
- wgtPixels(v) Size in pixels
- wgtChars(v) Size in character widths (multiplied by charWidth at layout)
- wgtPercent(v) Size as percentage of parent dimension
-
Widget Class Flags
-
Flag Description
- ---- -----------
- WCLASS_FOCUSABLE Can receive keyboard focus (Tab navigation)
- WCLASS_HORIZ_CONTAINER Lays out children horizontally (vs. vertical)
- WCLASS_PAINTS_CHILDREN Widget handles child rendering itself
- WCLASS_NO_HIT_RECURSE Hit testing stops here, no child recursion
- WCLASS_FOCUS_FORWARD Accel hit forwards focus to next focusable sibling
- WCLASS_HAS_POPUP Has dropdown popup overlay
- WCLASS_SCROLLABLE Accepts mouse wheel events
- WCLASS_SCROLL_CONTAINER Scroll container (ScrollPane)
- WCLASS_NEEDS_POLL Needs periodic polling
- WCLASS_SWALLOWS_TAB Tab key goes to widget, not focus navigation
- WCLASS_RELAYOUT_ON_SCROLL Full relayout on scrollbar drag
- WCLASS_PRESS_RELEASE Click = press + release (Button, ImageButton)
- WCLASS_ACCEL_WHEN_HIDDEN Accelerator matching works even when invisible
-
Window Integration
-
wgtInitWindow
-
WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win);
-
Initialize the widget system for a window. Creates a root VBox container that fills the content area, and installs callback handlers (onPaint, onMouse, onKey, onResize) for widget-based event dispatch. The window's userData is set to the AppContextT pointer.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to initialize
-
Returns: Root VBox widget (add children to this).
-
Widget Operations
-
wgtGetContext
-
AppContextT *wgtGetContext(const WidgetT *w);
-
Walk from any widget up the tree to the root, then retrieve the AppContextT stored in the window's userData. Lets any widget access the full application context.
-
Parameter Description
- --------- -----------
- w Any widget in the tree
-
Returns: Pointer to the AppContextT.
-
wgtInvalidate
-
void wgtInvalidate(WidgetT *w);
-
Mark a widget as needing both re-layout (measure + position) and repaint. Propagates upward to ancestors. Use after structural changes (adding/removing children, text changes that affect size).
-
Parameter Description
- --------- -----------
- w Widget to invalidate
-
wgtInvalidatePaint
-
void wgtInvalidatePaint(WidgetT *w);
-
Mark a widget as needing repaint only, without re-layout. Use for visual-only changes (checkbox toggle, selection highlight, cursor blink).
-
Parameter Description
- --------- -----------
- w Widget to repaint
-
wgtSetText
-
void wgtSetText(WidgetT *w, const char *text);
-
Set widget text content (dispatches to the widget class's SET_TEXT handler).
-
Parameter Description
- --------- -----------
- w Widget
- text New text
-
wgtGetText
-
const char *wgtGetText(const WidgetT *w);
-
Get the widget's current text content.
-
Parameter Description
- --------- -----------
- w Widget
-
Returns: Text string (empty string if no handler).
-
wgtSetEnabled
-
void wgtSetEnabled(WidgetT *w, bool enabled);
-
Enable or disable a widget. Disabled widgets are grayed out and do not receive input.
-
Parameter Description
- --------- -----------
- w Widget
- enabled true = enabled, false = disabled
-
wgtSetReadOnly
-
void wgtSetReadOnly(WidgetT *w, bool readOnly);
-
Set read-only mode. Allows scrolling and selection but blocks editing.
-
Parameter Description
- --------- -----------
- w Widget
- readOnly true = read-only
-
wgtSetFocused
-
void wgtSetFocused(WidgetT *w);
-
Set keyboard focus to a widget.
-
Parameter Description
- --------- -----------
- w Widget to focus
-
wgtGetFocused
-
WidgetT *wgtGetFocused(void);
-
Get the currently focused widget.
-
Returns: Focused widget, or NULL.
-
wgtSetVisible
-
void wgtSetVisible(WidgetT *w, bool visible);
-
Show or hide a widget.
-
Parameter Description
- --------- -----------
- w Widget
- visible true = visible, false = hidden
-
wgtSetName
-
void wgtSetName(WidgetT *w, const char *name);
-
Set a widget's name for lookup via wgtFind().
-
Parameter Description
- --------- -----------
- w Widget
- name Name string (max MAX_WIDGET_NAME chars)
-
wgtFind
-
WidgetT *wgtFind(WidgetT *root, const char *name);
-
Find a widget by name. Searches the subtree rooted at root.
-
Parameter Description
- --------- -----------
- root Root of subtree to search
- name Widget name to find
-
Returns: Matching widget, or NULL.
-
wgtDestroy
-
void wgtDestroy(WidgetT *w);
-
Destroy a widget and all its children. Removes from parent's child list.
-
Parameter Description
- --------- -----------
- w Widget to destroy
-
wgtSetTooltip
-
void wgtSetTooltip(WidgetT *w, const char *text);
-
Set tooltip text for a widget. Pass NULL to remove. Caller owns the string and it must outlive the widget.
-
Parameter Description
- --------- -----------
- w Widget
- text Tooltip text, or NULL
-
widgetOnResize
-
void widgetOnResize(WindowT *win, int32_t newW, int32_t newH);
-
Default window resize handler installed by wgtInitWindow(). Re-evaluates scrollbars and relayouts the widget tree. Call from custom onResize handlers to chain to the widget system.
-
Parameter Description
- --------- -----------
- win Window being resized
- newW, newH New content dimensions
-
Layout
-
wgtResolveSize
-
int32_t wgtResolveSize(int32_t taggedSize, int32_t parentSize, int32_t charWidth);
-
Decode a tagged size value (WGT_SIZE_PIXELS/CHARS/PERCENT) into a concrete pixel count. Returns 0 for a raw 0 input (meaning "auto").
-
Parameter Description
- --------- -----------
- taggedSize Tagged size value
- parentSize Parent dimension (for PERCENT mode)
- charWidth Font character width (for CHARS mode)
-
Returns: Size in pixels.
-
wgtLayout
-
void wgtLayout(WidgetT *root, int32_t availW, int32_t availH, const BitmapFontT *font);
-
Execute the full two-pass layout algorithm. Pass 1 (bottom-up): compute minimum sizes. Pass 2 (top-down): allocate space with weighted distribution. Normally called automatically; exposed for cases where layout must be forced before the next paint.
-
Parameter Description
- --------- -----------
- root Root widget
- availW/H Available space
- font Bitmap font (for character-based sizing)
-
wgtPaint
-
void wgtPaint(WidgetT *root, DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors);
-
Paint the entire widget tree by depth-first traversal. Each widget's clip rect is set to its bounds. Overlays (popups, tooltips) are painted in a second pass on top.
-
Parameter Description
- --------- -----------
- root Root widget
- d Display context
- ops Blit operations vtable
- font Bitmap font
- colors Color scheme
-
Debug
-
wgtSetDebugLayout
-
void wgtSetDebugLayout(AppContextT *ctx, bool enabled);
-
Draw colored borders around layout containers for debugging.
-
Parameter Description
- --------- -----------
- ctx Application context
- enabled true = draw debug borders
-
Dynamic Widget Registration
-
wgtRegisterClass
-
int32_t wgtRegisterClass(const WidgetClassT *wclass);
-
Register a new widget class at runtime. Appends to widgetClassTable. The WidgetClassT must remain valid for the lifetime of the process (typically static const in a DXE).
-
Parameter Description
- --------- -----------
- wclass Widget class vtable to register
-
Returns: Assigned type ID.
-
wgtRegisterApi
-
void wgtRegisterApi(const char *name, const void *api);
-
Register a widget API struct under a name. Each widget DXE registers its API during initialization. Callers retrieve it via wgtGetApi() and cast to the widget-specific type.
-
Parameter Description
- --------- -----------
- name Widget type name (e.g. "button", "listbox")
- api Pointer to the widget's API struct
-
wgtGetApi
-
const void *wgtGetApi(const char *name);
-
Retrieve a registered widget API struct by name.
-
Parameter Description
- --------- -----------
- name Widget type name
-
Returns: Pointer to the API struct, or NULL if not found.
-
Widget Interface Descriptors
-
wgtRegisterIface
-
void wgtRegisterIface(const char *name, const WgtIfaceT *iface);
-
Register an interface descriptor for a widget type. Used by the BASIC form runtime and IDE for generic property/method dispatch.
-
Parameter Description
- --------- -----------
- name Widget type name
- iface Interface descriptor
-
wgtGetIface
-
const WgtIfaceT *wgtGetIface(const char *name);
-
Retrieve an interface descriptor by widget type name.
-
Parameter Description
- --------- -----------
- name Widget type name
-
Returns: Interface descriptor, or NULL.
-
wgtFindByBasName
-
const char *wgtFindByBasName(const char *basName);
-
Find a widget type name by its VB-style name (e.g. "CommandButton" -> "button"). Case-insensitive search.
-
Parameter Description
- --------- -----------
- basName VB-style widget name
-
Returns: Internal type name, or NULL.
-
wgtIfaceCount
-
int32_t wgtIfaceCount(void);
-
Return the number of registered widget interfaces.
-
Returns: Count of registered interfaces.
-
wgtIfaceAt
-
const WgtIfaceT *wgtIfaceAt(int32_t idx, const char **outName);
-
Get a registered widget interface by index.
-
Parameter Description
- --------- -----------
- idx Index (0-based)
- outName Output: type name
-
Returns: Interface descriptor.
-
wgtIfaceGetPath
-
const char *wgtIfaceGetPath(const char *name);
-
Get the .wgt DXE file path for a registered widget.
-
Parameter Description
- --------- -----------
- name Widget type name
-
Returns: File path string.
-
wgtIfaceSetPath
-
void wgtIfaceSetPath(const char *name, const char *path);
-
Set the .wgt DXE file path for a registered widget (called by the loader).
-
Parameter Description
- --------- -----------
- name Widget type name
- path DXE file path
-
wgtIfaceGetPathIndex
-
int32_t wgtIfaceGetPathIndex(const char *name);
-
Get the 1-based index of this widget within its .wgt file. Used to construct suffixed resource names (e.g. "name-2", "icon16-2").
-
Parameter Description
- --------- -----------
- name Widget type name
-
Returns: 1-based index within the DXE file.
-
Typed Dispatch Helpers
-
The following inline functions provide type-safe dispatch through the WidgetClassT handler table. Each checks for a non-NULL handler before calling.
-
Function Method ID Description
- -------- --------- -----------
- wclsHas(w, methodId) -- Check if handler exists
- wclsPaint(w, d, ops, font, colors) WGT_METHOD_PAINT Paint the widget
- wclsPaintOverlay(w, d, ops, font, colors) WGT_METHOD_PAINT_OVERLAY Paint overlay (popups)
- wclsCalcMinSize(w, font) WGT_METHOD_CALC_MIN_SIZE Compute minimum size
- wclsLayout(w, font) WGT_METHOD_LAYOUT Layout children
- wclsGetLayoutMetrics(w, font, ...) WGT_METHOD_GET_LAYOUT_METRICS Get pad, gap, extraTop, borderW
- wclsOnMouse(w, root, vx, vy) WGT_METHOD_ON_MOUSE Handle mouse event
- wclsOnKey(w, key, mod) WGT_METHOD_ON_KEY Handle key event
- wclsOnAccelActivate(w, root) WGT_METHOD_ON_ACCEL_ACTIVATE Handle accelerator
- wclsDestroy(w) WGT_METHOD_DESTROY Destroy widget data
- wclsOnChildChanged(parent, child) WGT_METHOD_ON_CHILD_CHANGED Notify parent of change
- wclsGetText(w) WGT_METHOD_GET_TEXT Get widget text
- wclsSetText(w, text) WGT_METHOD_SET_TEXT Set widget text
- wclsClearSelection(w) WGT_METHOD_CLEAR_SELECTION Clear text selection
- wclsClosePopup(w) WGT_METHOD_CLOSE_POPUP Close dropdown popup
- wclsGetPopupRect(w, font, ...) WGT_METHOD_GET_POPUP_RECT Get popup screen rect
- wclsOnDragUpdate(w, root, x, y) WGT_METHOD_ON_DRAG_UPDATE Update during drag
- wclsOnDragEnd(w, root, x, y) WGT_METHOD_ON_DRAG_END End drag operation
- wclsGetCursorShape(w, vx, vy) WGT_METHOD_GET_CURSOR_SHAPE Get cursor for position
- wclsPoll(w, win) WGT_METHOD_POLL Periodic polling
- wclsQuickRepaint(w, outY, outH) WGT_METHOD_QUICK_REPAINT Fast partial repaint
- wclsScrollChildIntoView(parent, child) WGT_METHOD_SCROLL_CHILD_INTO_VIEW Scroll child visible
-
-
DVX Architecture Overview
-
DVX Architecture Overview
-
DOS Visual eXecutive -- A Windowing GUI for DJGPP/DPMI
-
DVX (DOS Visual eXecutive) is a complete windowing GUI compositor targeting DJGPP/DPMI on DOS. It provides overlapping windows with Motif-style chrome, a retained-mode widget toolkit, cooperative multitasking of DXE-loaded applications, and a dirty-rectangle compositor optimized for 486/Pentium hardware.
-
Key Design Constraints
-
-- VESA VBE 2.0+ LFB only -- no bank switching. If the hardware cannot provide a linear framebuffer, initialization fails.
-- 486 baseline -- all hot paths are written to be fast on a 486, with Pentium-specific paths where the gain is significant.
-- Single-tasking cooperative model -- applications yield the CPU via tsYield(); there is no preemptive scheduler.
-- 86Box is the trusted reference platform for testing. DOSBox-X is not used; any bugs observed are treated as DVX bugs.
-
-
No external font or cursor files -- all bitmaps are compiled in as static const data.
-
The runtime environment consists of a bootstrap loader (dvx.exe) that loads core DXE libraries, widget plugins, and the shell, which in turn loads and manages DXE application modules.
-
Contents
-
Five-Layer Architecture
-
Display Pipeline
-
Window System
-
Widget System
-
DXE Module System
-
Event Model
-
Font System
-
Color System
-
Platform Layer
-
Build System
-
-
Five-Layer Architecture
-
Five-Layer Architecture
-
DVX is organized into five layers, each implemented as a single .h/.c pair. Every header includes dvxTypes.h (the shared type definitions) to avoid circular dependencies. The layers are strictly stacked: each layer depends only on the layers below it.
-
Applications (DXE .app modules)
- ==================================================
- | |
- | +------------------------------------------+ |
- | | Layer 5: dvxApp (Application API) | | dvxApp.h / dvxApp.c
- | | Event loop, window creation, public API | |
- | +------------------------------------------+ |
- | | Layer 4: dvxWm (Window Manager) | | dvxWm.h / dvxWm.c
- | | Window stack, chrome, drag, resize | |
- | +------------------------------------------+ |
- | | Layer 3: dvxComp (Compositor) | | dvxComp.h / dvxComp.c
- | | Dirty rect tracking, merge, LFB flush | |
- | +------------------------------------------+ |
- | | Layer 2: dvxDraw (Drawing Primitives) | | dvxDraw.h / dvxDraw.c
- | | Rects, bevels, text, blits, cursors | |
- | +------------------------------------------+ |
- | | Layer 1: dvxVideo (Video Backend) | | dvxVideo.h / dvxVideo.c
- | | VESA VBE, LFB mapping, pixel format | |
- | +------------------------------------------+ |
- | |
- | +------------------------------------------+ |
- | | Platform Layer (dvxPlatform.h) | | dvxPlatformDos.c
- | | OS-specific: video, input, asm spans | |
- | +------------------------------------------+ |
- | |
- | +------------------------------------------+ |
- | | Shared Types (dvxTypes.h) | |
- | | DisplayT, WindowT, RectT, ColorSchemeT | |
- | +------------------------------------------+ |
- ==================================================
-
Layer Summary
-
Layer Header Responsibility
- ----- ------ --------------
- 1 - Video dvxVideo.h VESA VBE mode negotiation, LFB mapping via DPMI, backbuffer allocation, packColor() (RGB to native pixel format), display-wide clip rectangle.
- 2 - Draw dvxDraw.h All 2D drawing: rectFill, rectCopy, drawBevel, drawText/drawTextN, drawMaskedBitmap (cursor), drawTermRow (batch terminal row). Stateless beyond clip rect. Dispatches hot inner loops through BlitOpsT function pointers.
- 3 - Compositor dvxComp.h Dirty rectangle tracking (dirtyListAdd), pairwise merge of overlapping rects (dirtyListMerge), and flushRect to copy dirty regions from backBuf to LFB.
- 4 - Window Manager dvxWm.h Window lifecycle, Z-order stack, chrome drawing (title bars, bevels, close/minimize/maximize gadgets), hit testing, drag/resize, menu bars, scrollbars, system menu, keyboard move/resize, minimized icon bar.
- 5 - Application dvxApp.h Public API aggregating all layers into AppContextT. Provides dvxInit/dvxShutdown, dvxRun/dvxUpdate, window creation helpers, image loading, clipboard, accelerator tables, theme management, wallpaper, video mode switching, screenshot capture.
-
-
Display Pipeline
-
Display Pipeline
-
The double-buffer strategy is the single most important performance decision in DVX. All drawing goes to a system RAM backbuffer (DisplayT.backBuf); only dirty rectangles are flushed to the linear framebuffer (DisplayT.lfb) in video memory.
-
This matters because writes to video memory over the PCI bus are 10-50x slower than writes to main RAM on 486/Pentium hardware for random-access patterns.
-
Per-Frame Compositing Pipeline
-
1. Input poll (mouse, keyboard)
- |
- 2. Event dispatch (focus window callbacks)
- |
- 3. Layers call dirtyListAdd() for changed regions
- |
- 4. dirtyListMerge() consolidates overlapping rects
- |
- 5. For each merged dirty rect:
- a. Clip and redraw desktop background (or wallpaper)
- b. For each window (back-to-front, painter's algorithm):
- - wmDrawChrome() -- frame, title bar, gadgets, menu bar
- - wmDrawContent() -- blit per-window content buffer
- - wmDrawScrollbars()
- c. Draw minimized window icons
- d. Draw popup menus / tooltips (overlay pass)
- e. Draw software mouse cursor
- |
- 6. flushRect() -- copy each dirty rect from backBuf to LFB
- |
- 7. Yield (platformYield)
-
Key Data Structures
-
DisplayT -- Central display context: width, height, pitch, pixel format, LFB pointer, backbuffer pointer, palette, clip rectangle. Passed by pointer through every layer -- no globals.
-
BlitOpsT -- Vtable of span fill/copy function pointers resolved at init time for the active pixel depth. On DOS these dispatch to hand-written rep stosl / rep movsd asm inner loops.
-
DirtyListT -- Fixed-capacity dynamic array of RectT. Linear scanning for merge candidates is cache-friendly at typical sizes (under 128 rects). If the list fills up, the compositor merges aggressively or falls back to full-screen repaint.
-
Why This Works on a 486
-
-- A full 640x480x32bpp frame is 1.2 MB -- far too much to flush every frame over a slow PCI bus.
-- A typical dirty region during normal interaction (typing, menu open) is a few KB.
-- Merging overlapping dirty rects into larger rects reduces per-rect overhead and improves bus utilization.
-
-
Per-window content buffers persist across frames, so windows don't repaint on expose -- only when their own content changes.
-
-
Window System
-
Window System
-
WindowT Structure
-
Each WindowT is the central object of the window manager. Key fields:
-
Field Group Purpose
- ----------- -------
- Geometry (x, y, w, h) Outer frame rectangle (including chrome).
- Content area (contentX/Y/W/H) Computed from frame minus chrome. Where application content lives.
- Content buffer (contentBuf, contentPitch) Per-window backbuffer in native pixel format. Persists across frames.
- Chrome state (menuBar, vScroll, hScroll) Optional menu bar and scrollbars. Affect content area computation.
- Widget tree (widgetRoot) Root of the retained-mode widget tree (NULL if using raw callbacks).
- Callbacks onPaint, onKey, onKeyUp, onMouse, onResize, onClose, onMenu, onScroll, onFocus, onBlur, onCursorQuery.
-
Window Stack (Z-Order)
-
WindowStackT is an array of WindowT* ordered front-to-back: index count-1 is the topmost window. This allows:
-
-- Back-to-front iteration for painting (painter's algorithm).
-- Front-to-back iteration for hit testing (first hit wins).
-
-
Reordering by pointer swap (no copying of large WindowT structs).
-
Only one drag/resize/scroll operation can be active system-wide at a time (single mouse), so that state lives on the stack, not on individual windows.
-
Chrome Layout
-
+-------------------------------------------+
- | 4px outer border (raised bevel) |
- | +-------------------------------------+ |
- | | [X] Title Bar Text [_] [^] [X] | | 20px title height
- | +-------------------------------------+ |
- | | 2px inner border | |
- | +-------------------------------------+ |
- | | Menu Bar (optional, 20px) | |
- | +-------------------------------------+ |
- | | | |
- | | Content Area | |
- | | | |
- | | | S | | S = vertical scrollbar
- | | | B | | (16px wide)
- | +-------------------------------------+ |
- | | Horizontal Scrollbar (optional) | | 16px tall
- | +-------------------------------------+ |
- | 4px outer border |
- +-------------------------------------------+
-
Chrome constants are compile-time defines:
-
CHROME_BORDER_WIDTH = 4px
- CHROME_TITLE_HEIGHT = 20px
- CHROME_INNER_BORDER = 2px
- CHROME_MENU_HEIGHT = 20px
- SCROLLBAR_WIDTH = 16px
- CHROME_CLOSE_BTN_SIZE = 16px
-
Hit Test Regions
-
wmHitTest() iterates the stack front-to-back and returns a hit-part identifier: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, HIT_RESIZE, HIT_MENU, HIT_VSCROLL, HIT_HSCROLL, HIT_MINIMIZE, HIT_MAXIMIZE. Resize edge detection returns a bitmask of RESIZE_LEFT, RESIZE_RIGHT, RESIZE_TOP, RESIZE_BOTTOM (corners combine two edges).
-
Menu System
-
Menus use fixed-size arrays with inline char buffers (no heap strings). Up to 8 menus per bar, items dynamically allocated. Supports cascading submenus via MenuItemT.subMenu pointer. Item types: normal, checkbox, radio. Separators are non-interactive items. The popup state (PopupStateT) tracks a stack of parent frames for cascading submenu nesting.
-
Minimized Windows
-
Minimized windows display as 64x64 icons at the bottom of the screen with beveled borders, similar to a classic desktop icon bar. Icons show a scaled-down preview of the window's content buffer, refreshed one per frame in a round-robin fashion to amortize the scaling cost.
-
-
Widget System
-
Widget System
-
The widget system (dvxWidget.h) is a retained-mode toolkit layered on top of the window manager. Widgets form a tree rooted at a per-window VBox container.
-
WidgetT Base Structure
-
Every widget shares the same WidgetT struct. The type field is a runtime-assigned integer ID. The wclass pointer references the widget's WidgetClassT vtable. Widget-specific private data is stored in w->data (opaque void*).
-
Tree linkage: parent, firstChild, lastChild, nextSibling. No prevSibling -- this halves pointer overhead and removal is still O(n) for typical tree depths of 5-10.
-
Layout Engine
-
Two-pass flexbox-like algorithm:
-
-- Bottom-up (calcMinSize) -- compute minimum sizes for every widget, starting from leaves.
-
-
Top-down (layout) -- allocate space within available bounds, distributing extra space according to weight values (0 = fixed, 100 = normal stretch).
-
Size hints use a tagged encoding: the top 2 bits of an int32_t select the unit (pixels, character widths, or percentage of parent), the low 30 bits hold the value. Macros: wgtPixels(v), wgtChars(v), wgtPercent(v).
-
Widget Class Dispatch (WidgetClassT)
-
Each widget type provides a WidgetClassT with a handlers[] array indexed by stable method IDs. Method IDs are never reordered or reused -- new methods append at the end. This provides ABI-stable dispatch so that widget DXEs compiled against an older DVX version continue to work.
-
Methods include: PAINT, PAINT_OVERLAY, CALC_MIN_SIZE, LAYOUT, ON_MOUSE, ON_KEY, ON_ACCEL_ACTIVATE, DESTROY, GET_TEXT, SET_TEXT, POLL, and more (21 defined, room for 32).
-
Class Flags
-
Flag Meaning
- ---- -------
- WCLASS_FOCUSABLE Can receive keyboard focus (Tab navigation)
- WCLASS_HORIZ_CONTAINER Lays out children horizontally (HBox)
- WCLASS_PAINTS_CHILDREN Widget handles child rendering itself
- WCLASS_SCROLLABLE Accepts mouse wheel events
- WCLASS_SCROLL_CONTAINER ScrollPane -- scrolling viewport
- WCLASS_NEEDS_POLL Needs periodic polling (e.g. AnsiTerm comms)
- WCLASS_SWALLOWS_TAB Tab key goes to widget, not focus navigation
- WCLASS_PRESS_RELEASE Click = press + release (buttons)
-
Available Widget Types
-
Each widget is a separate .wgt DXE module. 29 widget types are included:
-
Widget Description
- ------ -----------
- Box (VBox/HBox) Vertical and horizontal layout containers
- Button Clickable push button with label
- Canvas Raw drawing surface for custom painting
- Checkbox Boolean toggle with checkmark
- ComboBox Text input with dropdown list
- DataCtrl Data-bound control for database operations
- DbGrid Database grid (tabular data display)
- Dropdown Dropdown selection list
- Image Static image display
- ImageButton Button with bitmap icon
- Label Static text label
- ListBox Scrollable selection list
- ListView Multi-column list with headers and sorting
- ProgressBar Determinate progress indicator
- Radio Radio button (mutual exclusion group)
- ScrollPane Scrollable viewport container
- Separator Visual divider line
- Slider Value selection via draggable thumb
- Spacer Empty space for layout
- Spinner Numeric input with up/down arrows
- Splitter Resizable split pane
- StatusBar Window status bar with sections
- TabControl Tabbed page container
- Terminal (AnsiTerm) ANSI terminal emulator widget
- TextInput Single-line text entry field
- Timer Periodic timer events
- Toolbar Toolbar with icon buttons
- TreeView Hierarchical tree display
- WrapBox Flow layout (wrapping horizontal container)
-
Widget API Registry
-
Each widget DXE registers a small API struct under a name during wgtRegister(). Callers retrieve it via wgtGetApi("button") and cast to the widget-specific API type. Per-widget headers provide typed accessors so callers avoid manual casts. Adding a new widget requires zero changes to the core.
-
Widget Interface Descriptors (WgtIfaceT)
-
Each widget can register an interface descriptor that describes its BASIC-facing properties, methods, and events. These descriptors are used by the form runtime and IDE for generic dispatch and property panel enumeration. Properties have typed getters/setters (WGT_IFACE_STRING, WGT_IFACE_INT, WGT_IFACE_BOOL, WGT_IFACE_ENUM).
-
-
DXE Module System
-
DXE Module System
-
DVX uses DJGPP's DXE3 (Dynamic eXtension) format for all loadable modules. DXE3 supports RTLD_GLOBAL symbol sharing -- symbols exported by one module are visible to all subsequently loaded modules. This is critical: widget DXEs call core API functions (e.g. rectFill, wgtInvalidate) that are exported by the core library DXE.
-
Module Types
-
Extension Directory Purpose Examples
- --------- --------- ------- --------
- .lib LIBS/ Core libraries loaded first. Provide infrastructure APIs. libtasks.lib, libdvx.lib, dvxshell.lib
- .wgt WIDGETS/ Widget type plugins. Each exports wgtRegister(). button.wgt, listview.wgt, terminal.wgt
- .app APPS/*/ Application modules. Each exports appDescriptor and appMain(). Loaded on demand by the shell. progman.app, notepad.app, cpanel.app
-
Boot Sequence
-
dvx.exe (loader)
- |
- +-- Enter VGA mode 13h, display splash screen with progress bar
- |
- +-- Scan LIBS/ for *.lib, WIDGETS/ for *.wgt
- |
- +-- Read .dep files for each module (dependency base names)
- |
- +-- Topological sort: load modules in dependency order
- | - dlopen() with RTLD_GLOBAL
- | - Each .wgt that exports wgtRegister() has it called
- |
- +-- Find and call shellMain() (exported by dvxshell.lib)
- |
- +-- dvxInit() -- video mode, input, font, colors, cursors
- |
- +-- Load desktop app (progman.app)
- |
- +-- Main loop:
- dvxUpdate() -> tsYield() -> shellReapApps()
-
Application Lifecycle
-
Two kinds of DXE apps:
-
Callback-only (hasMainLoop = false)
-
appMain() creates windows, registers callbacks, and returns. The app lives through GUI callbacks driven by the shell's main loop. Lifecycle ends when the last window is closed. No extra task stack needed -- simpler and cheaper.
-
Main-loop (hasMainLoop = true)
-
A dedicated cooperative task is created. appMain() runs in that task with its own loop, calling tsYield() to share CPU. Needed for apps with continuous work (terminal emulators, games). Lifecycle ends when appMain() returns.
-
Crash Recovery
-
The platform layer installs signal handlers for SIGSEGV, SIGFPE, SIGILL. On crash, the handler logs platform-specific diagnostics (register dump on DJGPP), then longjmps back to the shell's main loop. The crashed app is killed; other apps and the shell survive. This provides Windows 3.1-style fault tolerance.
-
Per-App Memory Tracking
-
All allocations route through dvxMalloc/dvxFree wrappers that prepend a 16-byte header recording the owning app ID and allocation size. The Task Manager displays per-app memory usage, and leaks are detected at app termination.
-
-
Event Model
-
Event Model
-
DVX uses a cooperative polling model. The main loop (dvxRun / dvxUpdate) runs this cycle each frame:
-
-- Poll mouse -- platformMousePoll() returns position and button bitmask. Compare with previous frame for press/release edge detection.
-- Poll keyboard -- platformKeyboardRead() returns ASCII + scancode. Non-blocking; returns false if buffer is empty.
-- Dispatch to focused window -- the event loop fires window callbacks (onKey, onMouse, etc.) on the focused window. If the window has a widget tree, the widget system's installed handlers dispatch to individual widgets.
-- Compositor pass -- merge dirty rects, composite, flush to LFB.
-
-
Yield -- platformYield() or idle callback.
-
Event Dispatch Chain
-
Mouse/Keyboard Input
- |
- Global handlers (Ctrl+Esc, modal filter)
- |
- Accelerator table check (focused window)
- |
- Window callback (onMouse / onKey)
- |
- [If widget tree installed:]
- |
- widgetOnMouse / widgetOnKey
- |
- Widget hit test (widgetHitTest)
- |
- wclsOnMouse / wclsOnKey (vtable dispatch)
- |
- Universal callbacks (onClick, onChange, etc.)
-
Accelerator Tables
-
Per-window accelerator tables map key + modifier combinations to command IDs. The runtime normalizes key/modifier at registration time (uppercase key, strip shift from modifiers) so matching at dispatch time is two integer comparisons per entry. Matched accelerators fire the window's onMenu callback with the command ID, unifying the menu and hotkey code paths.
-
Mouse Cursor
-
Software-rendered cursor using the classic AND/XOR mask approach. Seven cursor shapes are compiled in: arrow, horizontal resize, vertical resize, NW-SE diagonal resize, NE-SW diagonal resize, busy (hourglass), and crosshair. The cursor is painted into the backbuffer on top of the composited frame and the affected region is flushed to the LFB each frame.
-
Double-Click Detection
-
Timestamp-based: two clicks on the same target (title bar, minimized icon, close gadget) within the configurable double-click interval trigger the double-click action. Separate tracking for each target type.
-
-
Font System
-
Font System
-
DVX uses fixed-width 8-pixel-wide bitmap fonts only. One size is provided: 8x16, matching the standard VGA ROM font and CP437 encoding (256 glyphs).
-
BitmapFontT
-
typedef struct {
- int32_t charWidth; // fixed width per glyph (always 8)
- int32_t charHeight; // 16
- int32_t firstChar; // typically 0
- int32_t numChars; // typically 256
- const uint8_t *glyphData; // packed 1bpp, charHeight bytes per glyph
- } BitmapFontT;
-
Design rationale:
-
-- Character positions are pure multiplication (x = col * 8).
-- Glyph lookup is a single array index.
-- Each scanline of a glyph is exactly one byte (1bpp at 8 pixels wide).
-- No glyph-width tables, kerning, or per-character positioning needed.
-
-
8-pixel width aligns with byte boundaries -- no bit shifting in per-scanline rendering.
-
Text Rendering Functions
-
drawChar() -- Renders a single character. Supports opaque (background fill) and transparent modes.
-
drawTextN() -- Optimized batch rendering for a known character count. Clips once for the entire run, fills background in a single rectFill, then overlays glyph foreground pixels. Significantly faster than per-character rendering for long runs.
-
drawTermRow() -- Renders an 80-column terminal row in a single pass, with per-cell foreground/background from a 16-color palette, blink attribute support, and cursor rendering. Exists because per-character terminal rendering is unacceptably slow on target hardware.
-
drawTextAccel() -- Renders text with & accelerator markers. The character after & is underlined to indicate the keyboard shortcut.
-
Performance Optimization
-
AppContextT stores a fixed-point 16.16 reciprocal of font.charHeight (charHeightRecip) so that dividing by charHeight (for pixel-to-row conversion in terminal/text widgets) becomes a multiply+shift instead of an integer divide, which costs 40+ cycles on a 486.
-
-
Color System
-
Color System
-
Pixel Format
-
PixelFormatT describes the active VESA mode's pixel encoding. Populated once from the VBE mode info block. Stores shift, mask, and bit count for each channel so packColor() can convert RGB to native format with shift-and-mask arithmetic -- no per-pixel computation.
-
Supported depths:
-
Depth Bytes/Pixel Notes
- ----- ----------- -----
- 8 bpp 1 Palette mode. Nearest-index via 6x6x6 color cube + grey ramp.
- 15 bpp 2 5-5-5 RGB (1 bit unused).
- 16 bpp 2 5-6-5 RGB.
- 32 bpp 4 8-8-8 RGB (8 bits unused).
-
ColorSchemeT -- Theming
-
All 20 UI colors are pre-packed into display pixel format at init time. Every color is a uint32_t that can be written directly to the framebuffer with zero per-pixel conversion. The scheme must be regenerated on video mode change, but mode changes require re-init anyway.
-
Color roles mirror classic Motif/Windows 3.x conventions:
-
-- desktop -- desktop background
-- windowFace, windowHighlight, windowShadow -- window chrome bevel triplet
-- activeTitleBg/Fg, inactiveTitleBg/Fg -- focused vs. unfocused title bar
-- contentBg/Fg -- window content area
-- menuBg/Fg, menuHighlightBg/Fg -- menus
-- buttonFace -- button background
-- scrollbarBg/Fg/Trough -- scrollbar components
-
-
cursorFg/Bg -- mouse cursor colors
-
Source RGB values are kept in AppContextT.colorRgb[] for theme save/load. Themes are stored as INI files with a [colors] section. The API provides dvxLoadTheme(), dvxSaveTheme(), dvxSetColor(), and dvxResetColorScheme().
-
Bevel Styles
-
Bevels are the defining visual element of the Motif aesthetic. Convenience macros create bevel style descriptors by swapping highlight and shadow colors:
-
BEVEL_RAISED(colorScheme, borderWidth) -- raised 3D look
- BEVEL_SUNKEN(colorScheme, face, borderWidth) -- sunken/inset look
- BEVEL_TROUGH(colorScheme) -- 1px scrollbar trough
- BEVEL_SB_BUTTON(colorScheme) -- scrollbar button
-
-
Build System
-
Build System
-
Cross-Compilation
-
DVX is cross-compiled from Linux using a DJGPP cross-compiler (i586-pc-msdosdjgpp-gcc). The top-level Makefile orchestrates building all subsystems in dependency order.
-
make -- build everything
- ./mkcd.sh -- build + create ISO for 86Box
-
Build Targets
-
all: core tasks loader texthelp listhelp tools widgets shell taskmgr serial sql apps
-
Target Output Description
- ------ ------ -----------
- core bin/libs/libdvx.lib GUI core library (draw, comp, wm, app, widget infrastructure)
- tasks bin/libs/libtasks.lib Cooperative task switcher
- loader bin/dvx.exe Bootstrap loader (the DOS executable)
- widgets bin/widgets/*.wgt 29 widget type plugins
- shell bin/libs/dvxshell.lib DVX Shell (app management, desktop)
- taskmgr bin/libs/taskmgr.lib Task Manager (loaded as a separate DXE)
- texthelp shared library Shared text editing helpers (clipboard, word boundaries)
- listhelp shared library Shared dropdown/list helpers
- apps bin/apps/*/*.app Application modules (progman, notepad, clock, etc.)
- tools bin/dvxres Resource compiler (runs on Linux, builds resource sections into DXEs)
- serial serial DXE libs UART driver, HDLC packets, security, seclink
- sql SQL DXE lib SQLite integration
-
DXE3 Build Process
-
Each DXE module is compiled to an object file with GCC, then linked with dxe3gen:
-
# Compile
- i586-pc-msdosdjgpp-gcc -O2 -march=i486 -mtune=i586 -c -o widget.o widget.c
-
- # Link as DXE with exported symbols
- dxe3gen -o widget.wgt -E _wgtRegister -U widget.o
-
- # Optionally append resources
- dvxres build widget.wgt widget.res
-
The -E flag specifies exported symbols (prefixed with underscore per DJGPP convention). -U marks unresolved symbols as OK (they'll be resolved at load time from previously loaded DXEs).
-
Deployment (mkcd.sh)
-
-- Runs make all.
-- Verifies critical outputs exist (dvx.exe, libtasks.lib, libdvx.lib, dvxshell.lib).
-- Counts widget modules.
-- Creates an ISO 9660 image from bin/ using mkisofs: -iso-level 1 (strict 8.3 filenames for DOS), -J (Joliet extensions for long names), -V DVX (volume label).
-
-
Places the ISO at ~/.var/app/net._86box._86Box/data/86Box/dvx.iso for 86Box to mount as CD-ROM.
-
Compiler Flags
-
-O2 Optimization level 2
- -march=i486 486 instruction set baseline
- -mtune=i586 Optimize scheduling for Pentium
- -Wall -Wextra Full warnings
-
Directory Layout
-
dvxgui/
- +-- core/ Core library sources (dvxVideo, dvxDraw, dvxComp, dvxWm, dvxApp, widget infra)
- | +-- platform/ Platform abstraction (dvxPlatform.h, dvxPlatformDos.c)
- | +-- thirdparty/ stb_image, stb_ds, stb_image_write
- +-- loader/ Bootstrap loader (dvx.exe)
- +-- tasks/ Cooperative task switcher (libtasks.lib)
- +-- shell/ DVX Shell (dvxshell.lib)
- +-- widgets/ Widget DXE modules (*.wgt), each in its own subdirectory
- | +-- box/ VBox/HBox layout containers
- | +-- button/ Push button
- | +-- textInput/ Text entry field
- | +-- listView/ Multi-column list
- | +-- ... (29 widget types total)
- +-- texthelp/ Shared text editing helpers
- +-- listhelp/ Shared dropdown/list helpers
- +-- apps/ Application DXE modules (*.app)
- | +-- progman/ Program Manager (desktop)
- | +-- notepad/ Text editor
- | +-- cpanel/ Control Panel
- | +-- imgview/ Image viewer
- | +-- clock/ Clock
- | +-- dvxdemo/ Demo / showcase app
- | +-- dvxbasic/ DVX BASIC compiler and VM
- +-- tools/ Build tools (dvxres resource compiler)
- +-- rs232/ ISR-driven UART driver
- +-- packet/ HDLC framing, CRC-16, sliding window
- +-- security/ DH key exchange, XTEA cipher, DRBG RNG
- +-- seclink/ Encrypted channel wrapper
- +-- serial/ Combined serial stack DXE
- +-- proxy/ Linux proxy (86Box <-> secLink <-> telnet)
- +-- sql/ SQLite integration
- +-- bin/ Build output (dvx.exe, libs/, widgets/, apps/, config/)
- +-- obj/ Intermediate object files
- +-- docs/ Documentation
-
-
dvxTypes.h -- Shared Type Definitions
-
dvxTypes.h -- Shared Type Definitions
-
Central type definitions shared across all five layers of the DVX GUI stack. Every header includes this file. Contains no function definitions -- only structs, enums, typedefs, and compile-time constants.
-
Core Structures
-
PixelFormatT
-
Describes the pixel encoding for the active VESA video mode. Populated once at startup from the VBE mode info block, then treated as read-only.
-
Field Description
- ----- -----------
- int32_t bitsPerPixel 8, 15, 16, or 32
- int32_t bytesPerPixel 1, 2, 2, or 4
- uint32_t redMask, greenMask, blueMask Bitmasks for each color channel
- int32_t redShift, greenShift, blueShift Bit position of each color field
- int32_t redBits, greenBits, blueBits Number of bits per channel
-
DisplayT
-
Single display context passed by pointer through every layer. All drawing targets the backBuf; only dirty rects are flushed to lfb.
-
Field Description
- ----- -----------
- int32_t width, height Screen dimensions in pixels
- int32_t pitch Bytes per scanline
- PixelFormatT format Active pixel format
- uint8_t *lfb Mapped linear framebuffer (VESA LFB)
- uint8_t *backBuf System RAM backbuffer
- uint8_t *palette 768 bytes for 8-bit mode, NULL otherwise
- int32_t clipX, clipY, clipW, clipH Current clip rectangle
-
RectT
-
Rectangle in origin + extent form. Used throughout the compositor, window manager, and widget layout engine.
-
Field Description
- ----- -----------
- int32_t x, y Top-left corner
- int32_t w, h Width and height
-
BlitOpsT
-
Vtable for hot-path span operations. Resolved at init time based on pixel depth. On DOS, these dispatch to hand-written asm (rep stosl / rep movsd).
-
Field Description
- ----- -----------
- SpanFillFnT spanFill Fill a horizontal span with a solid color
- SpanCopyFnT spanCopy Copy a horizontal span between buffers
- int32_t bytesPerPixel Bytes per pixel for the active mode
- int32_t pitch Bytes per scanline
-
BevelStyleT
-
Bevel drawing parameters. Swapping highlight/shadow flips raised vs. sunken appearance.
-
Field Description
- ----- -----------
- uint32_t highlight Lighter color (top/left edges)
- uint32_t shadow Darker color (bottom/right edges)
- uint32_t face Interior fill color (0 = no fill)
- int32_t width Border thickness in pixels (typically 2)
-
BitmapFontT
-
Fixed-width 8-pixel-wide bitmap font descriptor. One size provided: 8x16 (standard VGA ROM font, CP437 encoding).
-
Field Description
- ----- -----------
- int32_t charWidth Fixed width per glyph (always 8)
- int32_t charHeight Glyph height (14 or 16)
- int32_t firstChar ASCII code of first glyph (typically 0)
- int32_t numChars Number of glyphs (typically 256)
- const uint8_t *glyphData Packed 1bpp data, charHeight bytes per glyph
-
ColorSchemeT
-
All UI colors pre-packed into display pixel format at init time. Theme support is achieved by swapping this struct.
-
Field Description
- ----- -----------
- uint32_t desktop Desktop background color
- uint32_t windowFace Window body / chrome face
- uint32_t windowHighlight Bevel highlight (top/left edge)
- uint32_t windowShadow Bevel shadow (bottom/right edge)
- uint32_t activeTitleBg, activeTitleFg Focused window title bar
- uint32_t inactiveTitleBg, inactiveTitleFg Unfocused window title bar
- uint32_t contentBg, contentFg Window content area default colors
- uint32_t menuBg, menuFg Menu bar and popup background/text
- uint32_t menuHighlightBg, menuHighlightFg Menu item highlight
- uint32_t buttonFace Button face color
- uint32_t scrollbarBg, scrollbarFg, scrollbarTrough Scrollbar element colors
- uint32_t cursorFg, cursorBg Mouse cursor colors
-
ColorIdE
-
Enum for addressing individual colors in ColorSchemeT. Order matches struct field order.
-
Values: ColorDesktopE, ColorWindowFaceE, ColorWindowHighlightE, ColorWindowShadowE, ColorActiveTitleBgE, ColorActiveTitleFgE, ColorInactiveTitleBgE, ColorInactiveTitleFgE, ColorContentBgE, ColorContentFgE, ColorMenuBgE, ColorMenuFgE, ColorMenuHighlightBgE, ColorMenuHighlightFgE, ColorButtonFaceE, ColorScrollbarBgE, ColorScrollbarFgE, ColorScrollbarTroughE, ColorCursorFgE, ColorCursorBgE, ColorCountE.
-
DirtyListT
-
Fixed-capacity list of dirty rectangles. Dynamic array, grows on demand.
-
Field Description
- ----- -----------
- RectT *rects Dynamic array of dirty rectangles
- int32_t count Current number of dirty rects
- int32_t cap Allocated capacity
-
WindowT
-
Central window object. Each window owns a persistent content backbuffer and receives events through callback function pointers.
-
Field Description
- ----- -----------
- int32_t id Unique window identifier
- int32_t appId Shell app ID (0 = shell itself)
- int32_t x, y, w, h Outer frame position and dimensions
- int32_t contentX, contentY, contentW, contentH Content area inset from frame
- char title[MAX_TITLE_LEN] Window title text (max 128 chars)
- bool visible, focused, minimized, maximized, resizable, modal Window state flags
- bool contentDirty true when contentBuf has changed
- bool needsPaint true until first onPaint call
- int32_t maxW, maxH Maximum dimensions
- int32_t preMaxX, preMaxY, preMaxW, preMaxH Saved geometry before maximize
- uint8_t *contentBuf Per-window content backbuffer
- int32_t contentPitch Content buffer bytes per row
- uint8_t *iconData Icon pixel data, NULL if none
- int32_t iconW, iconH, iconPitch Icon image dimensions and pitch
- MenuBarT *menuBar Menu bar (NULL if no menus)
- ScrollbarT *vScroll, *hScroll Scrollbars (NULL if not present)
- struct WidgetT *widgetRoot Widget tree root (NULL if none)
- MenuT *contextMenu Right-click context menu
- AccelTableT *accelTable Keyboard accelerator table
- void *userData Application-defined data pointer
-
Callbacks:
-
Callback Description
- -------- -----------
- onPaint(WindowT *win, RectT *dirtyArea) Content repaint requested
- onKey(WindowT *win, int32_t key, int32_t mod) Key press
- onKeyUp(WindowT *win, int32_t scancode, int32_t mod) Key release
- onMouse(WindowT *win, int32_t x, int32_t y, int32_t btn) Mouse event (content-relative)
- onResize(WindowT *win, int32_t newW, int32_t newH) Window resized
- onClose(WindowT *win) Close requested
- onMenu(WindowT *win, int32_t menuId) Menu item or accelerator activated
- onScroll(WindowT *win, ScrollbarOrientE orient, int32_t val) Scrollbar value changed
- onCursorQuery(WindowT *win, int32_t x, int32_t y) Return CURSOR_* for hit position
- onFocus(WindowT *win) Window gained focus
- onBlur(WindowT *win) Window lost focus
-
WindowStackT
-
Z-ordered window stack (front-to-back: index count-1 is topmost). Owns system-wide drag/resize/scroll interaction state.
-
Field Description
- ----- -----------
- WindowT **windows Dynamic array of window pointers
- int32_t count, cap Current count and allocated capacity
- int32_t focusedIdx Stack index of focused window
- int32_t dragWindow, dragOffX, dragOffY Active drag state
- int32_t resizeWindow, resizeEdge Active resize state
- int32_t scrollWindow, scrollOrient, scrollDragOff Active scroll drag state
-
MenuT / MenuItemT / MenuBarT
-
Menu system types. Fixed-size label buffers (MAX_MENU_LABEL = 32). Cascading submenus supported via MenuItemT.subMenu pointer.
-
Field Description
- ----- -----------
- MenuItemT.label Item text (supports & accelerator markers)
- MenuItemT.id Application-defined command ID
- MenuItemT.type MenuItemNormalE, MenuItemCheckE, or MenuItemRadioE
- MenuItemT.separator true = horizontal divider line
- MenuItemT.enabled, checked Item state
- MenuItemT.subMenu Child menu for cascading (NULL if leaf)
- MenuBarT.activeIdx Open popup index (-1 = none)
-
ScrollbarT
-
Window-level scrollbar state. Managed by the WM layer, drawn after content.
-
Field Description
- ----- -----------
- ScrollbarOrientE orient ScrollbarVerticalE or ScrollbarHorizontalE
- int32_t min, max Scroll range
- int32_t value Current position
- int32_t pageSize Visible portion (for proportional thumb sizing)
- int32_t x, y, length Computed screen position and track length
-
AccelTableT / AccelEntryT
-
Per-window keyboard accelerator table. Entries are matched against keystrokes in the event loop and fire onMenu(cmdId) on match.
-
Field Description
- ----- -----------
- AccelEntryT.key ASCII character or KEY_Fxx constant
- AccelEntryT.modifiers Bitmask of ACCEL_CTRL, ACCEL_SHIFT, ACCEL_ALT
- AccelEntryT.cmdId Command ID passed to onMenu
-
VideoModeInfoT
-
Describes an available video mode (enumerated at init).
-
Field Description
- ----- -----------
- int32_t w, h Resolution
- int32_t bpp Bits per pixel
-
CursorT
-
Software-rendered 16x16 cursor using AND/XOR mask encoding.
-
Field Description
- ----- -----------
- int32_t width, height Cursor dimensions (always 16x16)
- int32_t hotX, hotY Hot spot coordinates
- const uint16_t *andMask AND mask (0 = draw pixel, 1 = transparent)
- const uint16_t *xorData XOR data (0 = black, 1 = white where AND = 0)
-
Bevel Convenience Macros
-
Macro Description
- ----- -----------
- BEVEL_RAISED(cs, bw) Raised bevel style from ColorSchemeT ptr and border width
- BEVEL_SUNKEN(cs, face, bw) Sunken bevel style with explicit face color
- BEVEL_TROUGH(cs) 1px sunken trough (for scrollbar tracks)
- BEVEL_SB_BUTTON(cs) 1px raised scrollbar button
-
Chrome Constants
-
Define Value Description
- ------ ----- -----------
- CHROME_BORDER_WIDTH 4 Outer frame border width
- CHROME_TITLE_HEIGHT 20 Title bar height
- CHROME_TITLE_PAD 4 Title text padding
- CHROME_INNER_BORDER 2 Inner chrome border
- CHROME_MENU_HEIGHT 20 Menu bar height
- CHROME_TOTAL_TOP 26 Total inset from top of frame to content
- CHROME_TOTAL_SIDE 6 Total inset from side of frame to content
- CHROME_TOTAL_BOTTOM 6 Total inset from bottom of frame to content
- CHROME_CLOSE_BTN_SIZE 16 Close button gadget size
-
Hit Test Constants
-
Define Value Description
- ------ ----- -----------
- HIT_CONTENT 0 Content area
- HIT_TITLE 1 Title bar
- HIT_CLOSE 2 Close gadget
- HIT_RESIZE 3 Resize border
- HIT_MENU 4 Menu bar
- HIT_VSCROLL 5 Vertical scrollbar
- HIT_HSCROLL 6 Horizontal scrollbar
- HIT_MINIMIZE 7 Minimize gadget
- HIT_MAXIMIZE 8 Maximize gadget
- HIT_NONE -1 No window hit (desktop)
-
Mouse Button Flags
-
Define Value Description
- ------ ----- -----------
- MOUSE_LEFT 1 Left mouse button
- MOUSE_RIGHT 2 Right mouse button
- MOUSE_MIDDLE 4 Middle mouse button
-
Accelerator Modifier Flags
-
Define Value Description
- ------ ----- -----------
- ACCEL_SHIFT 0x03 Shift key (matches BIOS shift state bits)
- ACCEL_CTRL 0x04 Ctrl key
- ACCEL_ALT 0x08 Alt key
-
Extended Key Codes
-
Define Description
- ------ -----------
- KEY_F1 .. KEY_F12 Function keys (scancode | 0x100)
- KEY_INSERT Insert key
- KEY_DELETE Delete key
- KEY_HOME Home key
- KEY_END End key
- KEY_PGUP Page Up key
- KEY_PGDN Page Down key
-
Resize Edge Flags
-
Define Value Description
- ------ ----- -----------
- RESIZE_NONE 0 No resize edge
- RESIZE_LEFT 1 Left edge
- RESIZE_RIGHT 2 Right edge
- RESIZE_TOP 4 Top edge
- RESIZE_BOTTOM 8 Bottom edge (combinable via OR for corners)
-
Utility Macros
-
Macro Description
- ----- -----------
- DVX_MIN(a, b) Return the smaller of two values
- DVX_MAX(a, b) Return the larger of two values
-
-
dvxCursor.h -- Cursor Definitions
-
dvxCursor.h -- Cursor Definitions
-
Embedded 16x16 mouse cursor bitmaps compiled as static const data. No external cursor files. Uses the standard AND/XOR mask encoding from the IBM VGA hardware cursor spec.
-
Cursor Shape IDs
-
Define Value Description
- ------ ----- -----------
- CURSOR_ARROW 0 Standard arrow (hot spot at tip)
- CURSOR_RESIZE_H 1 Horizontal resize (left/right arrows)
- CURSOR_RESIZE_V 2 Vertical resize (up/down arrows)
- CURSOR_RESIZE_DIAG_NWSE 3 NW-SE diagonal resize
- CURSOR_RESIZE_DIAG_NESW 4 NE-SW diagonal resize
- CURSOR_BUSY 5 Hourglass (wait)
- CURSOR_CROSSHAIR 6 Crosshair for placement
- CURSOR_COUNT 7 Total number of cursor shapes
-
Data
-
dvxCursors[CURSOR_COUNT]
-
Static const array of CursorT structs, indexed by CURSOR_xxx constants. Each entry includes the AND mask, XOR data, dimensions, and hot spot coordinates.
-
-
dvxVideo.h -- Layer 1: VESA VBE Video Backend
-
dvxVideo.h -- Layer 1: VESA VBE Video Backend
-
The lowest layer. Responsible for VESA VBE mode negotiation, LFB mapping via DPMI, system RAM backbuffer allocation, pixel format discovery, and color packing. LFB-only design: bank switching is deliberately unsupported.
-
videoInit
-
int32_t videoInit(DisplayT *d, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);
-
Probe VBE for a mode matching the requested resolution and depth, enable it, map the LFB into DPMI linear address space, and allocate a system RAM backbuffer. preferredBpp is a hint; the closest available depth is used if an exact match is not found.
-
Parameter Description
- --------- -----------
- d Display context to initialize
- requestedW/H Desired screen resolution
- preferredBpp Preferred bits per pixel (8, 15, 16, or 32)
-
Returns: 0 on success, negative on failure.
-
videoShutdown
-
void videoShutdown(DisplayT *d);
-
Restore VGA text mode (mode 3), unmap the LFB, and free the backbuffer. Safe to call even if videoInit() failed.
-
Parameter Description
- --------- -----------
- d Display context to shut down
-
packColor
-
uint32_t packColor(const DisplayT *d, uint8_t r, uint8_t g, uint8_t b);
-
Pack an RGB triplet into the display's native pixel format. For direct-color modes (15/16/32 bpp), returns a packed pixel value using shift/mask fields. For 8-bit mode, returns the nearest palette index via Euclidean distance in RGB space.
-
Parameter Description
- --------- -----------
- d Display context (provides pixel format)
- r, g, b Color components (0-255)
-
Returns: Native pixel value suitable for direct framebuffer write.
-
setClipRect
-
void setClipRect(DisplayT *d, int32_t x, int32_t y, int32_t w, int32_t h);
-
Set the clip rectangle on the display. All subsequent draw operations clip to this rectangle. The caller must save and restore the clip rect around scoped operations.
-
Parameter Description
- --------- -----------
- d Display context
- x, y, w, h Clip rectangle in screen coordinates
-
resetClipRect
-
void resetClipRect(DisplayT *d);
-
Reset the clip rectangle to the full display dimensions.
-
Parameter Description
- --------- -----------
- d Display context
-
-
dvxDraw.h -- Layer 2: Drawing Primitives
-
dvxDraw.h -- Layer 2: Drawing Primitives
-
All 2D drawing operations: rectangle fills, bitmap blits, text rendering, bevels, lines, and cursor rendering. Every function draws into the display's backbuffer and clips to the current clip rectangle. This layer is stateless beyond the clip rect on DisplayT.
-
drawInit
-
void drawInit(BlitOpsT *ops, const DisplayT *d);
-
Populate a BlitOpsT with the correct span functions for the display's pixel depth. Must be called once after videoInit().
-
Parameter Description
- --------- -----------
- ops BlitOpsT to populate
- d Initialized display context
-
rectFill
-
void rectFill(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);
-
Fill a rectangle with a solid color. Clips to the display clip rect. Workhorse for backgrounds, window fills, and clear operations.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- x, y, w, h Rectangle to fill
- color Packed pixel color
-
rectCopy
-
void rectCopy(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h);
-
Copy a rectangle from an arbitrary source buffer into the backbuffer. Used to blit per-window content buffers during compositing.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- dstX, dstY Destination position in backbuffer
- srcBuf Source pixel buffer
- srcPitch Source buffer bytes per row
- srcX, srcY Origin within source buffer
- w, h Rectangle dimensions to copy
-
rectCopyGrayscale
-
void rectCopyGrayscale(DisplayT *d, const BlitOpsT *ops, int32_t dstX, int32_t dstY, const uint8_t *srcBuf, int32_t srcPitch, int32_t srcX, int32_t srcY, int32_t w, int32_t h);
-
Copy a rectangle with grayscale conversion. Each pixel's RGB is converted to luminance (0.299R + 0.587G + 0.114B) for a disabled/grayed appearance.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- dstX, dstY Destination position
- srcBuf, srcPitch Source buffer and pitch
- srcX, srcY Source origin
- w, h Rectangle dimensions
-
drawBevel
-
void drawBevel(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const BevelStyleT *style);
-
Draw a beveled frame. Top/left edges in highlight color, bottom/right in shadow. Interior filled with face color if non-zero.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- x, y, w, h Outer bevel rectangle
- style Bevel colors and width
-
drawChar
-
int32_t drawChar(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, char ch, uint32_t fg, uint32_t bg, bool opaque);
-
Draw a single character glyph. When opaque is true, the background fills the entire cell; when false, only foreground pixels are drawn (transparent background).
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- font Bitmap font
- x, y Character position
- ch Character to draw
- fg, bg Foreground and background packed colors
- opaque true = fill background, false = transparent
-
Returns: Advance width (always charWidth).
-
drawText
-
void drawText(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque);
-
Draw a null-terminated string. Calls drawChar per character.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- font Bitmap font
- x, y Start position
- text Null-terminated string
- fg, bg Foreground and background packed colors
- opaque true = fill background, false = transparent
-
drawTextN
-
void drawTextN(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, int32_t count, uint32_t fg, uint32_t bg, bool opaque);
-
Optimized batch text rendering for a known character count. Computes clip bounds once, fills background in a single rectFill, then overlays glyph foreground pixels. Significantly faster than per-character drawChar for long runs (terminal rows, list items).
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- font Bitmap font
- x, y Start position
- text Character buffer (not required to be null-terminated)
- count Number of characters to render
- fg, bg Foreground and background packed colors
- opaque true = fill background, false = transparent
-
textWidth
-
int32_t textWidth(const BitmapFontT *font, const char *text);
-
Return the pixel width of a null-terminated string (strlen(text) * charWidth).
-
Parameter Description
- --------- -----------
- font Bitmap font
- text Null-terminated string
-
Returns: Width in pixels.
-
accelParse
-
char accelParse(const char *text);
-
Scan text for an & prefix and return the following character as a lowercase accelerator key. "&File" returns 'f', "E&xit" returns 'x'.
-
Parameter Description
- --------- -----------
- text Text with optional & accelerator marker
-
Returns: Lowercase accelerator character, or 0 if none.
-
drawTextAccel
-
void drawTextAccel(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, const char *text, uint32_t fg, uint32_t bg, bool opaque);
-
Draw text with & accelerator markers. The character after & is drawn underlined to indicate the keyboard shortcut. && produces a literal &. Used for menu items and button labels.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- font Bitmap font
- x, y Start position
- text Text with & markers
- fg, bg Foreground and background packed colors
- opaque true = fill background, false = transparent
-
textWidthAccel
-
int32_t textWidthAccel(const BitmapFontT *font, const char *text);
-
Measure text width excluding & markers (so "&File" measures as 4 chars).
-
Parameter Description
- --------- -----------
- font Bitmap font
- text Text with optional & markers
-
Returns: Width in pixels.
-
drawMaskedBitmap
-
void drawMaskedBitmap(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, const uint16_t *andMask, const uint16_t *xorData, uint32_t fgColor, uint32_t bgColor);
-
Draw a 1-bit AND/XOR masked bitmap. Used for software-rendered mouse cursors.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- x, y Screen position
- w, h Bitmap dimensions
- andMask AND transparency mask (one uint16_t per row)
- xorData XOR color data
- fgColor, bgColor Cursor foreground and background packed colors
-
drawTermRow
-
void drawTermRow(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, int32_t x, int32_t y, int32_t cols, const uint8_t *lineData, const uint32_t *palette, bool blinkVisible, int32_t cursorCol);
-
Render an entire row of terminal character cells (ch/attr byte pairs) in a single pass. Colors looked up from a 16-color palette. Attribute bit 7 controls blink.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- font Bitmap font
- x, y Row start position
- cols Number of columns
- lineData Packed ch/attr byte pairs (2 bytes per cell)
- palette 16-entry packed color palette
- blinkVisible false = hide blinking characters
- cursorCol Column for inverted text cursor (-1 = none)
-
drawFocusRect
-
void drawFocusRect(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, int32_t h, uint32_t color);
-
Draw a 1px dotted rectangle (alternating pixels). Used for keyboard focus indicators, matching the Windows 3.x focus rectangle convention.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- x, y, w, h Focus rectangle bounds
- color Dot color (packed)
-
drawHLine
-
void drawHLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t w, uint32_t color);
-
Draw a horizontal line (1px tall).
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- x, y Start position
- w Width in pixels
- color Packed pixel color
-
drawVLine
-
void drawVLine(DisplayT *d, const BlitOpsT *ops, int32_t x, int32_t y, int32_t h, uint32_t color);
-
Draw a vertical line (1px wide).
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- x, y Start position
- h Height in pixels
- color Packed pixel color
-
-
dvxComp.h -- Layer 3: Dirty Rectangle Compositor
-
dvxComp.h -- Layer 3: Dirty Rectangle Compositor
-
Tracks changed screen regions and ensures only dirty regions are redrawn and flushed to video memory. The compositing pipeline: mark dirty, merge overlapping rects, redraw desktop + windows (back-to-front, painter's algorithm), flush to LFB.
-
dirtyListInit
-
void dirtyListInit(DirtyListT *dl);
-
Zero the dirty rect count. Called at the start of each frame.
-
Parameter Description
- --------- -----------
- dl Dirty list to initialize
-
dirtyListAdd
-
void dirtyListAdd(DirtyListT *dl, int32_t x, int32_t y, int32_t w, int32_t h);
-
Enqueue a dirty rectangle. Grows dynamically; triggers merge at a soft capacity limit.
-
Parameter Description
- --------- -----------
- dl Dirty list
- x, y, w, h Dirty rectangle in screen coordinates
-
dirtyListMerge
-
void dirtyListMerge(DirtyListT *dl);
-
Consolidate the dirty list by merging overlapping and adjacent rects. Uses iterative pairwise merge: if combining two rects does not increase total area beyond a threshold, they are merged. Reduces compositor passes and LFB flush operations.
-
Parameter Description
- --------- -----------
- dl Dirty list to merge
-
dirtyListClear
-
void dirtyListClear(DirtyListT *dl);
-
Reset the dirty list to empty (sets count to 0).
-
Parameter Description
- --------- -----------
- dl Dirty list to clear
-
flushRect
-
void flushRect(DisplayT *d, const RectT *r);
-
Copy a rectangle from the system RAM backbuffer to the LFB (video memory). This is the only place the real framebuffer is written. Uses platform-specific fast copy (rep movsd on DOS) for each scanline.
-
Parameter Description
- --------- -----------
- d Display context
- r Rectangle to flush
-
rectIntersect
-
bool rectIntersect(const RectT *a, const RectT *b, RectT *result);
-
Compute the intersection of two rectangles.
-
Parameter Description
- --------- -----------
- a, b Input rectangles
- result Output: intersection rectangle (valid only when return is true)
-
Returns: true if the rectangles overlap, false if disjoint.
-
rectIsEmpty
-
bool rectIsEmpty(const RectT *r);
-
Test whether a rectangle has zero or negative area.
-
Parameter Description
- --------- -----------
- r Rectangle to test
-
Returns: true if w <= 0 or h <= 0.
-
-
dvxWm.h -- Layer 4: Window Manager
-
dvxWm.h -- Layer 4: Window Manager
-
Manages the window lifecycle, Z-order stack, chrome drawing, hit testing, and interactive operations (drag, resize, scroll). The WM owns window geometry and chrome; content is owned by the application via callbacks or the widget system.
-
Initialization
-
wmInit
-
void wmInit(WindowStackT *stack);
-
Zero the window stack. Must be called before any other WM function.
-
Parameter Description
- --------- -----------
- stack Window stack to initialize
-
Window Lifecycle
-
wmCreateWindow
-
WindowT *wmCreateWindow(WindowStackT *stack, DisplayT *d, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);
-
Allocate a new window, initialize its geometry and content buffer, and push it to the top of the Z-order stack. Returns with all callbacks NULL; the caller should set onPaint/onKey/etc. before the next event loop iteration.
-
Parameter Description
- --------- -----------
- stack Window stack
- d Display context
- title Window title text
- x, y Initial position
- w, h Initial outer frame dimensions
- resizable true = allow user resize
-
Returns: Pointer to new WindowT, or NULL on failure.
-
wmDestroyWindow
-
void wmDestroyWindow(WindowStackT *stack, WindowT *win);
-
Free the window's content buffer and all attached resources (menu bar, scrollbars, widget tree), remove it from the stack, and dirty the vacated region.
-
Parameter Description
- --------- -----------
- stack Window stack
- win Window to destroy
-
Z-Order and Focus
-
wmRaiseWindow
-
void wmRaiseWindow(WindowStackT *stack, DirtyListT *dl, int32_t idx);
-
Move window at stack index idx to the top of the Z-order. Dirties both old and new top positions so overlapping windows get repainted.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list for repaint marking
- idx Stack index of window to raise
-
wmSetFocus
-
void wmSetFocus(WindowStackT *stack, DirtyListT *dl, int32_t idx);
-
Transfer keyboard focus to the window at stack index idx. Unfocuses the previously focused window and dirties both title bars.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- idx Stack index of window to focus
-
Geometry
-
wmUpdateContentRect
-
void wmUpdateContentRect(WindowT *win);
-
Recompute contentX/Y/W/H from the window's outer frame dimensions, accounting for chrome borders, title bar, menu bar, and scrollbars. Must be called after any change to frame size or chrome configuration.
-
Parameter Description
- --------- -----------
- win Window to update
-
wmReallocContentBuf
-
int32_t wmReallocContentBuf(WindowT *win, const DisplayT *d);
-
Reallocate the per-window content backbuffer to match current contentW/H. Old buffer contents are lost; caller should trigger a full repaint via onPaint afterward.
-
Parameter Description
- --------- -----------
- win Window to reallocate
- d Display context (for bytes-per-pixel)
-
Returns: 0 on success, -1 on allocation failure.
-
wmMinWindowSize
-
void wmMinWindowSize(const WindowT *win, int32_t *minW, int32_t *minH);
-
Get the minimum window size. Accounts for chrome, gadgets, and menu bar.
-
Parameter Description
- --------- -----------
- win Window
- minW, minH Output: minimum width and height
-
Menu Bar
-
wmAddMenuBar
-
MenuBarT *wmAddMenuBar(WindowT *win);
-
Allocate and attach a menu bar to a window. Adjusts content area to make room (CHROME_MENU_HEIGHT pixels). One menu bar per window.
-
Parameter Description
- --------- -----------
- win Window to add menu bar to
-
Returns: Pointer to the new MenuBarT.
-
wmDestroyMenuBar
-
void wmDestroyMenuBar(WindowT *win);
-
Free the menu bar and reclaim the content area.
-
Parameter Description
- --------- -----------
- win Window to remove menu bar from
-
wmAddMenu
-
MenuT *wmAddMenu(MenuBarT *bar, const char *label);
-
Append a dropdown menu to the menu bar. The label supports & accelerator markers (e.g. "&File").
-
Parameter Description
- --------- -----------
- bar Menu bar
- label Menu label text
-
Returns: Pointer to the new MenuT to populate with items.
-
wmAddMenuItem
-
void wmAddMenuItem(MenuT *menu, const char *label, int32_t id);
-
Append a clickable item to a menu. The id is passed to the window's onMenu callback when selected.
-
Parameter Description
- --------- -----------
- menu Menu to append to
- label Item label (supports & markers)
- id Application-defined command ID
-
wmAddMenuCheckItem
-
void wmAddMenuCheckItem(MenuT *menu, const char *label, int32_t id, bool checked);
-
Add a checkbox-style menu item. Check state toggles on click; rendered with a checkmark glyph.
-
Parameter Description
- --------- -----------
- menu Menu to append to
- label Item label
- id Command ID
- checked Initial checked state
-
wmAddMenuRadioItem
-
void wmAddMenuRadioItem(MenuT *menu, const char *label, int32_t id, bool checked);
-
Add a radio-style menu item. Radio groups are defined implicitly by consecutive radio items; selecting one unchecks the others in the group.
-
Parameter Description
- --------- -----------
- menu Menu to append to
- label Item label
- id Command ID
- checked Initial checked state
-
wmAddMenuSeparator
-
void wmAddMenuSeparator(MenuT *menu);
-
Insert a horizontal separator line. Separators are not interactive.
-
Parameter Description
- --------- -----------
- menu Menu to append separator to
-
wmMenuItemIsChecked
-
bool wmMenuItemIsChecked(MenuBarT *bar, int32_t id);
-
Query the checked state of a menu item by command ID. Searches all menus in the bar.
-
Parameter Description
- --------- -----------
- bar Menu bar
- id Command ID to query
-
Returns: true if checked.
-
wmMenuItemSetChecked
-
void wmMenuItemSetChecked(MenuBarT *bar, int32_t id, bool checked);
-
Set the checked state of a menu item by command ID. For radio items, setting checked=true also unchecks other radio items in the same group.
-
Parameter Description
- --------- -----------
- bar Menu bar
- id Command ID
- checked New checked state
-
wmMenuItemSetEnabled
-
void wmMenuItemSetEnabled(MenuBarT *bar, int32_t id, bool enabled);
-
Enable or disable a menu item by command ID.
-
Parameter Description
- --------- -----------
- bar Menu bar
- id Command ID
- enabled true = enabled, false = grayed out
-
wmAddSubMenu
-
MenuT *wmAddSubMenu(MenuT *parentMenu, const char *label);
-
Create a cascading submenu attached to a parent menu. The child MenuT is heap-allocated and freed when the parent window is destroyed.
-
Parameter Description
- --------- -----------
- parentMenu Parent menu to attach submenu to
- label Submenu label text
-
Returns: Pointer to the child MenuT, or NULL on allocation failure.
-
wmCreateMenu
-
MenuT *wmCreateMenu(void);
-
Allocate a heap-resident MenuT for use as a context menu (right-click). Unlike menu bar menus, context menus are standalone allocations. Free with wmFreeMenu().
-
Returns: Pointer to the new MenuT.
-
wmFreeMenu
-
void wmFreeMenu(MenuT *menu);
-
Free a standalone menu allocated with wmCreateMenu(). Also frees any heap-allocated submenu children recursively.
-
Parameter Description
- --------- -----------
- menu Menu to free
-
Scrollbars
-
wmAddVScrollbar
-
ScrollbarT *wmAddVScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize);
-
Attach a vertical scrollbar to the right edge of the window's content area. Shrinks contentW by SCROLLBAR_WIDTH pixels.
-
Parameter Description
- --------- -----------
- win Window
- min, max Scroll value range
- pageSize Visible portion (controls thumb size)
-
Returns: Pointer to the new ScrollbarT.
-
wmAddHScrollbar
-
ScrollbarT *wmAddHScrollbar(WindowT *win, int32_t min, int32_t max, int32_t pageSize);
-
Attach a horizontal scrollbar to the bottom edge. Shrinks contentH by SCROLLBAR_WIDTH pixels.
-
Parameter Description
- --------- -----------
- win Window
- min, max Scroll value range
- pageSize Visible portion
-
Returns: Pointer to the new ScrollbarT.
-
Drawing
-
wmDrawChrome
-
void wmDrawChrome(DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo);
-
Draw the window frame: outer bevel, title bar with text, close/minimize/maximize gadgets, and menu bar if present. Drawing is clipped to the intersection with clipTo.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- font Bitmap font for title text
- colors Color scheme
- win Window to draw chrome for
- clipTo Dirty rectangle to clip drawing to
-
wmDrawContent
-
void wmDrawContent(DisplayT *d, const BlitOpsT *ops, WindowT *win, const RectT *clipTo);
-
Blit the window's content backbuffer into the display backbuffer, clipped to the dirty rect. Pure copy operation (no drawing).
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- win Window
- clipTo Dirty rectangle
-
wmDrawScrollbars
-
void wmDrawScrollbars(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, WindowT *win, const RectT *clipTo);
-
Draw scrollbars (track, arrows, proportional thumb) for a window. Drawn after content so scrollbars overlay the content area edge.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- colors Color scheme
- win Window
- clipTo Dirty rectangle
-
wmDrawMinimizedIcons
-
void wmDrawMinimizedIcons(DisplayT *d, const BlitOpsT *ops, const ColorSchemeT *colors, const WindowStackT *stack, const RectT *clipTo);
-
Draw icons for all minimized windows along the bottom of the screen. Each icon shows a scaled preview of the window's content with a beveled border.
-
Parameter Description
- --------- -----------
- d Display context
- ops Blit operations vtable
- colors Color scheme
- stack Window stack
- clipTo Dirty rectangle
-
Hit Testing
-
wmHitTest
-
int32_t wmHitTest(const WindowStackT *stack, int32_t mx, int32_t my, int32_t *hitPart);
-
Determine which window and chrome region is under the given screen coordinates. Iterates front-to-back (highest Z first) so the topmost window wins.
-
Parameter Description
- --------- -----------
- stack Window stack
- mx, my Screen coordinates
- hitPart Output: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, etc.
-
Returns: Stack index of hit window, or -1 for desktop.
-
wmResizeEdgeHit
-
int32_t wmResizeEdgeHit(const WindowT *win, int32_t mx, int32_t my);
-
Determine which edge(s) of a window's border zone are targeted for resize.
-
Parameter Description
- --------- -----------
- win Window
- mx, my Screen coordinates
-
Returns: Bitmask of RESIZE_LEFT / RESIZE_RIGHT / RESIZE_TOP / RESIZE_BOTTOM.
-
wmMinimizedIconHit
-
int32_t wmMinimizedIconHit(const WindowStackT *stack, const DisplayT *d, int32_t mx, int32_t my);
-
Hit-test minimized icons at the bottom of the screen.
-
Parameter Description
- --------- -----------
- stack Window stack
- d Display context
- mx, my Screen coordinates
-
Returns: Stack index of the minimized window, or -1.
-
Drag and Resize
-
wmDragBegin
-
void wmDragBegin(WindowStackT *stack, int32_t idx, int32_t mouseX, int32_t mouseY);
-
Begin a window drag operation. Records the mouse offset from the window origin.
-
Parameter Description
- --------- -----------
- stack Window stack
- idx Stack index of window to drag
- mouseX/Y Current mouse position
-
wmDragMove
-
void wmDragMove(WindowStackT *stack, DirtyListT *dl, int32_t mouseX, int32_t mouseY, int32_t screenW, int32_t screenH);
-
Update window position during an active drag. Dirties both old and new positions.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- mouseX/Y Current mouse position
- screenW/H Screen dimensions (for clamping)
-
wmDragEnd
-
void wmDragEnd(WindowStackT *stack);
-
End the current drag operation. Clears dragWindow state.
-
Parameter Description
- --------- -----------
- stack Window stack
-
wmResizeBegin
-
void wmResizeBegin(WindowStackT *stack, int32_t idx, int32_t edge, int32_t mouseX, int32_t mouseY);
-
Begin a window resize operation. Records which edge(s) are being dragged.
-
Parameter Description
- --------- -----------
- stack Window stack
- idx Stack index
- edge Bitmask of RESIZE_xxx flags
- mouseX/Y Current mouse position
-
wmResizeMove
-
void wmResizeMove(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, int32_t *mouseX, int32_t *mouseY);
-
Update window dimensions during an active resize. Enforces MIN_WINDOW_W/H and maxW/maxH constraints. Reallocates content buffer and calls onResize if size changed. mouseX/mouseY are in/out: clamped on return for cursor warping.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- d Display context
- mouseX/Y In/out: mouse position (clamped on return)
-
wmResizeEnd
-
void wmResizeEnd(WindowStackT *stack);
-
End the current resize operation. Clears resizeWindow state.
-
Parameter Description
- --------- -----------
- stack Window stack
-
Scrollbar Interaction
-
wmScrollbarClick
-
void wmScrollbarClick(WindowStackT *stack, DirtyListT *dl, int32_t idx, int32_t orient, int32_t mx, int32_t my);
-
Handle an initial click on a scrollbar. Determines what was hit (arrows, trough, or thumb) and either adjusts the value immediately or begins a thumb drag.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- idx Stack index of window
- orient SCROLL_VERTICAL or SCROLL_HORIZONTAL
- mx, my Click screen coordinates
-
wmScrollbarDrag
-
void wmScrollbarDrag(WindowStackT *stack, DirtyListT *dl, int32_t mx, int32_t my);
-
Update the scroll value during an active thumb drag. Maps mouse position along the track to a proportional scroll value.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- mx, my Current mouse position
-
wmScrollbarEnd
-
void wmScrollbarEnd(WindowStackT *stack);
-
End an active scrollbar thumb drag.
-
Parameter Description
- --------- -----------
- stack Window stack
-
Minimize / Maximize / Restore
-
wmMaximize
-
void wmMaximize(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);
-
Maximize a window. Saves current geometry, then expands to screen or maxW/maxH bounds.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- d Display context
- win Window to maximize
-
wmMinimize
-
void wmMinimize(WindowStackT *stack, DirtyListT *dl, WindowT *win);
-
Minimize a window. Hides the window and shows an icon at the bottom of the screen.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- win Window to minimize
-
wmRestore
-
void wmRestore(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);
-
Restore a maximized window to its pre-maximize geometry.
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- d Display context
- win Maximized window to restore
-
wmRestoreMinimized
-
void wmRestoreMinimized(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);
-
Restore a minimized window (show it again and remove the icon).
-
Parameter Description
- --------- -----------
- stack Window stack
- dl Dirty list
- d Display context
- win Minimized window to restore
-
Minimized Icon Layout
-
wmMinimizedIconPos
-
void wmMinimizedIconPos(const DisplayT *d, int32_t index, int32_t *x, int32_t *y);
-
Compute the screen position of a minimized icon by ordinal index. Icons wrap into rows from bottom to top when the screen fills up.
-
Parameter Description
- --------- -----------
- d Display context
- index Ordinal index of the minimized icon
- x, y Output: screen position
-
wmMinimizedIconRect
-
void wmMinimizedIconRect(const WindowStackT *stack, const DisplayT *d, int32_t *y, int32_t *h);
-
Compute the screen rect covering all minimized icon rows. Used to dirty the icon area when windows are minimized or restored.
-
Parameter Description
- --------- -----------
- stack Window stack
- d Display context
- y, h Output: vertical extent of icon area
-
Miscellaneous
-
wmSetTitle
-
void wmSetTitle(WindowT *win, DirtyListT *dl, const char *title);
-
Set the window title and dirty the title bar for repaint.
-
Parameter Description
- --------- -----------
- win Window
- dl Dirty list
- title New title text
-
wmSetIcon
-
int32_t wmSetIcon(WindowT *win, const char *path, const DisplayT *d);
-
Load an icon image for a window from a file. Converts to display pixel format.
-
Parameter Description
- --------- -----------
- win Window
- path Image file path
- d Display context
-
Returns: 0 on success, -1 on failure.
-
-
dvxApp.h -- Layer 5: Application API
-
dvxApp.h -- Layer 5: Application API
-
The topmost layer and the public-facing API. Aggregates all lower layers into a single AppContextT. Applications interact exclusively through dvx*() functions and window callbacks. The event loop follows a cooperative model: poll, dispatch, composite, yield.
-
AppContextT
-
Single monolithic context that owns all GUI state. Contains the display, window stack, dirty list, blit ops, font, color scheme, popup state, cursor state, mouse/keyboard state, tooltip state, wallpaper buffer, video mode list, and various configuration fields. Allocated on the caller's stack or statically.
-
Initialization and Shutdown
-
dvxInit
-
int32_t dvxInit(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);
-
Initialize the entire GUI stack: video mode, input devices, font, color scheme, cursor shapes, and internal state. Single entry point for starting a DVX application.
-
Parameter Description
- --------- -----------
- ctx Application context to initialize
- requestedW/H Desired screen resolution
- preferredBpp Preferred bits per pixel
-
Returns: 0 on success, negative on failure.
-
dvxShutdown
-
void dvxShutdown(AppContextT *ctx);
-
Tear down the GUI stack in reverse order: destroy all windows, restore text mode, release input devices. Safe to call after a failed dvxInit().
-
Parameter Description
- --------- -----------
- ctx Application context
-
dvxChangeVideoMode
-
int32_t dvxChangeVideoMode(AppContextT *ctx, int32_t requestedW, int32_t requestedH, int32_t preferredBpp);
-
Switch to a new video mode live. Reallocates the backbuffer, all window content buffers, repacks colors, rescales wallpaper, and repositions off-screen windows.
-
Parameter Description
- --------- -----------
- ctx Application context
- requestedW/H New resolution
- preferredBpp New bits per pixel
-
Returns: 0 on success, -1 on failure (old mode restored).
-
Event Loop
-
dvxRun
-
void dvxRun(AppContextT *ctx);
-
Enter the main event loop. Polls input, dispatches events, composites dirty regions, and yields on each iteration. Returns when ctx->running becomes false.
-
Parameter Description
- --------- -----------
- ctx Application context
-
dvxUpdate
-
bool dvxUpdate(AppContextT *ctx);
-
Process exactly one frame of the event loop. For applications that integrate the GUI into their own main loop (e.g. polling serial ports between frames).
-
Parameter Description
- --------- -----------
- ctx Application context
-
Returns: false when the GUI wants to exit.
-
dvxQuit
-
void dvxQuit(AppContextT *ctx);
-
Request exit from the main event loop (sets ctx->running = false).
-
Parameter Description
- --------- -----------
- ctx Application context
-
Window Management
-
dvxCreateWindow
-
WindowT *dvxCreateWindow(AppContextT *ctx, const char *title, int32_t x, int32_t y, int32_t w, int32_t h, bool resizable);
-
Create a window at an explicit screen position. The window is raised to the top, focused, and its entire region is dirtied.
-
Parameter Description
- --------- -----------
- ctx Application context
- title Window title
- x, y Screen position
- w, h Outer frame dimensions
- resizable true = allow user resize
-
Returns: Pointer to new WindowT.
-
dvxCreateWindowCentered
-
WindowT *dvxCreateWindowCentered(AppContextT *ctx, const char *title, int32_t w, int32_t h, bool resizable);
-
Convenience wrapper that centers the window on screen.
-
Parameter Description
- --------- -----------
- ctx Application context
- title Window title
- w, h Outer frame dimensions
- resizable true = allow user resize
-
Returns: Pointer to new WindowT.
-
dvxDestroyWindow
-
void dvxDestroyWindow(AppContextT *ctx, WindowT *win);
-
Destroy a window, free all its resources, and dirty its former region.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to destroy
-
dvxRaiseWindow
-
void dvxRaiseWindow(AppContextT *ctx, WindowT *win);
-
Raise a window to the top of the Z-order and give it focus.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to raise
-
dvxFitWindow
-
void dvxFitWindow(AppContextT *ctx, WindowT *win);
-
Resize a window to exactly fit its widget tree's computed minimum size (plus chrome). Used for dialog boxes and fixed-layout windows.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to fit
-
dvxFitWindowW
-
void dvxFitWindowW(AppContextT *ctx, WindowT *win);
-
Resize window width only to fit widget tree's minimum width (plus chrome).
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to fit
-
dvxFitWindowH
-
void dvxFitWindowH(AppContextT *ctx, WindowT *win);
-
Resize window height only to fit widget tree's minimum height (plus chrome).
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to fit
-
dvxResizeWindow
-
void dvxResizeWindow(AppContextT *ctx, WindowT *win, int32_t newW, int32_t newH);
-
Programmatically resize a window to the specified outer dimensions.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to resize
- newW, newH New outer frame dimensions
-
dvxMinimizeWindow
-
void dvxMinimizeWindow(AppContextT *ctx, WindowT *win);
-
Minimize a window (show as icon at bottom of screen).
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to minimize
-
dvxMaximizeWindow
-
void dvxMaximizeWindow(AppContextT *ctx, WindowT *win);
-
Maximize a window (expand to fill screen or maxW/maxH).
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to maximize
-
dvxHideWindow
-
void dvxHideWindow(AppContextT *ctx, WindowT *win);
-
Hide a window without destroying it. Marks the exposed region dirty.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to hide
-
dvxShowWindow
-
void dvxShowWindow(AppContextT *ctx, WindowT *win);
-
Show a previously hidden window. Marks its region dirty for repaint.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to show
-
Invalidation
-
dvxInvalidateRect
-
void dvxInvalidateRect(AppContextT *ctx, WindowT *win, int32_t x, int32_t y, int32_t w, int32_t h);
-
Mark a sub-region of a window's content area as needing repaint. Coordinates are relative to the content area, not the screen. Triggers onPaint during the next composite pass.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window
- x, y, w, h Dirty rectangle in content-relative coordinates
-
dvxInvalidateWindow
-
void dvxInvalidateWindow(AppContextT *ctx, WindowT *win);
-
Mark the entire window content area as dirty.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to invalidate
-
Window Properties
-
dvxSetTitle
-
void dvxSetTitle(AppContextT *ctx, WindowT *win, const char *title);
-
Set a window's title text and dirty the title bar.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window
- title New title text
-
dvxSetWindowIcon
-
int32_t dvxSetWindowIcon(AppContextT *ctx, WindowT *win, const char *path);
-
Load an icon for a window from an image file.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window
- path Image file path
-
Returns: 0 on success, -1 on failure.
-
dvxSetBusy
-
void dvxSetBusy(AppContextT *ctx, bool busy);
-
Set or clear busy state. While busy, the hourglass cursor is shown and input is blocked.
-
Parameter Description
- --------- -----------
- ctx Application context
- busy true = show hourglass, false = normal
-
Accessors
-
dvxGetFont
-
const BitmapFontT *dvxGetFont(const AppContextT *ctx);
-
Get a pointer to the default font.
-
Parameter Description
- --------- -----------
- ctx Application context
-
Returns: Pointer to the active BitmapFontT.
-
dvxGetColors
-
const ColorSchemeT *dvxGetColors(const AppContextT *ctx);
-
Get a pointer to the current color scheme.
-
Parameter Description
- --------- -----------
- ctx Application context
-
Returns: Pointer to the active ColorSchemeT.
-
dvxGetDisplay
-
DisplayT *dvxGetDisplay(AppContextT *ctx);
-
Get a pointer to the display context.
-
Parameter Description
- --------- -----------
- ctx Application context
-
Returns: Pointer to the DisplayT.
-
dvxGetBlitOps
-
const BlitOpsT *dvxGetBlitOps(const AppContextT *ctx);
-
Get a pointer to the blit operations vtable.
-
Parameter Description
- --------- -----------
- ctx Application context
-
Returns: Pointer to the active BlitOpsT.
-
dvxGetVideoModes
-
const VideoModeInfoT *dvxGetVideoModes(const AppContextT *ctx, int32_t *count);
-
Return the list of available video modes enumerated at init time.
-
Parameter Description
- --------- -----------
- ctx Application context
- count Output: number of mode entries
-
Returns: Pointer to the VideoModeInfoT array.
-
Color Scheme
-
dvxSetColor
-
void dvxSetColor(AppContextT *ctx, ColorIdE id, uint8_t r, uint8_t g, uint8_t b);
-
Set a single color by ID. Repacks to native pixel format and invalidates the entire screen.
-
Parameter Description
- --------- -----------
- ctx Application context
- id Color ID (ColorIdE)
- r, g, b RGB values (0-255)
-
dvxGetColor
-
void dvxGetColor(const AppContextT *ctx, ColorIdE id, uint8_t *r, uint8_t *g, uint8_t *b);
-
Get a color's RGB values by ID.
-
Parameter Description
- --------- -----------
- ctx Application context
- id Color ID (ColorIdE)
- r, g, b Output: RGB values
-
dvxApplyColorScheme
-
void dvxApplyColorScheme(AppContextT *ctx);
-
Apply all colors from ctx->colorRgb[] at once (repack + full repaint).
-
Parameter Description
- --------- -----------
- ctx Application context
-
dvxResetColorScheme
-
void dvxResetColorScheme(AppContextT *ctx);
-
Reset all colors to the built-in defaults and repaint.
-
Parameter Description
- --------- -----------
- ctx Application context
-
dvxLoadTheme
-
bool dvxLoadTheme(AppContextT *ctx, const char *filename);
-
Load a theme file (INI format with [colors] section) and apply it.
-
Parameter Description
- --------- -----------
- ctx Application context
- filename Path to theme INI file
-
Returns: true on success.
-
dvxSaveTheme
-
bool dvxSaveTheme(const AppContextT *ctx, const char *filename);
-
Save the current color scheme to a theme file.
-
Parameter Description
- --------- -----------
- ctx Application context
- filename Output file path
-
Returns: true on success.
-
dvxColorName
-
const char *dvxColorName(ColorIdE id);
-
Return the INI key name for a color ID (e.g. "desktop", "windowFace").
-
Parameter Description
- --------- -----------
- id Color ID
-
Returns: Static string.
-
dvxColorLabel
-
const char *dvxColorLabel(ColorIdE id);
-
Return a human-readable display label (e.g. "Desktop", "Cursor Color").
-
Parameter Description
- --------- -----------
- id Color ID
-
Returns: Static string.
-
Wallpaper
-
dvxSetWallpaper
-
bool dvxSetWallpaper(AppContextT *ctx, const char *path);
-
Load and apply a wallpaper image using the current wallpaperMode (stretch/tile/center). Pass NULL to clear the wallpaper.
-
Parameter Description
- --------- -----------
- ctx Application context
- path Image file path, or NULL to clear
-
Returns: true on success.
-
dvxSetWallpaperMode
-
void dvxSetWallpaperMode(AppContextT *ctx, WallpaperModeE mode);
-
Change the wallpaper display mode and re-render. No effect if no wallpaper is loaded.
-
Parameter Description
- --------- -----------
- ctx Application context
- mode WallpaperStretchE, WallpaperTileE, or WallpaperCenterE
-
Mouse Configuration
-
dvxSetMouseConfig
-
void dvxSetMouseConfig(AppContextT *ctx, int32_t wheelDir, int32_t dblClickMs, int32_t accelThreshold);
-
Configure mouse behavior.
-
Parameter Description
- --------- -----------
- ctx Application context
- wheelDir 1 = normal, -1 = reversed
- dblClickMs Double-click speed in milliseconds (e.g. 500)
- accelThreshold Double-speed threshold in mickeys/sec (0 = don't change)
-
Accelerators
-
dvxCreateAccelTable
-
AccelTableT *dvxCreateAccelTable(void);
-
Allocate a new accelerator table. Attach to a window via win->accelTable.
-
Returns: Pointer to new AccelTableT.
-
dvxFreeAccelTable
-
void dvxFreeAccelTable(AccelTableT *table);
-
Free an accelerator table and its entries.
-
Parameter Description
- --------- -----------
- table Table to free
-
dvxAddAccel
-
void dvxAddAccel(AccelTableT *table, int32_t key, int32_t modifiers, int32_t cmdId);
-
Register a keyboard shortcut. On match, fires the window's onMenu callback with cmdId.
-
Parameter Description
- --------- -----------
- table Accelerator table
- key ASCII character or KEY_Fxx constant
- modifiers Bitmask of ACCEL_CTRL / ACCEL_SHIFT / ACCEL_ALT
- cmdId Command ID passed to onMenu
-
Window Arrangement
-
dvxCascadeWindows
-
void dvxCascadeWindows(AppContextT *ctx);
-
Cascade all visible, non-minimized windows. Each is offset diagonally by the title bar height.
-
Parameter Description
- --------- -----------
- ctx Application context
-
dvxTileWindows
-
void dvxTileWindows(AppContextT *ctx);
-
Arrange visible windows in an NxM grid filling the screen.
-
Parameter Description
- --------- -----------
- ctx Application context
-
dvxTileWindowsH
-
void dvxTileWindowsH(AppContextT *ctx);
-
Tile windows horizontally (side by side, equal width, full height).
-
Parameter Description
- --------- -----------
- ctx Application context
-
dvxTileWindowsV
-
void dvxTileWindowsV(AppContextT *ctx);
-
Tile windows vertically (stacked, full width, equal height).
-
Parameter Description
- --------- -----------
- ctx Application context
-
Image I/O
-
dvxLoadImage
-
uint8_t *dvxLoadImage(const AppContextT *ctx, const char *path, int32_t *outW, int32_t *outH, int32_t *outPitch);
-
Load an image file (BMP, PNG, JPEG, GIF) and convert to the display's native pixel format. Caller must free with dvxFreeImage().
-
Parameter Description
- --------- -----------
- ctx Application context
- path Image file path
- outW, outH Output: image dimensions
- outPitch Output: row pitch in bytes
-
Returns: Pixel buffer, or NULL on failure.
-
dvxLoadImageFromMemory
-
uint8_t *dvxLoadImageFromMemory(const AppContextT *ctx, const uint8_t *data, int32_t dataLen, int32_t *outW, int32_t *outH, int32_t *outPitch);
-
Load an image from a memory buffer. Same output format as dvxLoadImage(). Caller must free with dvxFreeImage().
-
Parameter Description
- --------- -----------
- ctx Application context
- data Image data buffer
- dataLen Buffer size in bytes
- outW, outH Output: image dimensions
- outPitch Output: row pitch in bytes
-
Returns: Pixel buffer, or NULL on failure.
-
dvxFreeImage
-
void dvxFreeImage(uint8_t *data);
-
Free a pixel buffer returned by dvxLoadImage() or dvxLoadImageFromMemory().
-
Parameter Description
- --------- -----------
- data Buffer to free
-
dvxImageInfo
-
bool dvxImageInfo(const char *path, int32_t *outW, int32_t *outH);
-
Query image dimensions without decoding the full file.
-
Parameter Description
- --------- -----------
- path Image file path
- outW, outH Output: image dimensions
-
Returns: true on success.
-
dvxSaveImage
-
int32_t dvxSaveImage(const AppContextT *ctx, const uint8_t *data, int32_t w, int32_t h, int32_t pitch, const char *path);
-
Save native-format pixel data to a PNG file.
-
Parameter Description
- --------- -----------
- ctx Application context
- data Pixel data in display native format
- w, h Image dimensions
- pitch Row pitch in bytes
- path Output file path
-
Returns: 0 on success, -1 on failure.
-
Screenshots
-
dvxScreenshot
-
int32_t dvxScreenshot(AppContextT *ctx, const char *path);
-
Save the entire screen (backbuffer contents) to a PNG file. Converts from native pixel format to RGB.
-
Parameter Description
- --------- -----------
- ctx Application context
- path Output PNG file path
-
Returns: 0 on success, -1 on failure.
-
dvxWindowScreenshot
-
int32_t dvxWindowScreenshot(AppContextT *ctx, WindowT *win, const char *path);
-
Save a window's content to a PNG file.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window
- path Output PNG file path
-
Returns: 0 on success, -1 on failure.
-
Clipboard
-
dvxClipboardCopy
-
void dvxClipboardCopy(const char *text, int32_t len);
-
Copy text to the process-wide clipboard buffer. Simple static buffer (not inter-process).
-
Parameter Description
- --------- -----------
- text Text to copy
- len Length in bytes
-
dvxClipboardGet
-
const char *dvxClipboardGet(int32_t *outLen);
-
Retrieve the current clipboard contents. Returns a pointer to the internal buffer (valid until the next dvxClipboardCopy), or NULL if empty.
-
Parameter Description
- --------- -----------
- outLen Output: length of clipboard text
-
Returns: Clipboard text, or NULL.
-
Resource Loading
-
dvxResLoadIcon
-
uint8_t *dvxResLoadIcon(AppContextT *ctx, const char *dxePath, const char *resName, int32_t *outW, int32_t *outH, int32_t *outPitch);
-
Load an icon/image resource from a DXE file and decode to native pixel format. Caller must free with dvxFreeImage().
-
Parameter Description
- --------- -----------
- ctx Application context
- dxePath Path to DXE file
- resName Resource name within the DXE
- outW, outH Output: image dimensions
- outPitch Output: row pitch
-
Returns: Pixel buffer, or NULL if not found.
-
dvxResLoadText
-
bool dvxResLoadText(const char *dxePath, const char *resName, char *buf, int32_t bufSize);
-
Load a text resource from a DXE file into a caller-provided buffer. Null-terminated and truncated to fit bufSize.
-
Parameter Description
- --------- -----------
- dxePath Path to DXE file
- resName Resource name
- buf Output buffer
- bufSize Buffer capacity
-
Returns: true on success.
-
dvxResLoadData
-
void *dvxResLoadData(const char *dxePath, const char *resName, uint32_t *outSize);
-
Load a raw binary resource from a DXE file. Returns a malloc'd buffer that the caller must free.
-
Parameter Description
- --------- -----------
- dxePath Path to DXE file
- resName Resource name
- outSize Output: data size in bytes
-
Returns: Data buffer, or NULL if not found.
-
Utilities
-
dvxTextHash
-
uint32_t dvxTextHash(const char *text);
-
Compute a djb2-xor hash for cheap dirty detection. Compare at save time with the current hash to detect changes without a shadow copy. Not cryptographic.
-
Parameter Description
- --------- -----------
- text Null-terminated string to hash
-
Returns: 32-bit hash value.
-
-
dvxWidget.h -- Widget System
-
dvxWidget.h -- Widget System
-
Retained-mode widget toolkit layered on the DVX window manager. Widgets form a tree (parent-child) rooted at a per-window VBox container. Layout is automatic: measure minimum sizes bottom-up, then allocate space top-down with flexbox-like weighted distribution. Widget types are registered dynamically at runtime via DXE plugins.
-
WidgetT Structure
-
Core widget structure. Generic across all widget types; type-specific data lives in the void *data pointer managed by each widget's DXE.
-
Field Description
- ----- -----------
- int32_t type Widget type ID (assigned by wgtRegisterClass)
- const WidgetClassT *wclass Vtable for this widget type
- char name[MAX_WIDGET_NAME] Widget name for lookup via wgtFind
- parent, firstChild, lastChild, nextSibling Tree linkage pointers
- WindowT *window Owning window
- int32_t x, y, w, h Computed geometry (relative to content area)
- int32_t calcMinW, calcMinH Computed minimum size (from layout pass)
- int32_t minW, minH, maxW, maxH, prefW, prefH Size hints (tagged sizes)
- int32_t weight Extra-space distribution weight (0=fixed, 100=normal)
- WidgetAlignE align Main-axis alignment for children
- int32_t spacing, padding Tagged sizes for child spacing and padding
- uint32_t fgColor, bgColor Custom colors (0 = use scheme defaults)
- bool visible, enabled, readOnly State flags
- bool swallowTab Tab key goes to widget, not focus navigation
- char accelKey Accelerator character (0 = none)
- void *userData, *data Application data and widget-private data
- const char *tooltip Tooltip text (NULL = none)
- MenuT *contextMenu Right-click menu (NULL = none)
-
Universal Callbacks:
-
Callback Description
- -------- -----------
- onClick(WidgetT *w) Widget clicked
- onDblClick(WidgetT *w) Widget double-clicked
- onChange(WidgetT *w) Value changed
- onFocus(WidgetT *w) Widget gained focus
- onBlur(WidgetT *w) Widget lost focus
- onKeyPress(WidgetT *w, int32_t keyAscii) ASCII key press
- onKeyDown(WidgetT *w, int32_t keyCode, int32_t shift) Key down
- onKeyUp(WidgetT *w, int32_t keyCode, int32_t shift) Key up
- onMouseDown(WidgetT *w, int32_t btn, int32_t x, int32_t y) Mouse button pressed
- onMouseUp(WidgetT *w, int32_t btn, int32_t x, int32_t y) Mouse button released
- onMouseMove(WidgetT *w, int32_t btn, int32_t x, int32_t y) Mouse moved
- onScroll(WidgetT *w, int32_t delta) Mouse wheel
- onValidate(WidgetT *w) Return false to cancel a write
-
Size Specification Macros
-
Macro Description
- ----- -----------
- wgtPixels(v) Size in pixels
- wgtChars(v) Size in character widths (multiplied by charWidth at layout)
- wgtPercent(v) Size as percentage of parent dimension
-
Widget Class Flags
-
Flag Description
- ---- -----------
- WCLASS_FOCUSABLE Can receive keyboard focus (Tab navigation)
- WCLASS_HORIZ_CONTAINER Lays out children horizontally (vs. vertical)
- WCLASS_PAINTS_CHILDREN Widget handles child rendering itself
- WCLASS_NO_HIT_RECURSE Hit testing stops here, no child recursion
- WCLASS_FOCUS_FORWARD Accel hit forwards focus to next focusable sibling
- WCLASS_HAS_POPUP Has dropdown popup overlay
- WCLASS_SCROLLABLE Accepts mouse wheel events
- WCLASS_SCROLL_CONTAINER Scroll container (ScrollPane)
- WCLASS_NEEDS_POLL Needs periodic polling
- WCLASS_SWALLOWS_TAB Tab key goes to widget, not focus navigation
- WCLASS_RELAYOUT_ON_SCROLL Full relayout on scrollbar drag
- WCLASS_PRESS_RELEASE Click = press + release (Button, ImageButton)
- WCLASS_ACCEL_WHEN_HIDDEN Accelerator matching works even when invisible
-
Window Integration
-
wgtInitWindow
-
WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win);
-
Initialize the widget system for a window. Creates a root VBox container that fills the content area, and installs callback handlers (onPaint, onMouse, onKey, onResize) for widget-based event dispatch. The window's userData is set to the AppContextT pointer.
-
Parameter Description
- --------- -----------
- ctx Application context
- win Window to initialize
-
Returns: Root VBox widget (add children to this).
-
Widget Operations
-
wgtGetContext
-
AppContextT *wgtGetContext(const WidgetT *w);
-
Walk from any widget up the tree to the root, then retrieve the AppContextT stored in the window's userData. Lets any widget access the full application context.
-
Parameter Description
- --------- -----------
- w Any widget in the tree
-
Returns: Pointer to the AppContextT.
-
wgtInvalidate
-
void wgtInvalidate(WidgetT *w);
-
Mark a widget as needing both re-layout (measure + position) and repaint. Propagates upward to ancestors. Use after structural changes (adding/removing children, text changes that affect size).
-
Parameter Description
- --------- -----------
- w Widget to invalidate
-
wgtInvalidatePaint
-
void wgtInvalidatePaint(WidgetT *w);
-
Mark a widget as needing repaint only, without re-layout. Use for visual-only changes (checkbox toggle, selection highlight, cursor blink).
-
Parameter Description
- --------- -----------
- w Widget to repaint
-
wgtSetText
-
void wgtSetText(WidgetT *w, const char *text);
-
Set widget text content (dispatches to the widget class's SET_TEXT handler).
-
Parameter Description
- --------- -----------
- w Widget
- text New text
-
wgtGetText
-
const char *wgtGetText(const WidgetT *w);
-
Get the widget's current text content.
-
Parameter Description
- --------- -----------
- w Widget
-
Returns: Text string (empty string if no handler).
-
wgtSetEnabled
-
void wgtSetEnabled(WidgetT *w, bool enabled);
-
Enable or disable a widget. Disabled widgets are grayed out and do not receive input.
-
Parameter Description
- --------- -----------
- w Widget
- enabled true = enabled, false = disabled
-
wgtSetReadOnly
-
void wgtSetReadOnly(WidgetT *w, bool readOnly);
-
Set read-only mode. Allows scrolling and selection but blocks editing.
-
Parameter Description
- --------- -----------
- w Widget
- readOnly true = read-only
-
wgtSetFocused
-
void wgtSetFocused(WidgetT *w);
-
Set keyboard focus to a widget.
-
Parameter Description
- --------- -----------
- w Widget to focus
-
wgtGetFocused
-
WidgetT *wgtGetFocused(void);
-
Get the currently focused widget.
-
Returns: Focused widget, or NULL.
-
wgtSetVisible
-
void wgtSetVisible(WidgetT *w, bool visible);
-
Show or hide a widget.
-
Parameter Description
- --------- -----------
- w Widget
- visible true = visible, false = hidden
-
wgtSetName
-
void wgtSetName(WidgetT *w, const char *name);
-
Set a widget's name for lookup via wgtFind().
-
Parameter Description
- --------- -----------
- w Widget
- name Name string (max MAX_WIDGET_NAME chars)
-
wgtFind
-
WidgetT *wgtFind(WidgetT *root, const char *name);
-
Find a widget by name. Searches the subtree rooted at root.
-
Parameter Description
- --------- -----------
- root Root of subtree to search
- name Widget name to find
-
Returns: Matching widget, or NULL.
-
wgtDestroy
-
void wgtDestroy(WidgetT *w);
-
Destroy a widget and all its children. Removes from parent's child list.
-
Parameter Description
- --------- -----------
- w Widget to destroy
-
wgtSetTooltip
-
void wgtSetTooltip(WidgetT *w, const char *text);
-
Set tooltip text for a widget. Pass NULL to remove. Caller owns the string and it must outlive the widget.
-
Parameter Description
- --------- -----------
- w Widget
- text Tooltip text, or NULL
-
widgetOnResize
-
void widgetOnResize(WindowT *win, int32_t newW, int32_t newH);
-
Default window resize handler installed by wgtInitWindow(). Re-evaluates scrollbars and relayouts the widget tree. Call from custom onResize handlers to chain to the widget system.
-
Parameter Description
- --------- -----------
- win Window being resized
- newW, newH New content dimensions
-
Layout
-
wgtResolveSize
-
int32_t wgtResolveSize(int32_t taggedSize, int32_t parentSize, int32_t charWidth);
-
Decode a tagged size value (WGT_SIZE_PIXELS/CHARS/PERCENT) into a concrete pixel count. Returns 0 for a raw 0 input (meaning "auto").
-
Parameter Description
- --------- -----------
- taggedSize Tagged size value
- parentSize Parent dimension (for PERCENT mode)
- charWidth Font character width (for CHARS mode)
-
Returns: Size in pixels.
-
wgtLayout
-
void wgtLayout(WidgetT *root, int32_t availW, int32_t availH, const BitmapFontT *font);
-
Execute the full two-pass layout algorithm. Pass 1 (bottom-up): compute minimum sizes. Pass 2 (top-down): allocate space with weighted distribution. Normally called automatically; exposed for cases where layout must be forced before the next paint.
-
Parameter Description
- --------- -----------
- root Root widget
- availW/H Available space
- font Bitmap font (for character-based sizing)
-
wgtPaint
-
void wgtPaint(WidgetT *root, DisplayT *d, const BlitOpsT *ops, const BitmapFontT *font, const ColorSchemeT *colors);
-
Paint the entire widget tree by depth-first traversal. Each widget's clip rect is set to its bounds. Overlays (popups, tooltips) are painted in a second pass on top.
-
Parameter Description
- --------- -----------
- root Root widget
- d Display context
- ops Blit operations vtable
- font Bitmap font
- colors Color scheme
-
Debug
-
wgtSetDebugLayout
-
void wgtSetDebugLayout(AppContextT *ctx, bool enabled);
-
Draw colored borders around layout containers for debugging.
-
Parameter Description
- --------- -----------
- ctx Application context
- enabled true = draw debug borders
-
Dynamic Widget Registration
-
wgtRegisterClass
-
int32_t wgtRegisterClass(const WidgetClassT *wclass);
-
Register a new widget class at runtime. Appends to widgetClassTable. The WidgetClassT must remain valid for the lifetime of the process (typically static const in a DXE).
-
Parameter Description
- --------- -----------
- wclass Widget class vtable to register
-
Returns: Assigned type ID.
-
wgtRegisterApi
-
void wgtRegisterApi(const char *name, const void *api);
-
Register a widget API struct under a name. Each widget DXE registers its API during initialization. Callers retrieve it via wgtGetApi() and cast to the widget-specific type.
-
Parameter Description
- --------- -----------
- name Widget type name (e.g. "button", "listbox")
- api Pointer to the widget's API struct
-
wgtGetApi
-
const void *wgtGetApi(const char *name);
-
Retrieve a registered widget API struct by name.
-
Parameter Description
- --------- -----------
- name Widget type name
-
Returns: Pointer to the API struct, or NULL if not found.
-
Widget Interface Descriptors
-
wgtRegisterIface
-
void wgtRegisterIface(const char *name, const WgtIfaceT *iface);
-
Register an interface descriptor for a widget type. Used by the BASIC form runtime and IDE for generic property/method dispatch.
-
Parameter Description
- --------- -----------
- name Widget type name
- iface Interface descriptor
-
wgtGetIface
-
const WgtIfaceT *wgtGetIface(const char *name);
-
Retrieve an interface descriptor by widget type name.
-
Parameter Description
- --------- -----------
- name Widget type name
-
Returns: Interface descriptor, or NULL.
-
wgtFindByBasName
-
const char *wgtFindByBasName(const char *basName);
-
Find a widget type name by its VB-style name (e.g. "CommandButton" -> "button"). Case-insensitive search.
-
Parameter Description
- --------- -----------
- basName VB-style widget name
-
Returns: Internal type name, or NULL.
-
wgtIfaceCount
-
int32_t wgtIfaceCount(void);
-
Return the number of registered widget interfaces.
-
Returns: Count of registered interfaces.
-
wgtIfaceAt
-
const WgtIfaceT *wgtIfaceAt(int32_t idx, const char **outName);
-
Get a registered widget interface by index.
-
Parameter Description
- --------- -----------
- idx Index (0-based)
- outName Output: type name
-
Returns: Interface descriptor.
-
wgtIfaceGetPath
-
const char *wgtIfaceGetPath(const char *name);
-
Get the .wgt DXE file path for a registered widget.
-
Parameter Description
- --------- -----------
- name Widget type name
-
Returns: File path string.
-
wgtIfaceSetPath
-
void wgtIfaceSetPath(const char *name, const char *path);
-
Set the .wgt DXE file path for a registered widget (called by the loader).
-
Parameter Description
- --------- -----------
- name Widget type name
- path DXE file path
-
wgtIfaceGetPathIndex
-
int32_t wgtIfaceGetPathIndex(const char *name);
-
Get the 1-based index of this widget within its .wgt file. Used to construct suffixed resource names (e.g. "name-2", "icon16-2").
-
Parameter Description
- --------- -----------
- name Widget type name
-
Returns: 1-based index within the DXE file.
-
Typed Dispatch Helpers
-
The following inline functions provide type-safe dispatch through the WidgetClassT handler table. Each checks for a non-NULL handler before calling.
-
Function Method ID Description
- -------- --------- -----------
- wclsHas(w, methodId) -- Check if handler exists
- wclsPaint(w, d, ops, font, colors) WGT_METHOD_PAINT Paint the widget
- wclsPaintOverlay(w, d, ops, font, colors) WGT_METHOD_PAINT_OVERLAY Paint overlay (popups)
- wclsCalcMinSize(w, font) WGT_METHOD_CALC_MIN_SIZE Compute minimum size
- wclsLayout(w, font) WGT_METHOD_LAYOUT Layout children
- wclsGetLayoutMetrics(w, font, ...) WGT_METHOD_GET_LAYOUT_METRICS Get pad, gap, extraTop, borderW
- wclsOnMouse(w, root, vx, vy) WGT_METHOD_ON_MOUSE Handle mouse event
- wclsOnKey(w, key, mod) WGT_METHOD_ON_KEY Handle key event
- wclsOnAccelActivate(w, root) WGT_METHOD_ON_ACCEL_ACTIVATE Handle accelerator
- wclsDestroy(w) WGT_METHOD_DESTROY Destroy widget data
- wclsOnChildChanged(parent, child) WGT_METHOD_ON_CHILD_CHANGED Notify parent of change
- wclsGetText(w) WGT_METHOD_GET_TEXT Get widget text
- wclsSetText(w, text) WGT_METHOD_SET_TEXT Set widget text
- wclsClearSelection(w) WGT_METHOD_CLEAR_SELECTION Clear text selection
- wclsClosePopup(w) WGT_METHOD_CLOSE_POPUP Close dropdown popup
- wclsGetPopupRect(w, font, ...) WGT_METHOD_GET_POPUP_RECT Get popup screen rect
- wclsOnDragUpdate(w, root, x, y) WGT_METHOD_ON_DRAG_UPDATE Update during drag
- wclsOnDragEnd(w, root, x, y) WGT_METHOD_ON_DRAG_END End drag operation
- wclsGetCursorShape(w, vx, vy) WGT_METHOD_GET_CURSOR_SHAPE Get cursor for position
- wclsPoll(w, win) WGT_METHOD_POLL Periodic polling
- wclsQuickRepaint(w, outY, outH) WGT_METHOD_QUICK_REPAINT Fast partial repaint
- wclsScrollChildIntoView(parent, child) WGT_METHOD_SCROLL_CHILD_INTO_VIEW Scroll child visible
-
-
Base WidgetT (Common Properties, Events, and Operations)
-
DVX Widget System
-
Complete reference for the DVX GUI widget toolkit. All widgets are implemented as dynamically loaded DXE modules. They are created via convenience macros that wrap the per-widget API function tables. The base WidgetT structure is defined in core/dvxWidget.h; individual widget headers live in widgets/.
-
Individual widgets are documented in their own sections. See the table of contents for the full list.
-
Base WidgetT (Common Properties, Events, and Operations)
-
Every widget inherits from the WidgetT structure defined in core/dvxWidget.h. The fields and callbacks listed here are available on all widget types.
-
Common Properties
-
Field Type Description
- ----- ---- -----------
- name char[32] Widget name for lookup via wgtFind().
- x, y, w, h int32_t Computed geometry relative to the window content area (set by layout).
- minW, minH int32_t (tagged) Minimum size hints. Use wgtPixels(), wgtChars(), or wgtPercent(). 0 = auto.
- maxW, maxH int32_t (tagged) Maximum size constraints. 0 = no limit.
- prefW, prefH int32_t (tagged) Preferred size. 0 = auto.
- weight int32_t Extra-space distribution weight. 0 = fixed, 100 = normal. A widget with weight=200 gets twice the extra space of one with weight=100.
- align WidgetAlignE Main-axis alignment for children: AlignStartE, AlignCenterE, AlignEndE.
- spacing int32_t (tagged) Spacing between children (containers only). 0 = default.
- padding int32_t (tagged) Internal padding (containers only). 0 = default.
- fgColor uint32_t Foreground color override. 0 = use color scheme default.
- bgColor uint32_t Background color override. 0 = use color scheme default.
- visible bool Visibility state.
- enabled bool Enabled state. Disabled widgets are grayed out and ignore input.
- readOnly bool Read-only mode: allows scrolling/selection but blocks editing.
- swallowTab bool When true, Tab key goes to the widget instead of navigating focus.
- accelKey char Lowercase accelerator character. 0 if none.
- tooltip const char * Tooltip text. NULL = none. Caller owns the string.
- contextMenu MenuT * Right-click context menu. NULL = none. Caller owns.
- userData void * Application-defined user data pointer.
-
Size Specification Macros
-
Macro Description
- ----- -----------
- wgtPixels(v) Size in pixels.
- wgtChars(v) Size in character widths (multiplied by font charWidth).
- wgtPercent(v) Size as a percentage of parent dimension.
-
Common Events (Callbacks)
-
These callback function pointers are available on every WidgetT. Set them directly on the widget struct.
-
Callback Signature Description
- -------- --------- -----------
- onClick void (*)(WidgetT *w) Fires on mouse click / activation.
- onDblClick void (*)(WidgetT *w) Fires on double-click.
- onChange void (*)(WidgetT *w) Fires when the widget's value changes (text, selection, check state, etc.).
- onFocus void (*)(WidgetT *w) Fires when the widget receives keyboard focus.
- onBlur void (*)(WidgetT *w) Fires when the widget loses keyboard focus.
- onKeyPress void (*)(WidgetT *w, int32_t keyAscii) Fires on a printable key press (ASCII value).
- onKeyDown void (*)(WidgetT *w, int32_t keyCode, int32_t shift) Fires on key down (scan code + shift state).
- onKeyUp void (*)(WidgetT *w, int32_t keyCode, int32_t shift) Fires on key up.
- onMouseDown void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) Fires on mouse button press.
- onMouseUp void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) Fires on mouse button release.
- onMouseMove void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) Fires on mouse movement over the widget.
- onScroll void (*)(WidgetT *w, int32_t delta) Fires on mouse wheel scroll.
- onValidate bool (*)(WidgetT *w) Validation callback. Return false to cancel a pending write.
-
Common Operations
-
Function Description
- -------- -----------
- WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win) Initialize widgets for a window. Returns the root VBox container.
- AppContextT *wgtGetContext(const WidgetT *w) Walk up from any widget to retrieve the AppContextT.
- void wgtInvalidate(WidgetT *w) Mark widget for re-layout and repaint. Propagates to ancestors.
- void wgtInvalidatePaint(WidgetT *w) Mark widget for repaint only (no layout recalculation).
- void wgtSetText(WidgetT *w, const char *text) Set widget text (label, button, textinput, etc.).
- const char *wgtGetText(const WidgetT *w) Get widget text.
- void wgtSetEnabled(WidgetT *w, bool enabled) Enable or disable a widget.
- void wgtSetReadOnly(WidgetT *w, bool readOnly) Set read-only mode.
- void wgtSetFocused(WidgetT *w) Set keyboard focus to a widget.
- WidgetT *wgtGetFocused(void) Get the currently focused widget.
- void wgtSetVisible(WidgetT *w, bool visible) Show or hide a widget.
- void wgtSetName(WidgetT *w, const char *name) Set widget name for lookup.
- WidgetT *wgtFind(WidgetT *root, const char *name) Find a widget by name in the subtree.
- void wgtDestroy(WidgetT *w) Destroy a widget and all its children.
- void wgtSetTooltip(WidgetT *w, const char *text) Set tooltip text. Pass NULL to remove.
-
-
AnsiTerm
-
AnsiTerm
-
A VT100/ANSI-compatible terminal emulator widget designed for connecting to BBS systems over the serial link. Uses a traditional text-mode cell buffer (character + attribute byte pairs) with the CP437 character set and 16-color CGA palette. Supports cursor movement, screen/line erase, scrolling regions, SGR colors, and scrollback history. Communication is abstracted through read/write function pointers, allowing the terminal to work with raw serial ports, the secLink encrypted channel, or any other byte-oriented transport.
-
Header: widgets/widgetAnsiTerm.h
-
Creation
-
WidgetT *term = wgtAnsiTerm(parent, 80, 25);
-
Macros
-
Macro Description
- ----- -----------
- wgtAnsiTerm(parent, cols, rows) Create an ANSI terminal widget with the given column and row dimensions.
- wgtAnsiTermWrite(w, data, len) Write raw bytes into the terminal's ANSI parser. data is a const uint8_t * buffer, len is the byte count.
- wgtAnsiTermClear(w) Clear the terminal screen and reset the cursor to the home position.
- wgtAnsiTermSetComm(w, ctx, readFn, writeFn) Attach a communication channel. readFn and writeFn are I/O callbacks; ctx is passed as their first argument.
- wgtAnsiTermSetScrollback(w, maxLines) Set the maximum number of scrollback lines. Lines scrolled off the top are saved in a circular buffer.
- wgtAnsiTermPoll(w) Poll the communication channel for incoming data and feed it into the ANSI parser.
- wgtAnsiTermRepaint(w, outY, outH) Fast repaint path that renders dirty rows directly into the window's content buffer, bypassing the widget pipeline. Returns the dirty region via outY/outH.
-
Properties (BASIC Interface)
-
Property Type Access Description
- -------- ---- ------ -----------
- Cols Integer Read-only Number of columns.
- Rows Integer Read-only Number of rows.
- Scrollback Integer Write-only Maximum scrollback lines.
-
Methods (BASIC Interface)
-
Method Description
- ------ -----------
- Clear Clear the terminal screen.
- Write Write a string into the terminal.
-
Events
-
AnsiTerm uses the common events only. No widget-specific events are defined.
-
-
Canvas
-
Canvas
-
A freeform drawing surface with a fixed-size pixel buffer. Provides drawing primitives (lines, rectangles, circles, text, individual pixels) and supports save/load to BMP files. Mouse interaction is available via a callback.
-
Header: widgets/widgetCanvas.h
-
Creation
-
WidgetT *cv = wgtCanvas(parent, 320, 200);
-
Macros
-
Macro Description
- ----- -----------
- wgtCanvas(parent, w, h) Create a canvas with the given pixel dimensions.
- wgtCanvasClear(w, color) Fill the entire canvas with a solid color.
- wgtCanvasSetPenColor(w, color) Set the drawing pen color.
- wgtCanvasSetPenSize(w, size) Set the drawing pen size in pixels.
- wgtCanvasDrawLine(w, x0, y0, x1, y1) Draw a line from (x0,y0) to (x1,y1).
- wgtCanvasDrawRect(w, x, y, width, height) Draw a rectangle outline.
- wgtCanvasFillRect(w, x, y, width, height) Draw a filled rectangle.
- wgtCanvasFillCircle(w, cx, cy, radius) Draw a filled circle.
- wgtCanvasSetPixel(w, x, y, color) Set a single pixel to the given color.
- wgtCanvasGetPixel(w, x, y) Get the color of a single pixel.
- wgtCanvasDrawText(w, x, y, text) Draw text at the given position using the current pen color.
- wgtCanvasSetMouseCallback(w, cb) Set a mouse interaction callback. Signature: void (*cb)(WidgetT *w, int32_t cx, int32_t cy, bool drag). Receives canvas-relative coordinates and whether the mouse is being dragged.
- wgtCanvasSave(w, path) Save the canvas contents to a BMP file.
- wgtCanvasLoad(w, path) Load a BMP file into the canvas.
-
Events
-
Callback Description
- -------- -----------
- onClick Fires when the canvas is clicked.
- Mouse callback (via wgtCanvasSetMouseCallback) Fires on mouse down and drag with canvas-local coordinates.
-
Methods (BASIC Interface)
-
Method Description
- ------ -----------
- Clear Clear the canvas to a given color.
-
-
ListView
-
ListView
-
A multi-column list with sortable headers. Supports single and multi-selection, column alignment, header click sorting, and drag-to-reorder. Data is provided as a flat array of strings (row-major order, one string per cell).
-
Header: widgets/widgetListView.h
-
Creation
-
WidgetT *lv = wgtListView(parent);
-ListViewColT cols[] = {
- { "Name", wgtChars(20), ListViewAlignLeftE },
- { "Size", wgtChars(10), ListViewAlignRightE }
-};
-wgtListViewSetColumns(lv, cols, 2);
-const char *cells[] = { "file.txt", "1234", "readme.md", "5678" };
-wgtListViewSetData(lv, cells, 2);
-
Column Definition
-
typedef struct {
- const char *title;
- int32_t width; // tagged size (wgtPixels/wgtChars/wgtPercent, 0 = auto)
- ListViewAlignE align; // ListViewAlignLeftE, ListViewAlignCenterE, ListViewAlignRightE
-} ListViewColT;
-
Sort Direction
-
typedef enum {
- ListViewSortNoneE,
- ListViewSortAscE,
- ListViewSortDescE
-} ListViewSortE;
-
Macros
-
Macro Description
- ----- -----------
- wgtListView(parent) Create a list view.
- wgtListViewSetColumns(w, cols, count) Define columns from an array of ListViewColT.
- wgtListViewSetData(w, cellData, rowCount) Set row data. cellData is a flat const char ** array of size rowCount * colCount.
- wgtListViewGetSelected(w) Get the index of the selected row (-1 if none).
- wgtListViewSetSelected(w, idx) Set the selected row by index.
- wgtListViewSetSort(w, col, dir) Set the sort column and direction.
- wgtListViewSetHeaderClickCallback(w, cb) Set a callback for header clicks. Signature: void (*cb)(WidgetT *w, int32_t col, ListViewSortE dir).
- wgtListViewSetMultiSelect(w, multi) Enable or disable multi-selection.
- wgtListViewIsItemSelected(w, idx) Check if a specific row is selected.
- wgtListViewSetItemSelected(w, idx, selected) Select or deselect a specific row.
- wgtListViewSelectAll(w) Select all rows.
- wgtListViewClearSelection(w) Deselect all rows.
- wgtListViewSetReorderable(w, reorderable) Enable drag-to-reorder of rows.
-
Events
-
Callback Description
- -------- -----------
- onClick Fires when a row is clicked.
- onDblClick Fires when a row is double-clicked.
- onChange Fires when the selection changes.
-
Properties (BASIC Interface)
-
Property Type Access Description
- -------- ---- ------ -----------
- ListIndex Integer Read/Write Index of the currently selected row.
-
Methods (BASIC Interface)
-
Method Description
- ------ -----------
- SelectAll Select all rows.
- ClearSelection Deselect all rows.
- SetMultiSelect Enable or disable multi-selection.
- SetReorderable Enable or disable drag-to-reorder.
- IsItemSelected Check if a specific row is selected by index.
- SetItemSelected Select or deselect a specific row by index.
-
-
-
TextInput / TextArea
-
TextInput / TextArea
-
Single-line text input, password input, masked input, and multi-line text area with optional syntax colorization, line numbers, find/replace, and gutter decorators.
-
Header: widgets/widgetTextInput.h
-
Creation
-
Macro Description
- ----- -----------
- wgtTextInput(parent, maxLen) Create a single-line text input. maxLen is the maximum number of characters.
- wgtPasswordInput(parent, maxLen) Create a password input (characters displayed as bullets).
- wgtMaskedInput(parent, mask) Create a masked input field. The mask string defines the input format.
- wgtTextArea(parent, maxLen) Create a multi-line text area.
-
Methods (TextArea-specific)
-
Macro Description
- ----- -----------
- wgtTextAreaSetColorize(w, fn, ctx) Set a syntax colorization callback. The callback receives each line and fills a color index array. Color indices: 0=default, 1=keyword, 2=string, 3=comment, 4=number, 5=operator, 6=type/builtin, 7=reserved.
- wgtTextAreaGoToLine(w, line) Scroll to and place the cursor on the given line number.
- wgtTextAreaSetAutoIndent(w, enable) Enable or disable automatic indentation on newline.
- wgtTextAreaSetShowLineNumbers(w, show) Show or hide line numbers in the gutter.
- wgtTextAreaSetCaptureTabs(w, capture) When true, Tab key inserts a tab/spaces instead of moving focus.
- wgtTextAreaSetTabWidth(w, width) Set the tab stop width in characters.
- wgtTextAreaSetUseTabChar(w, useChar) When true, insert literal tab characters; when false, insert spaces.
- wgtTextAreaFindNext(w, needle, caseSens, fwd) Search for the next occurrence. Returns true if found.
- wgtTextAreaReplaceAll(w, needle, repl, caseSens) Replace all occurrences. Returns the number of replacements made.
- wgtTextAreaSetLineDecorator(w, fn, ctx) Set a gutter line decorator callback. The callback returns a color and receives the line number, a color output pointer, and the user context.
- wgtTextAreaGetCursorLine(w) Get the current cursor line number.
- wgtTextAreaSetGutterClick(w, fn) Set a callback for gutter clicks (e.g. for breakpoint toggling). Callback receives the widget and line number.
-
Events
-
Callback Description
- -------- -----------
- onChange Fires when the text content changes.
- onKeyPress Fires on each key press (ASCII value).
- onValidate Called before committing a change. Return false to cancel.
-
-
-
Base WidgetT (Common Properties, Events, and Operations)
-
DVX Widget Reference
-
Complete reference for the DVX GUI widget toolkit. All widgets are implemented as dynamically loaded DXE modules. They are created via convenience macros that wrap the per-widget API function tables. The base WidgetT structure is defined in core/dvxWidget.h; individual widget headers live in widgets/.
-
Base WidgetT (Common Properties, Events, and Operations)
-
Every widget inherits from the WidgetT structure defined in core/dvxWidget.h. The fields and callbacks listed here are available on all widget types.
-
Common Properties
-
Field Type Description
- ----- ---- -----------
- name char[32] Widget name for lookup via wgtFind().
- x, y, w, h int32_t Computed geometry relative to the window content area (set by layout).
- minW, minH int32_t (tagged) Minimum size hints. Use wgtPixels(), wgtChars(), or wgtPercent(). 0 = auto.
- maxW, maxH int32_t (tagged) Maximum size constraints. 0 = no limit.
- prefW, prefH int32_t (tagged) Preferred size. 0 = auto.
- weight int32_t Extra-space distribution weight. 0 = fixed, 100 = normal. A widget with weight=200 gets twice the extra space of one with weight=100.
- align WidgetAlignE Main-axis alignment for children: AlignStartE, AlignCenterE, AlignEndE.
- spacing int32_t (tagged) Spacing between children (containers only). 0 = default.
- padding int32_t (tagged) Internal padding (containers only). 0 = default.
- fgColor uint32_t Foreground color override. 0 = use color scheme default.
- bgColor uint32_t Background color override. 0 = use color scheme default.
- visible bool Visibility state.
- enabled bool Enabled state. Disabled widgets are grayed out and ignore input.
- readOnly bool Read-only mode: allows scrolling/selection but blocks editing.
- swallowTab bool When true, Tab key goes to the widget instead of navigating focus.
- accelKey char Lowercase accelerator character. 0 if none.
- tooltip const char * Tooltip text. NULL = none. Caller owns the string.
- contextMenu MenuT * Right-click context menu. NULL = none. Caller owns.
- userData void * Application-defined user data pointer.
-
Size Specification Macros
-
Macro Description
- ----- -----------
- wgtPixels(v) Size in pixels.
- wgtChars(v) Size in character widths (multiplied by font charWidth).
- wgtPercent(v) Size as a percentage of parent dimension.
-
Common Events (Callbacks)
-
These callback function pointers are available on every WidgetT. Set them directly on the widget struct.
-
Callback Signature Description
- -------- --------- -----------
- onClick void (*)(WidgetT *w) Fires on mouse click / activation.
- onDblClick void (*)(WidgetT *w) Fires on double-click.
- onChange void (*)(WidgetT *w) Fires when the widget's value changes (text, selection, check state, etc.).
- onFocus void (*)(WidgetT *w) Fires when the widget receives keyboard focus.
- onBlur void (*)(WidgetT *w) Fires when the widget loses keyboard focus.
- onKeyPress void (*)(WidgetT *w, int32_t keyAscii) Fires on a printable key press (ASCII value).
- onKeyDown void (*)(WidgetT *w, int32_t keyCode, int32_t shift) Fires on key down (scan code + shift state).
- onKeyUp void (*)(WidgetT *w, int32_t keyCode, int32_t shift) Fires on key up.
- onMouseDown void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) Fires on mouse button press.
- onMouseUp void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) Fires on mouse button release.
- onMouseMove void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) Fires on mouse movement over the widget.
- onScroll void (*)(WidgetT *w, int32_t delta) Fires on mouse wheel scroll.
- onValidate bool (*)(WidgetT *w) Validation callback. Return false to cancel a pending write.
-
Common Operations
-
Function Description
- -------- -----------
- WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win) Initialize widgets for a window. Returns the root VBox container.
- AppContextT *wgtGetContext(const WidgetT *w) Walk up from any widget to retrieve the AppContextT.
- void wgtInvalidate(WidgetT *w) Mark widget for re-layout and repaint. Propagates to ancestors.
- void wgtInvalidatePaint(WidgetT *w) Mark widget for repaint only (no layout recalculation).
- void wgtSetText(WidgetT *w, const char *text) Set widget text (label, button, textinput, etc.).
- const char *wgtGetText(const WidgetT *w) Get widget text.
- void wgtSetEnabled(WidgetT *w, bool enabled) Enable or disable a widget.
- void wgtSetReadOnly(WidgetT *w, bool readOnly) Set read-only mode.
- void wgtSetFocused(WidgetT *w) Set keyboard focus to a widget.
- WidgetT *wgtGetFocused(void) Get the currently focused widget.
- void wgtSetVisible(WidgetT *w, bool visible) Show or hide a widget.
- void wgtSetName(WidgetT *w, const char *name) Set widget name for lookup.
- WidgetT *wgtFind(WidgetT *root, const char *name) Find a widget by name in the subtree.
- void wgtDestroy(WidgetT *w) Destroy a widget and all its children.
- void wgtSetTooltip(WidgetT *w, const char *text) Set tooltip text. Pass NULL to remove.
-
-
-
AnsiTerm
-
AnsiTerm
-
A VT100/ANSI-compatible terminal emulator widget designed for connecting to BBS systems over the serial link. Uses a traditional text-mode cell buffer (character + attribute byte pairs) with the CP437 character set and 16-color CGA palette. Supports cursor movement, screen/line erase, scrolling regions, SGR colors, and scrollback history. Communication is abstracted through read/write function pointers, allowing the terminal to work with raw serial ports, the secLink encrypted channel, or any other byte-oriented transport.
-
Header: widgets/widgetAnsiTerm.h
-
Creation
-
WidgetT *term = wgtAnsiTerm(parent, 80, 25);
-
Macros
-
Macro Description
- ----- -----------
- wgtAnsiTerm(parent, cols, rows) Create an ANSI terminal widget with the given column and row dimensions.
- wgtAnsiTermWrite(w, data, len) Write raw bytes into the terminal's ANSI parser. data is a const uint8_t * buffer, len is the byte count.
- wgtAnsiTermClear(w) Clear the terminal screen and reset the cursor to the home position.
- wgtAnsiTermSetComm(w, ctx, readFn, writeFn) Attach a communication channel. readFn and writeFn are I/O callbacks; ctx is passed as their first argument.
- wgtAnsiTermSetScrollback(w, maxLines) Set the maximum number of scrollback lines. Lines scrolled off the top are saved in a circular buffer.
- wgtAnsiTermPoll(w) Poll the communication channel for incoming data and feed it into the ANSI parser.
- wgtAnsiTermRepaint(w, outY, outH) Fast repaint path that renders dirty rows directly into the window's content buffer, bypassing the widget pipeline. Returns the dirty region via outY/outH.
-
Properties (BASIC Interface)
-
Property Type Access Description
- -------- ---- ------ -----------
- Cols Integer Read-only Number of columns.
- Rows Integer Read-only Number of rows.
- Scrollback Integer Write-only Maximum scrollback lines.
-
Methods (BASIC Interface)
-
Method Description
- ------ -----------
- Clear Clear the terminal screen.
- Write Write a string into the terminal.
-
Events
-
AnsiTerm uses the common events only. No widget-specific events are defined.
-
-
-
TextInput / TextArea
-
TextInput / TextArea
-
Single-line text input, password input, masked input, and multi-line text area with optional syntax colorization, line numbers, find/replace, and gutter decorators.
-
Header: widgets/widgetTextInput.h
-
Creation
-
Macro Description
- ----- -----------
- wgtTextInput(parent, maxLen) Create a single-line text input. maxLen is the maximum number of characters.
- wgtPasswordInput(parent, maxLen) Create a password input (characters displayed as bullets).
- wgtMaskedInput(parent, mask) Create a masked input field. The mask string defines the input format.
- wgtTextArea(parent, maxLen) Create a multi-line text area.
-
Methods (TextArea-specific)
-
Macro Description
- ----- -----------
- wgtTextAreaSetColorize(w, fn, ctx) Set a syntax colorization callback. The callback receives each line and fills a color index array. Color indices: 0=default, 1=keyword, 2=string, 3=comment, 4=number, 5=operator, 6=type/builtin, 7=reserved.
- wgtTextAreaGoToLine(w, line) Scroll to and place the cursor on the given line number.
- wgtTextAreaSetAutoIndent(w, enable) Enable or disable automatic indentation on newline.
- wgtTextAreaSetShowLineNumbers(w, show) Show or hide line numbers in the gutter.
- wgtTextAreaSetCaptureTabs(w, capture) When true, Tab key inserts a tab/spaces instead of moving focus.
- wgtTextAreaSetTabWidth(w, width) Set the tab stop width in characters.
- wgtTextAreaSetUseTabChar(w, useChar) When true, insert literal tab characters; when false, insert spaces.
- wgtTextAreaFindNext(w, needle, caseSens, fwd) Search for the next occurrence. Returns true if found.
- wgtTextAreaReplaceAll(w, needle, repl, caseSens) Replace all occurrences. Returns the number of replacements made.
- wgtTextAreaSetLineDecorator(w, fn, ctx) Set a gutter line decorator callback. The callback returns a color and receives the line number, a color output pointer, and the user context.
- wgtTextAreaGetCursorLine(w) Get the current cursor line number.
- wgtTextAreaSetGutterClick(w, fn) Set a callback for gutter clicks (e.g. for breakpoint toggling). Callback receives the widget and line number.
-
Events
-
Callback Description
- -------- -----------
- onChange Fires when the text content changes.
- onKeyPress Fires on each key press (ASCII value).
- onValidate Called before committing a change. Return false to cancel.
-
-
-
ListView
-
ListView
-
A multi-column list with sortable headers. Supports single and multi-selection, column alignment, header click sorting, and drag-to-reorder. Data is provided as a flat array of strings (row-major order, one string per cell).
-
Header: widgets/widgetListView.h
-
Creation
-
WidgetT *lv = wgtListView(parent);
-ListViewColT cols[] = {
- { "Name", wgtChars(20), ListViewAlignLeftE },
- { "Size", wgtChars(10), ListViewAlignRightE }
-};
-wgtListViewSetColumns(lv, cols, 2);
-const char *cells[] = { "file.txt", "1234", "readme.md", "5678" };
-wgtListViewSetData(lv, cells, 2);
-
Column Definition
-
typedef struct {
- const char *title;
- int32_t width; // tagged size (wgtPixels/wgtChars/wgtPercent, 0 = auto)
- ListViewAlignE align; // ListViewAlignLeftE, ListViewAlignCenterE, ListViewAlignRightE
-} ListViewColT;
-
Sort Direction
-
typedef enum {
- ListViewSortNoneE,
- ListViewSortAscE,
- ListViewSortDescE
-} ListViewSortE;
-
Macros
-
Macro Description
- ----- -----------
- wgtListView(parent) Create a list view.
- wgtListViewSetColumns(w, cols, count) Define columns from an array of ListViewColT.
- wgtListViewSetData(w, cellData, rowCount) Set row data. cellData is a flat const char ** array of size rowCount * colCount.
- wgtListViewGetSelected(w) Get the index of the selected row (-1 if none).
- wgtListViewSetSelected(w, idx) Set the selected row by index.
- wgtListViewSetSort(w, col, dir) Set the sort column and direction.
- wgtListViewSetHeaderClickCallback(w, cb) Set a callback for header clicks. Signature: void (*cb)(WidgetT *w, int32_t col, ListViewSortE dir).
- wgtListViewSetMultiSelect(w, multi) Enable or disable multi-selection.
- wgtListViewIsItemSelected(w, idx) Check if a specific row is selected.
- wgtListViewSetItemSelected(w, idx, selected) Select or deselect a specific row.
- wgtListViewSelectAll(w) Select all rows.
- wgtListViewClearSelection(w) Deselect all rows.
- wgtListViewSetReorderable(w, reorderable) Enable drag-to-reorder of rows.
-
Events
-
Callback Description
- -------- -----------
- onClick Fires when a row is clicked.
- onDblClick Fires when a row is double-clicked.
- onChange Fires when the selection changes.
-
Properties (BASIC Interface)
-
Property Type Access Description
- -------- ---- ------ -----------
- ListIndex Integer Read/Write Index of the currently selected row.
-
Methods (BASIC Interface)
-
Method Description
- ------ -----------
- SelectAll Select all rows.
- ClearSelection Deselect all rows.
- SetMultiSelect Enable or disable multi-selection.
- SetReorderable Enable or disable drag-to-reorder.
- IsItemSelected Check if a specific row is selected by index.
- SetItemSelected Select or deselect a specific row by index.
-
-
-
Canvas
-
Canvas
-
A freeform drawing surface with a fixed-size pixel buffer. Provides drawing primitives (lines, rectangles, circles, text, individual pixels) and supports save/load to BMP files. Mouse interaction is available via a callback.
-
Header: widgets/widgetCanvas.h
-
Creation
-
WidgetT *cv = wgtCanvas(parent, 320, 200);
-
Macros
-
Macro Description
- ----- -----------
- wgtCanvas(parent, w, h) Create a canvas with the given pixel dimensions.
- wgtCanvasClear(w, color) Fill the entire canvas with a solid color.
- wgtCanvasSetPenColor(w, color) Set the drawing pen color.
- wgtCanvasSetPenSize(w, size) Set the drawing pen size in pixels.
- wgtCanvasDrawLine(w, x0, y0, x1, y1) Draw a line from (x0,y0) to (x1,y1).
- wgtCanvasDrawRect(w, x, y, width, height) Draw a rectangle outline.
- wgtCanvasFillRect(w, x, y, width, height) Draw a filled rectangle.
- wgtCanvasFillCircle(w, cx, cy, radius) Draw a filled circle.
- wgtCanvasSetPixel(w, x, y, color) Set a single pixel to the given color.
- wgtCanvasGetPixel(w, x, y) Get the color of a single pixel.
- wgtCanvasDrawText(w, x, y, text) Draw text at the given position using the current pen color.
- wgtCanvasSetMouseCallback(w, cb) Set a mouse interaction callback. Signature: void (*cb)(WidgetT *w, int32_t cx, int32_t cy, bool drag). Receives canvas-relative coordinates and whether the mouse is being dragged.
- wgtCanvasSave(w, path) Save the canvas contents to a BMP file.
- wgtCanvasLoad(w, path) Load a BMP file into the canvas.
-
Events
-
Callback Description
- -------- -----------
- onClick Fires when the canvas is clicked.
- Mouse callback (via wgtCanvasSetMouseCallback) Fires on mouse down and drag with canvas-local coordinates.
-
Methods (BASIC Interface)
-
Method Description
- ------ -----------
- Clear Clear the canvas to a given color.
-
-
-
DVX BASIC IDE Guide
-
DVX BASIC IDE Guide
-
DVX BASIC is a Visual BASIC development environment for the DVX GUI System. It provides a VB3-style integrated development environment with a code editor, form designer, project system, and a full interactive debugger -- all running natively on DOS under the DVX windowing system.
-
This guide covers every feature of the IDE: menus, toolbar, editor, form designer, project management, debugger, and auxiliary windows.
-
IDE Windows
-
The DVX BASIC IDE is modeled after Visual Basic 3.0. It consists of several floating windows arranged on the DVX desktop:
-
-- Main Toolbar Window -- anchored at the top of the screen. Contains the menu bar, toolbar buttons, and status bar.
-- Code Editor -- the primary editing surface for BASIC source code, with Object/Event dropdowns, syntax highlighting, and line numbers.
-- Form Designer -- a visual design surface for .frm files, showing a WYSIWYG preview of the form with grab handles for resizing controls.
-- Project Explorer -- a tree view listing all files in the project.
-- Toolbox -- a palette of available controls for placing on forms.
-- Properties Panel -- a tree of controls and a list of editable properties for the selected control.
-- Output Window -- displays PRINT output and runtime errors.
-- Immediate Window -- an interactive REPL for evaluating expressions and modifying variables at runtime.
-
-
Debug Windows -- Locals, Call Stack, Watch, and Breakpoints windows that appear automatically when debugging.
-
The IDE compiles BASIC source into bytecode and runs it in an integrated virtual machine (VM). Programs execute in cooperative slices (10,000 VM steps per slice), yielding to the DVX event loop between slices so the GUI remains responsive.
-
File Menu
-
Edit Menu
-
Run Menu
-
View Menu
-
Window Menu
-
Tools Menu
-
Help Menu
-
Toolbar
-
Code Editor
-
Form Designer
-
Project System
-
Properties Panel
-
Toolbox
-
Debugger
-
Locals Window
-
Call Stack Window
-
Watch Window
-
Breakpoints Window
-
Immediate Window
-
Output Window
-
Find / Replace
-
Preferences
-
Keyboard Shortcuts
-
-
Code Editor
-
Code Editor
-
The Code Editor is the primary editing window for BASIC source code. It occupies the center of the screen, below the toolbar and above the Output and Immediate windows.
-
Object and Function Dropdowns
-
At the top of the Code Editor are two dropdown lists:
-
-- Object -- lists (General) plus all objects (form name, control names, menu item names). Selecting an object filters the Function dropdown.
-
-
Function -- lists all event handlers (procedures) for the selected object. Implemented handlers are listed first (plain text); unimplemented handlers follow in brackets (e.g., [Click]). Selecting an unimplemented event creates a new event handler stub.
-
The editor shows one procedure at a time. Each procedure has its own buffer, and switching between them is instantaneous. The (General) section contains module-level declarations and code.
-
Syntax Highlighting
-
The editor applies real-time syntax coloring as you type. The following categories are highlighted in distinct colors:
-
Category Examples
- -------- --------
- Keywords IF, THEN, FOR, NEXT, SUB, FUNCTION, DIM, PRINT, SELECT, CASE, DO, LOOP, WHILE, WEND, END, EXIT, CALL, GOSUB, GOTO, RETURN, DECLARE, CONST, TYPE, AND, OR, NOT, XOR, MOD, etc.
- Type names INTEGER, LONG, SINGLE, DOUBLE, STRING, BOOLEAN, BYTE, TRUE, FALSE
- String literals "Hello, World!"
- Comments ' This is a comment, REM This is a comment
- Numbers 42, 3.14
- Operators =, <, >, +, -, *, /, \, &
-
Editor Features
-
-- Line numbers -- displayed in the gutter on the left side.
-- Auto-indent -- new lines are automatically indented to match the previous line.
-- Tab handling -- the Tab key is captured by the editor. Tab width and whether to insert spaces or tab characters are configurable in Preferences (default: 3 spaces).
-- Gutter click -- clicking in the line number gutter toggles a breakpoint on that line.
-
-
Line decorations -- breakpoint lines show a red dot in the gutter. The current debug line (when paused) is highlighted with a yellow background.
-
Back to Overview
-
-
Form Designer
-
Form Designer
-
The Form Designer provides a visual design surface for editing .frm files. Switch to it with Shift+F7 or the Design toolbar button. It opens in a separate window showing a WYSIWYG preview of the form.
-
Design Surface
-
-- Grid snapping -- controls snap to an 8-pixel grid (DSGN_GRID_SIZE) when placed or resized.
-- Selection -- click a control to select it. The selected control is highlighted with grab handles.
-- Grab handles -- 6x6 pixel handles appear on the right edge (E), bottom edge (S), and bottom-right corner (SE) of the selected control. Drag a handle to resize the control.
-- Reordering -- drag a control vertically to reorder it within the form's layout (VBox/HBox).
-- Placing controls -- select a control type in the Toolbox, then click on the form to place a new instance. The control is auto-named (e.g., Command1, Command2). Clicking the same tool again deselects it (toggles back to pointer mode).
-- Menu bar preview -- if the form has menu items (defined via the Menu Editor), a preview menu bar is rendered on the design window.
-
-
Delete key -- removes the selected control from the form.
-
Form Properties
-
Forms have the following design-time properties: Name, Caption, Width, Height, Left, Top, Layout (VBox or HBox), Centered, AutoSize, and Resizable.
-
Properties Panel
-
Toolbox
-
Back to Overview
-
-
Project System
-
Project System
-
Project Files (.dbp)
-
A DVX BASIC project is stored as a .dbp file (DVX BASIC Project). The project file records:
-
-- Name -- the project display name (up to 32 characters).
-- Startup Form -- which form to show automatically when the program starts.
-- Metadata -- Author, Company, Version, Copyright, Description, and Icon Path (for compiled binaries).
-
-
File list -- relative paths (8.3 DOS names) of all .bas and .frm files in the project. Each entry tracks whether it is a form file.
-
Source Map
-
When the project is compiled, all files are concatenated into a single source stream. A source map tracks which lines belong to which file, enabling accurate error reporting and debugger navigation across multiple files. For .frm files, an injected BEGINFORM directive is prepended to the code section.
-
Project Operations
-
Operation Description
- --------- -----------
- New Project Creates a blank project with a name and directory. A default .frm file is added automatically.
- Open Project Opens a .dbp file and loads all referenced files into memory.
- Save Project Writes the .dbp file to disk.
- Close Project Closes the project, prompting to save unsaved changes.
- Add File Adds a .bas or .frm file to the project. Opening a file without a project auto-creates an implicit project.
- Remove File Removes a file from the project (prompts to save if modified).
- Project Properties Opens a dialog for editing project metadata (name, author, company, version, copyright, description, icon, startup form).
-
Project Explorer
-
The Project Explorer is a tree view window listing all project files. Double-click a file to open it: .bas files open in Code view, .frm files open in Design view. The selected file in the Project Explorer determines the target for View > Code and View > Designer commands.
-
Back to Overview
-
-
Properties Panel
-
Properties Panel
-
The Properties panel (Window > Properties) has two sections:
-
-- Control tree -- a TreeView at the top listing the form and all its controls in layout order. Click a control name to select it in both the Properties panel and the Form Designer. Drag items in the tree to reorder controls in the form's layout.
-
-
Property list -- a two-column ListView below the tree showing property names and values for the selected control. Double-click a property value to edit it via an InputBox dialog. Changes take effect immediately in the designer preview.
-
Each control type exposes different properties (e.g., Caption, Text, Width, Height, MaxWidth, MaxHeight, Weight, Alignment, Enabled, Visible, and type-specific properties like DataSource and DataField for data-bound controls).
-
Form Designer
-
Back to Overview
-
-
Debugger
-
Debugger
-
The DVX BASIC IDE includes a full interactive debugger. The debugger operates as a state machine with three states:
-
State Description
- ----- -----------
- DBG_IDLE No program loaded or running.
- DBG_RUNNING Program is executing (VM running in slices).
- DBG_PAUSED Execution is paused at a breakpoint or step point. The IDE GUI is fully interactive.
-
Starting a Debug Session
-
-- Shift+F5 (Debug) -- compiles the project and starts execution in debug mode. Breakpoints are active but execution does not pause at the first statement.
-- F8 (Step Into) -- if idle, starts a debug session and breaks at the first statement.
-
-
F5 (Run) -- compiles and runs without the debugger. No breakpoints are active. If already paused, resumes execution with debugging disabled.
-
Breakpoints
-
Setting Breakpoints
-
-- Press F9 to toggle a breakpoint on the current editor line.
-
-
Click in the line number gutter to toggle a breakpoint on that line.
-
Breakpoint Validation
-
Not every line can have a breakpoint. The IDE validates the line content and silently refuses to set breakpoints on:
-
-- Blank lines
-- Comment lines (' or REM)
-- SUB and FUNCTION declaration lines
-
-
END SUB and END FUNCTION lines
-
Breakpoint Storage
-
Each breakpoint records the project file index, the code line number within the file, the procedure index, and the procedure name (as Object.Event). When the project is compiled, breakpoints are converted to concatenated source line numbers that match the VM's OP_LINE opcodes.
-
Visual Indicators
-
-- Breakpoint lines show a red dot in the gutter.
-
-
The current debug line (when paused) has a yellow background.
-
Breakpoint Adjustment on Edit
-
When lines are added or removed in the editor, breakpoints below the edit point are automatically shifted to stay on the correct line.
-
Stepping
-
Action Shortcut Behavior
- ------ -------- --------
- Step Into F8 Execute one statement. If the statement is a SUB/FUNCTION call, step into it.
- Step Over Shift+F8 Execute one statement. If the statement is a SUB/FUNCTION call, execute the entire call and break at the next line in the current scope.
- Step Out Ctrl+Shift+F8 Run until the current SUB/FUNCTION returns to its caller.
- Run to Cursor Ctrl+F8 Run until execution reaches the line under the cursor.
-
The Debug Run Loop
-
When a program is running in debug mode, the IDE enters a cooperative loop:
-
-- The VM executes up to 10,000 steps per slice.
-- If the VM hits a breakpoint (BAS_VM_BREAKPOINT), the state transitions to DBG_PAUSED. The IDE navigates the code editor to the breakpoint line, highlights it in yellow, auto-opens the Locals and Call Stack windows, and updates all debug windows.
-- While paused, the IDE pumps dvxUpdate() continuously, keeping the GUI responsive. The user can inspect variables, modify them in the Immediate window, step, continue, or stop.
-
-
When the user resumes (F5/Shift+F5/F8/etc.), the state transitions back to DBG_RUNNING and the loop continues.
-
Stopping
-
Press Esc or click the Stop toolbar button at any time to halt execution. The VM is destroyed, debug state resets to DBG_IDLE, and the IDE restores the designer windows that were hidden at run start.
-
Locals Window
-
Call Stack Window
-
Watch Window
-
Breakpoints Window
-
Back to Overview
-
-
Locals Window
-
Locals Window
-
When the debugger pauses, the Locals and Call Stack windows are auto-opened (if not already visible). The Watch and Breakpoints windows can be opened manually from the Window menu.
-
Shows variables for the current execution scope. Displayed as a three-column ListView:
-
Column Content
- ------ -------
- Name Variable name (internal mangled names like static variable placeholders are filtered out).
- Type Data type: Integer, Long, Single, Double, String, Boolean, Array, UDT. Array types show the element type (e.g., Integer()).
- Value Current value. Strings are shown in quotes. Booleans as True/False. Arrays show bounds and element count (e.g., Integer(0 To 9) [10]). Uninitialized arrays show (uninitialized).
-
The Locals window displays:
-
-- Local variables for the current procedure (matched by proc index).
-- Global (module-level) variables.
-
-
Form-scoped variables for the current form (if the program is executing within a form context).
-
Up to 64 variables are displayed. The window is resizable.
-
Call Stack Window
-
Back to Overview
-
-
Call Stack Window
-
Call Stack Window
-
Shows the current call chain as a two-column ListView:
-
Column Content
- ------ -------
- Procedure Procedure name (or (module) for module-level code).
- Line Line number where execution is paused (shown for the topmost frame).
-
The current location is shown first, followed by each caller in the call stack (walking from the deepest frame back to the module entry point). Up to 32 frames are displayed.
-
Watch Window
-
Back to Overview
-
-
Watch Window
-
Watch Window
-
Allows monitoring arbitrary expressions while debugging. The window has a text input at the top and a two-column ListView below:
-
Column Content
- ------ -------
- Expression The watch expression text.
- Value Evaluated result (or <error> if evaluation fails). Blank when not paused.
-
Adding Watch Expressions
-
Type an expression in the text input and press Enter. Up to 16 watch expressions can be active at once.
-
Watch Expression Syntax
-
Watch expressions support:
-
-- Simple variable names: x, count
-- Array subscripts: arr(5), matrix(2, 3)
-- UDT field access: player.name
-- Combined: items(i).price
-
-
Arbitrary BASIC expressions (compiled and evaluated against the paused VM's state): x + y * 2, Len(name$)
-
Editing and Deleting
-
-- Double-click or press Enter on a watch entry to move it back into the input box for editing.
-
-
Press Delete to remove the selected watch expression.
-
Breakpoints Window
-
Back to Overview
-
-
Breakpoints Window
-
Breakpoints Window
-
Lists all set breakpoints as a three-column ListView:
-
Column Content
- ------ -------
- File Project file path.
- Procedure Procedure name (Object.Event format, or (General)).
- Line Code line number within the file.
-
-- Double-click a breakpoint to navigate the code editor to that location.
-
-
Press Delete to remove selected breakpoints (multi-select is supported).
-
Debugger
-
Back to Overview
-
-
Immediate Window
-
Immediate Window
-
The Immediate window is an interactive REPL at the bottom-right of the screen. Type a line of BASIC and press Enter to evaluate it. Results appear inline below your input.
-
Expression Evaluation
-
If the input is not a recognized statement keyword, it is automatically wrapped in a PRINT statement. For example, typing 2 + 2 evaluates as PRINT 2 + 2 and displays 4.
-
You can also type full statements:
-
-- PRINT x * 2 -- evaluate and print an expression.
-- DIM tmp As Integer -- declare a temporary variable.
-
-
LET x = 42 -- explicit assignment (see below).
-
Parse or runtime errors are displayed inline with an Error: prefix.
-
Inspecting Variables While Paused
-
When the debugger is paused at a breakpoint, the Immediate window has access to the running VM's state. Global variable values are copied into the evaluation VM, so expressions like count or name$ & " test" display live values.
-
Assigning Variables While Paused
-
When paused, you can modify variables in the running program directly from the Immediate window using assignment syntax:
-
variableName = newValue
-
The optional LET keyword is also accepted:
-
LET variableName = newValue
-
Assignment works for:
-
-- Scalar variables -- x = 42, name$ = "test"
-- Array elements -- arr(5) = 100, matrix(2, 3) = 7.5
-- UDT fields -- player.score = 1000
-
-
Combined -- items(0).price = 9.99
-
The new value is written directly into the VM's live variable slot (local, global, or form scope). A confirmation message is displayed, and the Locals and Watch windows update automatically to reflect the change.
-
If the assignment target cannot be resolved (unknown variable, out-of-bounds index, wrong type), an error message is displayed.
-
Back to Overview
-
-
Output Window
-
Output Window
-
The Output window is a read-only TextArea at the bottom-left of the screen. It displays:
-
-- PRINT output -- all PRINT statement output from the running program is appended here.
-- Runtime errors -- if the VM encounters a runtime error (division by zero, out-of-bounds, etc.), the error message and line number are displayed in the output with an Error on line N: prefix.
-
-
Compile errors -- if compilation fails, the error message and location are shown.
-
The output buffer holds up to 32,768 characters. Use Run > Clear Output to clear it.
-
INPUT statements prompt the user via a modal InputBox dialog; the prompt text is also echoed to the Output window.
-
Back to Overview
-
-
Find / Replace
-
Find / Replace
-
Open with Ctrl+F (Find) or Ctrl+H (Replace). The Find/Replace dialog is modeless -- it stays open while you continue editing.
-
Dialog Controls
-
Control Description
- ------- -----------
- Find input The text to search for.
- Replace checkbox + input Enable replacement mode and enter replacement text.
- Scope Radio group: Function, Object, File, or Project. Default is Project.
- Direction Radio group: Forward or Backward.
- Match Case Checkbox: case-sensitive search.
-
Buttons
-
Button Action
- ------ ------
- Find Next Find the next occurrence. Wraps across procedures, files, and the entire project depending on the scope setting.
- Replace Replace the current match and find the next one.
- Replace All Replace all occurrences within the selected scope.
- Close Close the dialog.
-
Keyboard Shortcut
-
F3 repeats the last search (Find Next) without opening the dialog.
-
Back to Overview
-
-
Preferences
-
Preferences
-
Open via Tools > Preferences. Settings are saved to dvxbasic.ini in the app's config directory.
-
Editor Section
-
Setting Description Default
- ------- ----------- -------
- Skip comments/strings when renaming When renaming a control or form, skip occurrences inside comments and string literals. On
- Require variable declaration (OPTION EXPLICIT) When enabled, variables must be declared with DIM before use. Off
- Tab width Number of spaces per tab stop (1-8). 3
- Insert spaces instead of tabs When enabled, pressing Tab inserts spaces. When disabled, inserts a real tab character. On
-
New Project Defaults Section
-
These fields set the default values for new project metadata:
-
Field Description Default
- ----- ----------- -------
- Author Default author name. (empty)
- Company Default company name. (empty)
- Version Default version string. 1.0
- Copyright Default copyright notice. (empty)
- Description Default project description (multi-line). (empty)
-
Back to Overview
-
-
Keyboard Shortcuts
-
Keyboard Shortcuts
-
Shortcut Action
- -------- ------
- Ctrl+O Add File
- Ctrl+S Save File
- Ctrl+A Select All
- Ctrl+X Cut
- Ctrl+C Copy
- Ctrl+V Paste
- Ctrl+F Find
- Ctrl+H Replace
- Ctrl+E Menu Editor
- F3 Find Next
- F5 Run
- Shift+F5 Debug
- Ctrl+F5 Run Without Recompile
- Esc Stop
- F7 Code View
- Shift+F7 Design View
- F8 Step Into
- Shift+F8 Step Over
- Ctrl+Shift+F8 Step Out
- Ctrl+F8 Run to Cursor
- F9 Toggle Breakpoint
- Del Delete
-
-
DVX BASIC 1.0 -- Copyright 2026 Scott Duensing
-
-
Data Types
-
Data Types
-
DVX BASIC supports the following data types. Each type has a corresponding type suffix character that can be appended to variable names.
-
Primary Types
-
Type Size Suffix Range / Description
- ---- ---- ------ -------------------
- Integer 2 bytes % -32768 to 32767
- Long 4 bytes & -2147483648 to 2147483647
- Single 4 bytes ! 32-bit float, approximately 7 digits precision
- Double 8 bytes # 64-bit float, approximately 15 digits precision
- String variable $ Variable-length, reference-counted, dynamic string
- Boolean 2 bytes (none) True (-1) or False (0)
-
Internal Types
-
These types are not directly declarable but are used internally by the runtime.
-
Internal Type Description
- ------------- -----------
- Array Reference-counted multi-dimensional array (up to 8 dimensions)
- UDT User-defined type instance (created with TYPE...END TYPE)
- Object Opaque host object (form reference, control reference)
- Ref ByRef pointer to a variable slot (used for ByRef parameters)
-
Type Suffixes
-
Type suffixes can be appended to variable names to declare their type implicitly:
-
count% = 42 ' Integer
-total& = 100000 ' Long
-rate! = 3.14 ' Single
-pi# = 3.14159265 ' Double
-name$ = "Hello" ' String
-
Numeric Literals
-
Form Example Description
- ---- ------- -----------
- Decimal integer 42 Values -32768..32767 are Integer; larger are Long
- Hex integer &HFF Hexadecimal literal
- Long suffix 42&, &HFF& Force Long type
- Floating-point 3.14, 1.5E10 Double by default
- Single suffix 3.14! Force Single type
- Double suffix 3.14# Force Double type
-
Type Promotion
-
When mixing types in expressions, values are automatically promoted to a common type: Integer -> Long -> Single -> Double. Strings are not automatically converted to numbers (use VAL and STR$).
-
See also: Conversion Functions
-
-
Operators
-
Operators
-
Operators listed from highest precedence (evaluated first) to lowest precedence (evaluated last).
-
Precedence Operator Description
- ---------- -------- -----------
- 1 (highest) ^ Exponentiation
- 2 - (unary) Negation
- 3 * / \ MOD Multiply, float div, integer div, modulus
- 4 + - Addition, subtraction
- 5 & String concatenation
- 6 = <> < > <= >= Comparison (returns Boolean)
- 7 NOT Logical/bitwise NOT
- 8 AND Logical/bitwise AND
- 9 XOR Logical/bitwise XOR
- 10 OR Logical/bitwise OR
- 11 EQV Logical/bitwise equivalence
- 12 (lowest) IMP Logical/bitwise implication
-
String Concatenation
-
Use & to concatenate strings. The + operator also concatenates when both operands are strings.
-
result$ = "Hello" & " " & "World"
-result$ = firstName$ & " " & lastName$
-
-
Statements Overview
-
Statements
-
Multiple statements can appear on one line separated by :. Lines can be continued with _ at the end. Comments start with ' or REM.
-
Declaration Statements (DIM, REDIM, CONST, TYPE)
-
Conditional Statements (IF, SELECT CASE)
-
Loop Statements (FOR, DO, WHILE)
-
Procedures (SUB, FUNCTION, DEF FN)
-
Flow Control (EXIT, CALL, GOTO, GOSUB, ON)
-
Input/Output (PRINT, INPUT, DATA/READ)
-
Miscellaneous Statements
-
-
Declaration Statements
-
Declaration Statements
-
DIM
-
Declares variables and arrays with an explicit type.
-
DIM variable AS type
-DIM variable(upperBound) AS type
-DIM variable(lower TO upper) AS type
-DIM variable(dim1, dim2, ...) AS type
-DIM variable AS UdtName
-DIM variable AS STRING * n
-DIM SHARED variable AS type
-
Examples:
-
Dim name As String
-Dim count As Integer
-Dim values(100) As Double
-Dim matrix(1 To 10, 1 To 10) As Single
-Dim Shared globalFlag As Boolean
-Dim record As PersonType
-Dim fixedStr As String * 20
-
Note: DIM SHARED makes a variable accessible from all procedures without passing it as a parameter.
-
REDIM
-
Reallocates a dynamic array, optionally preserving existing data.
-
REDIM array(newBounds) AS type
-REDIM PRESERVE array(newBounds) AS type
-
ReDim items(newSize) As String
-ReDim Preserve scores(1 To newCount) As Integer
-
CONST
-
Declares a named constant. The value must be a literal (integer, float, string, or boolean).
-
CONST name = value
-
Const MAX_SIZE = 100
-Const PI = 3.14159265
-Const APP_NAME = "DVX App"
-Const DEBUG_MODE = True
-
TYPE...END TYPE
-
Defines a user-defined type (record/structure).
-
TYPE TypeName
- fieldName AS type
- ...
-END TYPE
-
Type PersonType
- firstName As String
- lastName As String
- age As Integer
-End Type
-
-Dim p As PersonType
-p.firstName = "Scott"
-p.age = 30
-
UDT fields can themselves be UDTs (nested types).
-
DECLARE
-
Forward-declares a SUB or FUNCTION. Required when a procedure is called before it is defined.
-
DECLARE SUB name ([BYVAL] param AS type, ...)
-DECLARE FUNCTION name ([BYVAL] param AS type, ...) AS returnType
-
DECLARE LIBRARY
-
Declares external native functions from a dynamically loaded library. This allows BASIC programs to call functions exported by DXE libraries.
-
DECLARE LIBRARY "libraryName"
- DECLARE SUB name ([BYVAL] param AS type, ...)
- DECLARE FUNCTION name ([BYVAL] param AS type, ...) AS returnType
-END DECLARE
-
Declare Library "rs232"
- Declare Function ComOpen(ByVal port As Integer) As Integer
- Declare Sub ComClose(ByVal port As Integer)
- Declare Sub ComSend(ByVal port As Integer, ByVal data$ As String)
-End Declare
-
STATIC
-
Declares a local variable that retains its value between calls.
-
STATIC variable AS type
-
Sub Counter()
- Static count As Integer
- count = count + 1
- Print count
-End Sub
-
OPTION
-
Sets compiler options. Must appear before any executable code.
-
OPTION BASE 0 ' Arrays start at index 0 (default)
-OPTION BASE 1 ' Arrays start at index 1
-OPTION COMPARE BINARY ' Case-sensitive string comparisons (default)
-OPTION COMPARE TEXT ' Case-insensitive string comparisons
-OPTION EXPLICIT ' All variables must be declared with DIM
-
DEFtype Statements
-
Set the default type for variables based on their first letter.
-
DEFINT letterRange
-DEFLNG letterRange
-DEFSNG letterRange
-DEFDBL letterRange
-DEFSTR letterRange
-
DefInt I-N ' Variables starting with I through N default to Integer
-DefStr S ' Variables starting with S default to String
-
Assignment
-
Assigns a value to a variable, array element, or UDT field.
-
variable = expression
-array(index) = expression
-udt.field = expression
-LET variable = expression
-
The LET keyword is optional and supported for compatibility.
-
SWAP
-
Exchanges the values of two variables.
-
SWAP variable1, variable2
-
Swap a, b
-
ERASE
-
Frees the memory of an array and resets it.
-
ERASE arrayName
-
-
Conditional Statements
-
Conditional Statements
-
IF...THEN...ELSE...END IF
-
Conditional execution. Supports single-line and multi-line forms.
-
Single-line form
-
IF condition THEN statement
-IF condition THEN statement ELSE statement
-
Multi-line form
-
IF condition THEN
- statements
-ELSEIF condition THEN
- statements
-ELSE
- statements
-END IF
-
If x > 10 Then
- Print "Large"
-ElseIf x > 5 Then
- Print "Medium"
-Else
- Print "Small"
-End If
-
-If ready Then Print "Go!"
-
SELECT CASE
-
Multi-way branch based on an expression value.
-
SELECT CASE expression
- CASE value
- statements
- CASE value1, value2
- statements
- CASE low TO high
- statements
- CASE IS operator value
- statements
- CASE ELSE
- statements
-END SELECT
-
Select Case grade
- Case 90 To 100
- Print "A"
- Case 80 To 89
- Print "B"
- Case Is >= 70
- Print "C"
- Case 60, 65
- Print "D (borderline)"
- Case Else
- Print "F"
-End Select
-
CASE items can be combined with commas. The IS keyword allows comparison operators: <, >, <=, >=, =, <>.
-
-
Loop Statements
-
Loop Statements
-
FOR...NEXT
-
Counted loop with an optional step value.
-
FOR variable = start TO limit [STEP step]
- statements
-NEXT [variable]
-
For i = 1 To 10
- Print i
-Next i
-
-For x = 10 To 0 Step -2
- Print x
-Next
-
The variable name after NEXT is optional. Use EXIT FOR to break out early.
-
DO...LOOP
-
General-purpose loop with pre-test, post-test, or infinite forms.
-
DO [WHILE condition | UNTIL condition]
- statements
-LOOP [WHILE condition | UNTIL condition]
-
' Pre-test
-Do While count < 10
- count = count + 1
-Loop
-
-' Post-test
-Do
- line$ = ReadLine()
-Loop Until line$ = "quit"
-
-' Infinite loop (exit with EXIT DO)
-Do
- DoEvents
- If done Then Exit Do
-Loop
-
WHILE...WEND
-
Simple pre-test loop (legacy form; prefer DO...LOOP).
-
WHILE condition
- statements
-WEND
-
While Not EOF(1)
- Line Input #1, line$
- Print line$
-Wend
-
-
Procedures
-
Procedures
-
SUB...END SUB
-
Defines a subroutine (no return value).
-
SUB name ([BYVAL] param AS type, ...)
- statements
-END SUB
-
Sub Greet(ByVal name As String)
- Print "Hello, " & name
-End Sub
-
Parameters are passed ByRef by default. Use ByVal for value semantics. Use EXIT SUB to return early.
-
FUNCTION...END FUNCTION
-
Defines a function with a return value.
-
FUNCTION name ([BYVAL] param AS type, ...) AS returnType
- statements
- name = returnValue
-END FUNCTION
-
Function Square(ByVal n As Double) As Double
- Square = n * n
-End Function
-
Assign to the function name to set the return value. Use EXIT FUNCTION to return early.
-
DEF FN
-
Defines a single-expression function.
-
DEF FNname(params) = expression
-
Def FnSquare(x) = x * x
-Print FnSquare(5) ' prints 25
-
-
Flow Control
-
Flow Control
-
EXIT
-
Exits the current block early.
-
EXIT FOR
-EXIT DO
-EXIT SUB
-EXIT FUNCTION
-
CALL
-
Explicitly calls a subroutine or function. The return value (if any) is discarded.
-
CALL name
-CALL name(args)
-
Normally you can omit CALL and just use the name directly.
-
GOTO / GOSUB / RETURN
-
GOTO label
-GOSUB label
-RETURN
-
GOSUB pushes the return address, executes code at the label, and RETURN jumps back. At module level, RETURN returns from a GOSUB. Inside a SUB/FUNCTION, RETURN returns from the procedure.
-
GoSub Initialize
-Print "Done"
-End
-
-Initialize:
- count = 0
- name$ = ""
-Return
-
ON...GOTO / ON...GOSUB
-
Computed branch based on an integer expression.
-
ON expression GOTO label1, label2, ...
-ON expression GOSUB label1, label2, ...
-
If the expression evaluates to 1, control goes to the first label; 2, the second; and so on. If out of range, execution falls through.
-
-
Input/Output Statements
-
Input/Output Statements
-
PRINT
-
Outputs text to the console or to a file channel.
-
PRINT [expression] [{; | ,} expression] ...
-PRINT #channel, expression
-PRINT USING format$; expression [; expression] ...
-
-- ; between items -- no separator (items are concatenated)
-- , between items -- advance to the next 14-column tab zone
-- Trailing ; or , suppresses the newline
-
-
? is an alias for PRINT
-
Special functions inside PRINT:
-
-- SPC(n) -- print n spaces
-
-
TAB(n) -- advance to column n
-
Print "Name:"; Tab(20); name$
-Print Using "###.##"; total
-Print #1, "Written to file"
-
INPUT
-
Reads a line of text from the user or from a file channel.
-
INPUT variable
-INPUT "prompt"; variable
-INPUT #channel, variable
-
Input "Enter your name: "; name$
-Input #1, line$
-
DATA / READ / RESTORE
-
Inline data pool for constants.
-
DATA value1, value2, "string", ...
-READ variable1, variable2, ...
-RESTORE
-
DATA statements define a pool of values. READ reads the next value from the pool into a variable. RESTORE resets the read pointer to the beginning.
-
Data 10, 20, 30, "Hello"
-Read a, b, c, msg$
-Print a; b; c; msg$
-Restore
-
-
Miscellaneous Statements
-
Miscellaneous Statements
-
Error Handling
-
ON ERROR GOTO label ' Enable error handler
-ON ERROR GOTO 0 ' Disable error handler
-RESUME ' Retry the statement that caused the error
-RESUME NEXT ' Continue at the next statement after the error
-ERROR n ' Raise a runtime error with error number n
-
The ERR keyword returns the current error number in expressions.
-
On Error GoTo ErrorHandler
-Open "missing.txt" For Input As #1
-Exit Sub
-
-ErrorHandler:
- Print "Error number:"; Err
- Resume Next
-
SHELL
-
Executes an operating system command.
-
SHELL "command"
-
When used as a function, returns the exit code of the command.
-
Shell "DIR /B"
-exitCode = Shell("COPY A.TXT B.TXT")
-
SLEEP
-
Pauses execution for a specified number of seconds.
-
SLEEP seconds
-
RANDOMIZE
-
Seeds the random number generator.
-
RANDOMIZE seed
-RANDOMIZE TIMER ' Seed from system clock
-
END
-
Terminates program execution immediately.
-
END
-
-
File I/O
-
File I/O
-
OPEN
-
Opens a file for reading, writing, or appending.
-
OPEN filename$ FOR INPUT AS #channel
-OPEN filename$ FOR OUTPUT AS #channel
-OPEN filename$ FOR APPEND AS #channel
-OPEN filename$ FOR RANDOM AS #channel [LEN = recordSize]
-OPEN filename$ FOR BINARY AS #channel
-
Mode Description
- ---- -----------
- INPUT Open for sequential reading. File must exist.
- OUTPUT Open for sequential writing. Creates or truncates.
- APPEND Open for sequential writing at end of file.
- RANDOM Open for random-access record I/O.
- BINARY Open for raw binary I/O.
-
CLOSE
-
Closes an open file channel.
-
CLOSE #channel
-
PRINT #
-
Writes text to a file.
-
PRINT #channel, expression
-
INPUT #
-
Reads comma-delimited data from a file.
-
INPUT #channel, variable
-
LINE INPUT #
-
Reads an entire line from a file into a string variable.
-
LINE INPUT #channel, variable$
-
WRITE #
-
Writes comma-delimited data to a file. Strings are enclosed in quotes, numbers are undecorated. Each statement writes a newline at the end.
-
WRITE #channel, expr1, expr2, ...
-
Write #1, "Scott", 42, 3.14
-' Output: "Scott",42,3.14
-
GET / PUT
-
Read and write records in RANDOM or BINARY mode files.
-
GET #channel, [recordNum], variable
-PUT #channel, [recordNum], variable
-
SEEK
-
Sets the file position. As a function, returns the current position.
-
SEEK #channel, position ' Statement: set position
-pos = SEEK(channel) ' Function: get current position
-
-
String Functions
-
String Functions
-
Function Returns Description
- -------- ------- -----------
- ASC(s$) Integer ASCII code of first character of s$
- CHR$(n) String Character with ASCII code n
- FORMAT$(value, fmt$) String Formats a numeric value using format string
- HEX$(n) String Hexadecimal representation of n
- INSTR(s$, find$) Integer Position of find$ in s$ (1-based), 0 if not found
- INSTR(start, s$, find$) Integer Search starting at position start
- LCASE$(s$) String Converts s$ to lowercase
- LEFT$(s$, n) String Leftmost n characters of s$
- LEN(s$) Integer Length of s$
- LTRIM$(s$) String Removes leading spaces from s$
- MID$(s$, start [, length]) String Substring from position start (1-based)
- RIGHT$(s$, n) String Rightmost n characters of s$
- RTRIM$(s$) String Removes trailing spaces from s$
- SPACE$(n) String String of n spaces
- STR$(n) String Converts number n to string
- STRING$(n, char) String String of n copies of char
- TRIM$(s$) String Removes leading and trailing spaces from s$
- UCASE$(s$) String Converts s$ to uppercase
- VAL(s$) Double Converts string s$ to a numeric value
-
MID$ Assignment
-
MID$ can also be used on the left side of an assignment to replace a portion of a string:
-
Mid$(s$, 3, 2) = "XY" ' Replace 2 characters starting at position 3
-
-
Math Functions
-
Math Functions
-
Function Returns Description
- -------- ------- -----------
- ABS(n) Double Absolute value of n
- ATN(n) Double Arctangent of n (in radians)
- COS(n) Double Cosine of n (radians)
- EXP(n) Double e raised to the power n
- FIX(n) Integer Truncates n toward zero (removes fractional part)
- INT(n) Integer Largest integer less than or equal to n (floor)
- LOG(n) Double Natural logarithm (base e) of n
- RND[(n)] Double Random number between 0 (inclusive) and 1 (exclusive)
- SGN(n) Integer Sign of n: -1, 0, or 1
- SIN(n) Double Sine of n (radians)
- SQR(n) Double Square root of n
- TAN(n) Double Tangent of n (radians)
- TIMER Double Number of seconds since midnight
-
Note: RND with a negative argument seeds and returns. RND(0) returns the previous value. Use RANDOMIZE to seed the generator.
-
-
Conversion Functions
-
Conversion Functions
-
Function Returns Description
- -------- ------- -----------
- CDBL(n) Double Converts n to Double
- CINT(n) Integer Converts n to Integer (with banker's rounding)
- CLNG(n) Long Converts n to Long
- CSNG(n) Single Converts n to Single
- CSTR(n) String Converts n to its String representation
-
-
File I/O Functions
-
File I/O Functions
-
Function Returns Description
- -------- ------- -----------
- EOF(channel) Boolean True if file pointer is at end of file
- FREEFILE Integer Next available file channel number
- INPUT$(n, #channel) String Reads n characters from the file
- LOC(channel) Long Current read/write position in the file
- LOF(channel) Long Length of the file in bytes
- SEEK(channel) Long Current file position (function form)
- LBOUND(array [, dim]) Integer Lower bound of an array dimension
- UBOUND(array [, dim]) Integer Upper bound of an array dimension
-
-
Miscellaneous Functions
-
Miscellaneous Functions
-
Function Returns Description
- -------- ------- -----------
- DATE$ String Current date as "MM-DD-YYYY"
- TIME$ String Current time as "HH:MM:SS"
- ENVIRON$(name$) String Value of environment variable name$
- ERR Integer Current runtime error number (0 if no error)
-
-
Form and Control Statements
-
Form and Control Statements
-
DVX BASIC supports Visual Basic-style forms and controls for building graphical user interfaces. Forms are defined in .frm files and loaded at runtime.
-
Loading and Unloading Forms
-
LOAD FormName
-UNLOAD FormName
-
LOAD creates the form and its controls in memory. UNLOAD destroys the form and frees its resources.
-
Showing and Hiding Forms
-
FormName.Show [modal]
-FormName.Hide
-Me.Show [modal]
-Me.Hide
-
Pass vbModal (1) to Show for a modal dialog.
-
Form2.Show vbModal
-Me.Hide
-
Property Access
-
Read and write control properties using dot notation:
-
ControlName.Property = value
-value = ControlName.Property
-
Text1.Text = "Hello"
-label1.Caption = "Name: " & name$
-x = Text1.Left
-
Method Calls
-
ControlName.Method [args]
-
List1.AddItem "New entry"
-List1.Clear
-
Me Keyword
-
Me refers to the current form. Use it to access the form's own properties, controls, and methods from within event handlers.
-
Me.Caption = "Updated Title"
-Me.Text1.Text = ""
-Me.Hide
-
Control Arrays
-
Multiple controls can share a name with unique indices. Access individual controls with parenthesized indices:
-
Option1(0).Value = True
-Label1(idx).Caption = "Item " & Str$(idx)
-Me.Label1(i).Visible = True
-
DoEvents
-
Yields control to the DVX event loop, allowing the GUI to process pending events. Call this in long-running loops to keep the UI responsive.
-
DOEVENTS
-
For i = 1 To 10000
- ' process data
- If i Mod 100 = 0 Then DoEvents
-Next
-
MsgBox
-
Displays a message box dialog. Can be used as a statement (discards result) or as a function (returns the button clicked).
-
MSGBOX message$ [, flags]
-result = MSGBOX(message$ [, flags])
-
MsgBox "Operation complete"
-answer = MsgBox("Continue?", vbYesNo + vbQuestion)
-If answer = vbYes Then
- ' proceed
-End If
-
InputBox$
-
Displays an input dialog and returns the user's text entry.
-
result$ = INPUTBOX$(prompt$ [, title$ [, default$]])
-
name$ = InputBox$("Enter your name:", "Name Entry", "")
-
Event Handler Convention
-
Event handlers are named ControlName_EventName and defined as SUBs:
-
Sub Command1_Click()
- MsgBox "Button clicked!"
-End Sub
-
-Sub Form_Load()
- Me.Caption = "My App"
-End Sub
-
-Sub Text1_Change()
- Label1.Caption = "You typed: " & Text1.Text
-End Sub
-
Common Events
-
Event Description
- ----- -----------
- Click Control was clicked
- DblClick Control was double-clicked
- Change Control value/text changed
- KeyPress Key was pressed (receives key code)
- KeyDown Key went down (receives key code and shift state)
- KeyUp Key was released
- MouseDown Mouse button pressed
- MouseUp Mouse button released
- MouseMove Mouse moved over control
- GotFocus Control received input focus
- LostFocus Control lost input focus
- Form_Load Form is being loaded
- Form_Unload Form is being unloaded
- Form_Resize Form was resized
- Timer Timer interval elapsed
-
-
SQL Functions
-
SQL Functions
-
DVX BASIC includes built-in SQLite database support through a set of SQL functions. All functions use database handles and result set handles (integers) returned by SQLOpen and SQLQuery.
-
Opening and Closing Databases
-
SQLOpen
-
Opens a SQLite database file and returns a database handle.
-
db = SQLOPEN(path$)
-
db = SQLOpen(App.Data & "\mydata.db")
-
SQLClose
-
Closes an open database.
-
SQLCLOSE db
-
Executing SQL
-
SQLExec
-
Executes a SQL statement that does not return data (INSERT, UPDATE, DELETE, CREATE TABLE, etc.). Can be used as a statement or as a function returning a Boolean success flag.
-
SQLEXEC db, sql$
-ok = SQLEXEC(db, sql$)
-
SQLExec db, "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"
-SQLExec db, "INSERT INTO users (name) VALUES ('Scott')"
-ok = SQLExec(db, "DELETE FROM users WHERE id = 5")
-
SQLAffected
-
Returns the number of rows affected by the last INSERT, UPDATE, or DELETE.
-
count = SQLAFFECTED(db)
-
Querying Data
-
SQLQuery
-
Executes a SELECT query and returns a result set handle.
-
rs = SQLQUERY(db, sql$)
-
rs = SQLQuery(db, "SELECT id, name FROM users ORDER BY name")
-
SQLNext
-
Advances to the next row in the result set. Can be used as a statement or as a function returning True if a row is available.
-
SQLNEXT rs
-hasRow = SQLNEXT(rs)
-
SQLEof
-
Returns True if there are no more rows in the result set.
-
done = SQLEOF(rs)
-
Reading Fields
-
SQLField$
-
Returns a field value as a string. The field can be specified by column index (0-based) or by column name.
-
value$ = SQLFIELD$(rs, columnIndex)
-value$ = SQLFIELD$(rs, "columnName")
-
name$ = SQLField$(rs, "name")
-first$ = SQLField$(rs, 0)
-
SQLFieldInt
-
Returns a field value as an integer.
-
value = SQLFIELDINT(rs, columnIndex)
-
SQLFieldDbl
-
Returns a field value as a double.
-
value# = SQLFIELDDBL(rs, columnIndex)
-
SQLFieldCount
-
Returns the number of columns in the result set.
-
count = SQLFIELDCOUNT(rs)
-
Result Set Cleanup
-
SQLFreeResult
-
Frees a result set. Always call this when done iterating a query.
-
SQLFREERESULT rs
-
Error Information
-
SQLError$
-
Returns the last error message for the database.
-
msg$ = SQLERROR$(db)
-
Complete SQL Example
-
Dim db As Long
-Dim rs As Long
-
-db = SQLOpen(App.Data & "\contacts.db")
-SQLExec db, "CREATE TABLE IF NOT EXISTS contacts (name TEXT, phone TEXT)"
-SQLExec db, "INSERT INTO contacts VALUES ('Alice', '555-1234')"
-
-rs = SQLQuery(db, "SELECT name, phone FROM contacts")
-Do While Not SQLEof(rs)
- SQLNext rs
- Print SQLField$(rs, "name"); Tab(20); SQLField$(rs, "phone")
-Loop
-SQLFreeResult rs
-SQLClose db
-
-
App Object
-
App Object
-
The App object provides read-only properties for the application's directory paths.
-
Property Returns Description
- -------- ------- -----------
- App.Path String Directory containing the application's executable
- App.Config String Directory for application configuration files
- App.Data String Directory for application data files (databases, etc.)
-
configFile$ = App.Config & "\settings.ini"
-dbPath$ = App.Data & "\myapp.db"
-Print "Running from: " & App.Path
-
-
INI Functions
-
INI Functions
-
DVX BASIC provides built-in functions for reading and writing standard INI configuration files.
-
IniRead
-
Reads a value from an INI file. Returns the default value if the key is not found.
-
value$ = INIREAD(file$, section$, key$, default$)
-
name$ = IniRead(App.Config & "\app.ini", "User", "Name", "Unknown")
-fontSize = Val(IniRead(App.Config & "\app.ini", "Display", "FontSize", "12"))
-
IniWrite
-
Writes a value to an INI file. Creates the file, section, or key if they do not exist.
-
INIWRITE file$, section$, key$, value$
-
IniWrite App.Config & "\app.ini", "User", "Name", "Scott"
-IniWrite App.Config & "\app.ini", "Display", "FontSize", Str$(fontSize)
-
-
Predefined Constants
-
Predefined Constants
-
The following constants are predefined by the compiler and available in all programs.
-
MsgBox Button Style Flags
-
Constant Value Description
- -------- ----- -----------
- vbOKOnly 0 OK button only (default)
- vbOKCancel 1 OK and Cancel buttons
- vbYesNo 2 Yes and No buttons
- vbYesNoCancel 3 Yes, No, and Cancel buttons
- vbRetryCancel 4 Retry and Cancel buttons
-
MsgBox Icon Flags
-
Add an icon flag to the button style to display an icon in the message box.
-
Constant Value Description
- -------- ----- -----------
- vbInformation &H10 Information icon
- vbExclamation &H20 Warning icon
- vbCritical &H30 Error/critical icon
- vbQuestion &H40 Question mark icon
-
MsgBox Return Values
-
Constant Value Description
- -------- ----- -----------
- vbOK 1 User clicked OK
- vbCancel 2 User clicked Cancel
- vbYes 3 User clicked Yes
- vbNo 4 User clicked No
- vbRetry 5 User clicked Retry
-
Show Mode Flags
-
Constant Value Description
- -------- ----- -----------
- vbModal 1 Show form as modal dialog
-
Boolean Constants
-
Constant Value Description
- -------- ----- -----------
- True -1 Boolean true
- False 0 Boolean false
-
-
Common Properties, Events, and Methods
-
Common Properties, Events, and Methods
-
Every control in DVX BASIC inherits a set of common properties, events, and methods. These are handled by the form runtime before dispatching to widget-specific interface descriptors.
-
Common Properties
-
Property Type R/W Description
- ---------- ------- --- -------------------------------------------
- Name String R The control's name (e.g. "Command1"). Read-only at runtime.
- Left Integer R/W X position in pixels relative to the parent container.
- Top Integer R/W Y position in pixels relative to the parent container.
- Width Integer R/W Current width in pixels. Setting this changes the minimum width constraint.
- Height Integer R/W Current height in pixels. Setting this changes the minimum height constraint.
- MinWidth Integer R/W Minimum width for layout. Alias for Width in the setter.
- MinHeight Integer R/W Minimum height for layout. Alias for Height in the setter.
- MaxWidth Integer R/W Maximum width cap (0 = no limit, stretch to fill).
- MaxHeight Integer R/W Maximum height cap (0 = no limit, stretch to fill).
- Weight Integer R/W Layout weight. 0 = fixed size, >0 = share extra space proportionally.
- Visible Boolean R/W Whether the control is visible.
- Enabled Boolean R/W Whether the control accepts user input.
- BackColor Long R/W Background color as a 32-bit ARGB value.
- ForeColor Long R/W Foreground (text) color as a 32-bit ARGB value.
- TabIndex Integer R Accepted for VB compatibility but ignored. DVX has no tab order.
-
Common Events
-
These events are wired on every control loaded from a .frm file. Controls created dynamically at runtime via code only receive Click, DblClick, Change, GotFocus, and LostFocus; the keyboard, mouse, and scroll events below require the control to be defined in the .frm file.
-
Event Parameters Description
- --------- ------------------------------------------- -------------------------------------------
- Click (none) Fires when the control is clicked.
- DblClick (none) Fires when the control is double-clicked.
- Change (none) Fires when the control's value or text changes.
- GotFocus (none) Fires when the control receives keyboard focus.
- LostFocus (none) Fires when the control loses keyboard focus.
- KeyPress KeyAscii As Integer Fires when a printable key is pressed. KeyAscii is the ASCII code.
- KeyDown KeyCode As Integer, Shift As Integer Fires when any key is pressed down. KeyCode is the scan code; Shift indicates modifier keys.
- KeyUp KeyCode As Integer, Shift As Integer Fires when a key is released.
- MouseDown Button As Integer, X As Integer, Y As Integer Fires when a mouse button is pressed over the control.
- MouseUp Button As Integer, X As Integer, Y As Integer Fires when a mouse button is released over the control.
- MouseMove Button As Integer, X As Integer, Y As Integer Fires when the mouse moves over the control.
- Scroll Delta As Integer Fires when the control is scrolled (mouse wheel or scrollbar).
-
Common Methods
-
Method Parameters Description
- -------- ---------- -------------------------------------------
- SetFocus (none) Gives keyboard focus to this control.
- Refresh (none) Forces the control to repaint.
-
Form
-
Data Binding
-
FRM File Format
-
-
Data Binding
-
Data Binding
-
DVX BASIC provides VB3-style data binding through three properties that can be set on most controls:
-
Property Set On Description
- ---------- ----------- -------------------------------------------
- DataSource Any control Name of the Data control to bind to (e.g. "Data1").
- DataField Any control Column name from the Data control's recordset to display.
-
How It Works
-
-- Place a Data control on the form and set its DatabaseName and RecordSource properties.
-- Place one or more display/edit controls (TextBox, Label, etc.) and set their DataSource to the Data control's name and DataField to a column name.
-- When the form loads, the Data control auto-refreshes: it opens the database, runs the query, and navigates to the first record.
-- Bound controls are updated automatically each time the Data control repositions (the Reposition event fires, and the runtime pushes the current record's field values into all bound controls).
-
-
When a bound control loses focus (LostFocus), its current text is written back to the Data control's record cache, and Update is called automatically to persist changes.
-
Master-Detail Binding
-
For hierarchical data (e.g. orders and order items), use two Data controls:
-
-- A master Data control bound to the parent table.
-
-
A detail Data control with its MasterSource set to the master's name, MasterField set to the key column in the master, and DetailField set to the foreign key column in the detail table.
-
When the master record changes, the detail Data control automatically re-queries using the master's current value for filtering. All controls bound to the detail are refreshed.
-
DBGrid Binding
-
Set the DBGrid's DataSource to a Data control name. The grid auto-populates columns from the query results and refreshes whenever the Data control refreshes.
-
Example
-
VERSION DVX 1.00
-Begin Form frmData
- Caption = "Data Binding Example"
- AutoSize = False
- Width = 400
- Height = 280
- Begin Data Data1
- DatabaseName = "myapp.db"
- RecordSource = "customers"
- End
- Begin Label lblName
- Caption = "Name:"
- End
- Begin TextBox txtName
- DataSource = "Data1"
- DataField = "name"
- End
- Begin Label lblEmail
- Caption = "Email:"
- End
- Begin TextBox txtEmail
- DataSource = "Data1"
- DataField = "email"
- End
-End
-
-Sub Data1_Reposition ()
- Print "Current record changed"
-End Sub
-
-Sub Data1_Validate (Cancel As Integer)
- If txtName.Text = "" Then
- MsgBox "Name cannot be empty!"
- Cancel = 1
- End If
-End Sub
-
Data
-
DBGrid
-
-
Control Arrays
-
Control Arrays
-
DVX BASIC supports VB-style control arrays. Multiple controls can share the same name, differentiated by an Index property. When an event fires on a control array element, the element's index is passed as the first parameter.
-
Defining Control Arrays in FRM
-
Begin CommandButton Command1
- Caption = "Button A"
- Index = 0
-End
-Begin CommandButton Command1
- Caption = "Button B"
- Index = 1
-End
-Begin CommandButton Command1
- Caption = "Button C"
- Index = 2
-End
-
Event Handler Convention
-
When a control has an Index property (>= 0), the event handler receives Index As Integer as the first parameter, before any event-specific parameters.
-
Sub Command1_Click (Index As Integer)
- Select Case Index
- Case 0
- MsgBox "Button A clicked"
- Case 1
- MsgBox "Button B clicked"
- Case 2
- MsgBox "Button C clicked"
- End Select
-End Sub
-
Accessing Array Elements in Code
-
Use the indexed form ControlName(Index) to access a specific element:
-
Command1(0).Caption = "New Text"
-Command1(1).Enabled = False
-
Note: Control array elements share the same event handler Sub. The runtime prepends the Index argument automatically. If you define parameters on the Sub, Index comes first, followed by the event's own parameters (e.g. KeyPress would be Sub Ctrl1_KeyPress (Index As Integer, KeyAscii As Integer)).
-
Common Properties, Events, and Methods
-
FRM File Format
-
-
FRM File Format
-
FRM File Format
-
The .frm file is a text file that describes a form's layout, controls, menus, and code. It follows a format compatible with VB3 .frm files, with DVX-specific extensions.
-
Structure
-
VERSION DVX 1.00
-Begin Form FormName
- form-level properties...
-
- Begin Menu mnuFile
- Caption = "&File"
- Begin Menu mnuOpen
- Caption = "&Open"
- End
- End
-
- Begin TypeName ControlName
- property = value
- ...
- End
-
- Begin Frame Frame1
- Caption = "Group"
- Begin TypeName ChildName
- ...
- End
- End
-End
-
-BASIC code follows...
-
-Sub FormName_Load ()
- ...
-End Sub
-
Rules
-
-- The VERSION line is optional. VERSION DVX 1.00 marks a native DVX form. VB forms with version <= 2.0 are accepted for import.
-- The form block begins with Begin Form Name and ends with End.
-- Controls are nested with Begin TypeName Name / End.
-- Container controls (Frame, VBox, HBox, Toolbar, TabStrip, ScrollPane, Splitter, WrapBox) can have child controls nested inside them.
-- Properties are assigned as Key = Value. String values are optionally quoted.
-- Everything after the form's closing End is BASIC source code.
-- Comments in the form section use ' (single quote).
-
-
Blank lines are ignored in the form section.
-
Common FRM Properties
-
Property Applies To Description
- ----------------------- --------------- -------------------------------------------
- Caption Form, controls Display text or window title.
- Text TextBox, ComboBox Initial text content.
- MinWidth / Width Controls Minimum width. Both names are accepted.
- MinHeight / Height Controls Minimum height. Both names are accepted.
- MaxWidth Controls Maximum width (0 = no cap).
- MaxHeight Controls Maximum height (0 = no cap).
- Weight Controls Layout weight for flexible sizing.
- Left Form, controls X position (used by Form when Centered=False; informational for controls).
- Top Form, controls Y position.
- Index Controls Control array index (-1 or absent = not in array).
- Visible Controls Initial visibility.
- Enabled Controls Initial enabled state.
- Layout Form "VBox" or "HBox".
- AutoSize Form Auto-fit window to content.
- Resizable Form Allow runtime resizing.
- Centered Form Center window on screen.
- DatabaseName Data SQLite database file path.
- RecordSource Data Table name or SQL query.
- DataSource Bound controls Name of the Data control.
- DataField Bound controls Column name in the recordset.
-
Form
-
Common Properties, Events, and Methods
-
Menu System
-
Control Arrays
-
-
CheckBox
-
CheckBox
-
VB Equivalent: CheckBox -- DVX Widget: checkbox
-
A toggle control with a label. Checked state is exposed as a Boolean.
-
Type-Specific Properties
-
Property Type Description
- -------- ------- -------------------------------------------
- Caption String The text displayed next to the checkbox.
- Value Boolean True if checked, False if unchecked.
-
Default Event: Click
-
Example
-
Begin CheckBox Check1
- Caption = "Enable feature"
-End
-
-Sub Check1_Click ()
- If Check1.Value Then
- Label1.Caption = "Feature ON"
- Else
- Label1.Caption = "Feature OFF"
- End If
-End Sub
-
Common Properties, Events, and Methods
-
-
ComboBox
-
ComboBox
-
VB Equivalent: ComboBox -- DVX Widget: combobox (editable text field + drop-down list, max 256 chars)
-
A combination of a text input and a drop-down list. The user can type text or select from the list. Supports the same AddItem/RemoveItem/Clear/List methods as ListBox.
-
Type-Specific Properties
-
Property Type Description
- --------- ------- -------------------------------------------
- Text String The text in the editable field.
- ListIndex Integer Index of the currently selected list item (-1 = none).
- ListCount Integer Number of items in the drop-down list (read-only).
-
Type-Specific Methods
-
Same as ListBox: AddItem, RemoveItem, Clear, List.
-
See ListBox for details
-
Default Event: Click
-
Common Properties, Events, and Methods
-
-
Data
-
Data
-
VB Equivalent: Data -- DVX Widget: data (database record navigator)
-
A data access control that connects to a SQLite database and provides record navigation. Other controls can bind to a Data control via their DataSource and DataField properties.
-
See Data Binding for details
-
Type-Specific Properties
-
Property Type R/W Description
- ------------ ------- --- -------------------------------------------
- DatabaseName String R/W Path to the SQLite database file.
- RecordSource String R/W Table name or SQL SELECT query for the recordset.
- KeyColumn String R/W Primary key column name (used for UPDATE/DELETE operations).
- Caption String R/W Text displayed on the navigator bar.
- BOF Boolean R True if the current position is before the first record (read-only).
- EOF Boolean R True if the current position is past the last record (read-only).
- MasterSource String R/W Name of a master Data control (for master-detail binding).
- MasterField String R/W Column in the master recordset to filter by.
- DetailField String R/W Column in this recordset that matches the master field.
-
Type-Specific Methods
-
Method Parameters Description
- ------------ ---------- -------------------------------------------
- MoveFirst (none) Navigate to the first record.
- MoveLast (none) Navigate to the last record.
- MoveNext (none) Navigate to the next record.
- MovePrevious (none) Navigate to the previous record.
- AddNew (none) Add a new blank record.
- Delete (none) Delete the current record.
- Refresh (none) Re-query the database and reload records.
- Update (none) Write pending changes to the database.
-
Type-Specific Events
-
Event Parameters Description
- ---------- ----------------- -------------------------------------------
- Reposition (none) Fires after the current record changes (navigation). This is the default event.
- Validate Cancel As Integer Fires before writing a record. Set Cancel = 1 to abort.
-
Common Properties, Events, and Methods
-
Data Binding
-
DBGrid
-
-
DBGrid
-
DBGrid
-
VB Equivalent: DBGrid -- DVX Widget: dbgrid
-
A data-bound grid that displays records from a Data control in a tabular format. Columns are auto-generated from the query results. Bind it using the DataSource property.
-
Type-Specific Properties
-
Property Type Description
- ---------- ------- -------------------------------------------
- DataSource String Name of the Data control that supplies records.
- GridLines Boolean Show or hide grid lines between cells.
-
Type-Specific Methods
-
Method Parameters Description
- ------- ---------- -------------------------------------------
- Refresh (none) Reload and redraw the grid from the Data control.
-
Type-Specific Events
-
Event Parameters Description
- -------- ---------- -------------------------------------------
- Click (none) Fires when a cell is clicked.
- DblClick (none) Fires when a cell is double-clicked. This is the default event.
-
Common Properties, Events, and Methods
-
Data
-
Data Binding
-
-
DropDown
-
DropDown
-
DVX Extension -- DVX Widget: dropdown (non-editable drop-down list)
-
A read-only drop-down list. Unlike ComboBox, the user cannot type free text; they can only select from the provided items. Supports AddItem/RemoveItem/Clear/List.
-
Type-Specific Properties
-
Property Type Description
- --------- ------- -------------------------------------------
- ListIndex Integer Index of the currently selected item.
- ListCount Integer Number of items (read-only).
-
Type-Specific Methods
-
Same as ListBox: AddItem, RemoveItem, Clear, List.
-
See ListBox for details
-
Default Event: Click
-
Common Properties, Events, and Methods
-
-
Frame
-
Frame
-
VB Equivalent: Frame -- DVX Widget: frame (titled VBox container)
-
A container with a titled border. Child controls are placed inside the frame using VBox layout. In the .frm file, nest Begin/End blocks inside the Frame block.
-
Type-Specific Properties
-
Property Type Description
- -------- ------ -------------------------------------------
- Caption String The title displayed in the frame border.
-
Container: Yes
-
Default Event: Click
-
Example
-
Begin Frame Frame1
- Caption = "Options"
- Begin CheckBox Check1
- Caption = "Option A"
- End
- Begin CheckBox Check2
- Caption = "Option B"
- End
-End
-
Common Properties, Events, and Methods
-
-
HBox
-
HBox
-
DVX Extension -- DVX Widget: hbox (horizontal layout container)
-
A container that arranges its children horizontally, left to right. Use Weight on children to distribute extra space.
-
Container: Yes
-
Default Event: Click
-
No type-specific properties.
-
Common Properties, Events, and Methods
-
VBox
-
-
Image
-
Image
-
VB Equivalent: Image -- DVX Widget: image
-
A static image display control. Loads BMP images from file. Cannot be placed via the designer toolbox (requires pixel data at creation time); typically created in code or loaded via the Picture property.
-
Type-Specific Properties
-
Property Type Description
- ----------- ------- -------------------------------------------
- Picture String Path to a BMP file to load (write-only).
- ImageWidth Integer Width of the loaded image in pixels (read-only).
- ImageHeight Integer Height of the loaded image in pixels (read-only).
-
Default Event: Click
-
Common Properties, Events, and Methods
-
-
Label
-
Label
-
VB Equivalent: Label -- DVX Widget: label
-
A static text label. Supports left, center, and right alignment.
-
Type-Specific Properties
-
Property Type Description
- --------- ---- -------------------------------------------
- Caption String The text displayed by the label.
- Alignment Enum Text alignment: Left (default), Center, or Right.
-
Default Event: Click
-
Example
-
Begin Label Label1
- Caption = "Hello, World!"
- Alignment = "Center"
-End
-
Common Properties, Events, and Methods
-
-
Line
-
Line
-
VB Equivalent: Line -- DVX Widget: separator
-
A visual separator line. The underlying widget supports both horizontal and vertical orientations. The default (via BASIC) is horizontal.
-
No type-specific properties, events, or methods.
-
Common Properties, Events, and Methods
-
-
ListBox
-
ListBox
-
VB Equivalent: ListBox -- DVX Widget: listbox
-
A scrollable list of selectable items. Items are managed via methods (AddItem, RemoveItem, Clear). Supports single and multi-select modes.
-
Type-Specific Properties
-
Property Type Description
- --------- ------- -------------------------------------------
- ListIndex Integer Index of the currently selected item (-1 = no selection).
- ListCount Integer Number of items in the list (read-only).
-
Type-Specific Methods
-
Method Parameters Description
- --------------- --------------------------------------- -------------------------------------------
- AddItem Text As String Add an item to the end of the list.
- RemoveItem Index As Integer Remove the item at the given index.
- Clear (none) Remove all items from the list.
- List Index As Integer Return the text of the item at the given index.
- SelectAll (none) Select all items (multi-select mode).
- ClearSelection (none) Deselect all items.
- SetMultiSelect Multi As Boolean Enable or disable multi-select mode.
- SetReorderable Reorderable As Boolean Enable or disable drag-to-reorder.
- IsItemSelected Index As Integer Returns True if the item at Index is selected.
- SetItemSelected Index As Integer, Selected As Boolean Select or deselect a specific item.
-
Default Event: Click
-
Example
-
Sub Form_Load ()
- List1.AddItem "Apple"
- List1.AddItem "Banana"
- List1.AddItem "Cherry"
-End Sub
-
-Sub List1_Click ()
- Dim idx As Integer
- idx = List1.ListIndex
- If idx >= 0 Then
- Label1.Caption = "Selected: " & List1.List(idx)
- End If
-End Sub
-
Common Properties, Events, and Methods
-
ComboBox
-
DropDown
-
-
ListView
-
ListView
-
VB Equivalent: ListView -- DVX Widget: listview
-
A multi-column list with column headers. Supports sorting, multi-select, and drag-to-reorder. Columns are configured via the C API (SetColumns, SetData).
-
Type-Specific Properties
-
Property Type Description
- --------- ------- -------------------------------------------
- ListIndex Integer Index of the currently selected row (-1 = none).
-
Type-Specific Methods
-
Method Parameters Description
- --------------- --------------------------------------- -------------------------------------------
- SelectAll (none) Select all rows.
- ClearSelection (none) Deselect all rows.
- SetMultiSelect Multi As Boolean Enable or disable multi-select.
- SetReorderable Reorderable As Boolean Enable or disable row reordering.
- IsItemSelected Index As Integer Returns True if the row at Index is selected.
- SetItemSelected Index As Integer, Selected As Boolean Select or deselect a specific row.
-
Default Event: Click
-
Common Properties, Events, and Methods
-
-
PictureBox
-
PictureBox
-
VB Equivalent: PictureBox -- DVX Widget: canvas | Name Prefix: Picture
-
A drawing surface (canvas). Supports drawing lines, rectangles, circles, text, and individual pixels. Can save and load BMP images. The default canvas size is 64x64 pixels.
-
Type-Specific Methods
-
Method Parameters Description
- ------ ---------------- -------------------------------------------
- Clear Color As Integer Fill the entire canvas with the specified color.
-
Additional drawing methods (DrawLine, DrawRect, FillRect, FillCircle, SetPixel, GetPixel, DrawText, Save, Load) are available through the C API but not currently exposed through BASIC interface descriptors.
-
Default Event: Click
-
Common Properties, Events, and Methods
-
-
ProgressBar
-
ProgressBar
-
VB Equivalent: ProgressBar -- DVX Widget: progressbar
-
A horizontal progress indicator bar.
-
Type-Specific Properties
-
Property Type Description
- -------- ------- -------------------------------------------
- Value Integer Current progress value (0-100).
-
No type-specific events or methods. No default event.
-
Common Properties, Events, and Methods
-
-
Spacer
-
Spacer
-
DVX Extension -- DVX Widget: spacer
-
An invisible layout spacer. Takes up space in the layout without rendering anything. Useful for pushing controls apart. Give it a Weight to absorb extra space.
-
No type-specific properties, events, or methods.
-
Common Properties, Events, and Methods
-
-
Splitter
-
Splitter
-
DVX Extension -- DVX Widget: splitter
-
A resizable split pane. Holds exactly two child widgets separated by a draggable divider. Default orientation is vertical (top/bottom split).
-
Type-Specific Properties
-
Property Type Description
- -------- ------- -------------------------------------------
- Position Integer Position of the divider in pixels from the top (or left).
-
Container: Yes
-
No default event.
-
Common Properties, Events, and Methods
-
-
StatusBar
-
StatusBar
-
VB Equivalent: StatusBar -- DVX Widget: statusbar
-
A horizontal container styled as a status bar, typically placed at the bottom of a form. At the C API level it accepts child widgets, but it is not registered as a container in the form runtime, so child controls cannot be nested inside it in .frm files. Set its Caption property to display status text.
-
No type-specific properties, events, or methods.
-
Common Properties, Events, and Methods
-
-
TabStrip
-
TabStrip
-
VB Equivalent: TabStrip -- DVX Widget: tabcontrol
-
A tabbed container. Each tab page is a separate container that holds child controls. Switching tabs shows one page and hides others.
-
Type-Specific Properties
-
Property Type Description
- -------- ------- -------------------------------------------
- TabIndex Integer Index of the active tab (0-based). Note: this property name collides with the common VB-compatibility TabIndex property, which shadows it at runtime. Use the SetActive method instead to switch tabs.
-
Type-Specific Methods
-
Method Parameters Description
- --------- ----------------- -------------------------------------------
- SetActive Index As Integer Switch to the tab at the given index. This is the recommended way to change tabs at runtime (the TabIndex property is shadowed by the common property handler).
-
Container: Yes
-
Default Event: Click
-
Warning: The TabIndex property is shadowed by the common property handler at runtime. Use the SetActive method to change tabs programmatically.
-
Common Properties, Events, and Methods
-
-
Terminal
-
Terminal
-
DVX Extension -- DVX Widget: ansiterm (ANSI terminal emulator)
-
A VT100/ANSI terminal emulator widget. Supports ANSI escape sequences, scrollback buffer, and serial communication. Default size is 80 columns by 25 rows.
-
Type-Specific Properties
-
Property Type Description
- ---------- ------- -------------------------------------------
- Cols Integer Number of character columns (read-only).
- Rows Integer Number of character rows (read-only).
- Scrollback Integer Number of scrollback lines (write-only).
-
Type-Specific Methods
-
Method Parameters Description
- ------ --------------- -------------------------------------------
- Clear (none) Clear the terminal screen.
- Write Text As String Write text (with ANSI escape processing) to the terminal.
-
No default event.
-
Common Properties, Events, and Methods
-
-
TextArea
-
TextArea
-
VB Equivalent: TextArea (DVX extension) -- DVX Widget: textarea (multi-line text input, max 4096 chars)
-
A multi-line text editing area. This is a DVX extension with no direct VB3 equivalent (VB uses a TextBox with MultiLine=True). Supports syntax colorization, line numbers, auto-indent, and find/replace via the C API.
-
Type-Specific Properties
-
Property Type Description
- -------- ------ -------------------------------------------
- Text String The full text content.
-
Default Event: Change
-
Common Properties, Events, and Methods
-
-
TextBox
-
TextBox
-
VB Equivalent: TextBox -- DVX Widget: textbox (single-line text input, max 256 chars)
-
A single-line text input field. Supports data binding via DataSource and DataField properties.
-
Type-Specific Properties
-
Property Type Description
- ---------- ------ -------------------------------------------
- Text String The text content of the input field.
- DataSource String Name of a Data control for data binding.
- DataField String Column name for data binding.
-
Default Event: Change
-
Example
-
Begin TextBox Text1
- Text = "Enter text here"
-End
-
-Sub Text1_Change ()
- Label1.Caption = "You typed: " & Text1.Text
-End Sub
-
Common Properties, Events, and Methods
-
Data Binding
-
-
Timer
-
Timer
-
VB Equivalent: Timer -- DVX Widget: timer (non-visual)
-
A non-visual control that fires its event at a regular interval. The Timer widget is invisible at runtime -- it has no on-screen representation.
-
Type-Specific Properties
-
Property Type Description
- -------- ------- -------------------------------------------
- Enabled Boolean True to start the timer, False to stop it.
- Interval Integer Timer interval in milliseconds (write-only from BASIC).
-
Type-Specific Methods
-
Method Parameters Description
- ------ ---------- -------------------------------------------
- Start (none) Start the timer.
- Stop (none) Stop the timer.
-
Type-Specific Events
-
Event Parameters Description
- ----- ---------- -------------------------------------------
- Timer (none) Fires each time the interval elapses. This is the default event.
-
Note: The Timer control fires the Timer event instead of Change. The onChange callback on the underlying widget is remapped automatically.
-
Example
-
Begin Timer Timer1
- Interval = 1000
- Enabled = True
-End
-
-Dim counter As Integer
-
-Sub Timer1_Timer ()
- counter = counter + 1
- Label1.Caption = "Ticks: " & Str$(counter)
-End Sub
-
Common Properties, Events, and Methods
-
-
TreeView
-
TreeView
-
VB Equivalent: TreeView -- DVX Widget: treeview
-
A hierarchical tree of expandable/collapsible nodes. Nodes are created via the C API (wgtTreeItem). Supports multi-select and drag-to-reorder.
-
Type-Specific Methods
-
Method Parameters Description
- -------------- ---------------------- -------------------------------------------
- SetMultiSelect Multi As Boolean Enable or disable multi-select mode.
- SetReorderable Reorderable As Boolean Enable or disable node reordering.
-
Default Event: Click
-
Common Properties, Events, and Methods
-
-
VBox
-
VBox
-
DVX Extension -- DVX Widget: vbox (vertical layout container)
-
A container that arranges its children vertically, top to bottom. No title or border. Use Weight on children to distribute extra space.
-
Container: Yes
-
Default Event: Click
-
No type-specific properties.
-
Common Properties, Events, and Methods
-
HBox
-
-
WrapBox
-
WrapBox
-
DVX Extension -- DVX Widget: wrapbox
-
A container that arranges children in a flowing layout, wrapping to the next row when the available width is exceeded. Similar to CSS flexbox with flex-wrap: wrap.
-
Type-Specific Properties
-
Property Type Description
- --------- ---- -------------------------------------------
- Alignment Enum Horizontal alignment of items: Left, Center, or Right.
-
Container: Yes
-
Default Event: Click
-
Common Properties, Events, and Methods
-