From 289adb8c479f30c15f5460b444d5aa6fe4ea04c2 Mon Sep 17 00:00:00 2001 From: Scott Duensing Date: Thu, 2 Apr 2026 21:44:06 -0500 Subject: [PATCH] Readmes updated. --- README.md | 27 +++++++----- apps/README.md | 33 ++++++++++++-- apps/dvxbasic/README.md | 97 +++++++++++++++++++++++++++++++++++++++++ config/README.md | 4 ++ tools/README.md | 20 ++++++--- 5 files changed, 162 insertions(+), 19 deletions(-) create mode 100644 apps/dvxbasic/README.md diff --git a/README.md b/README.md index 2c7f7ba..73a2b7a 100644 --- a/README.md +++ b/README.md @@ -23,9 +23,12 @@ dvx.exe (loader) +-- libs/dvxshell.lib shell (app lifecycle, desktop) +-- libs/taskmgr.lib task manager (Ctrl+Esc, separate DXE) | + +-- libs/basrt.lib BASIC runtime (VM + values) + +-- libs/serial.lib serial communications (rs232 + packet + seclink) + | +-- widgets/*.wgt 26 widget type plugins | - +-- apps/*/*.app DXE applications + +-- apps/*/*.app DXE applications ``` @@ -42,7 +45,7 @@ dvx.exe (loader) | `taskmgr/` | `bin/libs/taskmgr.lib` | Task Manager (separate DXE, Ctrl+Esc) | | `widgets/` | `bin/widgets/*.wgt` | 26 individual widget DXE modules | | `apps/` | `bin/apps/*/*.app` | Application DXE modules | -| `tools/` | `bin/dvxres` | Resource tool (host native, not DXE) | +| `tools/` | `bin/dvxres`, `bin/mkicon`, `bin/mktbicon` | Resource and icon tools (host native) | | `config/` | `bin/config/`, `bin/libs/`, `bin/widgets/` | INI config, themes, wallpapers, dep files | | `rs232/` | `lib/librs232.a` | ISR-driven UART serial driver | | `packet/` | `lib/libpacket.a` | HDLC framing, CRC-16, Go-Back-N ARQ | @@ -85,6 +88,8 @@ bin/ listhelp.lib list/dropdown helpers dvxshell.lib DVX shell taskmgr.lib task manager (Ctrl+Esc) + basrt.lib BASIC runtime (VM + values) + serial.lib serial communications stack *.dep dependency files for load ordering widgets/ box.wgt VBox/HBox/Frame containers @@ -98,6 +103,7 @@ bin/ dvxdemo/dvxdemo.app widget showcase cpanel/cpanel.app control panel imgview/imgview.app image viewer + dvxbasic/dvxbasic.app DVX BASIC IDE + compiler config/ dvx.ini system configuration themes/ color theme files (.thm) @@ -171,14 +177,15 @@ running. Diagnostic information (registers, faulting EIP) is logged to ## Bundled Applications -| App | File | Type | Description | -|-----------------|---------------|-----------|------------------------------------------------------------| -| Program Manager | `progman.app` | Callback | App launcher grid, system info dialog | -| Notepad | `notepad.app` | Callback | Text editor with File/Edit menus, open/save, clipboard | -| Clock | `clock.app` | Main-loop | Digital clock display; multi-instance capable | -| DVX Demo | `dvxdemo.app` | Callback | Widget system showcase demonstrating 31 widget types | -| Control Panel | `cpanel.app` | Callback | Themes, wallpaper, video mode, mouse configuration | -| Image Viewer | `imgview.app` | Callback | Displays BMP, PNG, JPEG, GIF images with aspect-ratio zoom | +| App | File | Type | Description | +|-----------------|----------------|-----------|------------------------------------------------------------| +| Program Manager | `progman.app` | Callback | App launcher grid, system info dialog | +| Notepad | `notepad.app` | Callback | Text editor with File/Edit menus, open/save, clipboard | +| Clock | `clock.app` | Main-loop | Digital clock display; multi-instance capable | +| DVX Demo | `dvxdemo.app` | Callback | Widget system showcase demonstrating 31 widget types | +| Control Panel | `cpanel.app` | Callback | Themes, wallpaper, video mode, mouse configuration | +| Image Viewer | `imgview.app` | Callback | Displays BMP, PNG, JPEG, GIF images with aspect-ratio zoom | +| DVX BASIC | `dvxbasic.app` | Callback | Visual Basic 3 clone: form designer, compiler, VM | ## Serial / Networking Stack diff --git a/apps/README.md b/apps/README.md index 6682f09..10f1488 100644 --- a/apps/README.md +++ b/apps/README.md @@ -139,16 +139,35 @@ Manager. Widget headers used: none (raw paint callbacks with `dvxLoadImage()`). +### DVX BASIC (dvxbasic) + +| | | +|---|---| +| File | `apps/dvxbasic/dvxbasic.app` | +| Type | Callback-only | +| Multi-instance | No | + +Visual Basic 3 clone with form designer, per-procedure code editor, +project management, and stack-based bytecode compiler/VM. Supports +event-driven programming with visual forms, controls, and a full +BASIC language implementation. + +See `apps/dvxbasic/README.md` for detailed documentation. + +Also builds `basrt.lib` -- the BASIC runtime library (VM + values) +as a separate DXE so compiled BASIC apps can use it independently. + + ## Build ``` -make # builds all 6 app DXE modules +make # builds all 7 app DXE modules make clean # removes objects and app files ``` -Each app compiles to a single `.o`, then is packaged via `dxe3gen` -into a `.app` DXE exporting `appDescriptor` and `appMain` (plus -`appShutdown` for clock). +Each app compiles to a single `.o` (or multiple for DVX BASIC), +then is packaged via `dxe3gen` into a `.app` DXE exporting +`appDescriptor` and `appMain`. Output goes to `bin/apps//.app`. @@ -175,4 +194,10 @@ apps/ cpanel.c control panel imgview/ imgview.c image viewer + dvxbasic/ + compiler/ BASIC compiler (lexer, parser, codegen) + runtime/ VM and value system + formrt/ form runtime (BASIC <-> DVX widgets) + ide/ IDE (editor, designer, project, properties) + samples/ sample .bas, .frm, .dbp files ``` diff --git a/apps/dvxbasic/README.md b/apps/dvxbasic/README.md new file mode 100644 index 0000000..a18cb99 --- /dev/null +++ b/apps/dvxbasic/README.md @@ -0,0 +1,97 @@ +# DVX BASIC + +A Visual Basic 3 clone for the DVX GUI system. Provides a visual form +designer, per-procedure code editor, project management, and a +stack-based bytecode compiler/VM for running event-driven BASIC programs. + +## Architecture + +DVX BASIC is built as a DXE3 app (dvxbasic.app) loaded by the DVX shell. +It consists of four major subsystems: + +### Compiler (compiler/) + +Single-pass compiler that translates BASIC source to stack-based p-code. + +- **lexer.c** -- Tokenizer with keyword lookup, type suffixes, hex literals, + line continuation (`_`), and `?` as PRINT shortcut. +- **parser.c** -- Recursive descent parser. Handles all VB3 statements, + expressions, operator precedence (VB-correct: `^` binds tighter than + unary `-`), Sub/Function with forward references, bare sub calls, + OPTION EXPLICIT, STATIC, CONST, DEF FN, SELECT CASE, ON ERROR GOTO, + UDTs (nested), arrays of UDTs, DECLARE LIBRARY. +- **codegen.c** -- Bytecode emitter. Dynamic arrays (stb_ds) for code, + constants, and proc table. Module building, forward reference patching, + unresolved reference detection. +- **symtab.c** -- Symbol table with local/global scoping, type tracking. +- **opcodes.h** -- ~90 bytecode instructions. OP_END (explicit END statement) + vs OP_HALT (implicit end of module). + +### Runtime (runtime/) + +- **vm.c** -- Stack-based virtual machine. Step-limited execution for + cooperative multitasking. Event handler dispatch via basVmCallSub + (runs to completion, no step limit). basVmCallSubWithArgsOut for + events that return values (QueryUnload Cancel parameter). +- **values.c** -- Tagged value system: Integer, Long, Single, Double, + String (ref-counted), Boolean, Array (ref-counted, multi-dim), UDT + (ref-counted, nested), Object (opaque host pointer), Ref (ByRef). + +### Form Runtime (formrt/) + +- **formrt.c** -- Bridge between BASIC VM and DVX widgets. Loads .frm + files at runtime, creates windows and controls, dispatches events to + BASIC code. Supports property get/set, method calls, and control + creation via the widget interface system. + +Events: Click, DblClick, Change, GotFocus, LostFocus, KeyPress, +KeyDown, KeyUp, MouseDown, MouseUp, MouseMove, Scroll, Load, +QueryUnload, Unload, Resize, Activate, Deactivate, Timer. + +### IDE (ide/) + +- **ideMain.c** -- Main IDE orchestration. File switching via + `activateFile()`, per-procedure editing, Object/Event dropdowns + with hash-based syntax highlighting, dirty tracking with + `sEditorFileIdx` ownership, compile-and-run with IDE window + hiding, VB-style event loop. +- **ideDesigner.c** -- Visual form designer. Live widget creation, + drag/resize handles, widget interface property persistence + (including WGT_IFACE_ENUM with named values), code-in-FRM files. +- **ideProject.c** -- Project system (.dbp files, INI format). Project + window with tree view, project properties dialog with startup form + dropdown and icon browser. All files loaded into memory at project + open. +- **ideProperties.c** -- Property editor. ListView with type-aware + editing (bool toggle, int spinner, enum cycling, string input). + Interface property display via widget descriptors. +- **ideToolbox.c** -- Widget palette loaded from registered widget + interfaces. + +## Project Files + + project.dbp INI-format project file + module.bas BASIC module (code only) + form.frm Form file (layout + code section after "End") + +.bas modules are compiled before .frm code sections so CONST +declarations are available to form event handlers. + +## Build + + make -C apps/dvxbasic # cross-compile for DJGPP + make -C apps/dvxbasic tests # build native test programs + +Test programs: test_compiler, test_vm, test_lex, test_quick. +162 test sections covering the compiler, VM, and language features. + +## File Structure + + apps/dvxbasic/ + compiler/ Lexer, parser, codegen, symbol table, opcodes + runtime/ VM and tagged value system + formrt/ Form runtime (BASIC <-> DVX widget bridge) + ide/ IDE (main, designer, project, properties, toolbox) + samples/ Sample .bas, .frm, .dbp files + dvxbasic.res App resources (icons, toolbar buttons) + Makefile Builds basrt.lib (runtime) + dvxbasic.app (IDE) diff --git a/config/README.md b/config/README.md index 97fb39b..c232813 100644 --- a/config/README.md +++ b/config/README.md @@ -29,6 +29,8 @@ build. Text files are converted to DOS line endings (CR+LF) via sed. | `listbox.dep` | `bin/widgets/listbox.dep` | ListBox widget dep file | | `listview.dep` | `bin/widgets/listview.dep` | ListView widget dep file | | `treeview.dep` | `bin/widgets/treeview.dep` | TreeView widget dep file | +| `basrt.dep` | `bin/libs/basrt.dep` | BASIC runtime dep file | +| `serial.dep` | `bin/libs/serial.dep` | Serial communications dep file | ## dvx.ini Format @@ -126,6 +128,8 @@ ignored. Names are case-insensitive. | `texthelp.dep` | texthelp.lib | libtasks, libdvx | | `listhelp.dep` | listhelp.lib | libtasks, libdvx | | `dvxshell.dep` | dvxshell.lib | libtasks, libdvx, texthelp, listhelp | +| `basrt.dep` | basrt.lib | libtasks, libdvx | +| `serial.dep` | serial.lib | libtasks, libdvx | ### Widget Dependencies diff --git a/tools/README.md b/tools/README.md index 7cb24c4..a3a36cc 100644 --- a/tools/README.md +++ b/tools/README.md @@ -90,10 +90,19 @@ Generates simple 32x32 24-bit BMP pixel-art icons for DVX apps. mkicon ``` -Available icon types: `clock`, `notepad`, `cpanel`, `dvxdemo`, `imgview`. +Available icon types: `clock`, `notepad`, `cpanel`, `dvxdemo`, `imgview`, +`noicon`. -Note: mkicon is defined in `mkicon.c` but is not currently built by the -Makefile (it was used during initial development). + +## mktbicon -- Toolbar Icon Generator + +Generates 16x16 24-bit BMP toolbar button icons. + +``` +mktbicon +``` + +Used to create toolbar button resources for DVX BASIC and other apps. ## Files @@ -101,8 +110,9 @@ Makefile (it was used during initial development). | File | Description | |------|-------------| | `dvxres.c` | Resource tool implementation | -| `mkicon.c` | Icon generator (not built by default) | -| `Makefile` | Builds `bin/dvxres` (host native) | +| `mkicon.c` | 32x32 icon generator | +| `mktbicon.c` | 16x16 toolbar icon generator | +| `Makefile` | Builds `bin/dvxres`, `bin/mkicon`, `bin/mktbicon` (host native) | ## Build