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

Cleaning up HTML help.

Browse source
This commit is contained in:
Scott Duensing 2026-04-09 01:32:03 -05:00
parent 5ece172ad0
commit fe68899020
11 changed files with 0 additions and 13906 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1960
docs/dvx_api_reference.html
View file

File diff suppressed because it is too large Load diff

610
docs/dvx_architecture.html
View file

@ -1,610 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>DVX Architecture Overview</title>
<style>
body { font-family: sans-serif; margin: 0; padding: 0; display: flex; }
nav { width: 250px; min-width: 250px; background: #f0f0f0; padding: 16px;
border-right: 1px solid #ccc; height: 100vh; overflow-y: auto;
position: sticky; top: 0; box-sizing: border-box; }
nav ul { list-style: none; padding-left: 16px; margin: 4px 0; }
nav > ul { padding-left: 0; }
nav a { text-decoration: none; color: #0066cc; }
nav a:hover { text-decoration: underline; }
main { flex: 1; padding: 24px 32px; max-width: 800px; }
h1 { border-bottom: 2px solid #333; padding-bottom: 4px; }
h2 { border-bottom: 1px solid #999; padding-bottom: 2px; margin-top: 32px; }
h3 { margin-top: 24px; }
pre { background: #f8f8f8; border: 1px solid #ddd; padding: 8px;
overflow-x: auto; font-size: 14px; }
blockquote { background: #fffde7; border-left: 4px solid #ffc107;
padding: 8px 12px; margin: 12px 0; }
hr { border: none; border-top: 1px solid #ccc; margin: 24px 0; }
img { max-width: 100%; }
.topic { margin-bottom: 48px; }
</style>
</head>
<body>
<nav>
<h3>Contents</h3>
<ul>
<li><a href="#arch.overview">System Overview</a>
<ul>
<li><a href="#arch.layers">Five-Layer Architecture</a></li>
<li><a href="#arch.pipeline">Display Pipeline</a></li>
<li><a href="#arch.windows">Window System</a></li>
<li><a href="#arch.widgets">Widget System</a></li>
<li><a href="#arch.dxe">DXE Module System</a></li>
<li><a href="#arch.events">Event Model</a></li>
<li><a href="#arch.fonts">Font System</a></li>
<li><a href="#arch.colors">Color System</a></li>
<li><a href="#arch.platform">Platform Layer</a></li>
<li><a href="#arch.build">Build System</a></li>
</ul>
</li>
</ul>
<h3>Index</h3>
<ul>
<li><a href="#arch.overview">DVX</a></li>
<li><a href="#arch.overview">Architecture</a></li>
<li><a href="#arch.overview">DJGPP</a></li>
<li><a href="#arch.overview">DPMI</a></li>
<li><a href="#arch.layers">Layers</a></li>
<li><a href="#arch.layers">dvxVideo</a></li>
<li><a href="#arch.layers">dvxDraw</a></li>
<li><a href="#arch.layers">dvxComp</a></li>
<li><a href="#arch.layers">dvxWm</a></li>
<li><a href="#arch.layers">dvxApp</a></li>
<li><a href="#arch.pipeline">Display Pipeline</a></li>
<li><a href="#arch.pipeline">Backbuffer</a></li>
<li><a href="#arch.pipeline">Linear Framebuffer</a></li>
<li><a href="#arch.pipeline">LFB</a></li>
<li><a href="#arch.pipeline">Dirty Rects</a></li>
<li><a href="#arch.pipeline">Double Buffer</a></li>
<li><a href="#arch.pipeline">Compositing</a></li>
<li><a href="#arch.pipeline">DisplayT</a></li>
<li><a href="#arch.pipeline">BlitOpsT</a></li>
<li><a href="#arch.pipeline">DirtyListT</a></li>
<li><a href="#arch.windows">Window</a></li>
<li><a href="#arch.windows">WindowT</a></li>
<li><a href="#arch.windows">Z-Order</a></li>
<li><a href="#arch.windows">Chrome</a></li>
<li><a href="#arch.windows">Hit Testing</a></li>
<li><a href="#arch.windows">Menu System</a></li>
<li><a href="#arch.windows">Minimized Windows</a></li>
<li><a href="#arch.windows">Window Stack</a></li>
<li><a href="#arch.windows">Menus</a></li>
<li><a href="#arch.windows">Submenus</a></li>
<li><a href="#arch.widgets">Widgets</a></li>
<li><a href="#arch.widgets">WidgetT</a></li>
<li><a href="#arch.widgets">WidgetClassT</a></li>
<li><a href="#arch.widgets">Layout Engine</a></li>
<li><a href="#arch.widgets">Widget API</a></li>
<li><a href="#arch.widgets">Layout</a></li>
<li><a href="#arch.widgets">Flexbox</a></li>
<li><a href="#arch.widgets">WgtIfaceT</a></li>
<li><a href="#arch.dxe">DXE</a></li>
<li><a href="#arch.dxe">DXE3</a></li>
<li><a href="#arch.dxe">Modules</a></li>
<li><a href="#arch.dxe">Dynamic Loading</a></li>
<li><a href="#arch.dxe">Boot Sequence</a></li>
<li><a href="#arch.dxe">Crash Recovery</a></li>
<li><a href="#arch.dxe">Memory Tracking</a></li>
<li><a href="#arch.events">Events</a></li>
<li><a href="#arch.events">Input</a></li>
<li><a href="#arch.events">Mouse</a></li>
<li><a href="#arch.events">Keyboard</a></li>
<li><a href="#arch.events">Polling</a></li>
<li><a href="#arch.events">Cooperative</a></li>
<li><a href="#arch.events">Event Dispatch</a></li>
<li><a href="#arch.events">Accelerator Tables</a></li>
<li><a href="#arch.events">Cursor</a></li>
<li><a href="#arch.events">Double-Click</a></li>
<li><a href="#arch.fonts">Fonts</a></li>
<li><a href="#arch.fonts">Bitmap Font</a></li>
<li><a href="#arch.fonts">BitmapFontT</a></li>
<li><a href="#arch.fonts">Text Rendering</a></li>
<li><a href="#arch.fonts">CP437</a></li>
<li><a href="#arch.colors">Colors</a></li>
<li><a href="#arch.colors">Pixel Format</a></li>
<li><a href="#arch.colors">PixelFormatT</a></li>
<li><a href="#arch.colors">ColorSchemeT</a></li>
<li><a href="#arch.colors">Theming</a></li>
<li><a href="#arch.colors">Bevel</a></li>
<li><a href="#arch.platform">Platform Layer</a></li>
<li><a href="#arch.platform">dvxPlatform</a></li>
<li><a href="#arch.platform">VESA</a></li>
<li><a href="#arch.platform">VBE</a></li>
<li><a href="#arch.platform">INT 33h</a></li>
<li><a href="#arch.platform">INT 16h</a></li>
<li><a href="#arch.platform">Assembly</a></li>
<li><a href="#arch.platform">rep stosl</a></li>
<li><a href="#arch.platform">rep movsd</a></li>
<li><a href="#arch.build">Build</a></li>
<li><a href="#arch.build">Makefile</a></li>
<li><a href="#arch.build">Cross-Compilation</a></li>
<li><a href="#arch.build">dxe3gen</a></li>
<li><a href="#arch.build">mkcd.sh</a></li>
<li><a href="#arch.build">ISO</a></li>
</ul>
</nav>
<main>
<div class="topic" id="arch.overview">
<h1>DVX Architecture Overview</h1>
<h2>DVX Architecture Overview</h2>
<p>DOS Visual eXecutive -- A Windowing GUI for DJGPP/DPMI</p>
<p>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.</p>
<h3>Key Design Constraints</h3>
<ul>
<li>VESA VBE 2.0+ LFB only -- no bank switching. If the hardware cannot provide a linear framebuffer, initialization fails.</li>
<li>486 baseline -- all hot paths are written to be fast on a 486, with Pentium-specific paths where the gain is significant.</li>
<li>Single-tasking cooperative model -- applications yield the CPU via tsYield(); there is no preemptive scheduler.</li>
<li>86Box is the trusted reference platform for testing. DOSBox-X is not used; any bugs observed are treated as DVX bugs.</li>
</ul>
<p>No external font or cursor files -- all bitmaps are compiled in as static const data.</p>
<p>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.</p>
<h3>Contents</h3>
<p><a href="#arch.layers">Five-Layer Architecture</a></p>
<p><a href="#arch.pipeline">Display Pipeline</a></p>
<p><a href="#arch.windows">Window System</a></p>
<p><a href="#arch.widgets">Widget System</a></p>
<p><a href="#arch.dxe">DXE Module System</a></p>
<p><a href="#arch.events">Event Model</a></p>
<p><a href="#arch.fonts">Font System</a></p>
<p><a href="#arch.colors">Color System</a></p>
<p><a href="#arch.platform">Platform Layer</a></p>
<p><a href="#arch.build">Build System</a></p>
</div>
<div class="topic" id="arch.layers">
<h1>Five-Layer Architecture</h1>
<h2>Five-Layer Architecture</h2>
<p>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.</p>
<pre><code> 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 | |
| +------------------------------------------+ |
==================================================</code></pre>
<h3>Layer Summary</h3>
<pre> Layer Header Responsibility
----- ------ --------------
1 - Video dvxVideo.h VESA VBE mode negotiation, LFB mapping via DPMI, backbuffer allocation, packColor() (RGB to native pixel format), display-wide clip rectangle.
2 - Draw dvxDraw.h All 2D drawing: rectFill, rectCopy, drawBevel, drawText/drawTextN, drawMaskedBitmap (cursor), drawTermRow (batch terminal row). Stateless beyond clip rect. Dispatches hot inner loops through BlitOpsT function pointers.
3 - Compositor dvxComp.h Dirty rectangle tracking (dirtyListAdd), pairwise merge of overlapping rects (dirtyListMerge), and flushRect to copy dirty regions from backBuf to LFB.
4 - Window Manager dvxWm.h Window lifecycle, Z-order stack, chrome drawing (title bars, bevels, close/minimize/maximize gadgets), hit testing, drag/resize, menu bars, scrollbars, system menu, keyboard move/resize, minimized icon bar.
5 - Application dvxApp.h Public API aggregating all layers into AppContextT. Provides dvxInit/dvxShutdown, dvxRun/dvxUpdate, window creation helpers, image loading, clipboard, accelerator tables, theme management, wallpaper, video mode switching, screenshot capture.</pre>
</div>
<div class="topic" id="arch.pipeline">
<h1>Display Pipeline</h1>
<h2>Display Pipeline</h2>
<p>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.</p>
<p>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.</p>
<h3>Per-Frame Compositing Pipeline</h3>
<pre><code> 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)</code></pre>
<h3>Key Data Structures</h3>
<p>DisplayT -- Central display context: width, height, pitch, pixel format, LFB pointer, backbuffer pointer, palette, clip rectangle. Passed by pointer through every layer -- no globals.</p>
<p>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.</p>
<p>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.</p>
<h3>Why This Works on a 486</h3>
<ul>
<li>A full 640x480x32bpp frame is 1.2 MB -- far too much to flush every frame over a slow PCI bus.</li>
<li>A typical dirty region during normal interaction (typing, menu open) is a few KB.</li>
<li>Merging overlapping dirty rects into larger rects reduces per-rect overhead and improves bus utilization.</li>
</ul>
<p>Per-window content buffers persist across frames, so windows don't repaint on expose -- only when their own content changes.</p>
</div>
<div class="topic" id="arch.windows">
<h1>Window System</h1>
<h2>Window System</h2>
<h3>WindowT Structure</h3>
<p>Each WindowT is the central object of the window manager. Key fields:</p>
<pre> Field Group Purpose
----------- -------
Geometry (x, y, w, h) Outer frame rectangle (including chrome).
Content area (contentX/Y/W/H) Computed from frame minus chrome. Where application content lives.
Content buffer (contentBuf, contentPitch) Per-window backbuffer in native pixel format. Persists across frames.
Chrome state (menuBar, vScroll, hScroll) Optional menu bar and scrollbars. Affect content area computation.
Widget tree (widgetRoot) Root of the retained-mode widget tree (NULL if using raw callbacks).
Callbacks onPaint, onKey, onKeyUp, onMouse, onResize, onClose, onMenu, onScroll, onFocus, onBlur, onCursorQuery.</pre>
<h3>Window Stack (Z-Order)</h3>
<p>WindowStackT is an array of WindowT* ordered front-to-back: index count-1 is the topmost window. This allows:</p>
<ul>
<li>Back-to-front iteration for painting (painter's algorithm).</li>
<li>Front-to-back iteration for hit testing (first hit wins).</li>
</ul>
<p>Reordering by pointer swap (no copying of large WindowT structs).</p>
<p>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.</p>
<h3>Chrome Layout</h3>
<pre><code> +-------------------------------------------+
| 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 |
+-------------------------------------------+</code></pre>
<p>Chrome constants are compile-time defines:</p>
<pre><code> CHROME_BORDER_WIDTH = 4px
CHROME_TITLE_HEIGHT = 20px
CHROME_INNER_BORDER = 2px
CHROME_MENU_HEIGHT = 20px
SCROLLBAR_WIDTH = 16px
CHROME_CLOSE_BTN_SIZE = 16px</code></pre>
<h3>Hit Test Regions</h3>
<p>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).</p>
<h3>Menu System</h3>
<p>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.</p>
<h3>Minimized Windows</h3>
<p>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.</p>
</div>
<div class="topic" id="arch.widgets">
<h1>Widget System</h1>
<h2>Widget System</h2>
<p>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.</p>
<h3>WidgetT Base Structure</h3>
<p>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-&gt;data (opaque void*).</p>
<p>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.</p>
<h3>Layout Engine</h3>
<p>Two-pass flexbox-like algorithm:</p>
<ul>
<li>Bottom-up (calcMinSize) -- compute minimum sizes for every widget, starting from leaves.</li>
</ul>
<p>Top-down (layout) -- allocate space within available bounds, distributing extra space according to weight values (0 = fixed, 100 = normal stretch).</p>
<p>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).</p>
<h3>Widget Class Dispatch (WidgetClassT)</h3>
<p>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.</p>
<p>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).</p>
<h4>Class Flags</h4>
<pre> Flag Meaning
---- -------
WCLASS_FOCUSABLE Can receive keyboard focus (Tab navigation)
WCLASS_HORIZ_CONTAINER Lays out children horizontally (HBox)
WCLASS_PAINTS_CHILDREN Widget handles child rendering itself
WCLASS_SCROLLABLE Accepts mouse wheel events
WCLASS_SCROLL_CONTAINER ScrollPane -- scrolling viewport
WCLASS_NEEDS_POLL Needs periodic polling (e.g. AnsiTerm comms)
WCLASS_SWALLOWS_TAB Tab key goes to widget, not focus navigation
WCLASS_PRESS_RELEASE Click = press + release (buttons)</pre>
<h3>Available Widget Types</h3>
<p>Each widget is a separate .wgt DXE module. 29 widget types are included:</p>
<pre> Widget Description
------ -----------
Box (VBox/HBox) Vertical and horizontal layout containers
Button Clickable push button with label
Canvas Raw drawing surface for custom painting
Checkbox Boolean toggle with checkmark
ComboBox Text input with dropdown list
DataCtrl Data-bound control for database operations
DbGrid Database grid (tabular data display)
Dropdown Dropdown selection list
Image Static image display
ImageButton Button with bitmap icon
Label Static text label
ListBox Scrollable selection list
ListView Multi-column list with headers and sorting
ProgressBar Determinate progress indicator
Radio Radio button (mutual exclusion group)
ScrollPane Scrollable viewport container
Separator Visual divider line
Slider Value selection via draggable thumb
Spacer Empty space for layout
Spinner Numeric input with up/down arrows
Splitter Resizable split pane
StatusBar Window status bar with sections
TabControl Tabbed page container
Terminal (AnsiTerm) ANSI terminal emulator widget
TextInput Single-line text entry field
Timer Periodic timer events
Toolbar Toolbar with icon buttons
TreeView Hierarchical tree display
WrapBox Flow layout (wrapping horizontal container)</pre>
<h3>Widget API Registry</h3>
<p>Each widget DXE registers a small API struct under a name during wgtRegister(). Callers retrieve it via wgtGetApi(&quot;button&quot;) 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.</p>
<h3>Widget Interface Descriptors (WgtIfaceT)</h3>
<p>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).</p>
</div>
<div class="topic" id="arch.dxe">
<h1>DXE Module System</h1>
<h2>DXE Module System</h2>
<p>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.</p>
<h3>Module Types</h3>
<pre> Extension Directory Purpose Examples
--------- --------- ------- --------
.lib LIBS/ Core libraries loaded first. Provide infrastructure APIs. libtasks.lib, libdvx.lib, dvxshell.lib
.wgt WIDGETS/ Widget type plugins. Each exports wgtRegister(). button.wgt, listview.wgt, terminal.wgt
.app APPS/*/ Application modules. Each exports appDescriptor and appMain(). Loaded on demand by the shell. progman.app, notepad.app, cpanel.app</pre>
<h3>Boot Sequence</h3>
<pre><code> 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() -&gt; tsYield() -&gt; shellReapApps()</code></pre>
<h3>Application Lifecycle</h3>
<p>Two kinds of DXE apps:</p>
<h4>Callback-only (hasMainLoop = false)</h4>
<p>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.</p>
<h4>Main-loop (hasMainLoop = true)</h4>
<p>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.</p>
<h3>Crash Recovery</h3>
<p>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.</p>
<h3>Per-App Memory Tracking</h3>
<p>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.</p>
</div>
<div class="topic" id="arch.events">
<h1>Event Model</h1>
<h2>Event Model</h2>
<p>DVX uses a cooperative polling model. The main loop (dvxRun / dvxUpdate) runs this cycle each frame:</p>
<ul>
<li>Poll mouse -- platformMousePoll() returns position and button bitmask. Compare with previous frame for press/release edge detection.</li>
<li>Poll keyboard -- platformKeyboardRead() returns ASCII + scancode. Non-blocking; returns false if buffer is empty.</li>
<li>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.</li>
<li>Compositor pass -- merge dirty rects, composite, flush to LFB.</li>
</ul>
<p>Yield -- platformYield() or idle callback.</p>
<h3>Event Dispatch Chain</h3>
<pre><code> 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.)</code></pre>
<h3>Accelerator Tables</h3>
<p>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.</p>
<h3>Mouse Cursor</h3>
<p>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.</p>
<h3>Double-Click Detection</h3>
<p>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.</p>
</div>
<div class="topic" id="arch.fonts">
<h1>Font System</h1>
<h2>Font System</h2>
<p>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).</p>
<h3>BitmapFontT</h3>
<pre><code> 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;</code></pre>
<p>Design rationale:</p>
<ul>
<li>Character positions are pure multiplication (x = col * 8).</li>
<li>Glyph lookup is a single array index.</li>
<li>Each scanline of a glyph is exactly one byte (1bpp at 8 pixels wide).</li>
<li>No glyph-width tables, kerning, or per-character positioning needed.</li>
</ul>
<p>8-pixel width aligns with byte boundaries -- no bit shifting in per-scanline rendering.</p>
<h3>Text Rendering Functions</h3>
<p>drawChar() -- Renders a single character. Supports opaque (background fill) and transparent modes.</p>
<p>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.</p>
<p>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.</p>
<p>drawTextAccel() -- Renders text with &amp; accelerator markers. The character after &amp; is underlined to indicate the keyboard shortcut.</p>
<h3>Performance Optimization</h3>
<p>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.</p>
</div>
<div class="topic" id="arch.colors">
<h1>Color System</h1>
<h2>Color System</h2>
<h3>Pixel Format</h3>
<p>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.</p>
<p>Supported depths:</p>
<pre> Depth Bytes/Pixel Notes
----- ----------- -----
8 bpp 1 Palette mode. Nearest-index via 6x6x6 color cube + grey ramp.
15 bpp 2 5-5-5 RGB (1 bit unused).
16 bpp 2 5-6-5 RGB.
32 bpp 4 8-8-8 RGB (8 bits unused).</pre>
<h3>ColorSchemeT -- Theming</h3>
<p>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.</p>
<p>Color roles mirror classic Motif/Windows 3.x conventions:</p>
<ul>
<li>desktop -- desktop background</li>
<li>windowFace, windowHighlight, windowShadow -- window chrome bevel triplet</li>
<li>activeTitleBg/Fg, inactiveTitleBg/Fg -- focused vs. unfocused title bar</li>
<li>contentBg/Fg -- window content area</li>
<li>menuBg/Fg, menuHighlightBg/Fg -- menus</li>
<li>buttonFace -- button background</li>
<li>scrollbarBg/Fg/Trough -- scrollbar components</li>
</ul>
<p>cursorFg/Bg -- mouse cursor colors</p>
<p>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().</p>
<h3>Bevel Styles</h3>
<p>Bevels are the defining visual element of the Motif aesthetic. Convenience macros create bevel style descriptors by swapping highlight and shadow colors:</p>
<pre><code> 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</code></pre>
</div>
<div class="topic" id="arch.platform">
<h1>Platform Layer</h1>
<h2>Platform Layer</h2>
<p>All OS-specific and CPU-specific code is isolated behind dvxPlatform.h. To port DVX, implement a new dvxPlatformXxx.c against this header.</p>
<h3>Implementations</h3>
<pre> File Target Details
---- ------ -------
dvxPlatformDos.c DJGPP/DPMI Real 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.</pre>
<h3>Abstraction Areas</h3>
<h4>Video</h4>
<p>platformVideoInit() -- mode probe and framebuffer setup. platformVideoShutdown() -- restore previous mode. platformVideoEnumModes() -- enumerate available modes.</p>
<h4>Framebuffer Flush</h4>
<p>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.</p>
<h4>Optimized Memory Spans</h4>
<p>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.</p>
<h4>Mouse Input</h4>
<p>Polling model. platformMousePoll() returns position and button bitmask. Wheel support via CuteMouse API.</p>
<h4>Keyboard Input</h4>
<p>platformKeyboardRead() -- non-blocking key read. platformKeyUpRead() -- key release detection (requires INT 9 hook on DOS). platformAltScanToChar() -- scancode-to-ASCII lookup for Alt+key combinations.</p>
<h4>Crash Recovery</h4>
<p>platformInstallCrashHandler() -- signal handlers + longjmp for fault tolerance.</p>
<h4>DXE Support</h4>
<p>platformRegisterDxeExports() -- register C runtime and platform symbols for DXE resolution. platformRegisterSymOverrides() -- register function pointer overrides for module loader.</p>
</div>
<div class="topic" id="arch.build">
<h1>Build System</h1>
<h2>Build System</h2>
<h3>Cross-Compilation</h3>
<p>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.</p>
<pre><code> make -- build everything
./mkcd.sh -- build + create ISO for 86Box</code></pre>
<h3>Build Targets</h3>
<pre><code> all: core tasks loader texthelp listhelp tools widgets shell taskmgr serial sql apps</code></pre>
<pre> Target Output Description
------ ------ -----------
core bin/libs/libdvx.lib GUI core library (draw, comp, wm, app, widget infrastructure)
tasks bin/libs/libtasks.lib Cooperative task switcher
loader bin/dvx.exe Bootstrap loader (the DOS executable)
widgets bin/widgets/*.wgt 29 widget type plugins
shell bin/libs/dvxshell.lib DVX Shell (app management, desktop)
taskmgr bin/libs/taskmgr.lib Task Manager (loaded as a separate DXE)
texthelp shared library Shared text editing helpers (clipboard, word boundaries)
listhelp shared library Shared dropdown/list helpers
apps bin/apps/*/*.app Application modules (progman, notepad, clock, etc.)
tools bin/dvxres Resource compiler (runs on Linux, builds resource sections into DXEs)
serial serial DXE libs UART driver, HDLC packets, security, seclink
sql SQL DXE lib SQLite integration</pre>
<h3>DXE3 Build Process</h3>
<p>Each DXE module is compiled to an object file with GCC, then linked with dxe3gen:</p>
<pre><code> # 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</code></pre>
<p>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).</p>
<h3>Deployment (mkcd.sh)</h3>
<ul>
<li>Runs make all.</li>
<li>Verifies critical outputs exist (dvx.exe, libtasks.lib, libdvx.lib, dvxshell.lib).</li>
<li>Counts widget modules.</li>
<li>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).</li>
</ul>
<p>Places the ISO at ~/.var/app/net._86box._86Box/data/86Box/dvx.iso for 86Box to mount as CD-ROM.</p>
<h3>Compiler Flags</h3>
<pre><code> -O2 Optimization level 2
-march=i486 486 instruction set baseline
-mtune=i586 Optimize scheduling for Pentium
-Wall -Wextra Full warnings</code></pre>
<h3>Directory Layout</h3>
<pre><code> 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 &lt;-&gt; secLink &lt;-&gt; telnet)
+-- sql/ SQLite integration
+-- bin/ Build output (dvx.exe, libs/, widgets/, apps/, config/)
+-- obj/ Intermediate object files
+-- docs/ Documentation</code></pre>
</div>
</main>
</body>
</html>

3699
docs/dvx_help.html
View file

File diff suppressed because it is too large Load diff

155
docs/dvx_help_sample.html
View file

@ -1,155 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Welcome to DVX</title>
<style>
body { font-family: sans-serif; margin: 0; padding: 0; display: flex; }
nav { width: 250px; min-width: 250px; background: #f0f0f0; padding: 16px;
border-right: 1px solid #ccc; height: 100vh; overflow-y: auto;
position: sticky; top: 0; box-sizing: border-box; }
nav ul { list-style: none; padding-left: 16px; margin: 4px 0; }
nav > ul { padding-left: 0; }
nav a { text-decoration: none; color: #0066cc; }
nav a:hover { text-decoration: underline; }
main { flex: 1; padding: 24px 32px; max-width: 800px; }
h1 { border-bottom: 2px solid #333; padding-bottom: 4px; }
h2 { border-bottom: 1px solid #999; padding-bottom: 2px; margin-top: 32px; }
h3 { margin-top: 24px; }
pre { background: #f8f8f8; border: 1px solid #ddd; padding: 8px;
overflow-x: auto; font-size: 14px; }
blockquote { background: #fffde7; border-left: 4px solid #ffc107;
padding: 8px 12px; margin: 12px 0; }
hr { border: none; border-top: 1px solid #ccc; margin: 24px 0; }
img { max-width: 100%; }
.topic { margin-bottom: 48px; }
</style>
</head>
<body>
<nav>
<h3>Contents</h3>
<ul>
<li><a href="#intro">Welcome to DVX</a></li>
<li><a href="#overview">System Overview</a></li>
<li><a href="#widgets">Widget System</a></li>
<li><a href="#keyboard">Keyboard Shortcuts</a></li>
</ul>
<h3>Index</h3>
<ul>
<li><a href="#intro">DVX</a></li>
<li><a href="#intro">Introduction</a></li>
<li><a href="#intro">Getting Started</a></li>
<li><a href="#overview">Architecture</a></li>
<li><a href="#overview">Layers</a></li>
<li><a href="#widgets">Widgets</a></li>
<li><a href="#widgets">Controls</a></li>
<li><a href="#keyboard">Keyboard</a></li>
<li><a href="#keyboard">Shortcuts</a></li>
<li><a href="#keyboard">Hotkeys</a></li>
</ul>
</nav>
<main>
<div class="topic" id="intro">
<h1>Welcome to DVX</h1>
<h2>Welcome to DVX</h2>
<p>DVX is a graphical user interface environment for DOS, designed for
486-class hardware and above. It provides a windowing system with a
Motif-inspired visual style, cooperative multitasking, and a widget-based
application framework.</p>
<p>DVX features include:</p>
<ul>
<li>A window manager with drag, resize, and minimize support</li>
<li>Over 25 built-in widget types including buttons, lists, and trees</li>
<li>Dynamic application loading via DXE3 modules</li>
<li>Theme support with customizable color schemes</li>
</ul>
<p>VESA VBE 2.0+ linear framebuffer rendering</p>
<p><a href="#overview">See also: System Overview</a></p>
<hr>
<blockquote><strong>Tip:</strong> Press F1 from any DVX application to open context-sensitive help.</blockquote>
</div>
<div class="topic" id="overview">
<h1>System Overview</h1>
<h2>System Overview</h2>
<p>DVX is built as a five-layer architecture, with each layer providing
services to the layer above it.</p>
<h3>Video Layer</h3>
<p>The video layer (dvxVideo) handles VESA VBE initialization, linear
framebuffer mapping, backbuffer allocation, and pixel format detection. It
supports 8-bit, 16-bit, and 32-bit color depths.</p>
<h3>Drawing Layer</h3>
<p>The drawing layer (dvxDraw) provides primitive rendering operations: filled
rectangles, beveled borders, text rendering, bitmap blitting, and clipped
drawing.</p>
<h3>Compositor</h3>
<p>The compositor (dvxComp) manages a dirty rectangle list. Only regions that
have changed since the last frame are flushed from the system RAM backbuffer
to the video card's linear framebuffer.</p>
<h3>Window Manager</h3>
<p>The window manager (dvxWm) handles the window stack, chrome rendering (title
bars, borders, close buttons), drag and resize interaction, focus
management, and menu bars.</p>
<h3>Application Layer</h3>
<p>The application layer (dvxApp) ties everything together with the event loop,
mouse and keyboard input, accelerator tables, and the public API used by
applications.</p>
<p><a href="#widgets">See also: Widget System</a></p>
</div>
<div class="topic" id="widgets">
<h1>Widget System</h1>
<h2>Widget System</h2>
<p>DVX provides a rich set of widgets (controls) for building application user
interfaces. Widgets are loaded as DXE3 plugin modules at startup.</p>
<h3>Layout Widgets</h3>
<ul>
<li>VBox -- Vertical box layout (stacks children vertically)</li>
<li>HBox -- Horizontal box layout (stacks children horizontally)</li>
<li>Frame -- Labeled group box with border</li>
<li>ScrollPane -- Scrollable container for oversized content</li>
<li>Splitter -- Resizable split between two panes</li>
</ul>
<p>TabControl -- Tabbed container</p>
<h3>Input Widgets</h3>
<ul>
<li>Button -- Push button with text label</li>
<li>TextInput -- Single-line text entry field</li>
<li>TextArea -- Multi-line text editor with syntax highlighting</li>
<li>Checkbox -- Boolean toggle with label</li>
<li>Radio -- Mutually exclusive option selector</li>
<li>Dropdown -- Drop-down selection list</li>
<li>ComboBox -- Editable dropdown with text entry</li>
<li>Slider -- Horizontal or vertical value slider</li>
</ul>
<p>Spinner -- Numeric up/down control</p>
<h3>Display Widgets</h3>
<ul>
<li>Label -- Single-line text display</li>
<li>Image -- Bitmap image display</li>
<li>ProgressBar -- Visual progress indicator</li>
<li>Canvas -- Custom drawing surface</li>
</ul>
<p>Separator -- Horizontal or vertical divider line</p>
<h3>Data Widgets</h3>
<ul>
<li>ListBox -- Scrollable list of text items</li>
<li>ListView -- Multi-column sortable list with headers</li>
</ul>
<p>TreeView -- Hierarchical tree with expand/collapse</p>
</div>
<div class="topic" id="keyboard">
<h1>Keyboard Shortcuts</h1>
<h2>Keyboard Shortcuts</h2>
<p>The following keyboard shortcuts are available system-wide in DVX:</p>
<pre> Shortcut Action
-------- ------
Alt+F4 Close active window
F10 Activate menu bar
Ctrl+Esc Open task manager
Tab Move focus to next widget
Shift+Tab Move focus to previous widget
Enter Activate focused button
Escape Close dialog or cancel operation</pre>
</div>
</main>
</body>
</html>

1234
docs/dvx_widget_reference.html
View file

File diff suppressed because it is too large Load diff

134
docs/dvx_widget_system.html
View file

@ -1,134 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Base WidgetT (Common Properties, Events, and Operations)</title>
<style>
body { font-family: sans-serif; margin: 0; padding: 0; display: flex; }
nav { width: 250px; min-width: 250px; background: #f0f0f0; padding: 16px;
border-right: 1px solid #ccc; height: 100vh; overflow-y: auto;
position: sticky; top: 0; box-sizing: border-box; }
nav ul { list-style: none; padding-left: 16px; margin: 4px 0; }
nav > ul { padding-left: 0; }
nav a { text-decoration: none; color: #0066cc; }
nav a:hover { text-decoration: underline; }
main { flex: 1; padding: 24px 32px; max-width: 800px; }
h1 { border-bottom: 2px solid #333; padding-bottom: 4px; }
h2 { border-bottom: 1px solid #999; padding-bottom: 2px; margin-top: 32px; }
h3 { margin-top: 24px; }
pre { background: #f8f8f8; border: 1px solid #ddd; padding: 8px;
overflow-x: auto; font-size: 14px; }
blockquote { background: #fffde7; border-left: 4px solid #ffc107;
padding: 8px 12px; margin: 12px 0; }
hr { border: none; border-top: 1px solid #ccc; margin: 24px 0; }
img { max-width: 100%; }
.topic { margin-bottom: 48px; }
</style>
</head>
<body>
<nav>
<h3>Contents</h3>
<ul>
<li><a href="#widget.base">Widget System</a></li>
</ul>
<h3>Index</h3>
<ul>
<li><a href="#widget.base">WidgetT</a></li>
<li><a href="#widget.base">Widget Base</a></li>
<li><a href="#widget.base">Common Properties</a></li>
<li><a href="#widget.base">Common Events</a></li>
<li><a href="#widget.base">wgtPixels</a></li>
<li><a href="#widget.base">wgtChars</a></li>
<li><a href="#widget.base">wgtPercent</a></li>
<li><a href="#widget.base">onClick</a></li>
<li><a href="#widget.base">onChange</a></li>
<li><a href="#widget.base">onKeyPress</a></li>
<li><a href="#widget.base">onKeyDown</a></li>
<li><a href="#widget.base">onMouseDown</a></li>
<li><a href="#widget.base">wgtInitWindow</a></li>
<li><a href="#widget.base">wgtGetContext</a></li>
<li><a href="#widget.base">wgtInvalidate</a></li>
<li><a href="#widget.base">wgtSetText</a></li>
<li><a href="#widget.base">wgtGetText</a></li>
<li><a href="#widget.base">wgtSetEnabled</a></li>
<li><a href="#widget.base">wgtSetFocused</a></li>
<li><a href="#widget.base">wgtSetVisible</a></li>
<li><a href="#widget.base">wgtFind</a></li>
<li><a href="#widget.base">wgtDestroy</a></li>
</ul>
</nav>
<main>
<div class="topic" id="widget.base">
<h1>Base WidgetT (Common Properties, Events, and Operations)</h1>
<h2>DVX Widget System</h2>
<p>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/.</p>
<p>Individual widgets are documented in their own sections. See the table of contents for the full list.</p>
<h3>Base WidgetT (Common Properties, Events, and Operations)</h3>
<p>Every widget inherits from the WidgetT structure defined in core/dvxWidget.h. The fields and callbacks listed here are available on all widget types.</p>
<h4>Common Properties</h4>
<pre> Field Type Description
----- ---- -----------
name char[32] Widget name for lookup via wgtFind().
x, y, w, h int32_t Computed geometry relative to the window content area (set by layout).
minW, minH int32_t (tagged) Minimum size hints. Use wgtPixels(), wgtChars(), or wgtPercent(). 0 = auto.
maxW, maxH int32_t (tagged) Maximum size constraints. 0 = no limit.
prefW, prefH int32_t (tagged) Preferred size. 0 = auto.
weight int32_t Extra-space distribution weight. 0 = fixed, 100 = normal. A widget with weight=200 gets twice the extra space of one with weight=100.
align WidgetAlignE Main-axis alignment for children: AlignStartE, AlignCenterE, AlignEndE.
spacing int32_t (tagged) Spacing between children (containers only). 0 = default.
padding int32_t (tagged) Internal padding (containers only). 0 = default.
fgColor uint32_t Foreground color override. 0 = use color scheme default.
bgColor uint32_t Background color override. 0 = use color scheme default.
visible bool Visibility state.
enabled bool Enabled state. Disabled widgets are grayed out and ignore input.
readOnly bool Read-only mode: allows scrolling/selection but blocks editing.
swallowTab bool When true, Tab key goes to the widget instead of navigating focus.
accelKey char Lowercase accelerator character. 0 if none.
tooltip const char * Tooltip text. NULL = none. Caller owns the string.
contextMenu MenuT * Right-click context menu. NULL = none. Caller owns.
userData void * Application-defined user data pointer.</pre>
<h4>Size Specification Macros</h4>
<pre> Macro Description
----- -----------
wgtPixels(v) Size in pixels.
wgtChars(v) Size in character widths (multiplied by font charWidth).
wgtPercent(v) Size as a percentage of parent dimension.</pre>
<h4>Common Events (Callbacks)</h4>
<p>These callback function pointers are available on every WidgetT. Set them directly on the widget struct.</p>
<pre> Callback Signature Description
-------- --------- -----------
onClick void (*)(WidgetT *w) Fires on mouse click / activation.
onDblClick void (*)(WidgetT *w) Fires on double-click.
onChange void (*)(WidgetT *w) Fires when the widget's value changes (text, selection, check state, etc.).
onFocus void (*)(WidgetT *w) Fires when the widget receives keyboard focus.
onBlur void (*)(WidgetT *w) Fires when the widget loses keyboard focus.
onKeyPress void (*)(WidgetT *w, int32_t keyAscii) Fires on a printable key press (ASCII value).
onKeyDown void (*)(WidgetT *w, int32_t keyCode, int32_t shift) Fires on key down (scan code + shift state).
onKeyUp void (*)(WidgetT *w, int32_t keyCode, int32_t shift) Fires on key up.
onMouseDown void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) Fires on mouse button press.
onMouseUp void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) Fires on mouse button release.
onMouseMove void (*)(WidgetT *w, int32_t button, int32_t x, int32_t y) Fires on mouse movement over the widget.
onScroll void (*)(WidgetT *w, int32_t delta) Fires on mouse wheel scroll.
onValidate bool (*)(WidgetT *w) Validation callback. Return false to cancel a pending write.</pre>
<h4>Common Operations</h4>
<pre> Function Description
-------- -----------
WidgetT *wgtInitWindow(AppContextT *ctx, WindowT *win) Initialize widgets for a window. Returns the root VBox container.
AppContextT *wgtGetContext(const WidgetT *w) Walk up from any widget to retrieve the AppContextT.
void wgtInvalidate(WidgetT *w) Mark widget for re-layout and repaint. Propagates to ancestors.
void wgtInvalidatePaint(WidgetT *w) Mark widget for repaint only (no layout recalculation).
void wgtSetText(WidgetT *w, const char *text) Set widget text (label, button, textinput, etc.).
const char *wgtGetText(const WidgetT *w) Get widget text.
void wgtSetEnabled(WidgetT *w, bool enabled) Enable or disable a widget.
void wgtSetReadOnly(WidgetT *w, bool readOnly) Set read-only mode.
void wgtSetFocused(WidgetT *w) Set keyboard focus to a widget.
WidgetT *wgtGetFocused(void) Get the currently focused widget.
void wgtSetVisible(WidgetT *w, bool visible) Show or hide a widget.
void wgtSetName(WidgetT *w, const char *name) Set widget name for lookup.
WidgetT *wgtFind(WidgetT *root, const char *name) Find a widget by name in the subtree.
void wgtDestroy(WidgetT *w) Destroy a widget and all its children.
void wgtSetTooltip(WidgetT *w, const char *text) Set tooltip text. Pass NULL to remove.</pre>
</div>
</main>
</body>
</html>

1137
docs/dvxbasic_control_reference.html
View file

File diff suppressed because it is too large Load diff

349
docs/dvxbasic_controls_overview.html
View file

@ -1,349 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Common Properties, Events, and Methods</title>
<style>
body { font-family: sans-serif; margin: 0; padding: 0; display: flex; }
nav { width: 250px; min-width: 250px; background: #f0f0f0; padding: 16px;
border-right: 1px solid #ccc; height: 100vh; overflow-y: auto;
position: sticky; top: 0; box-sizing: border-box; }
nav ul { list-style: none; padding-left: 16px; margin: 4px 0; }
nav > ul { padding-left: 0; }
nav a { text-decoration: none; color: #0066cc; }
nav a:hover { text-decoration: underline; }
main { flex: 1; padding: 24px 32px; max-width: 800px; }
h1 { border-bottom: 2px solid #333; padding-bottom: 4px; }
h2 { border-bottom: 1px solid #999; padding-bottom: 2px; margin-top: 32px; }
h3 { margin-top: 24px; }
pre { background: #f8f8f8; border: 1px solid #ddd; padding: 8px;
overflow-x: auto; font-size: 14px; }
blockquote { background: #fffde7; border-left: 4px solid #ffc107;
padding: 8px 12px; margin: 12px 0; }
hr { border: none; border-top: 1px solid #ccc; margin: 24px 0; }
img { max-width: 100%; }
.topic { margin-bottom: 48px; }
</style>
</head>
<body>
<nav>
<h3>Contents</h3>
<ul>
<li><a href="#ctrl.common.props">Common Properties, Events, and Methods</a>
<ul>
<li><a href="#ctrl.databinding">Data Binding</a></li>
<li><a href="#ctrl.menus">Menu System</a></li>
<li><a href="#ctrl.arrays">Control Arrays</a></li>
<li><a href="#ctrl.frm">FRM File Format</a></li>
</ul>
</li>
</ul>
<h3>Index</h3>
<ul>
<li><a href="#ctrl.common.props">Common Properties</a></li>
<li><a href="#ctrl.common.props">Common Events</a></li>
<li><a href="#ctrl.common.props">Common Methods</a></li>
<li><a href="#ctrl.common.props">Properties</a></li>
<li><a href="#ctrl.common.props">Events</a></li>
<li><a href="#ctrl.common.props">Methods</a></li>
<li><a href="#ctrl.databinding">Data Binding</a></li>
<li><a href="#ctrl.databinding">DataSource</a></li>
<li><a href="#ctrl.databinding">DataField</a></li>
<li><a href="#ctrl.databinding">Master-Detail</a></li>
<li><a href="#ctrl.menus">Menu</a></li>
<li><a href="#ctrl.menus">Menu Bar</a></li>
<li><a href="#ctrl.menus">Submenu</a></li>
<li><a href="#ctrl.menus">Separator</a></li>
<li><a href="#ctrl.arrays">Control Arrays</a></li>
<li><a href="#ctrl.arrays">Index Property</a></li>
<li><a href="#ctrl.frm">FRM</a></li>
<li><a href="#ctrl.frm">.frm</a></li>
<li><a href="#ctrl.frm">Form File</a></li>
</ul>
</nav>
<main>
<div class="topic" id="ctrl.common.props">
<h1>Common Properties, Events, and Methods</h1>
<h2>Common Properties, Events, and Methods</h2>
<p>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.</p>
<h3>Common Properties</h3>
<pre> Property Type R/W Description
---------- ------- --- -------------------------------------------
Name String R The control's name (e.g. &quot;Command1&quot;). Read-only at runtime.
Left Integer R/W X position in pixels relative to the parent container.
Top Integer R/W Y position in pixels relative to the parent container.
Width Integer R/W Current width in pixels. Setting this changes the minimum width constraint.
Height Integer R/W Current height in pixels. Setting this changes the minimum height constraint.
MinWidth Integer R/W Minimum width for layout. Alias for Width in the setter.
MinHeight Integer R/W Minimum height for layout. Alias for Height in the setter.
MaxWidth Integer R/W Maximum width cap (0 = no limit, stretch to fill).
MaxHeight Integer R/W Maximum height cap (0 = no limit, stretch to fill).
Weight Integer R/W Layout weight. 0 = fixed size, &gt;0 = share extra space proportionally.
Visible Boolean R/W Whether the control is visible.
Enabled Boolean R/W Whether the control accepts user input.
BackColor Long R/W Background color as a 32-bit ARGB value.
ForeColor Long R/W Foreground (text) color as a 32-bit ARGB value.
TabIndex Integer R Accepted for VB compatibility but ignored. DVX has no tab order.</pre>
<h3>Common Events</h3>
<p>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.</p>
<pre> Event Parameters Description
--------- ------------------------------------------- -------------------------------------------
Click (none) Fires when the control is clicked.
DblClick (none) Fires when the control is double-clicked.
Change (none) Fires when the control's value or text changes.
GotFocus (none) Fires when the control receives keyboard focus.
LostFocus (none) Fires when the control loses keyboard focus.
KeyPress KeyAscii As Integer Fires when a printable key is pressed. KeyAscii is the ASCII code.
KeyDown KeyCode As Integer, Shift As Integer Fires when any key is pressed down. KeyCode is the scan code; Shift indicates modifier keys.
KeyUp KeyCode As Integer, Shift As Integer Fires when a key is released.
MouseDown Button As Integer, X As Integer, Y As Integer Fires when a mouse button is pressed over the control.
MouseUp Button As Integer, X As Integer, Y As Integer Fires when a mouse button is released over the control.
MouseMove Button As Integer, X As Integer, Y As Integer Fires when the mouse moves over the control.
Scroll Delta As Integer Fires when the control is scrolled (mouse wheel or scrollbar).</pre>
<h3>Common Methods</h3>
<pre> Method Parameters Description
-------- ---------- -------------------------------------------
SetFocus (none) Gives keyboard focus to this control.
Refresh (none) Forces the control to repaint.</pre>
<p><a href="#ctrl.form">Form</a></p>
<p><a href="#ctrl.databinding">Data Binding</a></p>
<p><a href="#ctrl.frm">FRM File Format</a></p>
</div>
<div class="topic" id="ctrl.databinding">
<h1>Data Binding</h1>
<h2>Data Binding</h2>
<p>DVX BASIC provides VB3-style data binding through three properties that can be set on most controls:</p>
<pre> Property Set On Description
---------- ----------- -------------------------------------------
DataSource Any control Name of the Data control to bind to (e.g. &quot;Data1&quot;).
DataField Any control Column name from the Data control's recordset to display.</pre>
<h3>How It Works</h3>
<ul>
<li>Place a Data control on the form and set its DatabaseName and RecordSource properties.</li>
<li>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.</li>
<li>When the form loads, the Data control auto-refreshes: it opens the database, runs the query, and navigates to the first record.</li>
<li>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).</li>
</ul>
<p>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.</p>
<h3>Master-Detail Binding</h3>
<p>For hierarchical data (e.g. orders and order items), use two Data controls:</p>
<ul>
<li>A master Data control bound to the parent table.</li>
</ul>
<p>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.</p>
<p>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.</p>
<h3>DBGrid Binding</h3>
<p>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.</p>
<h3>Example</h3>
<pre><code>VERSION DVX 1.00
Begin Form frmData
Caption = &quot;Data Binding Example&quot;
AutoSize = False
Width = 400
Height = 280
Begin Data Data1
DatabaseName = &quot;myapp.db&quot;
RecordSource = &quot;customers&quot;
End
Begin Label lblName
Caption = &quot;Name:&quot;
End
Begin TextBox txtName
DataSource = &quot;Data1&quot;
DataField = &quot;name&quot;
End
Begin Label lblEmail
Caption = &quot;Email:&quot;
End
Begin TextBox txtEmail
DataSource = &quot;Data1&quot;
DataField = &quot;email&quot;
End
End
Sub Data1_Reposition ()
Print &quot;Current record changed&quot;
End Sub
Sub Data1_Validate (Cancel As Integer)
If txtName.Text = &quot;&quot; Then
MsgBox &quot;Name cannot be empty!&quot;
Cancel = 1
End If
End Sub</code></pre>
<p><a href="#ctrl.data">Data</a></p>
<p><a href="#ctrl.dbgrid">DBGrid</a></p>
</div>
<div class="topic" id="ctrl.menus">
<h1>Menu System</h1>
<h2>Menu System</h2>
<p>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.</p>
<h3>FRM Syntax</h3>
<pre><code>Begin Form Form1
Caption = &quot;Menu Demo&quot;
Begin Menu mnuFile
Caption = &quot;&amp;File&quot;
Begin Menu mnuOpen
Caption = &quot;&amp;Open&quot;
End
Begin Menu mnuSave
Caption = &quot;&amp;Save&quot;
End
Begin Menu mnuSep1
Caption = &quot;-&quot;
End
Begin Menu mnuExit
Caption = &quot;E&amp;xit&quot;
End
End
Begin Menu mnuEdit
Caption = &quot;&amp;Edit&quot;
Begin Menu mnuCopy
Caption = &quot;&amp;Copy&quot;
End
Begin Menu mnuPaste
Caption = &quot;&amp;Paste&quot;
End
End
End</code></pre>
<h3>Menu Item Properties</h3>
<pre> Property Type Description
-------- ------- -------------------------------------------
Caption String The text displayed. Use &amp; for accelerator key. Set to &quot;-&quot; for a separator.
Checked Boolean Whether the menu item shows a checkmark.
Enabled Boolean Whether the menu item is enabled (default True).</pre>
<h3>Nesting</h3>
<p>Menu items are nested by placing Begin Menu blocks inside other Begin Menu blocks:</p>
<ul>
<li>Level 0: top-level menu bar headers (e.g. &quot;File&quot;, &quot;Edit&quot;).</li>
<li>Level 1: items within a top-level menu.</li>
</ul>
<p>Level 2+: submenu items.</p>
<p>A level-0 menu that contains children becomes a top-level menu header. A non-level-0 menu that contains children becomes a submenu.</p>
<h3>Event Dispatch</h3>
<p>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.</p>
<pre><code>Sub mnuOpen_Click ()
MsgBox &quot;Open was clicked&quot;
End Sub
Sub mnuExit_Click ()
Unload Form1
End Sub</code></pre>
<p><a href="#ctrl.form">Form</a></p>
<p><a href="#ctrl.frm">FRM File Format</a></p>
</div>
<div class="topic" id="ctrl.arrays">
<h1>Control Arrays</h1>
<h2>Control Arrays</h2>
<p>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.</p>
<h3>Defining Control Arrays in FRM</h3>
<pre><code>Begin CommandButton Command1
Caption = &quot;Button A&quot;
Index = 0
End
Begin CommandButton Command1
Caption = &quot;Button B&quot;
Index = 1
End
Begin CommandButton Command1
Caption = &quot;Button C&quot;
Index = 2
End</code></pre>
<h3>Event Handler Convention</h3>
<p>When a control has an Index property (&gt;= 0), the event handler receives Index As Integer as the first parameter, before any event-specific parameters.</p>
<pre><code>Sub Command1_Click (Index As Integer)
Select Case Index
Case 0
MsgBox &quot;Button A clicked&quot;
Case 1
MsgBox &quot;Button B clicked&quot;
Case 2
MsgBox &quot;Button C clicked&quot;
End Select
End Sub</code></pre>
<h3>Accessing Array Elements in Code</h3>
<p>Use the indexed form ControlName(Index) to access a specific element:</p>
<pre><code>Command1(0).Caption = &quot;New Text&quot;
Command1(1).Enabled = False</code></pre>
<blockquote><strong>Note:</strong> 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)).</blockquote>
<p><a href="#ctrl.common.props">Common Properties, Events, and Methods</a></p>
<p><a href="#ctrl.frm">FRM File Format</a></p>
</div>
<div class="topic" id="ctrl.frm">
<h1>FRM File Format</h1>
<h2>FRM File Format</h2>
<p>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.</p>
<h3>Structure</h3>
<pre><code>VERSION DVX 1.00
Begin Form FormName
form-level properties...
Begin Menu mnuFile
Caption = &quot;&amp;File&quot;
Begin Menu mnuOpen
Caption = &quot;&amp;Open&quot;
End
End
Begin TypeName ControlName
property = value
...
End
Begin Frame Frame1
Caption = &quot;Group&quot;
Begin TypeName ChildName
...
End
End
End
BASIC code follows...
Sub FormName_Load ()
...
End Sub</code></pre>
<h3>Rules</h3>
<ul>
<li>The VERSION line is optional. VERSION DVX 1.00 marks a native DVX form. VB forms with version &lt;= 2.0 are accepted for import.</li>
<li>The form block begins with Begin Form Name and ends with End.</li>
<li>Controls are nested with Begin TypeName Name / End.</li>
<li>Container controls (Frame, VBox, HBox, Toolbar, TabStrip, ScrollPane, Splitter, WrapBox) can have child controls nested inside them.</li>
<li>Properties are assigned as Key = Value. String values are optionally quoted.</li>
<li>Everything after the form's closing End is BASIC source code.</li>
<li>Comments in the form section use ' (single quote).</li>
</ul>
<p>Blank lines are ignored in the form section.</p>
<h3>Common FRM Properties</h3>
<pre> Property Applies To Description
----------------------- --------------- -------------------------------------------
Caption Form, controls Display text or window title.
Text TextBox, ComboBox Initial text content.
MinWidth / Width Controls Minimum width. Both names are accepted.
MinHeight / Height Controls Minimum height. Both names are accepted.
MaxWidth Controls Maximum width (0 = no cap).
MaxHeight Controls Maximum height (0 = no cap).
Weight Controls Layout weight for flexible sizing.
Left Form, controls X position (used by Form when Centered=False; informational for controls).
Top Form, controls Y position.
Index Controls Control array index (-1 or absent = not in array).
Visible Controls Initial visibility.
Enabled Controls Initial enabled state.
Layout Form &quot;VBox&quot; or &quot;HBox&quot;.
AutoSize Form Auto-fit window to content.
Resizable Form Allow runtime resizing.
Centered Form Center window on screen.
DatabaseName Data SQLite database file path.
RecordSource Data Table name or SQL query.
DataSource Bound controls Name of the Data control.
DataField Bound controls Column name in the recordset.</pre>
<p><a href="#ctrl.form">Form</a></p>
<p><a href="#ctrl.common.props">Common Properties, Events, and Methods</a></p>
<p><a href="#ctrl.menus">Menu System</a></p>
<p><a href="#ctrl.arrays">Control Arrays</a></p>
</div>
</main>
</body>
</html>

2824
docs/dvxbasic_help.html
View file

File diff suppressed because it is too large Load diff

758
docs/dvxbasic_ide_guide.html
View file

@ -1,758 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>DVX BASIC IDE Guide</title>
<style>
body { font-family: sans-serif; margin: 0; padding: 0; display: flex; }
nav { width: 250px; min-width: 250px; background: #f0f0f0; padding: 16px;
border-right: 1px solid #ccc; height: 100vh; overflow-y: auto;
position: sticky; top: 0; box-sizing: border-box; }
nav ul { list-style: none; padding-left: 16px; margin: 4px 0; }
nav > ul { padding-left: 0; }
nav a { text-decoration: none; color: #0066cc; }
nav a:hover { text-decoration: underline; }
main { flex: 1; padding: 24px 32px; max-width: 800px; }
h1 { border-bottom: 2px solid #333; padding-bottom: 4px; }
h2 { border-bottom: 1px solid #999; padding-bottom: 2px; margin-top: 32px; }
h3 { margin-top: 24px; }
pre { background: #f8f8f8; border: 1px solid #ddd; padding: 8px;
overflow-x: auto; font-size: 14px; }
blockquote { background: #fffde7; border-left: 4px solid #ffc107;
padding: 8px 12px; margin: 12px 0; }
hr { border: none; border-top: 1px solid #ccc; margin: 24px 0; }
img { max-width: 100%; }
.topic { margin-bottom: 48px; }
</style>
</head>
<body>
<nav>
<h3>Contents</h3>
<ul>
<li><a href="#ide.overview">Overview</a>
<ul>
<li><a href="#ide.menu.file">Menu Reference</a>
<ul>
<li><a href="#ide.menu.file">File Menu</a></li>
<li><a href="#ide.menu.edit">Edit Menu</a></li>
<li><a href="#ide.menu.run">Run Menu</a></li>
<li><a href="#ide.menu.view">View Menu</a></li>
<li><a href="#ide.menu.window">Window Menu</a></li>
<li><a href="#ide.menu.tools">Tools Menu</a></li>
<li><a href="#ide.menu.help">Help Menu</a></li>
</ul>
</li>
<li><a href="#ide.toolbar">Toolbar</a></li>
<li><a href="#ide.editor">Code Editor</a></li>
<li><a href="#ide.designer">Form Designer</a></li>
<li><a href="#ide.project">Project System</a></li>
<li><a href="#ide.properties">Properties Panel</a></li>
<li><a href="#ide.toolbox">Toolbox</a></li>
<li><a href="#ide.debugger">Debugger</a></li>
<li><a href="#ide.debug.locals">Debug Windows</a>
<ul>
<li><a href="#ide.debug.locals">Locals Window</a></li>
<li><a href="#ide.debug.callstack">Call Stack Window</a></li>
<li><a href="#ide.debug.watch">Watch Window</a></li>
<li><a href="#ide.debug.breakpoints">Breakpoints Window</a></li>
</ul>
</li>
<li><a href="#ide.immediate">Immediate Window</a></li>
<li><a href="#ide.output">Output Window</a></li>
<li><a href="#ide.findreplace">Find / Replace</a></li>
<li><a href="#ide.preferences">Preferences</a></li>
<li><a href="#ide.shortcuts">Keyboard Shortcuts</a></li>
</ul>
</li>
</ul>
<h3>Index</h3>
<ul>
<li><a href="#ide.overview">DVX BASIC</a></li>
<li><a href="#ide.overview">IDE</a></li>
<li><a href="#ide.overview">Visual Basic</a></li>
<li><a href="#ide.overview">Development Environment</a></li>
<li><a href="#ide.menu.file">File Menu</a></li>
<li><a href="#ide.menu.file">New Project</a></li>
<li><a href="#ide.menu.file">Open Project</a></li>
<li><a href="#ide.menu.file">Save Project</a></li>
<li><a href="#ide.menu.file">Close Project</a></li>
<li><a href="#ide.menu.file">Project Properties</a></li>
<li><a href="#ide.menu.file">Add File</a></li>
<li><a href="#ide.menu.file">Save File</a></li>
<li><a href="#ide.menu.file">Save All</a></li>
<li><a href="#ide.menu.file">Remove File</a></li>
<li><a href="#ide.menu.file">Exit</a></li>
<li><a href="#ide.menu.edit">Edit Menu</a></li>
<li><a href="#ide.menu.edit">Cut</a></li>
<li><a href="#ide.menu.edit">Copy</a></li>
<li><a href="#ide.menu.edit">Paste</a></li>
<li><a href="#ide.menu.edit">Select All</a></li>
<li><a href="#ide.menu.edit">Delete</a></li>
<li><a href="#ide.menu.edit">Find</a></li>
<li><a href="#ide.menu.edit">Find Next</a></li>
<li><a href="#ide.menu.edit">Replace</a></li>
<li><a href="#ide.menu.run">Run Menu</a></li>
<li><a href="#ide.menu.run">Run</a></li>
<li><a href="#ide.menu.run">Debug</a></li>
<li><a href="#ide.menu.run">Run Without Recompile</a></li>
<li><a href="#ide.menu.run">Stop</a></li>
<li><a href="#ide.menu.run">Step Into</a></li>
<li><a href="#ide.menu.run">Step Over</a></li>
<li><a href="#ide.menu.run">Step Out</a></li>
<li><a href="#ide.menu.run">Run to Cursor</a></li>
<li><a href="#ide.menu.run">Toggle Breakpoint</a></li>
<li><a href="#ide.menu.run">Clear Output</a></li>
<li><a href="#ide.menu.run">Save on Run</a></li>
<li><a href="#ide.menu.view">View Menu</a></li>
<li><a href="#ide.menu.view">Code View</a></li>
<li><a href="#ide.menu.view">Design View</a></li>
<li><a href="#ide.menu.view">Toolbar Toggle</a></li>
<li><a href="#ide.menu.view">Status Bar Toggle</a></li>
<li><a href="#ide.menu.view">Menu Editor</a></li>
<li><a href="#ide.menu.window">Window Menu</a></li>
<li><a href="#ide.menu.tools">Tools Menu</a></li>
<li><a href="#ide.menu.tools">Preferences</a></li>
<li><a href="#ide.menu.tools">Debug Layout</a></li>
<li><a href="#ide.menu.help">Help Menu</a></li>
<li><a href="#ide.menu.help">About</a></li>
<li><a href="#ide.toolbar">Toolbar</a></li>
<li><a href="#ide.editor">Code Editor</a></li>
<li><a href="#ide.editor">Syntax Highlighting</a></li>
<li><a href="#ide.editor">Object Dropdown</a></li>
<li><a href="#ide.editor">Function Dropdown</a></li>
<li><a href="#ide.editor">Line Numbers</a></li>
<li><a href="#ide.editor">Auto-indent</a></li>
<li><a href="#ide.designer">Form Designer</a></li>
<li><a href="#ide.designer">Design Surface</a></li>
<li><a href="#ide.designer">Grid Snapping</a></li>
<li><a href="#ide.designer">Grab Handles</a></li>
<li><a href="#ide.designer">Control Placement</a></li>
<li><a href="#ide.designer">WYSIWYG</a></li>
<li><a href="#ide.project">Project System</a></li>
<li><a href="#ide.project">Project Files</a></li>
<li><a href="#ide.project">.dbp Files</a></li>
<li><a href="#ide.project">Project Explorer</a></li>
<li><a href="#ide.project">Source Map</a></li>
<li><a href="#ide.properties">Properties Panel</a></li>
<li><a href="#ide.properties">Control Properties</a></li>
<li><a href="#ide.properties">Property List</a></li>
<li><a href="#ide.properties">Control Tree</a></li>
<li><a href="#ide.toolbox">Toolbox</a></li>
<li><a href="#ide.toolbox">Controls</a></li>
<li><a href="#ide.toolbox">Widget Palette</a></li>
<li><a href="#ide.debugger">Debugger</a></li>
<li><a href="#ide.debugger">Breakpoints</a></li>
<li><a href="#ide.debugger">Stepping</a></li>
<li><a href="#ide.debugger">Debug Mode</a></li>
<li><a href="#ide.debugger">DBG_IDLE</a></li>
<li><a href="#ide.debugger">DBG_RUNNING</a></li>
<li><a href="#ide.debugger">DBG_PAUSED</a></li>
<li><a href="#ide.debug.locals">Locals Window</a></li>
<li><a href="#ide.debug.locals">Variable Inspection</a></li>
<li><a href="#ide.debug.callstack">Call Stack</a></li>
<li><a href="#ide.debug.callstack">Stack Trace</a></li>
<li><a href="#ide.debug.watch">Watch Window</a></li>
<li><a href="#ide.debug.watch">Watch Expressions</a></li>
<li><a href="#ide.debug.breakpoints">Breakpoints Window</a></li>
<li><a href="#ide.immediate">Immediate Window</a></li>
<li><a href="#ide.immediate">REPL</a></li>
<li><a href="#ide.immediate">Expression Evaluation</a></li>
<li><a href="#ide.immediate">Variable Assignment</a></li>
<li><a href="#ide.output">Output Window</a></li>
<li><a href="#ide.output">PRINT Output</a></li>
<li><a href="#ide.output">Runtime Errors</a></li>
<li><a href="#ide.output">Compile Errors</a></li>
<li><a href="#ide.findreplace">Find</a></li>
<li><a href="#ide.findreplace">Replace</a></li>
<li><a href="#ide.findreplace">Find Next</a></li>
<li><a href="#ide.findreplace">Search</a></li>
<li><a href="#ide.preferences">Preferences</a></li>
<li><a href="#ide.preferences">Settings</a></li>
<li><a href="#ide.preferences">Tab Width</a></li>
<li><a href="#ide.preferences">Option Explicit</a></li>
<li><a href="#ide.shortcuts">Keyboard Shortcuts</a></li>
<li><a href="#ide.shortcuts">Hotkeys</a></li>
<li><a href="#ide.shortcuts">Accelerators</a></li>
</ul>
</nav>
<main>
<div class="topic" id="ide.overview">
<h1>DVX BASIC IDE Guide</h1>
<h2>DVX BASIC IDE Guide</h2>
<p>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.</p>
<p>This guide covers every feature of the IDE: menus, toolbar, editor, form designer, project management, debugger, and auxiliary windows.</p>
<h3>IDE Windows</h3>
<p>The DVX BASIC IDE is modeled after Visual Basic 3.0. It consists of several floating windows arranged on the DVX desktop:</p>
<ul>
<li>Main Toolbar Window -- anchored at the top of the screen. Contains the menu bar, toolbar buttons, and status bar.</li>
<li>Code Editor -- the primary editing surface for BASIC source code, with Object/Event dropdowns, syntax highlighting, and line numbers.</li>
<li>Form Designer -- a visual design surface for .frm files, showing a WYSIWYG preview of the form with grab handles for resizing controls.</li>
<li>Project Explorer -- a tree view listing all files in the project.</li>
<li>Toolbox -- a palette of available controls for placing on forms.</li>
<li>Properties Panel -- a tree of controls and a list of editable properties for the selected control.</li>
<li>Output Window -- displays PRINT output and runtime errors.</li>
<li>Immediate Window -- an interactive REPL for evaluating expressions and modifying variables at runtime.</li>
</ul>
<p>Debug Windows -- Locals, Call Stack, Watch, and Breakpoints windows that appear automatically when debugging.</p>
<p>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.</p>
<p><a href="#ide.menu.file">File Menu</a></p>
<p><a href="#ide.menu.edit">Edit Menu</a></p>
<p><a href="#ide.menu.run">Run Menu</a></p>
<p><a href="#ide.menu.view">View Menu</a></p>
<p><a href="#ide.menu.window">Window Menu</a></p>
<p><a href="#ide.menu.tools">Tools Menu</a></p>
<p><a href="#ide.menu.help">Help Menu</a></p>
<p><a href="#ide.toolbar">Toolbar</a></p>
<p><a href="#ide.editor">Code Editor</a></p>
<p><a href="#ide.designer">Form Designer</a></p>
<p><a href="#ide.project">Project System</a></p>
<p><a href="#ide.properties">Properties Panel</a></p>
<p><a href="#ide.toolbox">Toolbox</a></p>
<p><a href="#ide.debugger">Debugger</a></p>
<p><a href="#ide.debug.locals">Locals Window</a></p>
<p><a href="#ide.debug.callstack">Call Stack Window</a></p>
<p><a href="#ide.debug.watch">Watch Window</a></p>
<p><a href="#ide.debug.breakpoints">Breakpoints Window</a></p>
<p><a href="#ide.immediate">Immediate Window</a></p>
<p><a href="#ide.output">Output Window</a></p>
<p><a href="#ide.findreplace">Find / Replace</a></p>
<p><a href="#ide.preferences">Preferences</a></p>
<p><a href="#ide.shortcuts">Keyboard Shortcuts</a></p>
</div>
<div class="topic" id="ide.menu.file">
<h1>File Menu</h1>
<h2>File Menu</h2>
<pre> Menu Item Shortcut Description
--------- -------- -----------
New Project... Create a new DVX BASIC project.
Open Project... Open an existing .dbp project file.
Save Project Save the current project file to disk.
Close Project Close the current project (prompts to save unsaved changes).
---
Project Properties... Edit project metadata (name, author, version, startup form, icon, etc.).
---
Add File... Ctrl+O Add a .bas or .frm file to the project. If no project is open, creates an implicit project from the file.
Save File Ctrl+S Save the active file to disk.
Save All Save all modified files in the project.
---
Remove File Remove the selected file from the project (prompts to save if modified).
---
Exit Close the IDE (prompts to save unsaved changes).</pre>
<p><a href="#ide.menu.edit">Edit Menu</a></p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.menu.edit">
<h1>Edit Menu</h1>
<h2>Edit Menu</h2>
<pre> Menu Item Shortcut Description
--------- -------- -----------
Cut Ctrl+X Cut selected text to the clipboard.
Copy Ctrl+C Copy selected text to the clipboard.
Paste Ctrl+V Paste text from the clipboard.
---
Select All Ctrl+A Select all text in the active editor.
---
Delete Del Delete the selected text or control (in the form designer).
---
Find... Ctrl+F Open the Find/Replace dialog.
Find Next F3 Find the next occurrence of the search text.
Replace... Ctrl+H Open the Find/Replace dialog with replace enabled.</pre>
<p><a href="#ide.menu.run">Run Menu</a></p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.menu.run">
<h1>Run Menu</h1>
<h2>Run Menu</h2>
<pre> Menu Item Shortcut Description
--------- -------- -----------
Run F5 Compile and run the program. If paused at a breakpoint, resumes execution with debugging disabled (runs free).
Debug Shift+F5 Compile 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 Recompile Ctrl+F5 Re-run the last compiled module without recompiling.
Stop Esc Stop the running program immediately.
---
Step Into F8 Execute one statement, stepping into SUB/FUNCTION calls. If idle, starts a debug session and breaks at the first statement.
Step Over Shift+F8 Execute one statement, stepping over SUB/FUNCTION calls.
Step Out Ctrl+Shift+F8 Run until the current SUB/FUNCTION returns.
Run to Cursor Ctrl+F8 Run until execution reaches the line where the cursor is positioned.
---
Toggle Breakpoint F9 Toggle a breakpoint on the current editor line.
---
Clear Output Clear the Output window.
---
Save on Run Checkbox: when enabled, all modified files are saved automatically before compiling. Persisted in preferences.</pre>
<p><a href="#ide.menu.view">View Menu</a></p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.menu.view">
<h1>View Menu</h1>
<h2>View Menu</h2>
<pre> Menu Item Shortcut Description
--------- -------- -----------
Code F7 Switch to Code view for the active file (or the file selected in the Project Explorer).
Designer Shift+F7 Switch to Design view for the active form file.
---
Toolbar Checkbox: show or hide the toolbar. Persisted in preferences.
Status Bar Checkbox: show or hide the status bar. Persisted in preferences.
---
Menu Editor... Ctrl+E Open the Menu Editor dialog for the active form. Allows designing menu bars with captions, names, levels, checked state, and enabled state.</pre>
<p><a href="#ide.menu.window">Window Menu</a></p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.menu.window">
<h1>Window Menu</h1>
<h2>Window Menu</h2>
<pre> Menu Item Description
--------- -----------
Code Editor Show or raise the Code Editor window.
Output Show or raise the Output window.
Immediate Show or raise the Immediate window.
Locals Show or raise the Locals debug window.
Call Stack Show or raise the Call Stack debug window.
Watch Show or raise the Watch debug window.
Breakpoints Show or raise the Breakpoints window.
---
Project Explorer Show or raise the Project Explorer window.
Toolbox Show or raise the Toolbox window.
Properties Show or raise the Properties panel.</pre>
<p><a href="#ide.menu.tools">Tools Menu</a></p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.menu.tools">
<h1>Tools Menu</h1>
<h2>Tools Menu</h2>
<pre> Menu Item Description
--------- -----------
Preferences... Open the Preferences dialog (editor settings and project defaults).
---
Debug Layout Checkbox: toggle a debug overlay that shows widget layout boundaries. Useful for diagnosing widget layout issues.</pre>
<p><a href="#ide.menu.help">Help Menu</a></p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.menu.help">
<h1>Help Menu</h1>
<h2>Help Menu</h2>
<pre> Menu Item Description
--------- -----------
About DVX BASIC... Show the About dialog with version and copyright information.</pre>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.toolbar">
<h1>Toolbar</h1>
<h2>Toolbar</h2>
<p>The toolbar is organized into four groups separated by vertical dividers. Each button has a tooltip showing its name and keyboard shortcut.</p>
<h3>File Group</h3>
<pre> Button Shortcut Action
------ -------- ------
Open Ctrl+O Add a file to the project (same as File &gt; Add File).
Save Ctrl+S Save the active file.</pre>
<h3>Run Group</h3>
<pre> Button Shortcut Action
------ -------- ------
Run F5 Compile and run the program.
Stop Esc Stop the running program.</pre>
<h3>Debug Group</h3>
<pre> Button Shortcut Action
------ -------- ------
Debug Shift+F5 Start or resume a debug session.
Step Into F8 Step into the next statement.
Step Over Shift+F8 Step over the next statement.
Step Out Ctrl+Shift+F8 Step out of the current procedure.
Run to Cursor Ctrl+F8 Run to the cursor position.</pre>
<h3>View Group</h3>
<pre> Button Shortcut Action
------ -------- ------
Code F7 Switch to Code view.
Design Shift+F7 Switch to Design view.</pre>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.editor">
<h1>Code Editor</h1>
<h2>Code Editor</h2>
<p>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.</p>
<h3>Object and Function Dropdowns</h3>
<p>At the top of the Code Editor are two dropdown lists:</p>
<ul>
<li>Object -- lists (General) plus all objects (form name, control names, menu item names). Selecting an object filters the Function dropdown.</li>
</ul>
<p>Function -- lists all event handlers (procedures) for the selected object. Implemented handlers are listed first (plain text); unimplemented handlers follow in brackets (e.g., [Click]). Selecting an unimplemented event creates a new event handler stub.</p>
<p>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.</p>
<h3>Syntax Highlighting</h3>
<p>The editor applies real-time syntax coloring as you type. The following categories are highlighted in distinct colors:</p>
<pre> Category Examples
-------- --------
Keywords IF, THEN, FOR, NEXT, SUB, FUNCTION, DIM, PRINT, SELECT, CASE, DO, LOOP, WHILE, WEND, END, EXIT, CALL, GOSUB, GOTO, RETURN, DECLARE, CONST, TYPE, AND, OR, NOT, XOR, MOD, etc.
Type names INTEGER, LONG, SINGLE, DOUBLE, STRING, BOOLEAN, BYTE, TRUE, FALSE
String literals &quot;Hello, World!&quot;
Comments ' This is a comment, REM This is a comment
Numbers 42, 3.14
Operators =, &lt;, &gt;, +, -, *, /, \, &amp;</pre>
<h3>Editor Features</h3>
<ul>
<li>Line numbers -- displayed in the gutter on the left side.</li>
<li>Auto-indent -- new lines are automatically indented to match the previous line.</li>
<li>Tab handling -- the Tab key is captured by the editor. Tab width and whether to insert spaces or tab characters are configurable in Preferences (default: 3 spaces).</li>
<li>Gutter click -- clicking in the line number gutter toggles a breakpoint on that line.</li>
</ul>
<p>Line decorations -- breakpoint lines show a red dot in the gutter. The current debug line (when paused) is highlighted with a yellow background.</p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.designer">
<h1>Form Designer</h1>
<h2>Form Designer</h2>
<p>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.</p>
<h3>Design Surface</h3>
<ul>
<li>Grid snapping -- controls snap to an 8-pixel grid (DSGN_GRID_SIZE) when placed or resized.</li>
<li>Selection -- click a control to select it. The selected control is highlighted with grab handles.</li>
<li>Grab handles -- 6x6 pixel handles appear on the right edge (E), bottom edge (S), and bottom-right corner (SE) of the selected control. Drag a handle to resize the control.</li>
<li>Reordering -- drag a control vertically to reorder it within the form's layout (VBox/HBox).</li>
<li>Placing controls -- select a control type in the Toolbox, then click on the form to place a new instance. The control is auto-named (e.g., Command1, Command2). Clicking the same tool again deselects it (toggles back to pointer mode).</li>
<li>Menu bar preview -- if the form has menu items (defined via the Menu Editor), a preview menu bar is rendered on the design window.</li>
</ul>
<p>Delete key -- removes the selected control from the form.</p>
<h3>Form Properties</h3>
<p>Forms have the following design-time properties: Name, Caption, Width, Height, Left, Top, Layout (VBox or HBox), Centered, AutoSize, and Resizable.</p>
<p><a href="#ide.properties">Properties Panel</a></p>
<p><a href="#ide.toolbox">Toolbox</a></p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.project">
<h1>Project System</h1>
<h2>Project System</h2>
<h3>Project Files (.dbp)</h3>
<p>A DVX BASIC project is stored as a .dbp file (DVX BASIC Project). The project file records:</p>
<ul>
<li>Name -- the project display name (up to 32 characters).</li>
<li>Startup Form -- which form to show automatically when the program starts.</li>
<li>Metadata -- Author, Company, Version, Copyright, Description, and Icon Path (for compiled binaries).</li>
</ul>
<p>File list -- relative paths (8.3 DOS names) of all .bas and .frm files in the project. Each entry tracks whether it is a form file.</p>
<h3>Source Map</h3>
<p>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.</p>
<h3>Project Operations</h3>
<pre> Operation Description
--------- -----------
New Project Creates a blank project with a name and directory. A default .frm file is added automatically.
Open Project Opens a .dbp file and loads all referenced files into memory.
Save Project Writes the .dbp file to disk.
Close Project Closes the project, prompting to save unsaved changes.
Add File Adds a .bas or .frm file to the project. Opening a file without a project auto-creates an implicit project.
Remove File Removes a file from the project (prompts to save if modified).
Project Properties Opens a dialog for editing project metadata (name, author, company, version, copyright, description, icon, startup form).</pre>
<h3>Project Explorer</h3>
<p>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 &gt; Code and View &gt; Designer commands.</p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.properties">
<h1>Properties Panel</h1>
<h2>Properties Panel</h2>
<p>The Properties panel (Window &gt; Properties) has two sections:</p>
<ul>
<li>Control tree -- a TreeView at the top listing the form and all its controls in layout order. Click a control name to select it in both the Properties panel and the Form Designer. Drag items in the tree to reorder controls in the form's layout.</li>
</ul>
<p>Property list -- a two-column ListView below the tree showing property names and values for the selected control. Double-click a property value to edit it via an InputBox dialog. Changes take effect immediately in the designer preview.</p>
<p>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).</p>
<p><a href="#ide.designer">Form Designer</a></p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.toolbox">
<h1>Toolbox</h1>
<h2>Toolbox</h2>
<p>The Toolbox (Window &gt; 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.</p>
<p>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.</p>
<h3>Available Controls</h3>
<pre> VB Name Description
------- -----------
CommandButton Push button that triggers a Click event.
Label Static text label.
TextBox Single-line text input field.
TextArea Multi-line text editor.
CheckBox On/off checkbox.
OptionButton Radio button (mutually exclusive within a group).
ListBox Scrollable list of items.
ComboBox Drop-down combo box.
DropDown Simple drop-down list.
PictureBox Canvas for drawing and images.
Image Static image display.
ImageButton Clickable image button.
Frame Grouping container with a labeled border.
VBox Vertical layout container.
HBox Horizontal layout container.
WrapBox Flow layout container that wraps items to the next row.
Splitter Resizable split between two child panes.
ScrollPane Scrollable container for large content.
TabStrip Tabbed container with multiple pages.
ListView Multi-column list with headers.
TreeView Hierarchical tree control.
ProgressBar Progress indicator bar.
HScrollBar Horizontal slider/scrollbar.
SpinButton Numeric up/down spinner.
Line Horizontal or vertical separator line.
Spacer Invisible spacing element for layout.
Timer Non-visual timer that fires periodic events.
Toolbar Toolbar container for buttons.
StatusBar Status bar at the bottom of a form.
Terminal ANSI terminal emulator control.
Data Data control for binding to a database.
DBGrid Data-bound grid for displaying database query results.</pre>
<p><a href="#ide.designer">Form Designer</a></p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.debugger">
<h1>Debugger</h1>
<h2>Debugger</h2>
<p>The DVX BASIC IDE includes a full interactive debugger. The debugger operates as a state machine with three states:</p>
<pre> State Description
----- -----------
DBG_IDLE No program loaded or running.
DBG_RUNNING Program is executing (VM running in slices).
DBG_PAUSED Execution is paused at a breakpoint or step point. The IDE GUI is fully interactive.</pre>
<h3>Starting a Debug Session</h3>
<ul>
<li>Shift+F5 (Debug) -- compiles the project and starts execution in debug mode. Breakpoints are active but execution does not pause at the first statement.</li>
<li>F8 (Step Into) -- if idle, starts a debug session and breaks at the first statement.</li>
</ul>
<p>F5 (Run) -- compiles and runs without the debugger. No breakpoints are active. If already paused, resumes execution with debugging disabled.</p>
<h3>Breakpoints</h3>
<h4>Setting Breakpoints</h4>
<ul>
<li>Press F9 to toggle a breakpoint on the current editor line.</li>
</ul>
<p>Click in the line number gutter to toggle a breakpoint on that line.</p>
<h4>Breakpoint Validation</h4>
<p>Not every line can have a breakpoint. The IDE validates the line content and silently refuses to set breakpoints on:</p>
<ul>
<li>Blank lines</li>
<li>Comment lines (' or REM)</li>
<li>SUB and FUNCTION declaration lines</li>
</ul>
<p>END SUB and END FUNCTION lines</p>
<h4>Breakpoint Storage</h4>
<p>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.</p>
<h4>Visual Indicators</h4>
<ul>
<li>Breakpoint lines show a red dot in the gutter.</li>
</ul>
<p>The current debug line (when paused) has a yellow background.</p>
<h4>Breakpoint Adjustment on Edit</h4>
<p>When lines are added or removed in the editor, breakpoints below the edit point are automatically shifted to stay on the correct line.</p>
<h3>Stepping</h3>
<pre> Action Shortcut Behavior
------ -------- --------
Step Into F8 Execute one statement. If the statement is a SUB/FUNCTION call, step into it.
Step Over Shift+F8 Execute one statement. If the statement is a SUB/FUNCTION call, execute the entire call and break at the next line in the current scope.
Step Out Ctrl+Shift+F8 Run until the current SUB/FUNCTION returns to its caller.
Run to Cursor Ctrl+F8 Run until execution reaches the line under the cursor.</pre>
<h3>The Debug Run Loop</h3>
<p>When a program is running in debug mode, the IDE enters a cooperative loop:</p>
<ul>
<li>The VM executes up to 10,000 steps per slice.</li>
<li>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.</li>
<li>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.</li>
</ul>
<p>When the user resumes (F5/Shift+F5/F8/etc.), the state transitions back to DBG_RUNNING and the loop continues.</p>
<h3>Stopping</h3>
<p>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.</p>
<p><a href="#ide.debug.locals">Locals Window</a></p>
<p><a href="#ide.debug.callstack">Call Stack Window</a></p>
<p><a href="#ide.debug.watch">Watch Window</a></p>
<p><a href="#ide.debug.breakpoints">Breakpoints Window</a></p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.debug.locals">
<h1>Locals Window</h1>
<h2>Locals Window</h2>
<p>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.</p>
<p>Shows variables for the current execution scope. Displayed as a three-column ListView:</p>
<pre> Column Content
------ -------
Name Variable name (internal mangled names like static variable placeholders are filtered out).
Type Data type: Integer, Long, Single, Double, String, Boolean, Array, UDT. Array types show the element type (e.g., Integer()).
Value Current value. Strings are shown in quotes. Booleans as True/False. Arrays show bounds and element count (e.g., Integer(0 To 9) [10]). Uninitialized arrays show (uninitialized).</pre>
<p>The Locals window displays:</p>
<ul>
<li>Local variables for the current procedure (matched by proc index).</li>
<li>Global (module-level) variables.</li>
</ul>
<p>Form-scoped variables for the current form (if the program is executing within a form context).</p>
<p>Up to 64 variables are displayed. The window is resizable.</p>
<p><a href="#ide.debug.callstack">Call Stack Window</a></p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.debug.callstack">
<h1>Call Stack Window</h1>
<h2>Call Stack Window</h2>
<p>Shows the current call chain as a two-column ListView:</p>
<pre> Column Content
------ -------
Procedure Procedure name (or (module) for module-level code).
Line Line number where execution is paused (shown for the topmost frame).</pre>
<p>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.</p>
<p><a href="#ide.debug.watch">Watch Window</a></p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.debug.watch">
<h1>Watch Window</h1>
<h2>Watch Window</h2>
<p>Allows monitoring arbitrary expressions while debugging. The window has a text input at the top and a two-column ListView below:</p>
<pre> Column Content
------ -------
Expression The watch expression text.
Value Evaluated result (or &lt;error&gt; if evaluation fails). Blank when not paused.</pre>
<h3>Adding Watch Expressions</h3>
<p>Type an expression in the text input and press Enter. Up to 16 watch expressions can be active at once.</p>
<h3>Watch Expression Syntax</h3>
<p>Watch expressions support:</p>
<ul>
<li>Simple variable names: x, count</li>
<li>Array subscripts: arr(5), matrix(2, 3)</li>
<li>UDT field access: player.name</li>
<li>Combined: items(i).price</li>
</ul>
<p>Arbitrary BASIC expressions (compiled and evaluated against the paused VM's state): x + y * 2, Len(name$)</p>
<h3>Editing and Deleting</h3>
<ul>
<li>Double-click or press Enter on a watch entry to move it back into the input box for editing.</li>
</ul>
<p>Press Delete to remove the selected watch expression.</p>
<p><a href="#ide.debug.breakpoints">Breakpoints Window</a></p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.debug.breakpoints">
<h1>Breakpoints Window</h1>
<h2>Breakpoints Window</h2>
<p>Lists all set breakpoints as a three-column ListView:</p>
<pre> Column Content
------ -------
File Project file path.
Procedure Procedure name (Object.Event format, or (General)).
Line Code line number within the file.</pre>
<ul>
<li>Double-click a breakpoint to navigate the code editor to that location.</li>
</ul>
<p>Press Delete to remove selected breakpoints (multi-select is supported).</p>
<p><a href="#ide.debugger">Debugger</a></p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.immediate">
<h1>Immediate Window</h1>
<h2>Immediate Window</h2>
<p>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.</p>
<h3>Expression Evaluation</h3>
<p>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.</p>
<p>You can also type full statements:</p>
<ul>
<li>PRINT x * 2 -- evaluate and print an expression.</li>
<li>DIM tmp As Integer -- declare a temporary variable.</li>
</ul>
<p>LET x = 42 -- explicit assignment (see below).</p>
<p>Parse or runtime errors are displayed inline with an Error: prefix.</p>
<h3>Inspecting Variables While Paused</h3>
<p>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$ &amp; &quot; test&quot; display live values.</p>
<h3>Assigning Variables While Paused</h3>
<p>When paused, you can modify variables in the running program directly from the Immediate window using assignment syntax:</p>
<pre><code>variableName = newValue</code></pre>
<p>The optional LET keyword is also accepted:</p>
<pre><code>LET variableName = newValue</code></pre>
<p>Assignment works for:</p>
<ul>
<li>Scalar variables -- x = 42, name$ = &quot;test&quot;</li>
<li>Array elements -- arr(5) = 100, matrix(2, 3) = 7.5</li>
<li>UDT fields -- player.score = 1000</li>
</ul>
<p>Combined -- items(0).price = 9.99</p>
<p>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.</p>
<p>If the assignment target cannot be resolved (unknown variable, out-of-bounds index, wrong type), an error message is displayed.</p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.output">
<h1>Output Window</h1>
<h2>Output Window</h2>
<p>The Output window is a read-only TextArea at the bottom-left of the screen. It displays:</p>
<ul>
<li>PRINT output -- all PRINT statement output from the running program is appended here.</li>
<li>Runtime errors -- if the VM encounters a runtime error (division by zero, out-of-bounds, etc.), the error message and line number are displayed in the output with an Error on line N: prefix.</li>
</ul>
<p>Compile errors -- if compilation fails, the error message and location are shown.</p>
<p>The output buffer holds up to 32,768 characters. Use Run &gt; Clear Output to clear it.</p>
<p>INPUT statements prompt the user via a modal InputBox dialog; the prompt text is also echoed to the Output window.</p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.findreplace">
<h1>Find / Replace</h1>
<h2>Find / Replace</h2>
<p>Open with Ctrl+F (Find) or Ctrl+H (Replace). The Find/Replace dialog is modeless -- it stays open while you continue editing.</p>
<h3>Dialog Controls</h3>
<pre> Control Description
------- -----------
Find input The text to search for.
Replace checkbox + input Enable replacement mode and enter replacement text.
Scope Radio group: Function, Object, File, or Project. Default is Project.
Direction Radio group: Forward or Backward.
Match Case Checkbox: case-sensitive search.</pre>
<h3>Buttons</h3>
<pre> Button Action
------ ------
Find Next Find the next occurrence. Wraps across procedures, files, and the entire project depending on the scope setting.
Replace Replace the current match and find the next one.
Replace All Replace all occurrences within the selected scope.
Close Close the dialog.</pre>
<h3>Keyboard Shortcut</h3>
<p>F3 repeats the last search (Find Next) without opening the dialog.</p>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.preferences">
<h1>Preferences</h1>
<h2>Preferences</h2>
<p>Open via Tools &gt; Preferences. Settings are saved to dvxbasic.ini in the app's config directory.</p>
<h3>Editor Section</h3>
<pre> Setting Description Default
------- ----------- -------
Skip comments/strings when renaming When renaming a control or form, skip occurrences inside comments and string literals. On
Require variable declaration (OPTION EXPLICIT) When enabled, variables must be declared with DIM before use. Off
Tab width Number of spaces per tab stop (1-8). 3
Insert spaces instead of tabs When enabled, pressing Tab inserts spaces. When disabled, inserts a real tab character. On</pre>
<h3>New Project Defaults Section</h3>
<p>These fields set the default values for new project metadata:</p>
<pre> Field Description Default
----- ----------- -------
Author Default author name. (empty)
Company Default company name. (empty)
Version Default version string. 1.0
Copyright Default copyright notice. (empty)
Description Default project description (multi-line). (empty)</pre>
<p><a href="#ide.overview">Back to Overview</a></p>
</div>
<div class="topic" id="ide.shortcuts">
<h1>Keyboard Shortcuts</h1>
<h2>Keyboard Shortcuts</h2>
<pre> Shortcut Action
-------- ------
Ctrl+O Add File
Ctrl+S Save File
Ctrl+A Select All
Ctrl+X Cut
Ctrl+C Copy
Ctrl+V Paste
Ctrl+F Find
Ctrl+H Replace
Ctrl+E Menu Editor
F3 Find Next
F5 Run
Shift+F5 Debug
Ctrl+F5 Run Without Recompile
Esc Stop
F7 Code View
Shift+F7 Design View
F8 Step Into
Shift+F8 Step Over
Ctrl+Shift+F8 Step Out
Ctrl+F8 Run to Cursor
F9 Toggle Breakpoint
Del Delete</pre>
<hr>
<p>DVX BASIC 1.0 -- Copyright 2026 Scott Duensing</p>
</div>
</main>
</body>
</html>

1046
docs/dvxbasic_language_reference.html
View file

File diff suppressed because it is too large Load diff