From 0f5da09d1f113af7a83ef1c4180b67b09c5e03cb Mon Sep 17 00:00:00 2001 From: Scott Duensing Date: Mon, 6 Apr 2026 22:25:06 -0500 Subject: [PATCH] Docs added. --- apps/dvxbasic/compiler/parser.c | 20 +- core/dvxFont.h | 8 +- core/dvxTypes.h | 9 +- core/platform/dvxPlatform.h | 45 +- docs/dvx_api_reference.html | 2933 +++++++++++++++++++++++++ docs/dvx_architecture.html | 1045 +++++++++ docs/dvx_widget_reference.html | 1553 +++++++++++++ docs/dvxbasic_control_reference.html | 1687 ++++++++++++++ docs/dvxbasic_ide_guide.html | 895 ++++++++ docs/dvxbasic_language_reference.html | 1973 +++++++++++++++++ 10 files changed, 10125 insertions(+), 43 deletions(-) create mode 100644 docs/dvx_api_reference.html create mode 100644 docs/dvx_architecture.html create mode 100644 docs/dvx_widget_reference.html create mode 100644 docs/dvxbasic_control_reference.html create mode 100644 docs/dvxbasic_ide_guide.html create mode 100644 docs/dvxbasic_language_reference.html diff --git a/apps/dvxbasic/compiler/parser.c b/apps/dvxbasic/compiler/parser.c index e2205fb..0505308 100644 --- a/apps/dvxbasic/compiler/parser.c +++ b/apps/dvxbasic/compiler/parser.c @@ -247,6 +247,9 @@ static void addPredefConsts(BasParserT *p) { addPredefConst(p, "vbYes", 3); addPredefConst(p, "vbNo", 4); addPredefConst(p, "vbRetry", 5); + + // Show mode flags + addPredefConst(p, "vbModal", 1); } @@ -1911,9 +1914,14 @@ static void parseAssignOrCall(BasParserT *p) { basEmitU16(&p->cg, nameIdx); basEmit8(&p->cg, OP_LOAD_FORM); uint8_t modal = 0; - if (check(p, TOK_INT_LIT) || check(p, TOK_IDENT)) { - // Parse modal flag - if (check(p, TOK_INT_LIT) && p->lex.token.intVal != 0) { + if (check(p, TOK_INT_LIT)) { + if (p->lex.token.intVal != 0) { + modal = 1; + } + advance(p); + } else if (check(p, TOK_IDENT)) { + BasSymbolT *modSym = basSymTabFind(&p->sym, p->lex.token.text); + if (modSym && modSym->kind == SYM_CONST && modSym->constInt != 0) { modal = 1; } advance(p); @@ -5034,6 +5042,12 @@ static void parseStatement(BasParserT *p) { modal = 1; } advance(p); + } else if (check(p, TOK_IDENT)) { + BasSymbolT *modSym = basSymTabFind(&p->sym, p->lex.token.text); + if (modSym && modSym->kind == SYM_CONST && modSym->constInt != 0) { + modal = 1; + } + advance(p); } basEmit8(&p->cg, OP_SHOW_FORM); basEmit8(&p->cg, modal); diff --git a/core/dvxFont.h b/core/dvxFont.h index 78e178e..fd42988 100644 --- a/core/dvxFont.h +++ b/core/dvxFont.h @@ -5,12 +5,8 @@ // byte copy of the font stored in the VGA BIOS ROM. // // Embedding as a static const array (rather than reading from the VGA ROM -// at INT 10h) serves two purposes: -// 1. The data is available on non-DOS platforms (Linux/SDL) where no -// VGA BIOS exists. -// 2. On DOS, reading the VGA ROM font requires a real-mode interrupt -// call during init, and the data would need to be copied somewhere -// anyway. Compiling it in is simpler and more portable. +// at INT 10h) avoids a real-mode interrupt call during init and the need +// to copy the data from the ROM. Compiling it in is simpler. // // The glyph format is 1 bit per pixel, 8 pixels wide, with MSB = leftmost // pixel. Each glyph occupies 16 consecutive bytes. The drawing code in diff --git a/core/dvxTypes.h b/core/dvxTypes.h index f2dcf72..140f927 100644 --- a/core/dvxTypes.h +++ b/core/dvxTypes.h @@ -52,8 +52,7 @@ typedef struct { // // The single display context passed by pointer through every layer. // Using one struct instead of globals makes the entire stack reentrant -// in principle and simplifies testing under Linux (where lfb points to -// an SDL surface instead of real VESA memory). +// in principle and keeps the API clean. // // The double-buffer strategy (backBuf in system RAM, lfb is the real // framebuffer) exists because writes to video memory over the PCI bus @@ -162,8 +161,8 @@ typedef struct { // (x = col * 8), glyph lookup is a single array index, and the 1bpp // format means each scanline of a glyph is exactly one byte. // -// Two font sizes are provided (8x14 and 8x16), matching the standard -// VGA ROM fonts and CP437 encoding. Proportional fonts would require +// One font size is provided (8x16), matching the standard +// VGA ROM font and CP437 encoding. Proportional fonts would require // glyph-width tables, kerning, and per-character positioning -- none of // which is worth the complexity for a DOS-era window manager targeting // 640x480 screens. The 8-pixel width also aligns nicely with byte @@ -173,7 +172,7 @@ typedef struct { typedef struct { int32_t charWidth; // fixed width per glyph (e.g. 8) - int32_t charHeight; // e.g. 14 or 16 + int32_t charHeight; // 16 (only 8x16 font provided) int32_t firstChar; // ASCII code of first glyph (typically 0) int32_t numChars; // number of glyphs (typically 256) const uint8_t *glyphData; // packed 1bpp, charHeight bytes per glyph diff --git a/core/platform/dvxPlatform.h b/core/platform/dvxPlatform.h index 650ff0d..65d8958 100644 --- a/core/platform/dvxPlatform.h +++ b/core/platform/dvxPlatform.h @@ -4,11 +4,9 @@ // interface. To port DVX to a new platform, implement a new // dvxPlatformXxx.c against this header. // -// Currently two implementations exist: +// Currently one implementation exists: // dvxPlatformDos.c -- DJGPP/DPMI: real VESA VBE, INT 33h mouse, // INT 16h keyboard, rep movsd/stosl asm spans -// dvxPlatformLinux.c -- SDL2: software rendering to an SDL window, -// used for development and testing on Linux // // The abstraction covers five areas: video mode setup, framebuffer // flushing, optimized memory spans, mouse input, and keyboard input. @@ -53,13 +51,12 @@ void dvxLog(const char *fmt, ...); // ============================================================ // One-time platform initialisation. On DOS this installs signal handlers -// for clean shutdown on Ctrl+C/Ctrl+Break. On Linux this initializes SDL. +// for clean shutdown on Ctrl+C/Ctrl+Break. void platformInit(void); // Cooperative yield -- give up the CPU timeslice when the event loop has // nothing to do. On DOS this calls __dpmi_yield() to be friendly to -// multitaskers (Windows 3.x, OS/2). On Linux this calls -// SDL_Delay(1) to avoid busy-spinning at 100% CPU. +// multitaskers (Windows 3.x, OS/2). void platformYield(void); // ============================================================ @@ -68,8 +65,7 @@ void platformYield(void); // Probe for a suitable video mode, enable it, map the framebuffer, and // allocate the system RAM backbuffer. On DOS this involves VBE BIOS calls -// and DPMI physical memory mapping. On Linux this creates an SDL window -// and software surface. Fills in all DisplayT fields on success. +// and DPMI physical memory mapping. Fills in all DisplayT fields on success. int32_t platformVideoInit(DisplayT *d, int32_t requestedW, int32_t requestedH, int32_t preferredBpp); // Restore the previous video mode and free all video resources. On DOS @@ -78,13 +74,11 @@ void platformVideoShutdown(DisplayT *d); // Enumerate LFB-capable graphics modes. The callback is invoked for each // available mode. Used by videoInit() to find the best match for the -// requested resolution and depth. On Linux, this reports a fixed set of -// common resolutions since SDL doesn't enumerate modes the same way. +// requested resolution and depth. void platformVideoEnumModes(void (*cb)(int32_t w, int32_t h, int32_t bpp, void *userData), void *userData); // Program the VGA/VESA DAC palette registers (8-bit mode only). pal -// points to RGB triplets (3 bytes per entry). On Linux this is a no-op -// since the SDL surface is always truecolor. +// points to RGB triplets (3 bytes per entry). void platformVideoSetPalette(const uint8_t *pal, int32_t firstEntry, int32_t count); // ============================================================ @@ -94,7 +88,6 @@ void platformVideoSetPalette(const uint8_t *pal, int32_t firstEntry, int32_t cou // Copy a rectangle from the system RAM backbuffer (d->backBuf) to the // display surface (d->lfb). On DOS this copies to real video memory via // the LFB mapping -- the critical path where PCI bus write speed matters. -// On Linux this copies to the SDL surface, then SDL_UpdateRect is called. // Each scanline is copied as a contiguous block; rep movsd on DOS gives // near-optimal bus utilization for aligned 32-bit writes. void platformFlushRect(const DisplayT *d, const RectT *r); @@ -106,8 +99,7 @@ void platformFlushRect(const DisplayT *d, const RectT *r); // These are the innermost loops of the renderer -- called once per // scanline of every rectangle fill, blit, and text draw. On DOS they // use inline assembly: rep stosl for fills (one instruction fills an -// entire scanline) and rep movsd for copies. On Linux they use memset/ -// memcpy which the compiler can auto-vectorize. +// entire scanline) and rep movsd for copies. // // Three variants per operation (8/16/32 bpp) because the fill semantics // differ by depth: 8-bit fills a byte per pixel, 16-bit fills a word @@ -128,7 +120,7 @@ void platformSpanCopy32(uint8_t *dst, const uint8_t *src, int32_t count); // Initialize the mouse driver and constrain movement to the screen bounds. // On DOS this calls INT 33h functions to detect the mouse, set the X/Y -// range, and center the cursor. On Linux this initializes SDL mouse state. +// range, and center the cursor. void platformMouseInit(int32_t screenW, int32_t screenH); // Poll the current mouse state. Buttons is a bitmask: bit 0 = left, @@ -156,8 +148,8 @@ int32_t platformMouseWheelPoll(void); void platformMouseSetAccel(int32_t threshold); // Move the mouse cursor to an absolute screen position. Uses INT 33h -// function 04h on DOS, SDL_WarpMouseInWindow on Linux. Used to clamp -// the cursor to window edges during resize operations. +// function 04h on DOS. Used to clamp the cursor to window edges during +// resize operations. void platformMouseWarp(int32_t x, int32_t y); // ============================================================ @@ -166,8 +158,7 @@ void platformMouseWarp(int32_t x, int32_t y); // Return the current modifier key state in BIOS shift-state format: // bits 0-1 = either shift, bit 2 = ctrl, bit 3 = alt. On DOS this -// reads the BIOS data area at 0040:0017. On Linux this queries SDL -// modifier state and translates to the same bit format. +// reads the BIOS data area at 0040:0017. int32_t platformKeyboardGetModifiers(void); // Non-blocking read of the next key from the keyboard buffer. Returns @@ -179,13 +170,11 @@ bool platformKeyboardRead(PlatformKeyEventT *evt); // Non-blocking read of the next key-up event. Returns true if a // key release was detected. On DOS this requires an INT 9 hook to -// detect break codes (scan code with bit 7 set). On Linux this -// uses SDL_KEYUP events. +// detect break codes (scan code with bit 7 set). bool platformKeyUpRead(PlatformKeyEventT *evt); // Install/remove the INT 9 hook for key-up detection. On DOS this -// chains the hardware keyboard interrupt. On Linux this is a no-op -// (SDL provides key-up events natively). Call Init before using +// chains the hardware keyboard interrupt. Call Init before using // platformKeyUpRead, and Shutdown before exit. void platformKeyUpInit(void); void platformKeyUpShutdown(void); @@ -209,7 +198,6 @@ char platformAltScanToChar(int32_t scancode); // The display pointer provides the current video mode info. Returns a // pointer to a static buffer valid for the lifetime of the process. // On DOS this uses CPUID, RDTSC, DPMI, INT 21h, INT 33h, and VBE. -// On other platforms it returns whatever the OS can report. const char *platformGetSystemInfo(const DisplayT *display); // ============================================================ @@ -219,7 +207,6 @@ const char *platformGetSystemInfo(const DisplayT *display); // Validate a filename against platform-specific rules. On DOS this // enforces 8.3 naming (no long filenames), checks for reserved device // names (CON, PRN, etc.), and rejects characters illegal in FAT filenames. -// On Linux the rules are much more permissive (just no slashes or NUL). // Returns NULL if the filename is valid, or a human-readable error string // describing why it's invalid. Used by the file dialog's save-as validation. const char *platformValidateFilename(const char *name); @@ -272,11 +259,11 @@ void platformVideoFreeBuffers(DisplayT *d); // Return a pointer to the last directory separator in path, or NULL if // none is found. On DOS this checks both '/' and '\\' since DJGPP -// accepts either. On other platforms only '/' is recognised. +// accepts either. char *platformPathDirEnd(const char *path); // Return the platform's native line ending string. -// "\r\n" on DOS/Windows, "\n" on Unix/Linux. +// "\r\n" on DOS. const char *platformLineEnding(void); // Strip platform-specific line ending characters from a buffer in place. @@ -290,7 +277,7 @@ int32_t platformStripLineEndings(char *buf, int32_t len); // Register platform and C runtime symbols with the dynamic module // loader so that DXE modules can resolve them at load time. On DOS // this calls dlregsym() with the full DJGPP libc/libm/libgcc/platform -// export table. On platforms without DXE (Linux/SDL), this is a no-op. +// export table. void platformRegisterDxeExports(void); // ============================================================ diff --git a/docs/dvx_api_reference.html b/docs/dvx_api_reference.html new file mode 100644 index 0000000..93c1f6a --- /dev/null +++ b/docs/dvx_api_reference.html @@ -0,0 +1,2933 @@ + + + + +DVX GUI API Reference + + + + +
+

DVX GUI API Reference

+

DOS Visual eXecutive -- Complete public API documentation generated from source headers

+
+ +
+ + + + + + + + + + + +
+

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. +
+
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 (e.g. 0xF800 for red in 565)
+
int32_t redShift, greenShift, blueShift
Bit position of each color field
+
int32_t redBits, greenBits, blueBits
Number of bits per channel (5, 6, 8, etc.)
+
+
+
+ +
+
DisplayT
+
+ Single display context passed by pointer through every layer. All drawing targets + the backBuf; only dirty rects are flushed to lfb. +
+
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. +
+
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). +
+
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. +
+
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). +
+
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. +
+
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. +
+
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. +
+
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 since last icon refresh
+
bool needsPaint
true until first onPaint call (auto-paint on next frame)
+
int32_t maxW, maxH
Maximum dimensions (WM_MAX_FROM_SCREEN = use screen size)
+
int32_t preMaxX, preMaxY, preMaxW, preMaxH
Saved geometry before maximize (for restore)
+
uint8_t *contentBuf
Per-window content backbuffer
+
int32_t contentPitch
Content buffer bytes per row
+
uint8_t *iconData
Icon pixel data (display format), NULL if none
+
int32_t iconW, iconH, iconPitch
Icon image dimensions and row 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 no widgets)
+
MenuT *contextMenu
Right-click context menu (NULL if none)
+
AccelTableT *accelTable
Keyboard accelerator table (NULL if none)
+
void *userData
Application-defined data pointer
+
+

Callbacks:

+
+
onPaint(WindowT *win, RectT *dirtyArea)
Content repaint requested
+
onKey(WindowT *win, int32_t key, int32_t mod)
Key press
+
onKeyUp(WindowT *win, int32_t scancode, int32_t mod)
Key release
+
onMouse(WindowT *win, int32_t x, int32_t y, int32_t buttons)
Mouse event (content-relative coords)
+
onResize(WindowT *win, int32_t newW, int32_t newH)
Window resized
+
onClose(WindowT *win)
Close requested
+
onMenu(WindowT *win, int32_t menuId)
Menu item or accelerator activated
+
onScroll(WindowT *win, ScrollbarOrientE orient, int32_t value)
Scrollbar value changed
+
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. +
+
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. +
+
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. +
+
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. +
+
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). +
+
int32_t w, h
Resolution
+
int32_t bpp
Bits per pixel
+
+
+
+ +
+
CursorT
+
+ Software-rendered 16x16 cursor using AND/XOR mask encoding. +
+
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

+ + + + + + + +
MacroDescription
BEVEL_RAISED(cs, bw)Raised bevel style from a ColorSchemeT pointer 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

+ + + + + + + + + + + + +
DefineValueDescription
CHROME_BORDER_WIDTH4Outer frame border width
CHROME_TITLE_HEIGHT20Title bar height
CHROME_TITLE_PAD4Title text padding
CHROME_INNER_BORDER2Inner chrome border
CHROME_MENU_HEIGHT20Menu bar height
CHROME_TOTAL_TOP26Total inset from top of frame to content
CHROME_TOTAL_SIDE6Total inset from side of frame to content
CHROME_TOTAL_BOTTOM6Total inset from bottom of frame to content
CHROME_CLOSE_BTN_SIZE16Close button gadget size
+ +

Hit Test Constants

+ + + + + + + + + + + + + +
DefineValueDescription
HIT_CONTENT0Content area
HIT_TITLE1Title bar
HIT_CLOSE2Close gadget
HIT_RESIZE3Resize border
HIT_MENU4Menu bar
HIT_VSCROLL5Vertical scrollbar
HIT_HSCROLL6Horizontal scrollbar
HIT_MINIMIZE7Minimize gadget
HIT_MAXIMIZE8Maximize gadget
HIT_NONE-1No window hit (desktop)
+ +

Mouse Button Flags

+ + + + + + +
DefineValueDescription
MOUSE_LEFT1Left mouse button
MOUSE_RIGHT2Right mouse button
MOUSE_MIDDLE4Middle mouse button
+ +

Accelerator Modifier Flags

+ + + + + + +
DefineValueDescription
ACCEL_SHIFT0x03Shift key (matches BIOS shift state bits)
ACCEL_CTRL0x04Ctrl key
ACCEL_ALT0x08Alt key
+ +

Extended Key Codes

+ + + + + + + + + + +
DefineDescription
KEY_F1 .. KEY_F12Function keys (scancode | 0x100)
KEY_INSERTInsert key
KEY_DELETEDelete key
KEY_HOMEHome key
KEY_ENDEnd key
KEY_PGUPPage Up key
KEY_PGDNPage Down key
+ +

Resize Edge Flags

+ + + + + + + + +
DefineValueDescription
RESIZE_NONE0No resize edge
RESIZE_LEFT1Left edge
RESIZE_RIGHT2Right edge
RESIZE_TOP4Top edge
RESIZE_BOTTOM8Bottom edge (combinable via OR for corners)
+ +

Utility Macros

+ + + + + +
MacroDescription
DVX_MIN(a, b)Return the smaller of two values
DVX_MAX(a, b)Return the larger of two values
+ +
+ + + + + +
+

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

+ + + + + + + + + + + +
DefineValueDescription
CURSOR_ARROW0Standard arrow (hot spot at tip)
CURSOR_RESIZE_H1Horizontal resize (left/right arrows)
CURSOR_RESIZE_V2Vertical resize (up/down arrows)
CURSOR_RESIZE_DIAG_NWSE3NW-SE diagonal resize
CURSOR_RESIZE_DIAG_NESW4NE-SW diagonal resize
CURSOR_BUSY5Hourglass (wait)
CURSOR_CROSSHAIR6Crosshair for placement
CURSOR_COUNT7Total 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

+

+ 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. +

+ +
+
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.

+
+
d
Display context to initialize
+
requestedW, requestedH
Desired screen resolution
+
preferredBpp
Preferred bits per pixel (8, 15, 16, or 32)
+
+

Returns: 0 on success, negative on failure

+
+
+ +
+
void videoShutdown(DisplayT *d);
+
+

Restore VGA text mode (mode 3), unmap the LFB, and free the backbuffer. + Safe to call even if videoInit() failed.

+
+
d
Display context to shut down
+
+
+
+ +
+
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.

+
+
d
Display context (provides pixel format)
+
r, g, b
Color components (0-255)
+
+

Returns: Native pixel value suitable for direct framebuffer write

+
+
+ +
+
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.

+
+
d
Display context
+
x, y, w, h
Clip rectangle in screen coordinates
+
+
+
+ +
+
void resetClipRect(DisplayT *d);
+
+

Reset the clip rectangle to the full display dimensions.

+
+
d
Display context
+
+
+
+ +
+ + + + + +
+

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. +

+ +
+
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().

+
+
ops
BlitOpsT to populate
+
d
Initialized display context
+
+
+
+ +
+
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.

+
+
d
Display context
+
ops
Blit operations vtable
+
x, y, w, h
Rectangle to fill
+
color
Packed pixel color
+
+
+
+ +
+
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.

+
+
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
+
+
+
+ +
+
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.

+
+
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
+
+
+
+ +
+
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.

+
+
d
Display context
+
ops
Blit operations vtable
+
x, y, w, h
Outer bevel rectangle
+
style
Bevel colors and width
+
+
+
+ +
+
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).

+
+
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)

+
+
+ +
+
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.

+
+
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
+
+
+
+ +
+
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).

+
+
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
+
+
+
+ +
+
int32_t textWidth(const BitmapFontT *font, const char *text);
+
+

Return the pixel width of a null-terminated string (strlen(text) * charWidth).

+
+
font
Bitmap font
+
text
Null-terminated string
+
+

Returns: Width in pixels

+
+
+ +
+
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'.

+
+
text
Text with optional & accelerator marker
+
+

Returns: Lowercase accelerator character, or 0 if none

+
+
+ +
+
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.

+
+
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
+
+
+
+ +
+
int32_t textWidthAccel(const BitmapFontT *font, const char *text);
+
+

Measure text width excluding & markers (so "&File" measures as 4 chars).

+
+
font
Bitmap font
+
text
Text with optional & markers
+
+

Returns: Width in pixels

+
+
+ +
+
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.

+
+
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
+
+
+
+ +
+
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.

+
+
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)
+
+
+
+ +
+
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.

+
+
d
Display context
+
ops
Blit operations vtable
+
x, y, w, h
Focus rectangle bounds
+
color
Dot color (packed)
+
+
+
+ +
+
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).

+
+
d
Display context
+
ops
Blit operations vtable
+
x, y
Start position
+
w
Width in pixels
+
color
Packed pixel color
+
+
+
+ +
+
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).

+
+
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

+

+ 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. +

+ +
+
void dirtyListInit(DirtyListT *dl);
+
+

Zero the dirty rect count. Called at the start of each frame.

+
+
dl
Dirty list to initialize
+
+
+
+ +
+
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.

+
+
dl
Dirty list
+
x, y, w, h
Dirty rectangle in screen coordinates
+
+
+
+ +
+
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.

+
+
dl
Dirty list to merge
+
+
+
+ +
+
void dirtyListClear(DirtyListT *dl);
+
+

Reset the dirty list to empty (sets count to 0).

+
+
dl
Dirty list to clear
+
+
+
+ +
+
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.

+
+
d
Display context
+
r
Rectangle to flush
+
+
+
+ +
+
bool rectIntersect(const RectT *a, const RectT *b, RectT *result);
+
+

Compute the intersection of two rectangles.

+
+
a, b
Input rectangles
+
result
Output: intersection rectangle (valid only when return is true)
+
+

Returns: true if the rectangles overlap, false if disjoint

+
+
+ +
+
bool rectIsEmpty(const RectT *r);
+
+

Test whether a rectangle has zero or negative area.

+
+
r
Rectangle to test
+
+

Returns: true if w <= 0 or h <= 0

+
+
+ +
+ + + + + +
+

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

+ +
+
void wmInit(WindowStackT *stack);
+
+

Zero the window stack. Must be called before any other WM function.

+
+
stack
Window stack to initialize
+
+
+
+ +

Window Lifecycle

+ +
+
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.

+
+
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

+
+
+ +
+
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.

+
+
stack
Window stack
+
win
Window to destroy
+
+
+
+ +

Z-Order and Focus

+ +
+
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.

+
+
stack
Window stack
+
dl
Dirty list for repaint marking
+
idx
Stack index of window to raise
+
+
+
+ +
+
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.

+
+
stack
Window stack
+
dl
Dirty list
+
idx
Stack index of window to focus
+
+
+
+ +

Geometry

+ +
+
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.

+
+
win
Window to update
+
+
+
+ +
+
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.

+
+
win
Window to reallocate
+
d
Display context (for bytes-per-pixel)
+
+

Returns: 0 on success, -1 on allocation failure

+
+
+ +
+
void wmMinWindowSize(const WindowT *win, int32_t *minW, int32_t *minH);
+
+

Get the minimum window size. Accounts for chrome, gadgets, and menu bar.

+
+
win
Window
+
minW, minH
Output: minimum width and height
+
+
+
+ +

Menu Bar

+ +
+
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.

+
+
win
Window to add menu bar to
+
+

Returns: Pointer to the new MenuBarT

+
+
+ +
+
void wmDestroyMenuBar(WindowT *win);
+
+

Free the menu bar and reclaim the content area.

+
+
win
Window to remove menu bar from
+
+
+
+ +
+
MenuT *wmAddMenu(MenuBarT *bar, const char *label);
+
+

Append a dropdown menu to the menu bar. The label supports & accelerator markers + (e.g. "&File").

+
+
bar
Menu bar
+
label
Menu label text
+
+

Returns: Pointer to the new MenuT to populate with items

+
+
+ +
+
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.

+
+
menu
Menu to append to
+
label
Item label (supports & markers)
+
id
Application-defined command ID
+
+
+
+ +
+
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.

+
+
menu
Menu to append to
+
label
Item label
+
id
Command ID
+
checked
Initial checked state
+
+
+
+ +
+
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.

+
+
menu
Menu to append to
+
label
Item label
+
id
Command ID
+
checked
Initial checked state
+
+
+
+ +
+
void wmAddMenuSeparator(MenuT *menu);
+
+

Insert a horizontal separator line. Separators are not interactive.

+
+
menu
Menu to append separator to
+
+
+
+ +
+
bool wmMenuItemIsChecked(MenuBarT *bar, int32_t id);
+
+

Query the checked state of a menu item by command ID. Searches all menus in the bar.

+
+
bar
Menu bar
+
id
Command ID to query
+
+

Returns: true if checked

+
+
+ +
+
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.

+
+
bar
Menu bar
+
id
Command ID
+
checked
New checked state
+
+
+
+ +
+
void wmMenuItemSetEnabled(MenuBarT *bar, int32_t id, bool enabled);
+
+

Enable or disable a menu item by command ID.

+
+
bar
Menu bar
+
id
Command ID
+
enabled
true = enabled, false = grayed out
+
+
+
+ +
+
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.

+
+
parentMenu
Parent menu to attach submenu to
+
label
Submenu label text
+
+

Returns: Pointer to the child MenuT, or NULL on allocation failure

+
+
+ +
+
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

+
+
+ +
+
void wmFreeMenu(MenuT *menu);
+
+

Free a standalone menu allocated with wmCreateMenu(). Also frees any heap-allocated + submenu children recursively.

+
+
menu
Menu to free
+
+
+
+ +

Scrollbars

+ +
+
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.

+
+
win
Window
+
min, max
Scroll value range
+
pageSize
Visible portion (controls thumb size)
+
+

Returns: Pointer to the new ScrollbarT

+
+
+ +
+
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.

+
+
win
Window
+
min, max
Scroll value range
+
pageSize
Visible portion
+
+

Returns: Pointer to the new ScrollbarT

+
+
+ +

Drawing

+ +
+
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.

+
+
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
+
+
+
+ +
+
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).

+
+
d
Display context
+
ops
Blit operations vtable
+
win
Window
+
clipTo
Dirty rectangle
+
+
+
+ +
+
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.

+
+
d
Display context
+
ops
Blit operations vtable
+
colors
Color scheme
+
win
Window
+
clipTo
Dirty rectangle
+
+
+
+ +
+
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.

+
+
d
Display context
+
ops
Blit operations vtable
+
colors
Color scheme
+
stack
Window stack
+
clipTo
Dirty rectangle
+
+
+
+ +

Hit Testing

+ +
+
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.

+
+
stack
Window stack
+
mx, my
Screen coordinates
+
hitPart
Output: HIT_CONTENT, HIT_TITLE, HIT_CLOSE, HIT_RESIZE, HIT_MENU, HIT_VSCROLL, HIT_HSCROLL, HIT_MINIMIZE, HIT_MAXIMIZE
+
+

Returns: Stack index of hit window, or -1 for desktop

+
+
+ +
+
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.

+
+
win
Window
+
mx, my
Screen coordinates
+
+

Returns: Bitmask of RESIZE_LEFT / RESIZE_RIGHT / RESIZE_TOP / RESIZE_BOTTOM

+
+
+ +
+
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.

+
+
stack
Window stack
+
d
Display context
+
mx, my
Screen coordinates
+
+

Returns: Stack index of the minimized window, or -1

+
+
+ +

Drag and Resize

+ +
+
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.

+
+
stack
Window stack
+
idx
Stack index of window to drag
+
mouseX, mouseY
Current mouse position
+
+
+
+ +
+
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.

+
+
stack
Window stack
+
dl
Dirty list
+
mouseX, mouseY
Current mouse position
+
screenW, screenH
Screen dimensions (for clamping)
+
+
+
+ +
+
void wmDragEnd(WindowStackT *stack);
+
+

End the current drag operation. Clears dragWindow state.

+
+
stack
Window stack
+
+
+
+ +
+
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.

+
+
stack
Window stack
+
idx
Stack index
+
edge
Bitmask of RESIZE_xxx flags
+
mouseX, mouseY
Current mouse position
+
+
+
+ +
+
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.

+
+
stack
Window stack
+
dl
Dirty list
+
d
Display context
+
mouseX, mouseY
In/out: mouse position (clamped on return)
+
+
+
+ +
+
void wmResizeEnd(WindowStackT *stack);
+
+

End the current resize operation. Clears resizeWindow state.

+
+
stack
Window stack
+
+
+
+ +

Scrollbar Interaction

+ +
+
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.

+
+
stack
Window stack
+
dl
Dirty list
+
idx
Stack index of window
+
orient
SCROLL_VERTICAL or SCROLL_HORIZONTAL
+
mx, my
Click screen coordinates
+
+
+
+ +
+
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.

+
+
stack
Window stack
+
dl
Dirty list
+
mx, my
Current mouse position
+
+
+
+ +
+
void wmScrollbarEnd(WindowStackT *stack);
+
+

End an active scrollbar thumb drag.

+
+
stack
Window stack
+
+
+
+ +

Minimize / Maximize / Restore

+ +
+
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.

+
+
stack
Window stack
+
dl
Dirty list
+
d
Display context
+
win
Window to maximize
+
+
+
+ +
+
void wmMinimize(WindowStackT *stack, DirtyListT *dl, WindowT *win);
+
+

Minimize a window. Hides the window and shows an icon at the bottom of the screen.

+
+
stack
Window stack
+
dl
Dirty list
+
win
Window to minimize
+
+
+
+ +
+
void wmRestore(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);
+
+

Restore a maximized window to its pre-maximize geometry.

+
+
stack
Window stack
+
dl
Dirty list
+
d
Display context
+
win
Maximized window to restore
+
+
+
+ +
+
void wmRestoreMinimized(WindowStackT *stack, DirtyListT *dl, const DisplayT *d, WindowT *win);
+
+

Restore a minimized window (show it again and remove the icon).

+
+
stack
Window stack
+
dl
Dirty list
+
d
Display context
+
win
Minimized window to restore
+
+
+
+ +

Minimized Icon Layout

+ +
+
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.

+
+
d
Display context
+
index
Ordinal index of the minimized icon
+
x, y
Output: screen position
+
+
+
+ +
+
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.

+
+
stack
Window stack
+
d
Display context
+
y, h
Output: vertical extent of icon area
+
+
+
+ +

Miscellaneous

+ +
+
void wmSetTitle(WindowT *win, DirtyListT *dl, const char *title);
+
+

Set the window title and dirty the title bar for repaint.

+
+
win
Window
+
dl
Dirty list
+
title
New title text
+
+
+
+ +
+
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.

+
+
win
Window
+
path
Image file path
+
d
Display context
+
+

Returns: 0 on success, -1 on failure

+
+
+ +
+ + + + + +
+

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

+ +
+
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

+ +
+
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.

+
+
ctx
Application context to initialize
+
requestedW, requestedH
Desired screen resolution
+
preferredBpp
Preferred bits per pixel
+
+

Returns: 0 on success, negative on failure

+
+
+ +
+
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().

+
+
ctx
Application context
+
+
+
+ +
+
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.

+
+
ctx
Application context
+
requestedW, requestedH
New resolution
+
preferredBpp
New bits per pixel
+
+

Returns: 0 on success, -1 on failure (old mode restored)

+
+
+ +

Event Loop

+ +
+
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.

+
+
ctx
Application context
+
+
+
+ +
+
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).

+
+
ctx
Application context
+
+

Returns: false when the GUI wants to exit

+
+
+ +
+
void dvxQuit(AppContextT *ctx);
+
+

Request exit from the main event loop (sets ctx->running = false).

+
+
ctx
Application context
+
+
+
+ +

Window Management

+ +
+
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.

+
+
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

+
+
+ +
+
WindowT *dvxCreateWindowCentered(AppContextT *ctx, const char *title, int32_t w, int32_t h, bool resizable);
+
+

Convenience wrapper that centers the window on screen.

+
+
ctx
Application context
+
title
Window title
+
w, h
Outer frame dimensions
+
resizable
true = allow user resize
+
+

Returns: Pointer to new WindowT

+
+
+ +
+
void dvxDestroyWindow(AppContextT *ctx, WindowT *win);
+
+

Destroy a window, free all its resources, and dirty its former region.

+
+
ctx
Application context
+
win
Window to destroy
+
+
+
+ +
+
void dvxRaiseWindow(AppContextT *ctx, WindowT *win);
+
+

Raise a window to the top of the Z-order and give it focus.

+
+
ctx
Application context
+
win
Window to raise
+
+
+
+ +
+
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.

+
+
ctx
Application context
+
win
Window to fit
+
+
+
+ +
+
void dvxFitWindowW(AppContextT *ctx, WindowT *win);
+
+

Resize window width only to fit widget tree's minimum width (plus chrome).

+
+
ctx
Application context
+
win
Window to fit
+
+
+
+ +
+
void dvxFitWindowH(AppContextT *ctx, WindowT *win);
+
+

Resize window height only to fit widget tree's minimum height (plus chrome).

+
+
ctx
Application context
+
win
Window to fit
+
+
+
+ +
+
void dvxResizeWindow(AppContextT *ctx, WindowT *win, int32_t newW, int32_t newH);
+
+

Programmatically resize a window to the specified outer dimensions.

+
+
ctx
Application context
+
win
Window to resize
+
newW, newH
New outer frame dimensions
+
+
+
+ +
+
void dvxMinimizeWindow(AppContextT *ctx, WindowT *win);
+
+

Minimize a window (show as icon at bottom of screen).

+
+
ctx
Application context
+
win
Window to minimize
+
+
+
+ +
+
void dvxMaximizeWindow(AppContextT *ctx, WindowT *win);
+
+

Maximize a window (expand to fill screen or maxW/maxH).

+
+
ctx
Application context
+
win
Window to maximize
+
+
+
+ +
+
void dvxHideWindow(AppContextT *ctx, WindowT *win);
+
+

Hide a window without destroying it. Marks the exposed region dirty.

+
+
ctx
Application context
+
win
Window to hide
+
+
+
+ +
+
void dvxShowWindow(AppContextT *ctx, WindowT *win);
+
+

Show a previously hidden window. Marks its region dirty for repaint.

+
+
ctx
Application context
+
win
Window to show
+
+
+
+ +

Invalidation

+ +
+
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.

+
+
ctx
Application context
+
win
Window
+
x, y, w, h
Dirty rectangle in content-relative coordinates
+
+
+
+ +
+
void dvxInvalidateWindow(AppContextT *ctx, WindowT *win);
+
+

Mark the entire window content area as dirty.

+
+
ctx
Application context
+
win
Window to invalidate
+
+
+
+ +

Window Properties

+ +
+
void dvxSetTitle(AppContextT *ctx, WindowT *win, const char *title);
+
+

Set a window's title text and dirty the title bar.

+
+
ctx
Application context
+
win
Window
+
title
New title text
+
+
+
+ +
+
int32_t dvxSetWindowIcon(AppContextT *ctx, WindowT *win, const char *path);
+
+

Load an icon for a window from an image file.

+
+
ctx
Application context
+
win
Window
+
path
Image file path
+
+

Returns: 0 on success, -1 on failure

+
+
+ +
+
void dvxSetBusy(AppContextT *ctx, bool busy);
+
+

Set or clear busy state. While busy, the hourglass cursor is shown and input is blocked.

+
+
ctx
Application context
+
busy
true = show hourglass, false = normal
+
+
+
+ +

Accessors

+ +
+
const BitmapFontT *dvxGetFont(const AppContextT *ctx);
+
+

Get a pointer to the default font.

+
+
ctx
Application context
+
+

Returns: Pointer to the active BitmapFontT

+
+
+ +
+
const ColorSchemeT *dvxGetColors(const AppContextT *ctx);
+
+

Get a pointer to the current color scheme.

+
+
ctx
Application context
+
+

Returns: Pointer to the active ColorSchemeT

+
+
+ +
+
DisplayT *dvxGetDisplay(AppContextT *ctx);
+
+

Get a pointer to the display context.

+
+
ctx
Application context
+
+

Returns: Pointer to the DisplayT

+
+
+ +
+
const BlitOpsT *dvxGetBlitOps(const AppContextT *ctx);
+
+

Get a pointer to the blit operations vtable.

+
+
ctx
Application context
+
+

Returns: Pointer to the active BlitOpsT

+
+
+ +
+
const VideoModeInfoT *dvxGetVideoModes(const AppContextT *ctx, int32_t *count);
+
+

Return the list of available video modes enumerated at init time.

+
+
ctx
Application context
+
count
Output: number of mode entries
+
+

Returns: Pointer to the VideoModeInfoT array

+
+
+ +

Color Scheme

+ +
+
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.

+
+
ctx
Application context
+
id
Color ID (ColorIdE)
+
r, g, b
RGB values (0-255)
+
+
+
+ +
+
void dvxGetColor(const AppContextT *ctx, ColorIdE id, uint8_t *r, uint8_t *g, uint8_t *b);
+
+

Get a color's RGB values by ID.

+
+
ctx
Application context
+
id
Color ID (ColorIdE)
+
r, g, b
Output: RGB values
+
+
+
+ +
+
void dvxApplyColorScheme(AppContextT *ctx);
+
+

Apply all colors from ctx->colorRgb[] at once (repack + full repaint).

+
+
ctx
Application context
+
+
+
+ +
+
void dvxResetColorScheme(AppContextT *ctx);
+
+

Reset all colors to the built-in defaults and repaint.

+
+
ctx
Application context
+
+
+
+ +
+
bool dvxLoadTheme(AppContextT *ctx, const char *filename);
+
+

Load a theme file (INI format with [colors] section) and apply it.

+
+
ctx
Application context
+
filename
Path to theme INI file
+
+

Returns: true on success

+
+
+ +
+
bool dvxSaveTheme(const AppContextT *ctx, const char *filename);
+
+

Save the current color scheme to a theme file.

+
+
ctx
Application context
+
filename
Output file path
+
+

Returns: true on success

+
+
+ +
+
const char *dvxColorName(ColorIdE id);
+
+

Return the INI key name for a color ID (e.g. "desktop", "windowFace").

+
+
id
Color ID
+
+

Returns: Static string

+
+
+ +
+
const char *dvxColorLabel(ColorIdE id);
+
+

Return a human-readable display label (e.g. "Desktop", "Cursor Color").

+
+
id
Color ID
+
+

Returns: Static string

+
+
+ +

Wallpaper

+ +
+
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.

+
+
ctx
Application context
+
path
Image file path, or NULL to clear
+
+

Returns: true on success

+
+
+ +
+
void dvxSetWallpaperMode(AppContextT *ctx, WallpaperModeE mode);
+
+

Change the wallpaper display mode and re-render. No effect if no wallpaper is loaded.

+
+
ctx
Application context
+
mode
WallpaperStretchE, WallpaperTileE, or WallpaperCenterE
+
+
+
+ +

Mouse Configuration

+ +
+
void dvxSetMouseConfig(AppContextT *ctx, int32_t wheelDir, int32_t dblClickMs, int32_t accelThreshold);
+
+

Configure mouse behavior.

+
+
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

+ +
+
AccelTableT *dvxCreateAccelTable(void);
+
+

Allocate a new accelerator table. Attach to a window via win->accelTable.

+

Returns: Pointer to new AccelTableT

+
+
+ +
+
void dvxFreeAccelTable(AccelTableT *table);
+
+

Free an accelerator table and its entries.

+
+
table
Table to free
+
+
+
+ +
+
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.

+
+
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

+ +
+
void dvxCascadeWindows(AppContextT *ctx);
+
+

Cascade all visible, non-minimized windows. Each is offset diagonally by the title bar height.

+
+
ctx
Application context
+
+
+
+ +
+
void dvxTileWindows(AppContextT *ctx);
+
+

Arrange visible windows in an NxM grid filling the screen.

+
+
ctx
Application context
+
+
+
+ +
+
void dvxTileWindowsH(AppContextT *ctx);
+
+

Tile windows horizontally (side by side, equal width, full height).

+
+
ctx
Application context
+
+
+
+ +
+
void dvxTileWindowsV(AppContextT *ctx);
+
+

Tile windows vertically (stacked, full width, equal height).

+
+
ctx
Application context
+
+
+
+ +

Image I/O

+ +
+
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().

+
+
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

+
+
+ +
+
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().

+
+
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

+
+
+ +
+
void dvxFreeImage(uint8_t *data);
+
+

Free a pixel buffer returned by dvxLoadImage() or dvxLoadImageFromMemory().

+
+
data
Buffer to free
+
+
+
+ +
+
bool dvxImageInfo(const char *path, int32_t *outW, int32_t *outH);
+
+

Query image dimensions without decoding the full file.

+
+
path
Image file path
+
outW, outH
Output: image dimensions
+
+

Returns: true on success

+
+
+ +
+
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.

+
+
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

+ +
+
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.

+
+
ctx
Application context
+
path
Output PNG file path
+
+

Returns: 0 on success, -1 on failure

+
+
+ +
+
int32_t dvxWindowScreenshot(AppContextT *ctx, WindowT *win, const char *path);
+
+

Save a window's content to a PNG file.

+
+
ctx
Application context
+
win
Window
+
path
Output PNG file path
+
+

Returns: 0 on success, -1 on failure

+
+
+ +

Clipboard

+ +
+
void dvxClipboardCopy(const char *text, int32_t len);
+
+

Copy text to the process-wide clipboard buffer. Simple static buffer (not inter-process).

+
+
text
Text to copy
+
len
Length in bytes
+
+
+
+ +
+
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.

+
+
outLen
Output: length of clipboard text
+
+

Returns: Clipboard text, or NULL

+
+
+ +

Resource Loading

+ +
+
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().

+
+
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

+
+
+ +
+
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.

+
+
dxePath
Path to DXE file
+
resName
Resource name
+
buf
Output buffer
+
bufSize
Buffer capacity
+
+

Returns: true on success

+
+
+ +
+
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.

+
+
dxePath
Path to DXE file
+
resName
Resource name
+
outSize
Output: data size in bytes
+
+

Returns: Data buffer, or NULL if not found

+
+
+ +

Utilities

+ +
+
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.

+
+
text
Null-terminated string to hash
+
+

Returns: 32-bit hash value

+
+
+ +
+ + + + + +
+

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

+ +
+
WidgetT
+
+ Core widget structure. Generic across all widget types; type-specific data lives in + the void *data pointer managed by each widget's DXE. +
+
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 window content area)
+
int32_t calcMinW, calcMinH
Computed minimum size (from layout pass)
+
int32_t minW, minH, maxW, maxH, prefW, prefH
Size hints (tagged: wgtPixels/wgtChars/wgtPercent)
+
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 internal 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:

+
+
onClick(WidgetT *w)
Widget clicked
+
onDblClick(WidgetT *w)
Widget double-clicked
+
onChange(WidgetT *w)
Value changed
+
onFocus(WidgetT *w)
Widget gained focus
+
onBlur(WidgetT *w)
Widget lost focus
+
onKeyPress(WidgetT *w, int32_t keyAscii)
ASCII key press
+
onKeyDown(WidgetT *w, int32_t keyCode, int32_t shift)
Key down
+
onKeyUp(WidgetT *w, int32_t keyCode, int32_t shift)
Key up
+
onMouseDown(WidgetT *w, int32_t button, int32_t x, int32_t y)
Mouse button pressed
+
onMouseUp(WidgetT *w, int32_t button, int32_t x, int32_t y)
Mouse button released
+
onMouseMove(WidgetT *w, int32_t button, int32_t x, int32_t y)
Mouse moved
+
onScroll(WidgetT *w, int32_t delta)
Mouse wheel
+
onValidate(WidgetT *w)
Return false to cancel a write
+
+
+
+ +

Size Specification Macros

+ + + + + + +
MacroDescription
wgtPixels(v)Size in pixels
wgtChars(v)Size in character widths (multiplied by charWidth at layout time)
wgtPercent(v)Size as percentage of parent dimension
+ +

Widget Class Flags

+ + + + + + + + + + + + + + + + +
FlagDescription
WCLASS_FOCUSABLECan receive keyboard focus (Tab navigation)
WCLASS_HORIZ_CONTAINERLays out children horizontally (vs. vertical)
WCLASS_PAINTS_CHILDRENWidget handles child rendering itself
WCLASS_NO_HIT_RECURSEHit testing stops here, no child recursion
WCLASS_FOCUS_FORWARDAccel hit forwards focus to next focusable sibling
WCLASS_HAS_POPUPHas dropdown popup overlay
WCLASS_SCROLLABLEAccepts mouse wheel events
WCLASS_SCROLL_CONTAINERScroll container (ScrollPane)
WCLASS_NEEDS_POLLNeeds periodic polling
WCLASS_SWALLOWS_TABTab key goes to widget, not focus navigation
WCLASS_RELAYOUT_ON_SCROLLFull relayout on scrollbar drag
WCLASS_PRESS_RELEASEClick = press + release (Button, ImageButton)
WCLASS_ACCEL_WHEN_HIDDENAccelerator matching works even when invisible
+ +

Window Integration

+ +
+
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.

+
+
ctx
Application context
+
win
Window to initialize
+
+

Returns: Root VBox widget (add children to this)

+
+
+ +

Widget Operations

+ +
+
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.

+
+
w
Any widget in the tree
+
+

Returns: Pointer to the AppContextT

+
+
+ +
+
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).

+
+
w
Widget to invalidate
+
+
+
+ +
+
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).

+
+
w
Widget to repaint
+
+
+
+ +
+
void wgtSetText(WidgetT *w, const char *text);
+
+

Set widget text content (dispatches to the widget class's SET_TEXT handler).

+
+
w
Widget
+
text
New text
+
+
+
+ +
+
const char *wgtGetText(const WidgetT *w);
+
+

Get the widget's current text content.

+
+
w
Widget
+
+

Returns: Text string (empty string if no handler)

+
+
+ +
+
void wgtSetEnabled(WidgetT *w, bool enabled);
+
+

Enable or disable a widget. Disabled widgets are grayed out and do not receive input.

+
+
w
Widget
+
enabled
true = enabled, false = disabled
+
+
+
+ +
+
void wgtSetReadOnly(WidgetT *w, bool readOnly);
+
+

Set read-only mode. Allows scrolling and selection but blocks editing.

+
+
w
Widget
+
readOnly
true = read-only
+
+
+
+ +
+
void wgtSetFocused(WidgetT *w);
+
+

Set keyboard focus to a widget.

+
+
w
Widget to focus
+
+
+
+ +
+
WidgetT *wgtGetFocused(void);
+
+

Get the currently focused widget.

+

Returns: Focused widget, or NULL

+
+
+ +
+
void wgtSetVisible(WidgetT *w, bool visible);
+
+

Show or hide a widget.

+
+
w
Widget
+
visible
true = visible, false = hidden
+
+
+
+ +
+
void wgtSetName(WidgetT *w, const char *name);
+
+

Set a widget's name for lookup via wgtFind().

+
+
w
Widget
+
name
Name string (max MAX_WIDGET_NAME chars)
+
+
+
+ +
+
WidgetT *wgtFind(WidgetT *root, const char *name);
+
+

Find a widget by name. Searches the subtree rooted at root.

+
+
root
Root of subtree to search
+
name
Widget name to find
+
+

Returns: Matching widget, or NULL

+
+
+ +
+
void wgtDestroy(WidgetT *w);
+
+

Destroy a widget and all its children. Removes from parent's child list.

+
+
w
Widget to destroy
+
+
+
+ +
+
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.

+
+
w
Widget
+
text
Tooltip text, or NULL
+
+
+
+ +
+
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.

+
+
win
Window being resized
+
newW, newH
New content dimensions
+
+
+
+ +

Layout

+ +
+
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").

+
+
taggedSize
Tagged size value
+
parentSize
Parent dimension (for PERCENT mode)
+
charWidth
Font character width (for CHARS mode)
+
+

Returns: Size in pixels

+
+
+ +
+
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.

+
+
root
Root widget
+
availW, availH
Available space
+
font
Bitmap font (for character-based sizing)
+
+
+
+ +
+
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.

+
+
root
Root widget
+
d
Display context
+
ops
Blit operations vtable
+
font
Bitmap font
+
colors
Color scheme
+
+
+
+ +

Debug

+ +
+
void wgtSetDebugLayout(AppContextT *ctx, bool enabled);
+
+

Draw colored borders around layout containers for debugging.

+
+
ctx
Application context
+
enabled
true = draw debug borders
+
+
+
+ +

Dynamic Widget Registration

+ +
+
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).

+
+
wclass
Widget class vtable to register
+
+

Returns: Assigned type ID

+
+
+ +
+
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.

+
+
name
Widget type name (e.g. "button", "listbox")
+
api
Pointer to the widget's API struct
+
+
+
+ +
+
const void *wgtGetApi(const char *name);
+
+

Retrieve a registered widget API struct by name.

+
+
name
Widget type name
+
+

Returns: Pointer to the API struct, or NULL if not found

+
+
+ +

Widget Interface Descriptors

+ +
+
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.

+
+
name
Widget type name
+
iface
Interface descriptor
+
+
+
+ +
+
const WgtIfaceT *wgtGetIface(const char *name);
+
+

Retrieve an interface descriptor by widget type name.

+
+
name
Widget type name
+
+

Returns: Interface descriptor, or NULL

+
+
+ +
+
const char *wgtFindByBasName(const char *basName);
+
+

Find a widget type name by its VB-style name (e.g. "CommandButton" -> "button"). + Case-insensitive search.

+
+
basName
VB-style widget name
+
+

Returns: Internal type name, or NULL

+
+
+ +
+
int32_t wgtIfaceCount(void);
+
+

Return the number of registered widget interfaces.

+

Returns: Count of registered interfaces

+
+
+ +
+
const WgtIfaceT *wgtIfaceAt(int32_t idx, const char **outName);
+
+

Get a registered widget interface by index.

+
+
idx
Index (0-based)
+
outName
Output: type name
+
+

Returns: Interface descriptor

+
+
+ +
+
const char *wgtIfaceGetPath(const char *name);
+
+

Get the .wgt DXE file path for a registered widget.

+
+
name
Widget type name
+
+

Returns: File path string

+
+
+ +
+
void wgtIfaceSetPath(const char *name, const char *path);
+
+

Set the .wgt DXE file path for a registered widget (called by the loader).

+
+
name
Widget type name
+
path
DXE file path
+
+
+
+ +
+
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").

+
+
name
Widget type name
+
+

Returns: 1-based index within the DXE file

+
+
+ +

Typed Dispatch Helpers (Inline)

+ +

The following inline functions provide type-safe dispatch through the WidgetClassT +handler table. Each checks for a non-NULL handler before calling.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
FunctionMethod IDDescription
wclsHas(w, methodId)--Check if a handler exists for the given method ID
wclsPaint(w, d, ops, font, colors)WGT_METHOD_PAINTPaint the widget
wclsPaintOverlay(w, d, ops, font, colors)WGT_METHOD_PAINT_OVERLAYPaint overlay (popups, dropdowns)
wclsCalcMinSize(w, font)WGT_METHOD_CALC_MIN_SIZECompute minimum size
wclsLayout(w, font)WGT_METHOD_LAYOUTLayout children
wclsGetLayoutMetrics(w, font, ...)WGT_METHOD_GET_LAYOUT_METRICSGet pad, gap, extraTop, borderW
wclsOnMouse(w, root, vx, vy)WGT_METHOD_ON_MOUSEHandle mouse event
wclsOnKey(w, key, mod)WGT_METHOD_ON_KEYHandle key event
wclsOnAccelActivate(w, root)WGT_METHOD_ON_ACCEL_ACTIVATEHandle accelerator activation
wclsDestroy(w)WGT_METHOD_DESTROYDestroy widget-private data
wclsOnChildChanged(parent, child)WGT_METHOD_ON_CHILD_CHANGEDNotify parent of child change
wclsGetText(w)WGT_METHOD_GET_TEXTGet widget text
wclsSetText(w, text)WGT_METHOD_SET_TEXTSet widget text
wclsClearSelection(w)WGT_METHOD_CLEAR_SELECTIONClear text selection
wclsClosePopup(w)WGT_METHOD_CLOSE_POPUPClose dropdown popup
wclsGetPopupRect(w, font, ...)WGT_METHOD_GET_POPUP_RECTGet popup screen rect
wclsOnDragUpdate(w, root, x, y)WGT_METHOD_ON_DRAG_UPDATEUpdate during drag
wclsOnDragEnd(w, root, x, y)WGT_METHOD_ON_DRAG_ENDEnd drag operation
wclsGetCursorShape(w, vx, vy)WGT_METHOD_GET_CURSOR_SHAPEGet cursor shape for position
wclsPoll(w, win)WGT_METHOD_POLLPeriodic polling (comms, etc.)
wclsQuickRepaint(w, outY, outH)WGT_METHOD_QUICK_REPAINTFast partial repaint
wclsScrollChildIntoView(parent, child)WGT_METHOD_SCROLL_CHILD_INTO_VIEWScroll to make child visible
+ +
+ +
+ + + + + diff --git a/docs/dvx_architecture.html b/docs/dvx_architecture.html new file mode 100644 index 0000000..22a71bf --- /dev/null +++ b/docs/dvx_architecture.html @@ -0,0 +1,1045 @@ + + + + + +DVX Architecture Overview + + + + +

DVX Architecture Overview

+

DOS Visual eXecutive -- A Windowing GUI for DJGPP/DPMI

+ +
+Contents + +
+ + +

1. System Overview

+ +

+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:

+ + +

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.

+ + +

2. 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  |  |
+ |  +------------------------------------------+  |
+ ==================================================
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LayerHeaderResponsibility
1 - VideodvxVideo.hVESA VBE mode negotiation, LFB mapping via DPMI, backbuffer + allocation, packColor() (RGB to native pixel format), + display-wide clip rectangle.
2 - DrawdvxDraw.hAll 2D drawing operations: rectFill, rectCopy, + drawBevel, drawText/drawTextN, + drawMaskedBitmap (cursor), drawTermRow + (batch terminal row rendering). Stateless beyond the clip rect on + DisplayT. Dispatches hot inner loops through BlitOpsT + function pointers.
3 - CompositordvxComp.hDirty rectangle tracking (dirtyListAdd), pairwise merge + of overlapping rects (dirtyListMerge), and the + flushRect function that copies dirty regions from the + system RAM backbuffer to the LFB.
4 - Window ManagerdvxWm.hWindow 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 mode, minimized icon + bar.
5 - ApplicationdvxApp.hPublic 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.
+ + +

3. 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

+ + + +

4. Window System

+ +

WindowT Structure

+ +

Each WindowT is the central object of the window manager. Key +fields:

+ + + + + + + + + + + + + + + +
Field GroupPurpose
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).
CallbacksonPaint, 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:

+ + +

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. +

+ + +

5. 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:

+
    +
  1. Bottom-up (calcMinSize) -- compute minimum sizes for + every widget, starting from leaves.
    2. +
  2. Top-down (layout) -- allocate space within available + bounds, distributing extra space according to weight + values (0 = fixed, 100 = normal stretch).
    3. +
+ +

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 encode static properties:

+ + + + + + + + + + +
FlagMeaning
WCLASS_FOCUSABLECan receive keyboard focus (Tab navigation)
WCLASS_HORIZ_CONTAINERLays out children horizontally (HBox)
WCLASS_PAINTS_CHILDRENWidget handles child rendering itself
WCLASS_SCROLLABLEAccepts mouse wheel events
WCLASS_SCROLL_CONTAINERScrollPane -- scrolling viewport
WCLASS_NEEDS_POLLNeeds periodic polling (e.g. AnsiTerm comms)
WCLASS_SWALLOWS_TABTab key goes to widget, not focus navigation
WCLASS_PRESS_RELEASEClick = press + release (buttons)
+ +

Available Widget Types

+ +

Each widget is a separate .wgt DXE module. 29 widget types +are included:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
WidgetDescription
Box (VBox/HBox)Vertical and horizontal layout containers
ButtonClickable push button with label
CanvasRaw drawing surface for custom painting
CheckboxBoolean toggle with checkmark
ComboBoxText input with dropdown list
DataCtrlData-bound control for database operations
DbGridDatabase grid (tabular data display)
DropdownDropdown selection list
ImageStatic image display
ImageButtonButton with bitmap icon
LabelStatic text label
ListBoxScrollable selection list
ListViewMulti-column list with headers and sorting
ProgressBarDeterminate progress indicator
RadioRadio button (mutual exclusion group)
ScrollPaneScrollable viewport container
SeparatorVisual divider line
SliderValue selection via draggable thumb
SpacerEmpty space for layout
SpinnerNumeric input with up/down arrows
SplitterResizable split pane
StatusBarWindow status bar with sections
TabControlTabbed page container
Terminal (AnsiTerm)ANSI terminal emulator widget
TextInputSingle-line text entry field
TimerPeriodic timer events
ToolbarToolbar with icon buttons
TreeViewHierarchical tree display
WrapBoxFlow 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).

+ + +

6. 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

+ + + + + + + + + + + + + + + + + + + + + +
ExtensionDirectoryPurposeExamples
.libLIBS/Core libraries loaded first. Provide infrastructure APIs.libtasks.lib (task switcher), + libdvx.lib (GUI core), + dvxshell.lib (shell)
.wgtWIDGETS/Widget type plugins. Each exports a wgtRegister() + function called at load time.button.wgt, listview.wgt, + terminal.wgt
.appAPPS/*/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. +

+ + +

7. Event Model

+ +

DVX uses a cooperative polling model. The main loop +(dvxRun / dvxUpdate) runs this cycle each frame:

+ +
    +
  1. Poll mouse -- platformMousePoll() returns + position and button bitmask. Compare with previous frame for + press/release edge detection.
    2. +
  2. Poll keyboard -- platformKeyboardRead() + returns ASCII + scancode. Non-blocking; returns false if buffer is + empty.
    3. +
  3. 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.
    4. +
  4. Compositor pass -- merge dirty rects, composite, + flush to LFB.
    5. +
  5. Yield -- platformYield() or idle + callback.
    6. +
+ +

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. +

+ + +

8. 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:

+ + +

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. +

+ + +

9. 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:

+ + + + + + +
DepthBytes/PixelNotes
8 bpp1Palette mode. Nearest-index via 6x6x6 color cube + grey ramp.
15 bpp25-5-5 RGB (1 bit unused).
16 bpp25-6-5 RGB.
32 bpp48-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:

+ + +

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
+
+ + +

10. Platform Layer

+ +

All OS-specific and CPU-specific code is isolated behind +dvxPlatform.h. To port DVX, implement a new +dvxPlatformXxx.c against this header.

+ +

Implementations

+ + + + + + + + +
FileTargetDetails
dvxPlatformDos.cDJGPP / DPMIReal VESA VBE, INT 33h mouse, INT 16h keyboard, + rep movsd/rep stosl asm spans, + DPMI physical memory mapping for LFB, INT 9 hook for key-up, + CuteMouse Wheel API.
+ +

Abstraction Areas

+ +
+
Video
+
platformVideoInit() -- mode probe and framebuffer setup.
+ platformVideoShutdown() -- restore previous mode.
+ platformVideoEnumModes() -- enumerate available modes.
+ +
Framebuffer Flush
+
platformFlushRect() -- copy dirty rect from backBuf to LFB. + On DOS, each scanline uses rep movsd for near-optimal + aligned 32-bit writes over the PCI bus.
+ +
Optimized Memory Spans
+
Six functions: platformSpanFill8/16/32() and + platformSpanCopy8/16/32(). Called once per scanline of + every rectangle fill, blit, and text draw. On DOS these use inline + assembly for critical inner loops + memset/memcpy.
+ +
Mouse Input
+
Polling model. platformMousePoll() returns position and + button bitmask. Wheel support via CuteMouse API.
+ +
Keyboard Input
+
platformKeyboardRead() -- non-blocking key read.
+ platformKeyUpRead() -- key release detection (requires + INT 9 hook on DOS).
+ platformAltScanToChar() -- scancode-to-ASCII lookup for + Alt+key combinations.
+ +
Crash Recovery
+
platformInstallCrashHandler() -- signal handlers + + longjmp for fault tolerance.
+ +
DXE Support
+
platformRegisterDxeExports() -- register C runtime and + platform symbols for DXE resolution.
+ platformRegisterSymOverrides() -- register function + pointer overrides for module loader.
+
+ + +

11. 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
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
TargetOutputDescription
corebin/libs/libdvx.libGUI core library (draw, comp, wm, app, widget infrastructure)
tasksbin/libs/libtasks.libCooperative task switcher
loaderbin/dvx.exeBootstrap loader (the DOS executable)
widgetsbin/widgets/*.wgt29 widget type plugins
shellbin/libs/dvxshell.libDVX Shell (app management, desktop)
taskmgrbin/libs/taskmgr.libTask Manager (loaded as a separate DXE)
texthelpshared libraryShared text editing helpers (clipboard, word boundaries)
listhelpshared libraryShared dropdown/list helpers
appsbin/apps/*/*.appApplication modules (progman, notepad, clock, etc.)
toolsbin/dvxresResource compiler (runs on Linux, builds resource sections into DXEs)
serialserial DXE libsUART driver, HDLC packets, security, seclink
sqlSQL DXE libSQLite 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)

+
    +
  1. Runs make all.
    2. +
  2. Verifies critical outputs exist (dvx.exe, + libtasks.lib, libdvx.lib, + dvxshell.lib).
    3. +
  3. Counts widget modules.
    4. +
  4. 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
      • +
    +
    5. +
  5. Places the ISO at + ~/.var/app/net._86box._86Box/data/86Box/dvx.iso for + 86Box to mount as CD-ROM.
    6. +
+ +

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
+
+ +
+

Generated 2026-04-06. Source: DVX GUI codebase headers and design documents.

+ + + diff --git a/docs/dvx_widget_reference.html b/docs/dvx_widget_reference.html new file mode 100644 index 0000000..7f4a2c8 --- /dev/null +++ b/docs/dvx_widget_reference.html @@ -0,0 +1,1553 @@ + + + + +DVX Widget Reference + + + + +

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/. +

+ + + + +
+

Table of Contents

+ +
+ + + + +
+

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namechar[32]Widget name for lookup via wgtFind().
x, y, w, hint32_tComputed geometry relative to the window content area (set by layout).
minW, minHint32_t (tagged)Minimum size hints. Use wgtPixels(), wgtChars(), or wgtPercent(). 0 = auto.
maxW, maxHint32_t (tagged)Maximum size constraints. 0 = no limit.
prefW, prefHint32_t (tagged)Preferred size. 0 = auto.
weightint32_tExtra-space distribution weight. 0 = fixed, 100 = normal. A widget with weight=200 gets twice the extra space of one with weight=100.
alignWidgetAlignEMain-axis alignment for children: AlignStartE, AlignCenterE, AlignEndE.
spacingint32_t (tagged)Spacing between children (containers only). 0 = default.
paddingint32_t (tagged)Internal padding (containers only). 0 = default.
fgColoruint32_tForeground color override. 0 = use color scheme default.
bgColoruint32_tBackground color override. 0 = use color scheme default.
visibleboolVisibility state.
enabledboolEnabled state. Disabled widgets are grayed out and ignore input.
readOnlyboolRead-only mode: allows scrolling/selection but blocks editing.
swallowTabboolWhen true, Tab key goes to the widget instead of navigating focus.
accelKeycharLowercase accelerator character. 0 if none.
tooltipconst char *Tooltip text. NULL = none. Caller owns the string.
contextMenuMenuT *Right-click context menu. NULL = none. Caller owns.
userDatavoid *Application-defined user data pointer.
+ +

Size Specification Macros

+ + + + + +
MacroDescription
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.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CallbackSignatureDescription
onClickvoid (*)(WidgetT *w)Fires on mouse click / activation.
onDblClickvoid (*)(WidgetT *w)Fires on double-click.
onChangevoid (*)(WidgetT *w)Fires when the widget's value changes (text, selection, check state, etc.).
onFocusvoid (*)(WidgetT *w)Fires when the widget receives keyboard focus.
onBlurvoid (*)(WidgetT *w)Fires when the widget loses keyboard focus.
onKeyPressvoid (*)(WidgetT *w, int32_t keyAscii)Fires on a printable key press (ASCII value).
onKeyDownvoid (*)(WidgetT *w, int32_t keyCode, int32_t shift)Fires on key down (scan code + shift state).
onKeyUpvoid (*)(WidgetT *w, int32_t keyCode, int32_t shift)Fires on key up.
onMouseDownvoid (*)(WidgetT *w, int32_t button, int32_t x, int32_t y)Fires on mouse button press.
onMouseUpvoid (*)(WidgetT *w, int32_t button, int32_t x, int32_t y)Fires on mouse button release.
onMouseMovevoid (*)(WidgetT *w, int32_t button, int32_t x, int32_t y)Fires on mouse movement over the widget.
onScrollvoid (*)(WidgetT *w, int32_t delta)Fires on mouse wheel scroll.
onValidatebool (*)(WidgetT *w)Validation callback. Return false to cancel a pending write.
+ +

Common Operations

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FunctionDescription
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

+

+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

+ + + + + + + + + +
MacroDescription
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)

+ + + + + +
PropertyTypeAccessDescription
ColsIntegerRead-onlyNumber of columns.
RowsIntegerRead-onlyNumber of rows.
ScrollbackIntegerWrite-onlyMaximum scrollback lines.
+ +

Methods (BASIC Interface)

+ + + + +
MethodDescription
ClearClear the terminal screen.
WriteWrite a string into the terminal.
+ +

Events

+

AnsiTerm uses the common events only. No widget-specific events are defined.

+
+ + + + +
+

Box (VBox / HBox / Frame)

+

+Container widgets that arrange their children in a vertical column (VBox), +horizontal row (HBox), or a titled group box (Frame). These are the primary +layout building blocks. Children are laid out using a flexbox-like algorithm +with weight-based extra-space distribution. +

+

Header: widgets/widgetBox.h

+ +

Creation

+ + + + + +
MacroDescription
wgtVBox(parent)Create a vertical box container. Children are stacked top to bottom.
wgtHBox(parent)Create a horizontal box container. Children are placed left to right.
wgtFrame(parent, title)Create a titled group box (a VBox with a border and label).
+ +

Properties

+

Box containers use the common WidgetT fields for layout control:

+ + + + + + +
PropertyDescription
alignMain-axis alignment of children. HBox: Start=left, Center=center, End=right. VBox: Start=top, Center=center, End=bottom.
spacingGap between children (tagged size).
paddingInternal padding around children (tagged size).
weightControls how the box itself stretches within its parent.
+ +

Events

+

Containers use the common events only. No widget-specific events.

+
+ + + + +
+

Button

+

+A push button with a text label. Fires onClick when pressed +and released. Supports keyboard activation via accelerator keys. +

+

Header: widgets/widgetButton.h

+ +

Creation

+
WidgetT *btn = wgtButton(parent, "OK");
+ +

Macro

+ + + +
MacroDescription
wgtButton(parent, text)Create a push button with the given label text.
+ +

Properties

+

Uses common WidgetT properties. Set accelKey for keyboard shortcut. Use wgtSetText() / wgtGetText() to change the label.

+ +

Events

+ + + +
CallbackDescription
onClickFires when the button is clicked (press + release).
+
+ + + + +
+

Label

+

+A static text label. Does not accept keyboard focus. Typically used to +describe other widgets. Supports text alignment and accelerator keys +(with WCLASS_FOCUS_FORWARD, the accelerator moves focus to the +next focusable sibling). +

+

Header: widgets/widgetLabel.h

+ +

Creation

+
WidgetT *lbl = wgtLabel(parent, "Name:");
+ +

Macros

+ + + + +
MacroDescription
wgtLabel(parent, text)Create a text label.
wgtLabelSetAlign(w, align)Set the text alignment (AlignStartE, AlignCenterE, AlignEndE).
+ +

Properties

+

Use wgtSetText() / wgtGetText() to change the text. Set accelKey for accelerator support (focus forwards to next focusable widget).

+ +

Events

+

Labels use the common events only. Typically no callbacks are set on labels.

+ +

Properties (BASIC Interface)

+ + + +
PropertyTypeAccessDescription
AlignmentEnum (Left, Center, Right)Read/WriteText alignment within the label.
+
+ + + + +
+

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

+ + + + + + +
MacroDescription
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)

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
MacroDescription
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

+ + + + + +
CallbackDescription
onChangeFires when the text content changes.
onKeyPressFires on each key press (ASCII value).
onValidateCalled before committing a change. Return false to cancel.
+
+ + + + +
+

Checkbox

+

+A toggle control with a text label. Clicking toggles between checked and +unchecked states. +

+

Header: widgets/widgetCheckbox.h

+ +

Creation

+
WidgetT *cb = wgtCheckbox(parent, "Enable logging");
+ +

Macros

+ + + + + +
MacroDescription
wgtCheckbox(parent, text)Create a checkbox with the given label text.
wgtCheckboxIsChecked(w)Returns true if the checkbox is checked.
wgtCheckboxSetChecked(w, checked)Set the checked state programmatically.
+ +

Events

+ + + + +
CallbackDescription
onClickFires when clicked (after toggle).
onChangeFires when the checked state changes.
+ +

Properties (BASIC Interface)

+ + + +
PropertyTypeAccessDescription
ValueBooleanRead/WriteWhether the checkbox is checked.
+
+ + + + +
+

Radio Button

+

+A mutually exclusive selection control. Radio buttons must be placed inside +a radio group container. Only one radio button within a group can be selected +at a time. +

+

Header: widgets/widgetRadio.h

+ +

Creation

+
WidgetT *grp = wgtRadioGroup(parent);
+WidgetT *r1  = wgtRadio(grp, "Option A");
+WidgetT *r2  = wgtRadio(grp, "Option B");
+ +

Macros

+ + + + + + +
MacroDescription
wgtRadioGroup(parent)Create a radio group container.
wgtRadio(parent, text)Create a radio button inside a group.
wgtRadioGroupSetSelected(w, idx)Set the selected radio button by index within the group.
wgtRadioGetIndex(w)Get the index of the currently selected radio button.
+ +

Events

+ + + + +
CallbackDescription
onClickFires on the radio button when clicked.
onChangeFires when the selection changes.
+ +

Properties (BASIC Interface)

+ + + +
PropertyTypeAccessDescription
ValueIntegerRead-onlyIndex of the currently selected radio button in the group.
+ +

Methods (BASIC Interface)

+ + + +
MethodDescription
SetSelectedSet the selected radio button by index.
+
+ + + + + + + + + +
+

ComboBox

+

+A combination of a text input and a dropdown list. The user can either type +a value or select from a list of predefined options. Unlike Dropdown, the +text field is editable. +

+

Header: widgets/widgetComboBox.h

+ +

Creation

+
WidgetT *cb = wgtComboBox(parent, 128);
+const char *items[] = { "Arial", "Courier", "Times" };
+wgtComboBoxSetItems(cb, items, 3);
+ +

Macros

+ + + + + + +
MacroDescription
wgtComboBox(parent, maxLen)Create a combo box. maxLen is the maximum text input length.
wgtComboBoxSetItems(w, items, count)Set the dropdown items.
wgtComboBoxGetSelected(w)Get the index of the selected item (-1 if the text does not match any item).
wgtComboBoxSetSelected(w, idx)Set the selected item by index.
+ +

Events

+ + + +
CallbackDescription
onChangeFires when the text or selection changes.
+ +

Properties (BASIC Interface)

+ + + +
PropertyTypeAccessDescription
ListIndexIntegerRead/WriteIndex of the currently selected item.
+
+ + + + +
+

DataCtrl

+

+A VB3-style Data control for database binding. Displays a visible navigation +bar that connects to a SQLite database via dvxSql* functions. +Reads all rows from the RecordSource query into an in-memory cache for +bidirectional navigation. Fires Reposition events when the cursor moves so +bound controls can update. Supports master-detail linking between Data +controls. +

+

Header: widgets/widgetDataCtrl.h

+ +

Creation

+
WidgetT *data = wgtDataCtrl(parent);
+ +

Macros

+ + + + + + + + + + + + + + + + + + + + +
MacroDescription
wgtDataCtrl(parent)Create a Data control.
wgtDataCtrlRefresh(w)Re-execute the RecordSource query and rebuild the row cache.
wgtDataCtrlMoveFirst(w)Move the cursor to the first row.
wgtDataCtrlMovePrev(w)Move the cursor to the previous row.
wgtDataCtrlMoveNext(w)Move the cursor to the next row.
wgtDataCtrlMoveLast(w)Move the cursor to the last row.
wgtDataCtrlGetField(w, colName)Get the value of a column in the current row. Returns const char *.
wgtDataCtrlSetField(w, colName, value)Set the value of a column in the current row (marks the row dirty).
wgtDataCtrlUpdateRow(w)Write the current row's pending changes back to the database.
wgtDataCtrlUpdate(w)Flush all pending changes to the database.
wgtDataCtrlAddNew(w)Begin a new row. Sets dirty state; call Update to commit.
wgtDataCtrlDelete(w)Delete the current row from the database.
wgtDataCtrlSetMasterValue(w, val)Set the master-detail filter value for this control.
wgtDataCtrlGetRowCount(w)Get the total number of cached rows.
wgtDataCtrlGetColCount(w)Get the number of columns in the result set.
wgtDataCtrlGetColName(w, col)Get the name of a column by index. Returns const char *.
wgtDataCtrlGetCellText(w, row, col)Get the text of a specific cell by row and column index. Returns const char *.
wgtDataCtrlSetCurrentRow(w, row)Set the current row by index (0-based).
+ +

Properties (BASIC Interface)

+ + + + + + + + + + + +
PropertyTypeAccessDescription
DatabaseNameStringRead/WritePath to the SQLite database file.
RecordSourceStringRead/WriteSQL query or table name for the result set.
KeyColumnStringRead/WritePrimary key column name (used for UPDATE/DELETE).
MasterSourceStringRead/WriteName of the master Data control for master-detail linking.
MasterFieldStringRead/WriteColumn in the master control to read for the filter value.
DetailFieldStringRead/WriteColumn in this table to filter by the master value.
CaptionStringRead/WriteText displayed on the navigation bar.
BOFBooleanRead-onlyTrue when the cursor is before the first row.
EOFBooleanRead-onlyTrue when the cursor is past the last row.
+ +

Methods (BASIC Interface)

+ + + + + + + + + + +
MethodDescription
AddNewBegin a new row.
DeleteDelete the current row.
MoveFirstMove to the first row.
MoveLastMove to the last row.
MoveNextMove to the next row.
MovePreviousMove to the previous row.
RefreshRe-execute the query and rebuild the cache.
UpdateWrite pending changes to the database.
+ +

Events

+ + + + +
EventDescription
RepositionFires when the current row changes (navigation, refresh, etc.). Default event.
ValidateFires before writing changes. Return false to cancel.
+
+ + + + +
+

DbGrid

+

+A database grid widget that displays all records from a Data control in a +scrollable, sortable table. Columns auto-populate from the Data control's +column names and can be hidden, resized, and renamed by the application. +Clicking a column header sorts the display. Selecting a row syncs the +Data control's cursor position. The grid reads directly from the Data +control's cached rows, so there is no separate copy of the data. +

+

Header: widgets/widgetDbGrid.h

+ +

Creation

+
WidgetT *grid = wgtDbGrid(parent);
+wgtDbGridSetDataWidget(grid, dataCtrl);
+ +

Macros

+ + + + + + + + + +
MacroDescription
wgtDbGrid(parent)Create a database grid widget.
wgtDbGridSetDataWidget(w, dataWidget)Bind the grid to a Data control. The grid reads rows from this widget.
wgtDbGridRefresh(w)Re-read the Data control's state and repaint the grid.
wgtDbGridSetColumnVisible(w, fieldName, visible)Show or hide a column by field name.
wgtDbGridSetColumnHeader(w, fieldName, header)Set a display header for a column (overrides the field name).
wgtDbGridSetColumnWidth(w, fieldName, width)Set the width of a column by field name (tagged size, 0 = auto).
wgtDbGridGetSelectedRow(w)Get the index of the currently selected data row (-1 if none).
+ +

Properties (BASIC Interface)

+ + + +
PropertyTypeAccessDescription
GridLinesBooleanRead/WriteWhether to draw grid lines between cells.
+ +

Methods (BASIC Interface)

+ + + +
MethodDescription
RefreshRe-read the Data control and repaint.
+ +

Events

+ + + + +
EventDescription
ClickFires when a row is clicked.
DblClickFires when a row is double-clicked. Default event.
+
+ + + + +
+

ListBox

+

+A scrollable list of text items. Supports single and multi-selection modes +and drag-to-reorder. +

+

Header: widgets/widgetListBox.h

+ +

Creation

+
WidgetT *lb = wgtListBox(parent);
+const char *items[] = { "Alpha", "Beta", "Gamma" };
+wgtListBoxSetItems(lb, items, 3);
+ +

Macros

+ + + + + + + + + + + + +
MacroDescription
wgtListBox(parent)Create a list box.
wgtListBoxSetItems(w, items, count)Set the list items.
wgtListBoxGetSelected(w)Get the index of the selected item (-1 if none).
wgtListBoxSetSelected(w, idx)Set the selected item by index.
wgtListBoxSetMultiSelect(w, multi)Enable or disable multi-selection mode.
wgtListBoxIsItemSelected(w, idx)Check if a specific item is selected (multi-select mode).
wgtListBoxSetItemSelected(w, idx, selected)Select or deselect a specific item.
wgtListBoxSelectAll(w)Select all items (multi-select mode).
wgtListBoxClearSelection(w)Deselect all items.
wgtListBoxSetReorderable(w, reorderable)Enable drag-to-reorder.
+ +

Events

+ + + + + +
CallbackDescription
onClickFires when an item is clicked.
onDblClickFires when an item is double-clicked.
onChangeFires when the selection changes.
+ +

Properties (BASIC Interface)

+ + + +
PropertyTypeAccessDescription
ListIndexIntegerRead/WriteIndex of the currently selected item.
+ +

Methods (BASIC Interface)

+ + + + + + + + +
MethodDescription
SelectAllSelect all items.
ClearSelectionDeselect all items.
SetMultiSelectEnable or disable multi-selection.
SetReorderableEnable or disable drag-to-reorder.
IsItemSelectedCheck if a specific item is selected by index.
SetItemSelectedSelect or deselect a specific item by index.
+
+ + + + +
+

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

+ + + + + + + + + + + + + + + +
MacroDescription
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

+ + + + + +
CallbackDescription
onClickFires when a row is clicked.
onDblClickFires when a row is double-clicked.
onChangeFires when the selection changes.
+ +

Properties (BASIC Interface)

+ + + +
PropertyTypeAccessDescription
ListIndexIntegerRead/WriteIndex of the currently selected row.
+ +

Methods (BASIC Interface)

+ + + + + + + + +
MethodDescription
SelectAllSelect all rows.
ClearSelectionDeselect all rows.
SetMultiSelectEnable or disable multi-selection.
SetReorderableEnable or disable drag-to-reorder.
IsItemSelectedCheck if a specific row is selected by index.
SetItemSelectedSelect or deselect a specific row by index.
+
+ + + + +
+

TreeView

+

+A hierarchical tree control with expandable/collapsible nodes. Supports +single and multi-selection and drag-to-reorder. Tree items are added as +children of the TreeView or of other tree items to create nested hierarchies. +

+

Header: widgets/widgetTreeView.h

+ +

Creation

+
WidgetT *tv    = wgtTreeView(parent);
+WidgetT *root  = wgtTreeItem(tv, "Root");
+WidgetT *child = wgtTreeItem(root, "Child");
+ +

Macros

+ + + + + + + + + + + + +
MacroDescription
wgtTreeView(parent)Create a tree view control.
wgtTreeItem(parent, text)Add a tree item as a child of the tree view or another tree item.
wgtTreeViewGetSelected(w)Get the currently selected tree item (returns WidgetT *, NULL if none).
wgtTreeViewSetSelected(w, item)Set the selected tree item.
wgtTreeViewSetMultiSelect(w, multi)Enable or disable multi-selection.
wgtTreeViewSetReorderable(w, reorderable)Enable drag-to-reorder of items.
wgtTreeItemSetExpanded(w, expanded)Expand or collapse a tree item.
wgtTreeItemIsExpanded(w)Check if a tree item is expanded.
wgtTreeItemIsSelected(w)Check if a tree item is selected (multi-select mode).
wgtTreeItemSetSelected(w, selected)Select or deselect a tree item.
+ +

Events

+ + + + + +
CallbackDescription
onClickFires when a tree item is clicked.
onDblClickFires when a tree item is double-clicked.
onChangeFires when the selection changes.
+ +

Methods (BASIC Interface)

+ + + + +
MethodDescription
SetMultiSelectEnable or disable multi-selection.
SetReorderableEnable or disable drag-to-reorder.
+
+ + + + +
+

Image

+

+Displays a bitmap image. Can be created from raw pixel data or loaded from +a BMP file on disk. The image is rendered at its natural size within the +widget bounds. +

+

Header: widgets/widgetImage.h

+ +

Creation

+ + + + +
MacroDescription
wgtImage(parent, data, w, h, pitch)Create an image widget from raw pixel data. data is a uint8_t * pixel buffer, w/h are dimensions, pitch is bytes per row.
wgtImageFromFile(parent, path)Create an image widget by loading a BMP file from disk.
+ +

Methods

+ + + + +
MacroDescription
wgtImageSetData(w, data, imgW, imgH, pitch)Replace the displayed image with new raw pixel data.
wgtImageLoadFile(w, path)Replace the displayed image by loading a new file.
+ +

Events

+ + + +
CallbackDescription
onClickFires when the image is clicked.
+ +

Properties (BASIC Interface)

+ + + + + +
PropertyTypeAccessDescription
PictureStringWrite-onlyLoad an image from a file path.
ImageWidthIntegerRead-onlyWidth of the currently loaded image in pixels.
ImageHeightIntegerRead-onlyHeight of the currently loaded image in pixels.
+
+ + + + +
+

ImageButton

+

+A clickable button that displays an image instead of text. Has press/release +visual feedback like a regular button. Can be created from raw pixel data or +a BMP file. +

+

Header: widgets/widgetImageButton.h

+ +

Creation

+ + + + +
MacroDescription
wgtImageButton(parent, data, w, h, pitch)Create an image button from raw pixel data.
wgtImageButtonFromFile(parent, path)Create an image button by loading a BMP file.
+ +

Methods

+ + + + +
MacroDescription
wgtImageButtonSetData(w, data, imgW, imgH, pitch)Replace the image with new raw pixel data.
wgtImageButtonLoadFile(w, path)Replace the image by loading a new file.
+ +

Events

+ + + +
CallbackDescription
onClickFires when the image button is clicked (press + release).
+ +

Properties (BASIC Interface)

+ + + + + +
PropertyTypeAccessDescription
PictureStringWrite-onlyLoad an image from a file path.
ImageWidthIntegerRead-onlyWidth of the currently loaded image in pixels.
ImageHeightIntegerRead-onlyHeight of the currently loaded image in pixels.
+
+ + + + +
+

Slider

+

+A horizontal slider (track bar) for selecting an integer value within a +range. The user drags the thumb or clicks the track to change the value. +

+

Header: widgets/widgetSlider.h

+ +

Creation

+
WidgetT *sl = wgtSlider(parent, 0, 100);
+ +

Macros

+ + + + + +
MacroDescription
wgtSlider(parent, minVal, maxVal)Create a slider with the given integer range.
wgtSliderSetValue(w, value)Set the slider value programmatically.
wgtSliderGetValue(w)Get the current slider value.
+ +

Events

+ + + +
CallbackDescription
onChangeFires when the slider value changes.
+ +

Properties (BASIC Interface)

+ + + +
PropertyTypeAccessDescription
ValueIntegerRead/WriteCurrent slider value.
+
+ + + + +
+

Spinner

+

+A numeric input with up/down buttons for incrementing and decrementing a +value within a range. Supports both integer and floating-point (real) modes. +

+

Header: widgets/widgetSpinner.h

+ +

Creation

+
WidgetT *sp = wgtSpinner(parent, 0, 100, 1);
+ +

Macros

+ + + + + + + + + + + + + +
MacroDescription
wgtSpinner(parent, minVal, maxVal, step)Create a spinner with the given integer range and step size.
wgtSpinnerSetValue(w, value)Set the integer value.
wgtSpinnerGetValue(w)Get the current integer value.
wgtSpinnerSetRange(w, minVal, maxVal)Set the integer range.
wgtSpinnerSetStep(w, step)Set the integer step size.
wgtSpinnerSetRealMode(w, enable)Switch to floating-point mode.
wgtSpinnerGetRealValue(w)Get the current floating-point value.
wgtSpinnerSetRealValue(w, value)Set the floating-point value.
wgtSpinnerSetRealRange(w, minVal, maxVal)Set the floating-point range.
wgtSpinnerSetRealStep(w, step)Set the floating-point step size.
wgtSpinnerSetDecimals(w, decimals)Set the number of decimal places displayed in real mode.
+ +

Events

+ + + +
CallbackDescription
onChangeFires when the value changes.
+ +

Properties (BASIC Interface)

+ + + + + +
PropertyTypeAccessDescription
ValueIntegerRead/WriteCurrent integer value.
RealModeBooleanRead/WriteWhether floating-point mode is active.
DecimalsIntegerRead/WriteNumber of decimal places displayed in real mode.
+ +

Methods (BASIC Interface)

+ + + + +
MethodDescription
SetRangeSet the integer range (min, max).
SetStepSet the integer step size.
+
+ + + + +
+

ProgressBar

+

+A visual indicator of progress, displayed as a filled bar. Supports both +horizontal and vertical orientations. Value ranges from 0 to 100. +

+

Header: widgets/widgetProgressBar.h

+ +

Creation

+ + + + +
MacroDescription
wgtProgressBar(parent)Create a horizontal progress bar.
wgtProgressBarV(parent)Create a vertical progress bar.
+ +

Methods

+ + + + +
MacroDescription
wgtProgressBarSetValue(w, value)Set the progress value (0-100).
wgtProgressBarGetValue(w)Get the current progress value.
+ +

Events

+

ProgressBar is a display-only widget. Typically no callbacks are set.

+ +

Properties (BASIC Interface)

+ + + +
PropertyTypeAccessDescription
ValueIntegerRead/WriteCurrent progress value (0-100).
+
+ + + + +
+

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

+ + + + + + + + + + + + + + + + +
MacroDescription
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

+ + + + +
CallbackDescription
onClickFires when the canvas is clicked.
Mouse callback (set via wgtCanvasSetMouseCallback)Fires on mouse down and drag with canvas-local coordinates.
+ +

Methods (BASIC Interface)

+ + + +
MethodDescription
ClearClear the canvas to a given color.
+
+ + + + +
+

Timer

+

+A non-visual widget that fires its onClick callback at a +regular interval. Useful for animations, polling, and periodic updates. +Must be explicitly started after creation. +

+

Header: widgets/widgetTimer.h

+ +

Creation

+
WidgetT *tmr = wgtTimer(parent, 1000, true);  // 1 second, repeating
+tmr->onClick = onTimerTick;
+wgtTimerStart(tmr);
+ +

Macros

+ + + + + + + + +
MacroDescription
wgtTimer(parent, intervalMs, repeat)Create a timer. intervalMs is the interval in milliseconds. repeat: true for repeating, false for one-shot.
wgtTimerStart(w)Start the timer.
wgtTimerStop(w)Stop the timer.
wgtTimerSetInterval(w, intervalMs)Change the timer interval.
wgtTimerIsRunning(w)Returns true if the timer is currently running.
wgtUpdateTimers()Global tick function. Called by the event loop to advance all active timers.
+ +

Events

+ + + +
CallbackDescription
onClickFires each time the timer elapses.
+ +

Properties (BASIC Interface)

+ + + + +
PropertyTypeAccessDescription
EnabledBooleanRead/WriteWhether the timer is running. Reading returns the running state; writing starts or stops it.
IntervalIntegerWrite-onlyTimer interval in milliseconds.
+ +

Methods (BASIC Interface)

+ + + + +
MethodDescription
StartStart the timer.
StopStop the timer.
+ +

Extra Events (BASIC Interface)

+ + + +
EventDescription
TimerFires each time the timer elapses. Default event.
+
+ + + + +
+

Toolbar

+

+A horizontal container for toolbar buttons and controls. Typically placed +at the top of a window. Children (usually ImageButtons or Buttons) are +laid out horizontally with toolbar-appropriate spacing. +

+

Header: widgets/widgetToolbar.h

+ +

Creation

+
WidgetT *tb = wgtToolbar(parent);
+wgtImageButtonFromFile(tb, "icons/save.bmp");
+wgtImageButtonFromFile(tb, "icons/open.bmp");
+ +

Macro

+ + + +
MacroDescription
wgtToolbar(parent)Create a toolbar container.
+ +

Properties

+

Uses common container properties. Add children (buttons, separators, etc.) to populate the toolbar.

+ +

Events

+

Toolbar itself has no widget-specific events. Events fire on the child widgets.

+
+ + + + +
+

StatusBar

+

+A horizontal bar typically placed at the bottom of a window for displaying +status text and informational widgets. Children are laid out horizontally. +

+

Header: widgets/widgetStatusBar.h

+ +

Creation

+
WidgetT *sb = wgtStatusBar(parent);
+wgtLabel(sb, "Ready");
+ +

Macro

+ + + +
MacroDescription
wgtStatusBar(parent)Create a status bar container.
+ +

Properties

+

Uses common container properties. Add child widgets (labels, progress bars, etc.) to populate.

+ +

Events

+

StatusBar itself has no widget-specific events. Events fire on the child widgets.

+
+ + + + +
+

ScrollPane

+

+A scrollable container that provides vertical and/or horizontal scrollbars +when its content exceeds the visible area. Place a single child (typically +a VBox or HBox) inside the scroll pane. +

+

Header: widgets/widgetScrollPane.h

+ +

Creation

+
WidgetT *sp = wgtScrollPane(parent);
+WidgetT *content = wgtVBox(sp);
+// add children to content...
+ +

Macros

+ + + + + +
MacroDescription
wgtScrollPane(parent)Create a scroll pane container.
wgtScrollPaneScrollToChild(sp, child)Scroll so that the given child widget is visible.
wgtScrollPaneSetNoBorder(w, noBorder)When true, removes the border around the scroll pane.
+ +

Events

+ + + +
CallbackDescription
onScrollFires when the scroll position changes.
+ +

Properties (BASIC Interface)

+ + + +
PropertyTypeAccessDescription
NoBorderBooleanRead/WriteWhether the border around the scroll pane is hidden.
+
+ + + + +
+

Splitter

+

+A two-pane container with a draggable divider. The user drags the splitter +bar to resize the two panes. Can be oriented vertically (left/right panes) +or horizontally (top/bottom panes). Add exactly two children. +

+

Header: widgets/widgetSplitter.h

+ +

Creation

+
WidgetT *sp = wgtSplitter(parent, true);  // vertical = left|right
+WidgetT *left  = wgtVBox(sp);
+WidgetT *right = wgtVBox(sp);
+ +

Macros

+ + + + + +
MacroDescription
wgtSplitter(parent, vertical)Create a splitter. vertical=true for left/right panes, false for top/bottom.
wgtSplitterSetPos(w, pos)Set the divider position in pixels.
wgtSplitterGetPos(w)Get the current divider position in pixels.
+ +

Events

+ + + +
CallbackDescription
onChangeFires when the divider position changes.
+ +

Properties (BASIC Interface)

+ + + +
PropertyTypeAccessDescription
PositionIntegerRead/WriteDivider position in pixels.
+
+ + + + +
+

TabControl

+

+A tabbed container that displays one page at a time with clickable tabs +along the top. Each tab page is a container that holds its own child widgets. +

+

Header: widgets/widgetTabControl.h

+ +

Creation

+
WidgetT *tabs = wgtTabControl(parent);
+WidgetT *page1 = wgtTabPage(tabs, "General");
+WidgetT *page2 = wgtTabPage(tabs, "Advanced");
+// add children to page1, page2...
+ +

Macros

+ + + + + + +
MacroDescription
wgtTabControl(parent)Create a tab control.
wgtTabPage(parent, title)Add a tab page with the given title. Returns the page container widget.
wgtTabControlSetActive(w, idx)Set the active tab by index (0-based).
wgtTabControlGetActive(w)Get the index of the active tab.
+ +

Events

+ + + +
CallbackDescription
onChangeFires when the active tab changes.
+ +

Properties (BASIC Interface)

+ + + +
PropertyTypeAccessDescription
TabIndexIntegerRead/WriteIndex of the currently active tab (0-based).
+ +

Methods (BASIC Interface)

+ + + +
MethodDescription
SetActiveSet the active tab by index.
+
+ + + + +
+

Separator

+

+A visual dividing line used to separate groups of widgets. Available in +horizontal and vertical orientations. +

+

Header: widgets/widgetSeparator.h

+ +

Creation

+ + + + +
MacroDescription
wgtHSeparator(parent)Create a horizontal separator line.
wgtVSeparator(parent)Create a vertical separator line.
+ +

Events

+

Separator is a visual-only widget. No events.

+
+ + + + +
+

Spacer

+

+An invisible widget used for layout purposes. By default it has +weight=100, so it absorbs available extra space. Useful for +pushing other widgets apart or aligning them to edges. +

+

Header: widgets/widgetSpacer.h

+ +

Creation

+
WidgetT *row = wgtHBox(parent);
+wgtButton(row, "OK");
+wgtSpacer(row);           // pushes Cancel to the right
+wgtButton(row, "Cancel");
+ +

Macro

+ + + +
MacroDescription
wgtSpacer(parent)Create an invisible spacer widget.
+ +

Events

+

Spacer is an invisible layout widget. No events.

+
+ + + + +
+

WrapBox

+

+A flow/wrap layout container that arranges children left-to-right, wrapping +to the next row when the available width is exceeded. Each row's height is +the maximum child height in that row. Supports configurable spacing between +items and rows, and per-row alignment for short rows. +

+

Header: widgets/widgetWrapBox.h

+ +

Creation

+
WidgetT *wrap = wgtWrapBox(parent);
+wgtButton(wrap, "Tag 1");
+wgtButton(wrap, "Tag 2");
+wgtButton(wrap, "Tag 3");
+ +

Macro

+ + + +
MacroDescription
wgtWrapBox(parent)Create a wrap box container.
+ +

Properties

+

WrapBox uses the common WidgetT container fields for layout control:

+ + + + +
PropertyDescription
spacingGap between children in both the horizontal and vertical directions (tagged size). Default is 4 pixels.
paddingInternal padding around children (tagged size). Default is 2 pixels.
+ +

Properties (BASIC Interface)

+ + + +
PropertyTypeAccessDescription
AlignmentEnum (Left, Center, Right)Read/WriteRow alignment for rows that do not fill the full width.
+ +

Events

+

WrapBox is a container widget. It uses the common events only. No widget-specific events are defined.

+
+ + + + +
+

+DVX Widget Reference -- Generated from source headers in +core/dvxWidget.h and widgets/*.h. +

+ + + diff --git a/docs/dvxbasic_control_reference.html b/docs/dvxbasic_control_reference.html new file mode 100644 index 0000000..38c5241 --- /dev/null +++ b/docs/dvxbasic_control_reference.html @@ -0,0 +1,1687 @@ + + + + +DVX BASIC Control Reference + + + + +

DVX BASIC Control Reference

+ +

+This document describes every VB-style control available in DVX BASIC. +Each control maps to an underlying DVX widget loaded dynamically via +.wgt DXE files. Properties and methods are dispatched through +interface descriptors registered by each widget. +

+ +
+Table of Contents + +
+ + + +

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

+ + + + + + + + + + + + + + + + + + +
PropertyTypeR/WDescription
NameStringRThe control's name (e.g. "Command1"). Read-only at runtime.
LeftIntegerR/WX position in pixels relative to the parent container.
TopIntegerR/WY position in pixels relative to the parent container.
WidthIntegerR/WCurrent width in pixels. Setting this changes the minimum width constraint.
HeightIntegerR/WCurrent height in pixels. Setting this changes the minimum height constraint.
MinWidthIntegerR/WMinimum width for layout. Alias for Width in the setter.
MinHeightIntegerR/WMinimum height for layout. Alias for Height in the setter.
MaxWidthIntegerR/WMaximum width cap (0 = no limit, stretch to fill).
MaxHeightIntegerR/WMaximum height cap (0 = no limit, stretch to fill).
WeightIntegerR/WLayout weight. 0 = fixed size, >0 = share extra space proportionally.
VisibleBooleanR/WWhether the control is visible.
EnabledBooleanR/WWhether the control accepts user input.
BackColorLongR/WBackground color as a 32-bit ARGB value.
ForeColorLongR/WForeground (text) color as a 32-bit ARGB value.
TabIndexIntegerRAccepted 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. +

+ + + + + + + + + + + + + + + +
EventParametersDescription
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.
KeyPressKeyAscii As IntegerFires when a printable key is pressed. KeyAscii is the ASCII code.
KeyDownKeyCode As Integer, Shift As IntegerFires when any key is pressed down. KeyCode is the scan code; Shift indicates modifier keys.
KeyUpKeyCode As Integer, Shift As IntegerFires when a key is released.
MouseDownButton As Integer, X As Integer, Y As IntegerFires when a mouse button is pressed over the control.
MouseUpButton As Integer, X As Integer, Y As IntegerFires when a mouse button is released over the control.
MouseMoveButton As Integer, X As Integer, Y As IntegerFires when the mouse moves over the control.
ScrollDelta As IntegerFires when the control is scrolled (mouse wheel or scrollbar).
+ +

Common Methods

+ + + + + +
MethodParametersDescription
SetFocus(none)Gives keyboard focus to this control.
Refresh(none)Forces the control to repaint.
+ + + +

Form

+ + +
+VB Equivalent: Form    +DVX Widget: Window + VBox/HBox root +
+ +

+The Form is the top-level container representing a DVX window. It is declared +in the .frm file with Begin Form FormName. +All controls are children of the form's content box, which uses either VBox +(default) or HBox layout. +

+ +

Form Properties

+ + + + + + + + + + + + + +
PropertyTypeDefaultDescription
NameString"Form1"The form's name, used for event dispatch and Load statement.
CaptionString(same as Name)Window title bar text.
WidthInteger400Window width in pixels. Setting this disables AutoSize.
HeightInteger300Window height in pixels. Setting this disables AutoSize.
LeftInteger0Initial X position. Used when Centered is False.
TopInteger0Initial Y position. Used when Centered is False.
LayoutString"VBox"Content box layout: "VBox" (vertical) or "HBox" (horizontal).
AutoSizeBooleanTrueWhen True, the window shrink-wraps to fit its content.
ResizableBooleanTrueWhether the user can resize the window at runtime.
CenteredBooleanTrueWhen True, the window is centered on screen. When False, Left/Top are used.
+ +

Form Events

+ + + + + + + + + +
EventParametersDescription
Load(none)Fires after the form and all controls are created. This is the default event.
Unload(none)Fires when the form is being closed or unloaded.
QueryUnloadCancel As IntegerFires before Unload. Set Cancel = 1 to abort the close.
Resize(none)Fires when the window is resized by the user.
Activate(none)Fires when the window gains focus.
Deactivate(none)Fires when the window loses focus.
+ +

Form Methods (called on the form object)

+ + + + + + + + +
StatementDescription
Load FormNameLoad the form (creates the window and controls, fires Load event).
Unload FormNameUnload the form (fires Unload, destroys window).
FormName.ShowMake the form visible.
FormName.Show 1Show as modal dialog (blocks until closed).
FormName.HideHide the form without unloading it.
+ +

Example

+ +
+Sub Form_Load ()
+    Form1.Caption = "Hello World"
+    Print "Form loaded!"
+End Sub
+
+Sub Form_QueryUnload (Cancel As Integer)
+    If MsgBox("Really quit?", 4) <> 6 Then
+        Cancel = 1
+    End If
+End Sub
+
+Sub Form_Resize ()
+    Print "Window resized"
+End Sub
+
+ + + +

CommandButton

+ + +
+VB Equivalent: CommandButton    +DVX Widget: button | Name Prefix: Command +
+ +

+A push button that triggers an action when clicked. Created with +wgtButton(parent, text). +

+ +

Type-Specific Properties

+ + + + +
PropertyTypeDescription
CaptionStringThe text displayed on the button. Use & for accelerator keys (e.g. "&OK").
+ +

No additional type-specific properties beyond common properties and Caption.

+ +

Default Event: Click

+ +

Example

+ +
+Begin Form Form1
+    Caption = "Button Demo"
+    Begin CommandButton Command1
+        Caption = "&Click Me!"
+    End
+End
+
+Sub Command1_Click ()
+    MsgBox "Button was clicked!"
+End Sub
+
+ + + +

Label

+ + +
+VB Equivalent: Label    +DVX Widget: label +
+ +

+A static text label. Supports left, center, and right alignment. +

+ +

Type-Specific Properties

+ + + + + +
PropertyTypeDescription
CaptionStringThe text displayed by the label.
AlignmentEnumText alignment: Left (default), Center, or Right.
+ +

Default Event: Click

+ +

Example

+ +
+Begin Label Label1
+    Caption   = "Hello, World!"
+    Alignment = "Center"
+End
+
+ + + +

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

+ + + + + + +
PropertyTypeDescription
TextStringThe text content of the input field.
DataSourceStringName of a Data control for data binding.
DataFieldStringColumn 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
+
+ + + +

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

+ + + + +
PropertyTypeDescription
TextStringThe full text content.
+ +

Default Event: Change

+ + + +

CheckBox

+ + +
+VB Equivalent: CheckBox    +DVX Widget: checkbox +
+ +

+A toggle control with a label. Checked state is exposed as a Boolean. +

+ +

Type-Specific Properties

+ + + + + +
PropertyTypeDescription
CaptionStringThe text displayed next to the checkbox.
ValueBooleanTrue 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
+
+ + + +

OptionButton

+ + +
+VB Equivalent: OptionButton    +DVX Widget: radio (radio group + radio button) | Name Prefix: Option +
+ +

+A radio button for mutually exclusive choices. DVX uses a radio group +container; individual OptionButtons are children of the group. The +Value property returns the button's index within its group. +

+ +

Type-Specific Properties

+ + + + + +
PropertyTypeDescription
CaptionStringThe text displayed next to the radio button.
ValueIntegerThe index of this radio button within its group (read-only).
+ +

Type-Specific Methods

+ + + + +
MethodParametersDescription
SetSelectedIndex As IntegerSelect the radio button at the given index within the group.
+ +

Default Event: Click

+ + + +

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

+ + + + +
PropertyTypeDescription
CaptionStringThe 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
+
+ + + +

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.

+ + + +

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.

+ + + +

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

+ + + + + +
PropertyTypeDescription
ListIndexIntegerIndex of the currently selected item (-1 = no selection).
ListCountIntegerNumber of items in the list (read-only).
+ +

Type-Specific Methods

+ + + + + + + + + + + + + +
MethodParametersDescription
AddItemText As StringAdd an item to the end of the list.
RemoveItemIndex As IntegerRemove the item at the given index.
Clear(none)Remove all items from the list.
ListIndex As IntegerReturn the text of the item at the given index.
SelectAll(none)Select all items (multi-select mode).
ClearSelection(none)Deselect all items.
SetMultiSelectMulti As BooleanEnable or disable multi-select mode.
SetReorderableReorderable As BooleanEnable or disable drag-to-reorder.
IsItemSelectedIndex As IntegerReturns True if the item at Index is selected.
SetItemSelectedIndex As Integer, Selected As BooleanSelect 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
+
+ + + +

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

+ + + + + + +
PropertyTypeDescription
TextStringThe text in the editable field.
ListIndexIntegerIndex of the currently selected list item (-1 = none).
ListCountIntegerNumber of items in the drop-down list (read-only).
+ +

Type-Specific Methods

+ +

Same as ListBox: AddItem, RemoveItem, Clear, List.

+ +

Default Event: Click

+ + + + + + +
+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

+ + + + + +
PropertyTypeDescription
ListIndexIntegerIndex of the currently selected item.
ListCountIntegerNumber of items (read-only).
+ +

Type-Specific Methods

+ +

Same as ListBox: AddItem, RemoveItem, Clear, List.

+ +

Default Event: Click

+ + + +

HScrollBar

+ + +
+VB Equivalent: HScrollBar    +DVX Widget: slider | Name Prefix: HScroll +
+ +

+A horizontal slider/scrollbar control. The value ranges between a minimum +and maximum set at creation time (default 0 to 100). +

+ +

Type-Specific Properties

+ + + + +
PropertyTypeDescription
ValueIntegerThe current slider position (clamped to min/max range).
+ +

Default Event: Change

+ +

Example

+ +
+Begin HScrollBar HScroll1
+    MinWidth = 200
+End
+
+Sub HScroll1_Change ()
+    Label1.Caption = "Value: " & Str$(HScroll1.Value)
+End Sub
+
+ + + +

SpinButton

+ + +
+DVX Extension    +DVX Widget: spinner | Name Prefix: Spin +
+ +

+A numeric input with up/down buttons. Supports integer mode (default) and +real-number mode with configurable decimal places. +

+ +

Type-Specific Properties

+ + + + + + +
PropertyTypeDescription
ValueIntegerCurrent integer value (in integer mode).
RealModeBooleanTrue to use floating-point mode; False for integer mode.
DecimalsIntegerNumber of decimal places shown in real mode.
+ +

Type-Specific Methods

+ + + + + +
MethodParametersDescription
SetRangeMin As Integer, Max As IntegerSet the allowed value range.
SetStepStep As IntegerSet the increment per button click.
+ +

Default Event: Change

+ + + +

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

+ + + + + +
PropertyTypeDescription
EnabledBooleanTrue to start the timer, False to stop it.
IntervalIntegerTimer interval in milliseconds (write-only from BASIC).
+ +

Type-Specific Methods

+ + + + + +
MethodParametersDescription
Start(none)Start the timer.
Stop(none)Stop the timer.
+ +

Type-Specific Events

+ + + + +
EventParametersDescription
Timer(none)Fires each time the interval elapses. This is the default event.
+ +
+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
+
+ + + +

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

+ + + + +
MethodParametersDescription
ClearColor As IntegerFill 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

+ + + +

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

+ + + + + + +
PropertyTypeDescription
PictureStringPath to a BMP file to load (write-only).
ImageWidthIntegerWidth of the loaded image in pixels (read-only).
ImageHeightIntegerHeight of the loaded image in pixels (read-only).
+ +

Default Event: Click

+ + + +

ImageButton

+ + +
+DVX Extension    +DVX Widget: imagebutton +
+ +

+A button that displays an image instead of text. Like Image, it requires +pixel data at creation time and is typically loaded via the +Picture property. +

+ +

Type-Specific Properties

+ + + + + + +
PropertyTypeDescription
PictureStringPath to a BMP file to load (write-only).
ImageWidthIntegerWidth of the loaded image in pixels (read-only).
ImageHeightIntegerHeight of the loaded image in pixels (read-only).
+ +

Default Event: Click

+ + + +

ProgressBar

+ + +
+VB Equivalent: ProgressBar    +DVX Widget: progressbar +
+ +

+A horizontal progress indicator bar. +

+ +

Type-Specific Properties

+ + + + +
PropertyTypeDescription
ValueIntegerCurrent progress value (0-100).
+ +

No type-specific events or methods. No default event.

+ + + +

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

+ + + + +
PropertyTypeDescription
ListIndexIntegerIndex of the currently selected row (-1 = none).
+ +

Type-Specific Methods

+ + + + + + + + + +
MethodParametersDescription
SelectAll(none)Select all rows.
ClearSelection(none)Deselect all rows.
SetMultiSelectMulti As BooleanEnable or disable multi-select.
SetReorderableReorderable As BooleanEnable or disable row reordering.
IsItemSelectedIndex As IntegerReturns True if the row at Index is selected.
SetItemSelectedIndex As Integer, Selected As BooleanSelect or deselect a specific row.
+ +

Default Event: Click

+ + + +

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

+ + + + + +
MethodParametersDescription
SetMultiSelectMulti As BooleanEnable or disable multi-select mode.
SetReorderableReorderable As BooleanEnable or disable node reordering.
+ +

Default Event: Click

+ + + +

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

+ + + + +
PropertyTypeDescription
TabIndexIntegerIndex 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

+ + + + +
MethodParametersDescription
SetActiveIndex As IntegerSwitch 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

+ + + +

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

+ + + + +
PropertyTypeDescription
PositionIntegerPosition of the divider in pixels from the top (or left).
+ +

Container: Yes

+

No default event.

+ + + +

ScrollPane

+ + +
+DVX Extension    +DVX Widget: scrollpane | Name Prefix: Scroll +
+ +

+A scrollable container. Place child controls inside and the ScrollPane +automatically provides scrollbars when the content exceeds the visible area. +

+ +

Type-Specific Properties

+ + + + +
PropertyTypeDescription
NoBorderBooleanWhen True, suppresses the border around the scroll pane.
+ +

Container: Yes

+

No default event.

+ + + +

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

+ + + + +
PropertyTypeDescription
AlignmentEnumHorizontal alignment of items: Left, Center, or Right.
+ +

Container: Yes

+

Default Event: Click

+ + + +

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.

+ + + +

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.

+ + + +

Toolbar

+ + +
+VB Equivalent: Toolbar    +DVX Widget: toolbar +
+ +

+A horizontal container styled as a toolbar, with compact padding and +spacing. Place buttons, labels, or other controls inside. +

+ +

Container: Yes

+

No type-specific properties, events, or methods.

+ + + +

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.

+ + + +

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

+ + + + + + +
PropertyTypeDescription
ColsIntegerNumber of character columns (read-only).
RowsIntegerNumber of character rows (read-only).
ScrollbackIntegerNumber of scrollback lines (write-only).
+ +

Type-Specific Methods

+ + + + + +
MethodParametersDescription
Clear(none)Clear the terminal screen.
WriteText As StringWrite text (with ANSI escape processing) to the terminal.
+ +

No default event.

+ + + +

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 the Data Binding section for details. +

+ +

Type-Specific Properties

+ + + + + + + + + + + + +
PropertyTypeR/WDescription
DatabaseNameStringR/WPath to the SQLite database file.
RecordSourceStringR/WTable name or SQL SELECT query for the recordset.
KeyColumnStringR/WPrimary key column name (used for UPDATE/DELETE operations).
CaptionStringR/WText displayed on the navigator bar.
BOFBooleanRTrue if the current position is before the first record (read-only).
EOFBooleanRTrue if the current position is past the last record (read-only).
MasterSourceStringR/WName of a master Data control (for master-detail binding).
MasterFieldStringR/WColumn in the master recordset to filter by.
DetailFieldStringR/WColumn in this recordset that matches the master field.
+ +

Type-Specific Methods

+ + + + + + + + + + + +
MethodParametersDescription
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

+ + + + + +
EventParametersDescription
Reposition(none)Fires after the current record changes (navigation). This is the default event.
ValidateCancel As IntegerFires before writing a record. Set Cancel = 1 to abort.
+ + + +

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

+ + + + + +
PropertyTypeDescription
DataSourceStringName of the Data control that supplies records.
GridLinesBooleanShow or hide grid lines between cells.
+ +

Type-Specific Methods

+ + + + +
MethodParametersDescription
Refresh(none)Reload and redraw the grid from the Data control.
+ +

Type-Specific Events

+ + + + + +
EventParametersDescription
Click(none)Fires when a cell is clicked.
DblClick(none)Fires when a cell is double-clicked. This is the default event.
+ + + +

Data Binding

+ + +

+DVX BASIC provides VB3-style data binding through three properties that can +be set on most controls: +

+ + + + + +
PropertySet OnDescription
DataSourceAny controlName of the Data control to bind to (e.g. "Data1").
DataFieldAny controlColumn name from the Data control's recordset to display.
+ +

How It Works

+ +
    +
  1. Place a Data control on the form and set its DatabaseName + and RecordSource properties.
    2. +
  2. 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.
    3. +
  3. When the form loads, the Data control auto-refreshes: it opens the database, + runs the query, and navigates to the first record.
    4. +
  4. 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).
    5. +
  5. 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.
    6. +
+ +

Master-Detail Binding

+ +

+For hierarchical data (e.g. orders and order items), use two Data controls: +

+ +
    +
  1. A master Data control bound to the parent table.
    2. +
  2. 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.
    3. +
+ +

+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
+
+ + + + + + +

+Menus are defined in the .frm file using Begin Menu +blocks. Each menu item has a name, caption, and nesting level. Menu items +fire Click events dispatched as +MenuName_Click. +

+ +

FRM Syntax

+ +
+Begin Form Form1
+    Caption = "Menu Demo"
+
+    Begin Menu mnuFile
+        Caption = "&File"
+        Begin Menu mnuOpen
+            Caption = "&Open"
+        End
+        Begin Menu mnuSave
+            Caption = "&Save"
+        End
+        Begin Menu mnuSep1
+            Caption = "-"
+        End
+        Begin Menu mnuExit
+            Caption = "E&xit"
+        End
+    End
+
+    Begin Menu mnuEdit
+        Caption = "&Edit"
+        Begin Menu mnuCopy
+            Caption = "&Copy"
+        End
+        Begin Menu mnuPaste
+            Caption = "&Paste"
+        End
+    End
+End
+
+ +

Menu Item Properties

+ + + + + + +
PropertyTypeDescription
CaptionStringThe text displayed. Use & for accelerator key. Set to "-" for a separator.
CheckedBooleanWhether the menu item shows a checkmark.
EnabledBooleanWhether the menu item is enabled (default True).
+ +

Nesting

+ +

+Menu items are nested by placing Begin Menu blocks inside +other Begin Menu blocks: +

+ + + +

+A level-0 menu that contains children becomes a top-level menu header. +A non-level-0 menu that contains children becomes a submenu. +

+ +

Event Dispatch

+ +

+Each clickable menu item (not headers, not separators) receives a unique +numeric ID at load time. When clicked, the form's onMenu +handler maps the ID to the menu item's name and fires +MenuName_Click. +

+ +
+Sub mnuOpen_Click ()
+    MsgBox "Open was clicked"
+End Sub
+
+Sub mnuExit_Click ()
+    Unload Form1
+End Sub
+
+ + + +

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
+
+ +
+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)). +
+ + + +

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

+ + + +

Common FRM Properties

+ + + + + + + + + + + + + + + + + + + + + + + +
PropertyApplies ToDescription
CaptionForm, controlsDisplay text or window title.
TextTextBox, ComboBoxInitial text content.
MinWidth / WidthControlsMinimum width. Both names are accepted.
MinHeight / HeightControlsMinimum height. Both names are accepted.
MaxWidthControlsMaximum width (0 = no cap).
MaxHeightControlsMaximum height (0 = no cap).
WeightControlsLayout weight for flexible sizing.
LeftForm, controlsX position (used by Form when Centered=False; informational for controls).
TopForm, controlsY position.
IndexControlsControl array index (-1 or absent = not in array).
VisibleControlsInitial visibility.
EnabledControlsInitial enabled state.
LayoutForm"VBox" or "HBox".
AutoSizeFormAuto-fit window to content.
ResizableFormAllow runtime resizing.
CenteredFormCenter window on screen.
DatabaseNameDataSQLite database file path.
RecordSourceDataTable name or SQL query.
DataSourceBound controlsName of the Data control.
DataFieldBound controlsColumn name in the recordset.
+ + +
+

+DVX BASIC Control Reference -- Generated from source code analysis of +formrt.c, ideProperties.c, ideDesigner.c, and widget DXE interface descriptors. +

+ + + diff --git a/docs/dvxbasic_ide_guide.html b/docs/dvxbasic_ide_guide.html new file mode 100644 index 0000000..4a82f00 --- /dev/null +++ b/docs/dvxbasic_ide_guide.html @@ -0,0 +1,895 @@ + + + + +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. +

+ +
+Table of Contents + +
+ + +

1. Overview

+ +

+The DVX BASIC IDE is modeled after Visual Basic 3.0. It consists of several +floating windows arranged on the DVX desktop: +

+ + +

+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

+ + + + + + + + + + + + + + + + +
Menu ItemShortcutDescription
New Project...Create a new DVX BASIC project.
Open Project...Open an existing .dbp project file.
Save ProjectSave the current project file to disk.
Close ProjectClose the current project (prompts to save unsaved changes).
Project Properties...Edit project metadata (name, author, version, startup form, icon, etc.).
Add File...Ctrl+OAdd a .bas or .frm file to the project. If no project is open, creates an implicit project from the file.
Save FileCtrl+SSave the active file to disk.
Save AllSave all modified files in the project.
Remove FileRemove the selected file from the project (prompts to save if modified).
ExitClose the IDE (prompts to save unsaved changes).
+ +

Edit Menu

+ + + + + + + + + + + + + +
Menu ItemShortcutDescription
CutCtrl+XCut selected text to the clipboard.
CopyCtrl+CCopy selected text to the clipboard.
PasteCtrl+VPaste text from the clipboard.
Select AllCtrl+ASelect all text in the active editor.
DeleteDelDelete the selected text or control (in the form designer).
Find...Ctrl+FOpen the Find/Replace dialog.
Find NextF3Find the next occurrence of the search text.
Replace...Ctrl+HOpen the Find/Replace dialog with replace enabled.
+ +

Run Menu

+ + + + + + + + + + + + + + + + + +
Menu ItemShortcutDescription
RunF5Compile and run the program. If paused at a breakpoint, resumes execution with debugging disabled (runs free).
DebugShift+F5Compile and run with the debugger active. Breakpoints are active but execution does not pause at the first statement. If paused, resumes to the next breakpoint.
Run Without RecompileCtrl+F5Re-run the last compiled module without recompiling.
StopEscStop the running program immediately.
Step IntoF8Execute one statement, stepping into SUB/FUNCTION calls. If idle, starts a debug session and breaks at the first statement.
Step OverShift+F8Execute one statement, stepping over SUB/FUNCTION calls.
Step OutCtrl+Shift+F8Run until the current SUB/FUNCTION returns.
Run to CursorCtrl+F8Run until execution reaches the line where the cursor is positioned.
Toggle BreakpointF9Toggle a breakpoint on the current editor line.
Clear OutputClear the Output window.
Save on RunCheckbox: when enabled, all modified files are saved automatically before compiling. Persisted in preferences.
+ +

View Menu

+ + + + + + + + + +
Menu ItemShortcutDescription
CodeF7Switch to Code view for the active file (or the file selected in the Project Explorer).
DesignerShift+F7Switch to Design view for the active form file.
ToolbarCheckbox: show or hide the toolbar. Persisted in preferences.
Status BarCheckbox: show or hide the status bar. Persisted in preferences.
Menu Editor...Ctrl+EOpen the Menu Editor dialog for the active form. Allows designing menu bars with captions, names, levels, checked state, and enabled state.
+ +

Window Menu

+ + + + + + + + + + + + + +
Menu ItemDescription
Code EditorShow or raise the Code Editor window.
OutputShow or raise the Output window.
ImmediateShow or raise the Immediate window.
LocalsShow or raise the Locals debug window.
Call StackShow or raise the Call Stack debug window.
WatchShow or raise the Watch debug window.
BreakpointsShow or raise the Breakpoints window.
Project ExplorerShow or raise the Project Explorer window.
ToolboxShow or raise the Toolbox window.
PropertiesShow or raise the Properties panel.
+ +

Tools Menu

+ + + + + +
Menu ItemDescription
Preferences...Open the Preferences dialog (editor settings and project defaults).
Debug LayoutCheckbox: toggle a debug overlay that shows widget layout boundaries. Useful for diagnosing widget layout issues.
+ +

Help Menu

+ + + +
Menu ItemDescription
About DVX BASIC...Show the About dialog with version and copyright information.
+ + +

3. Toolbar

+ +

+The toolbar is organized into four groups separated by vertical dividers. +Each button has a tooltip showing its name and keyboard shortcut. +

+ +

File Group

+ + + + +
ButtonShortcutAction
OpenCtrl+OAdd a file to the project (same as File > Add File).
SaveCtrl+SSave the active file.
+ +

Run Group

+ + + + +
ButtonShortcutAction
RunF5Compile and run the program.
StopEscStop the running program.
+ +

Debug Group

+ + + + + + + +
ButtonShortcutAction
DebugShift+F5Start or resume a debug session.
Step IntoF8Step into the next statement.
Step OverShift+F8Step over the next statement.
Step OutCtrl+Shift+F8Step out of the current procedure.
Run to CursorCtrl+F8Run to the cursor position.
+ +

View Group

+ + + + +
ButtonShortcutAction
CodeF7Switch to Code view.
DesignShift+F7Switch to Design view.
+ + +

4. 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: +

+ +

+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: +

+ + + + + + + + +
CategoryExamples
KeywordsIF, 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 namesINTEGER, LONG, SINGLE, DOUBLE, STRING, BOOLEAN, BYTE, TRUE, FALSE
String literals"Hello, World!"
Comments' This is a comment, REM This is a comment
Numbers42, 3.14
Operators=, <, >, +, -, *, /, \, &
+ +

Editor Features

+ + + +

5. 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

+ + +

Form Properties

+

+Forms have the following design-time properties: Name, Caption, Width, Height, +Left, Top, Layout (VBox or HBox), Centered, AutoSize, and Resizable. +

+ + +

6. Project System

+ +

Project Files (.dbp)

+

+A DVX BASIC project is stored as a .dbp file (DVX BASIC Project). +The project file records: +

+ + +

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

+ + + + + + + + + +
OperationDescription
New ProjectCreates a blank project with a name and directory. A default .frm file is added automatically.
Open ProjectOpens a .dbp file and loads all referenced files into memory.
Save ProjectWrites the .dbp file to disk.
Close ProjectCloses the project, prompting to save unsaved changes.
Add FileAdds a .bas or .frm file to the project. Opening a file without a project auto-creates an implicit project.
Remove FileRemoves a file from the project (prompts to save if modified).
Project PropertiesOpens 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. +

+ + +

7. Properties Panel

+ +

+The Properties panel (Window > Properties) has two sections: +

+ +

+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). +

+ + +

8. Toolbox

+ +

+The Toolbox (Window > Toolbox) is a floating palette of +buttons, one for each available control type. Controls are loaded dynamically +from the widget plugin registry -- any widget DXE that provides a +basName appears in the toolbox. +

+

+Click a tool to select it (the active tool name is stored in the designer +state), then click on the form to place a new instance. Click the same tool +again to deselect it and return to pointer mode. +

+ +

Available Controls

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VB NameDescription
CommandButtonPush button that triggers a Click event.
LabelStatic text label.
TextBoxSingle-line text input field.
TextAreaMulti-line text editor.
CheckBoxOn/off checkbox.
OptionButtonRadio button (mutually exclusive within a group).
ListBoxScrollable list of items.
ComboBoxDrop-down combo box.
DropDownSimple drop-down list.
PictureBoxCanvas for drawing and images.
ImageStatic image display.
ImageButtonClickable image button.
FrameGrouping container with a labeled border.
VBoxVertical layout container.
HBoxHorizontal layout container.
WrapBoxFlow layout container that wraps items to the next row.
SplitterResizable split between two child panes.
ScrollPaneScrollable container for large content.
TabStripTabbed container with multiple pages.
ListViewMulti-column list with headers.
TreeViewHierarchical tree control.
ProgressBarProgress indicator bar.
HScrollBarHorizontal slider/scrollbar.
SpinButtonNumeric up/down spinner.
LineHorizontal or vertical separator line.
SpacerInvisible spacing element for layout.
TimerNon-visual timer that fires periodic events.
ToolbarToolbar container for buttons.
StatusBarStatus bar at the bottom of a form.
TerminalANSI terminal emulator control.
DataData control for binding to a database.
DBGridData-bound grid for displaying database query results.
+ + +

9. Debugger

+ +

+The DVX BASIC IDE includes a full interactive debugger. The debugger operates +as a state machine with three states: +

+ + + + + +
StateDescription
DBG_IDLENo program loaded or running.
DBG_RUNNINGProgram is executing (VM running in slices).
DBG_PAUSEDExecution is paused at a breakpoint or step point. The IDE GUI is fully interactive.
+ +

Starting a Debug Session

+ + +

Breakpoints

+ +

Setting Breakpoints

+ + +

Breakpoint Validation

+

+Not every line can have a breakpoint. The IDE validates the line content and +silently refuses to set breakpoints on: +

+ + +

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 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

+ + + + + + +
ActionShortcutBehavior
Step IntoF8Execute one statement. If the statement is a SUB/FUNCTION call, step into it.
Step OverShift+F8Execute 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 OutCtrl+Shift+F8Run until the current SUB/FUNCTION returns to its caller.
Run to CursorCtrl+F8Run 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: +

+
    +
  1. The VM executes up to 10,000 steps per slice.
    2. +
  2. 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.
    3. +
  3. 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.
    4. +
  4. When the user resumes (F5/Shift+F5/F8/etc.), the state transitions back + to DBG_RUNNING and the loop continues.
    5. +
+ +

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. +

+ + +

10. Debug Windows

+ +

+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. +

+ +

Locals Window

+

+Shows variables for the current execution scope. Displayed as a three-column +ListView: +

+ + + + + +
ColumnContent
NameVariable name (internal mangled names like static variable placeholders are filtered out).
TypeData type: Integer, Long, Single, Double, String, Boolean, Array, UDT. Array types show the element type (e.g., Integer()).
ValueCurrent 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: +

+ +

+Up to 64 variables are displayed. The window is resizable. +

+ +

Call Stack Window

+

+Shows the current call chain as a two-column ListView: +

+ + + + +
ColumnContent
ProcedureProcedure name (or (module) for module-level code).
LineLine 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

+

+Allows monitoring arbitrary expressions while debugging. The window has +a text input at the top and a two-column ListView below: +

+ + + + +
ColumnContent
ExpressionThe watch expression text.
ValueEvaluated 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: +

+ + +

Editing and Deleting

+ + +

Breakpoints Window

+

+Lists all set breakpoints as a three-column ListView: +

+ + + + + +
ColumnContent
FileProject file path.
ProcedureProcedure name (Object.Event format, or (General)).
LineCode line number within the file.
+ + + +

11. 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: +

+ +

+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: +

+ +

+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. +

+ + +

12. Output Window

+ +

+The Output window is a read-only TextArea at the bottom-left of the screen. +It displays: +

+ +

+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. +

+ + +

13. 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

+ + + + + + + +
ControlDescription
Find inputThe text to search for.
Replace checkbox + inputEnable replacement mode and enter replacement text.
ScopeRadio group: Function, Object, File, or Project. Default is Project.
DirectionRadio group: Forward or Backward.
Match CaseCheckbox: case-sensitive search.
+ +

Buttons

+ + + + + + +
ButtonAction
Find NextFind the next occurrence. Wraps across procedures, files, and the entire project depending on the scope setting.
ReplaceReplace the current match and find the next one.
Replace AllReplace all occurrences within the selected scope.
CloseClose the dialog.
+ +

Keyboard Shortcut

+

+F3 repeats the last search (Find Next) without opening the dialog. +

+ + +

14. Preferences

+ +

+Open via Tools > Preferences. Settings are saved to +dvxbasic.ini in the app's config directory. +

+ +

Editor Section

+ + + + + + +
SettingDescriptionDefault
Skip comments/strings when renamingWhen 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 widthNumber of spaces per tab stop (1-8).3
Insert spaces instead of tabsWhen 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: +

+ + + + + + + +
FieldDescriptionDefault
AuthorDefault author name.(empty)
CompanyDefault company name.(empty)
VersionDefault version string.1.0
CopyrightDefault copyright notice.(empty)
DescriptionDefault project description (multi-line).(empty)
+ +
+ +

Keyboard Shortcut Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + +
ShortcutAction
Ctrl+OAdd File
Ctrl+SSave File
Ctrl+ASelect All
Ctrl+XCut
Ctrl+CCopy
Ctrl+VPaste
Ctrl+FFind
Ctrl+HReplace
Ctrl+EMenu Editor
F3Find Next
F5Run
Shift+F5Debug
Ctrl+F5Run Without Recompile
EscStop
F7Code View
Shift+F7Design View
F8Step Into
Shift+F8Step Over
Ctrl+Shift+F8Step Out
Ctrl+F8Run to Cursor
F9Toggle Breakpoint
DelDelete
+ +
+

DVX BASIC 1.0 -- Copyright 2026 Scott Duensing

+ + + diff --git a/docs/dvxbasic_language_reference.html b/docs/dvxbasic_language_reference.html new file mode 100644 index 0000000..2b3f7cd --- /dev/null +++ b/docs/dvxbasic_language_reference.html @@ -0,0 +1,1973 @@ + + + + +DVX BASIC Language Reference + + + + +

DVX BASIC Language Reference

+ +

Complete reference for the DVX BASIC language as implemented in the +DVX BASIC compiler and runtime. DVX BASIC is a QuickBASIC/Visual Basic +compatible dialect targeting the DVX GUI environment.

+ +
+Table of Contents + +
+ + + +

1. Data Types

+ + +

DVX BASIC supports the following data types. Each type has a corresponding +type suffix character that can be appended to variable names.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeSizeSuffixRange / Description
Integer2 bytes%-32768 to 32767
Long4 bytes&-2147483648 to 2147483647
Single4 bytes!32-bit float, approximately 7 digits precision
Double8 bytes#64-bit float, approximately 15 digits precision
Stringvariable$Variable-length, reference-counted, dynamic string
Boolean2 bytesTrue (-1) or False (0)
+ +

Internal Types (not directly declarable)

+ + + + + + + + + + + + + + + + + + + + + + +
Internal TypeDescription
ArrayReference-counted multi-dimensional array (up to 8 dimensions)
UDTUser-defined type instance (created with TYPE...END TYPE)
ObjectOpaque host object (form reference, control reference)
RefByRef 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

+ + + + + + + + + +
FormExampleDescription
Decimal integer42Values -32768..32767 are Integer; larger values are Long
Hex integer&HFFHexadecimal literal
Long suffix42&, &HFF&Force Long type
Floating-point3.14, 1.5E10Double by default
Single suffix3.14!Force Single type
Double suffix3.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$).

+ + + +

2. Operators

+ + +

Operators listed from highest precedence (evaluated first) to lowest +precedence (evaluated last).

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PrecedenceOperatorDescription
1 (highest)^Exponentiation
2- (unary)Negation
3*   /   \ +   MODMultiplication, float division, integer division, modulus
4+   -Addition, subtraction
5&String concatenation
6=   <>   < +   >   <=   + >=Comparison (returns Boolean)
7NOTLogical/bitwise NOT
8ANDLogical/bitwise AND
9XORLogical/bitwise XOR
10ORLogical/bitwise OR
11EQVLogical/bitwise equivalence
12 (lowest)IMPLogical/bitwise implication
+ +

String Concatenation

+ +

Use & to concatenate strings. The + operator +also concatenates when both operands are strings.

+ +
+result$ = "Hello" & " " & "World"
+result$ = firstName$ & " " & lastName$
+
+ + + +

3. Statements

+ + +

Multiple statements can appear on one line separated by :. +Lines can be continued with _ at the end. Comments start with +' or REM.

+ + + +

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
+
+ +
+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).

+ + + +

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: <, >, +<=, >=, =, +<>.

+ + + +

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
+
+ + + +

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
+
+ + + +

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.

+ + + +

PRINT

+ +

Outputs text to the console or to a file channel.

+ +
+PRINT [expression] [{; | ,} expression] ...
+PRINT #channel, expression
+PRINT USING format$; expression [; expression] ...
+
+ + + +

Special functions inside PRINT:

+ + + +
+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
+
+ + + +

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
+
+ + + +

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
+
+ + + +

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
+
+ + + +

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
+
+ + + +

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
+
+ + + +

4. 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
+
+ + + + + + + + +
ModeDescription
INPUTOpen for sequential reading. File must exist.
OUTPUTOpen for sequential writing. Creates or truncates.
APPENDOpen for sequential writing at end of file.
RANDOMOpen for random-access record I/O.
BINARYOpen for raw binary I/O.
+ + +

CLOSE

+ +
+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
+
+ + + +

5. Built-in Functions

+ + + + +

String Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FunctionArgsReturnsDescription
ASC(s$)1IntegerReturns the ASCII code of the first character of s$.
CHR$(n)1StringReturns the character with ASCII code n.
FORMAT$(value, fmt$)2StringFormats a numeric value using the format string fmt$.
HEX$(n)1StringReturns the hexadecimal representation of n.
INSTR(s$, find$)2-3IntegerReturns the position of find$ in s$ (1-based). Optionally + takes a starting position as the first argument: + INSTR(start, s$, find$). Returns 0 if + not found.
LCASE$(s$)1StringConverts s$ to lowercase.
LEFT$(s$, n)2StringReturns the leftmost n characters of s$.
LEN(s$)1IntegerReturns the length of s$.
LTRIM$(s$)1StringRemoves leading spaces from s$.
MID$(s$, start [, length])2-3StringReturns a substring starting at position start (1-based). If + length is omitted, returns from start to end.
RIGHT$(s$, n)2StringReturns the rightmost n characters of s$.
RTRIM$(s$)1StringRemoves trailing spaces from s$.
SPACE$(n)1StringReturns a string of n spaces.
STR$(n)1StringConverts number n to its string representation.
STRING$(n, char)2StringReturns a string of n copies of char (ASCII code or + single-character string).
TRIM$(s$)1StringRemoves leading and trailing spaces from s$.
UCASE$(s$)1StringConverts s$ to uppercase.
VAL(s$)1DoubleConverts the 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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FunctionArgsReturnsDescription
ABS(n)1DoubleAbsolute value of n.
ATN(n)1DoubleArctangent of n (in radians).
COS(n)1DoubleCosine of n (radians).
EXP(n)1DoubleReturns e raised to the power n.
FIX(n)1IntegerTruncates n toward zero (removes the fractional part).
INT(n)1IntegerReturns the largest integer less than or equal to n (floor).
LOG(n)1DoubleNatural logarithm (base e) of n.
RND[(n)]0-1DoubleReturns a random number between 0 (inclusive) and 1 (exclusive). + With a negative argument, seeds and returns. With 0, returns the + previous value.
SGN(n)1IntegerReturns the sign of n: -1, 0, or 1.
SIN(n)1DoubleSine of n (radians).
SQR(n)1DoubleSquare root of n.
TAN(n)1DoubleTangent of n (radians).
TIMER0DoubleReturns the number of seconds since midnight.
+ + + +

Conversion Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FunctionArgsReturnsDescription
CDBL(n)1DoubleConverts n to Double.
CINT(n)1IntegerConverts n to Integer (with banker's rounding).
CLNG(n)1LongConverts n to Long.
CSNG(n)1SingleConverts n to Single.
CSTR(n)1StringConverts n to its String representation.
+ + + +

File I/O Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FunctionArgsReturnsDescription
EOF(channel)1BooleanReturns True if the file pointer is at end of file.
FREEFILE0IntegerReturns the next available file channel number.
INPUT$(n, #channel)2StringReads n characters from the file and returns them as a string.
LOC(channel)1LongReturns the current read/write position in the file.
LOF(channel)1LongReturns the length of the file in bytes.
SEEK(channel)1LongReturns the current file position (function form of SEEK).
LBOUND(array [, dim])1-2IntegerReturns the lower bound of an array dimension.
UBOUND(array [, dim])1-2IntegerReturns the upper bound of an array dimension.
+ + + +

Miscellaneous Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FunctionArgsReturnsDescription
DATE$0StringReturns the current date as "MM-DD-YYYY".
TIME$0StringReturns the current time as "HH:MM:SS".
ENVIRON$(name$)1StringReturns the value of the environment variable name$.
ERR0IntegerReturns the current runtime error number (0 if no error).
+ + + +

6. 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:

+ + + + + + + + + + + + + + + + + + +
EventDescription
ClickControl was clicked
DblClickControl was double-clicked
ChangeControl value/text changed
KeyPressKey was pressed (receives key code)
KeyDownKey went down (receives key code and shift state)
KeyUpKey was released
MouseDownMouse button pressed
MouseUpMouse button released
MouseMoveMouse moved over control
GotFocusControl received input focus
LostFocusControl lost input focus
Form_LoadForm is being loaded
Form_UnloadForm is being unloaded
Form_ResizeForm was resized
TimerTimer interval elapsed
+ + + +

7. 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
+
+ + + +

8. App Object

+ + +

The App object provides read-only properties for the +application's directory paths.

+ + + + + + + + + + + + + + + + + + + + + + +
PropertyReturnsDescription
App.PathStringThe directory containing the application's executable.
App.ConfigStringThe directory for application configuration files.
App.DataStringThe directory for application data files (databases, etc.).
+ +
+configFile$ = App.Config & "\settings.ini"
+dbPath$ = App.Data & "\myapp.db"
+Print "Running from: " & App.Path
+
+ + + +

9. 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)
+
+ + + +

10. Predefined Constants

+ + +

The following constants are predefined by the compiler and available in all +programs.

+ +

MsgBox Button Style Flags

+ + + + + + + + +
ConstantValueDescription
vbOKOnly0OK button only (default)
vbOKCancel1OK and Cancel buttons
vbYesNo2Yes and No buttons
vbYesNoCancel3Yes, No, and Cancel buttons
vbRetryCancel4Retry and Cancel buttons
+ +

MsgBox Icon Flags

+ +

Add an icon flag to the button style to display an icon in the message +box.

+ + + + + + + +
ConstantValueDescription
vbInformation&H10Information icon
vbExclamation&H20Warning icon
vbCritical&H30Error/critical icon
vbQuestion&H40Question mark icon
+ +

MsgBox Return Values

+ + + + + + + + +
ConstantValueDescription
vbOK1User clicked OK
vbCancel2User clicked Cancel
vbYes3User clicked Yes
vbNo4User clicked No
vbRetry5User clicked Retry
+ +

Show Mode Flags

+ + + + +
ConstantValueDescription
vbModal1Show form as modal dialog
+ +

Boolean Constants

+ + + + + +
ConstantValueDescription
True-1Boolean true
False0Boolean false
+ + +
+

DVX BASIC Language Reference -- Generated from compiler source code. +Covers the lexer, parser, and VM opcode set as implemented.

+ + +