.app.
+compile-help: deploy-helpsrc
@mkdir -p docs
$(HLPC) -o bin/apps/kpunch/dvxhelp/dvxhelp.hlp \
--html docs/dvx_help_viewer.html \
src/apps/kpunch/dvxhelp/help.dhs
+ libHelp=$$($(HELP_FILES) libs) && \
$(HLPC) -o bin/apps/kpunch/progman/dvxhelp.hlp \
--html docs/dvx_system_reference.html \
-i src/libs/kpunch/libdvx \
- $(SYSTEM_DHS) \
+ $(USER_GUIDE_DHS) \
+ $$libHelp \
+ src/widgets/kpunch/wgtsys.dhs \
$$(find src/widgets/kpunch -name "*.dhs" ! -path "*/wgtsys.dhs" | sort)
$(HLPC) -o bin/apps/kpunch/dvxbasic/dvxbasic.hlp \
--html docs/dvx_basic_reference.html \
$(BASIC_DHS) \
$$(find src/widgets/kpunch -name "*.bhs" | sort)
+ $(HELP_FILES) compile $(HLPC)
SDKDIR = bin/sdk
-deploy-sdk:
+# Public header lists (SDK_*_H), shared with the ABI size test.
+SDK_ROOT =
+include src/sdkHeaders.mk
+
+# The SDK's own files (README, sdk.mk, newProject.sh, project templates)
+# live in src/sdk; its bin/ holds the host tools a project build runs.
+SDK_SRC = src/sdk
+SDK_TOOLS = bin/host/dvxres bin/host/dvxhlpc bin/host/bascomp src/tools/dxeGen.sh
+
+# The host tools come from tools (dvxres, dvxhlpc) and apps (bascomp).
+deploy-sdk: tools apps
@echo "Building SDK..."
- @mkdir -p $(SDKDIR)/include/core $(SDKDIR)/include/shell $(SDKDIR)/include/tasks $(SDKDIR)/include/sql $(SDKDIR)/include/basic $(SDKDIR)/samples/basic/basdemo $(SDKDIR)/samples/basic/widshow
- @# Core headers (libdvx public API)
- @for f in src/libs/kpunch/libdvx/dvxApp.h src/libs/kpunch/libdvx/dvxTypes.h \
- src/libs/kpunch/libdvx/dvxWgt.h src/libs/kpunch/libdvx/dvxWgtP.h \
- src/libs/kpunch/libdvx/dvxWm.h src/libs/kpunch/libdvx/dvxDraw.h \
- src/libs/kpunch/libdvx/dvxVideo.h src/libs/kpunch/libdvx/dvxComp.h \
- src/libs/kpunch/libdvx/dvxPrefs.h src/libs/kpunch/libdvx/dvxDlg.h \
- src/libs/kpunch/libdvx/dvxRes.h src/libs/kpunch/libdvx/dvxFont.h \
- src/libs/kpunch/libdvx/dvxCur.h src/libs/kpunch/libdvx/dvxPal.h \
- src/libs/kpunch/libdvx/dvxMem.h src/libs/kpunch/libdvx/platform/dvxPlat.h; do \
- [ -f "$$f" ] && cp "$$f" $(SDKDIR)/include/core/; \
+ @# Start from an empty tree so a header dropped from the lists goes away.
+ rm -rf $(SDKDIR)
+ @mkdir -p $(SDKDIR)/bin $(SDKDIR)/include/core $(SDKDIR)/include/shell $(SDKDIR)/include/tasks $(SDKDIR)/include/sql $(SDKDIR)/include/texthelp $(SDKDIR)/include/listhelp $(SDKDIR)/include/fileops $(SDKDIR)/include/xfer $(SDKDIR)/include/conn $(SDKDIR)/include/print $(SDKDIR)/include/net $(SDKDIR)/include/basic $(SDKDIR)/samples/basic/basdemo $(SDKDIR)/samples/basic/widshow
+ cp $(SDK_CORE_H) $(SDKDIR)/include/core/
+ cp $(SDK_SHELL_H) $(SDKDIR)/include/shell/
+ cp $(SDK_TASKS_H) $(SDKDIR)/include/tasks/
+ cp $(SDK_SQL_H) $(SDKDIR)/include/sql/
+ cp $(SDK_TEXTHELP_H) $(SDKDIR)/include/texthelp/
+ cp $(SDK_LISTHELP_H) $(SDKDIR)/include/listhelp/
+ cp $(SDK_FILEOPS_H) $(SDKDIR)/include/fileops/
+ cp $(SDK_XFER_H) $(SDKDIR)/include/xfer/
+ cp $(SDK_CONN_H) $(SDKDIR)/include/conn/
+ cp $(SDK_PRINT_H) $(SDKDIR)/include/print/
+ @# Networking: dvxNet.h and the standard socket headers, which keep their
+ @# subdirectories (sys/, netinet/, arpa/); sdk.mk adds include/net only
+ @# for programs that set NET = 1.
+ cp $(SDK_NET_H) $(SDKDIR)/include/net/
+ @for h in $(SDK_NET_STD_H); do \
+ mkdir -p $(SDKDIR)/include/net/$$(dirname $$h) && cp $(SDK_NET_DIR)/$$h $(SDKDIR)/include/net/$$h || exit 1; \
+ done
+ @for h in $(SDK_SERIAL_H); do \
+ mkdir -p $(SDKDIR)/include/serial/$$(dirname $$h) && cp $(SDK_SERIAL_DIR)/$$h $(SDKDIR)/include/serial/$$h || exit 1; \
done
- @# Shell header
- @cp src/libs/kpunch/dvxshell/shellApp.h $(SDKDIR)/include/shell/
- @cp src/libs/kpunch/dvxshell/shellInf.h $(SDKDIR)/include/shell/
- @# Tasks header
- @cp src/libs/kpunch/libtasks/taskSwch.h $(SDKDIR)/include/tasks/
- @# SQL header
- @cp src/libs/kpunch/sql/dvxSql.h $(SDKDIR)/include/sql/
@# Widget headers -- one subdir per widget
- @for d in src/widgets/kpunch/*/; do \
- for h in "$$d"*.h; do \
- [ -f "$$h" ] || continue; \
- wgt=$$(basename "$$d"); \
- mkdir -p $(SDKDIR)/include/widget/"$$wgt"; \
- cp "$$h" $(SDKDIR)/include/widget/"$$wgt"/; \
- done; \
+ @for h in $(SDK_WIDGET_H); do \
+ wgt=$$(basename $$(dirname $$h)); \
+ mkdir -p $(SDKDIR)/include/widget/$$wgt && cp $$h $(SDKDIR)/include/widget/$$wgt/ || exit 1; \
done
@# BASIC include files
@cp src/include/basic/*.bas $(SDKDIR)/include/basic/
- @# BASIC sample: basdemo (project file + form + icon)
+ @# BASIC sample: basdemo (project file + form + icon + help source)
@cp src/apps/kpunch/basdemo/basdemo.dbp $(SDKDIR)/samples/basic/basdemo/
@cp src/apps/kpunch/basdemo/basdemo.frm $(SDKDIR)/samples/basic/basdemo/
+ @cp src/apps/kpunch/basdemo/basdemo.dhs $(SDKDIR)/samples/basic/basdemo/
@cp src/apps/kpunch/basdemo/ICON32.BMP $(SDKDIR)/samples/basic/basdemo/
@# BASIC sample: widshow (widget showcase)
@cp src/apps/kpunch/widshow/widshow.dbp $(SDKDIR)/samples/basic/widshow/
@cp src/apps/kpunch/widshow/widshow.frm $(SDKDIR)/samples/basic/widshow/
+ @cp src/apps/kpunch/widshow/widshow.dhs $(SDKDIR)/samples/basic/widshow/
@cp src/apps/kpunch/widshow/ICON32.BMP $(SDKDIR)/samples/basic/widshow/
- @# README
- @printf '%s\n' \
- 'DVX SDK' \
- '=======' \
- '' \
- 'Headers for developing applications and widgets against the DVX GUI.' \
- '' \
- 'Directory Structure' \
- '-------------------' \
- '' \
- ' include/' \
- ' core/ DVX core headers (types, drawing, windows, widgets)' \
- ' shell/ Shell/app loading API' \
- ' tasks/ Cooperative task switching API' \
- ' sql/ SQLite database wrapper API' \
- ' widget/ Per-widget public API headers' \
- ' basic/ BASIC include files (DECLARE LIBRARY modules)' \
- ' samples/' \
- ' basic/ Example BASIC projects (open in the DVX BASIC IDE)' \
- '' \
- 'Requirements' \
- '------------' \
- '' \
- ' - DJGPP cross-compiler (i586-pc-msdosdjgpp-gcc)' \
- ' - dxe3gen (included with DJGPP)' \
- ' - DVX resource compiler (SYSTEM/DVXRES.EXE on the target,' \
- ' or bin/host/dvxres on the host)' \
- ' - DVX help compiler (SYSTEM/DVXHLPC.EXE on the target,' \
- ' or bin/host/dvxhlpc on the host)' \
- '' \
- 'For complete working examples, see the app sources under' \
- 'src/apps/kpunch/ in the DVX repository.' \
- > $(SDKDIR)/README.TXT
+ @# SDK files, project templates and the host tools
+ cp $(SDK_SRC)/README.TXT $(SDK_SRC)/sdk.mk $(SDK_SRC)/newProject.sh $(SDKDIR)/
+ cp -R $(SDK_SRC)/templates $(SDKDIR)/
+ cp $(SDK_TOOLS) $(SDKDIR)/bin/
+# Every build output: the DOS targets through each directory's clean,
+# then the whole object tree (host libraries, test binaries, coverage)
+# and the host-only bin/ directories.
clean:
- $(MAKE) -C src/libs/kpunch/libdvx clean
- $(MAKE) -C src/libs/kpunch/libtasks clean
+ for d in $(LIBS); do $(MAKE) -C src/libs/kpunch/$$d clean || exit 1; done
$(MAKE) -C src/loader clean
- $(MAKE) -C src/libs/kpunch/texthelp clean
- $(MAKE) -C src/libs/kpunch/listhelp clean
$(MAKE) -C src/widgets/kpunch clean
- $(MAKE) -C src/libs/kpunch/dvxshell clean
- $(MAKE) -C src/libs/kpunch/taskmgr clean
- $(MAKE) -C src/libs/kpunch/serial clean
- $(MAKE) -C src/libs/kpunch/sql clean
$(MAKE) -C src/apps/kpunch clean
$(MAKE) -C src/tools clean
- -rmdir obj 2>/dev/null
- -rm -rf bin/config bin/widgets bin/libs bin/sdk
- -rm -f docs/*.html
+ $(MAKE) -C src/tools/proxy clean
+ rm -rf obj bin/host bin/test bin/system
+ rm -rf bin/config bin/widgets bin/libs bin/sdk
+ rm -f docs/*.html
diff --git a/README.md b/README.md
index d5a77b58..263e1925 100644
--- a/README.md
+++ b/README.md
@@ -54,17 +54,47 @@ to what actually changes on screen, so the desktop is responsive even at
## Building and Deploying
```
-make # build everything
-make clean # remove all build artifacts
-./mkcd.sh # build and produce a CD-ROM ISO image
+./installToolchain.sh # once, after a fresh clone: fetch the toolchain
+make # build everything
+make test # host test suites, goldens and the lint gate
+make test-dos # run the real DOS build in 86Box (see below)
+make clean # remove all build artifacts
+./mkcd.sh # build and produce a CD-ROM ISO image
```
+Everything the build and the tests need that is not a standard Linux
+package lives in `toolchains/`, which is not kept in git.
+`./installToolchain.sh` downloads each piece, checks it against a
+pinned SHA-256, and unpacks it there (no sudo, nothing outside the
+project); run it again with `--force` to reinstall:
+
+* DJGPP (GCC 12.2.0) and the CWSDPMI stub -- the DOS cross compiler
+* 86Box 6.0 and its ROM set, FreeDOS 1.3 boot files and CuteMouse,
+ and DOSBox Staging 0.83.0 -- the emulator test harness
+* cppcheck 2.21, built from source -- used by the static gate
+* lrzsz 0.12.20 -- the Terminal tests' ZMODEM peer
+
+It needs curl, tar, bzip2, xz, unzip, make, g++, mtools and xvfb-run.
+To build with a different DOS toolchain, pass `DJGPP_PREFIX=...` and
+`CWSDSTUB=...` to `make`.
+
`make` builds in dependency order: core, tasks, loader, helpers,
host tools, widgets, shell, task manager, apps. Build output goes to
`bin/` and intermediate objects to `obj/`.
+`make test-dos` boots FreeDOS in 86Box (headless, under Xvfb), runs
+`DVX /SCRIPT=...` for every script in `src/test/dos/scripts`, and
+compares the screenshots with the goldens. `EMULATOR=dosbox` uses
+DOSBox Staging instead (much faster); `SCRIPTS="boot apps"` runs a
+subset. The emulators never touch your home directory. See
+`src/test/dos/runDos.sh --help`.
+
`./mkcd.sh` builds everything, then wraps `bin/` into an ISO 9660
-image for use with an emulator or for burning to physical media.
+image for use with an emulator or for burning to physical media. On
+the target machine, change to the CD drive and type `INSTALL`: DVX
+starts from the CD with its Setup program, which copies DVX to a
+hard-disk folder (and can add it to AUTOEXEC.BAT). Holding Shift while
+DVX starts (or `DVX /SAFE`) starts it in 640x480 safe video mode.
## Directory Layout
@@ -76,6 +106,7 @@ dvxgui/
config/ shipped INI, themes, wallpapers
docs/ HTML exports of the built-in help content
LICENSE.txt MIT license
+ installToolchain.sh fetches the toolchain and test tools into toolchains/
Makefile top-level build
mkcd.sh build-and-package script
src/
@@ -83,14 +114,19 @@ dvxgui/
include/ shared include files (BASIC library declarations)
libs/ core libraries (GUI, tasks, shell, helpers, serial, SQL)
loader/ bootstrap executable
+ sdk/ SDK project templates, build rules and newProject.sh
tools/ host-native development tools and the BASIC compiler
widgets/ widget plug-in modules
+ toolchains/ DJGPP, CWSDPMI, emulators, cppcheck (not in git; see
+ installToolchain.sh)
```
See `src/tools/README.md` for the host-side development tools
(resource tool, icon generators, help compiler, proxy), and
`src/apps/kpunch/README.md` for the SDK contract applications must
-follow.
+follow. `make` also writes the SDK to `bin/sdk`: headers, host tools
+and a template for each kind of module (`bin/sdk/newProject.sh app
+NAME`); the SDK Quick Start in the system help walks through it.
## Documentation
diff --git a/analyze.sh b/analyze.sh
index e32bc0cc..9d844561 100755
--- a/analyze.sh
+++ b/analyze.sh
@@ -25,7 +25,9 @@ set -u
cd "$(dirname "$0")"
-REAL_CC="$HOME/djgpp/djgpp/bin/i586-pc-msdosdjgpp-gcc"
+# The DJGPP compiler the build uses (src/common.mk finds the toolchain;
+# DJGPP_PREFIX in the environment overrides it).
+REAL_CC="$(make -s --no-print-directory -f src/common.mk --eval 'printCc: ; @echo $(CC)' printCc)"
if [ ! -x "$REAL_CC" ]; then
echo "analyze.sh: $REAL_CC not executable" >&2
diff --git a/config/ASSOC.INI b/config/ASSOC.INI
new file mode 100644
index 00000000..f10e92ce
--- /dev/null
+++ b/config/ASSOC.INI
@@ -0,0 +1,23 @@
+; DVX File Associations
+;
+; Which program opens each kind of document. Program Manager, File
+; Manager and the Control Panel (File Types page) all use this list.
+;
+; Each line is: EXTENSION = program[,arguments]
+; EXTENSION the file extension without the dot
+; program the program to run, relative to the DVX folder
+; arguments optional; %1 stands for the document. Without arguments
+; the document is passed on its own.
+
+[associations]
+TXT = apps/kpunch/notepad/notepad.app
+INI = apps/kpunch/notepad/notepad.app
+BMP = apps/kpunch/imgview/imgview.app
+JPG = apps/kpunch/imgview/imgview.app
+PNG = apps/kpunch/imgview/imgview.app
+GIF = apps/kpunch/imgview/imgview.app
+BAS = apps/kpunch/dvxbasic/dvxbasic.app
+DBP = apps/kpunch/dvxbasic/dvxbasic.app
+FRM = apps/kpunch/dvxbasic/dvxbasic.app
+HLP = apps/kpunch/dvxhelp/dvxhelp.app
+DHS = apps/kpunch/dvxhelp/helpedit.app
diff --git a/config/README.md b/config/README.md
index c2328139..850b6a37 100644
--- a/config/README.md
+++ b/config/README.md
@@ -11,8 +11,10 @@ build. Text files are converted to DOS line endings (CR+LF) via sed.
| Source File | Build Output | Description |
|-------------|-------------|-------------|
| `dvx.ini` | `bin/config/dvx.ini` | System configuration |
+| `ASSOC.INI` | `bin/config/ASSOC.INI` | File associations: which program opens each document type (shellAssoc.h; edited on the Control Panel's File Types page) |
| `themes/cde.thm` | `bin/config/themes/cde.thm` | CDE color theme |
| `themes/geos.thm` | `bin/config/themes/geos.thm` | GEOS Ensemble theme |
+| `themes/hotdog.thm` | `bin/config/themes/hotdog.thm` | Hot Dog Stand theme |
| `themes/win31.thm` | `bin/config/themes/win31.thm` | Windows 3.1 theme |
| `wpaper/blueglow.jpg` | `bin/config/wpaper/blueglow.jpg` | Wallpaper image |
| `wpaper/swoop.jpg` | `bin/config/wpaper/swoop.jpg` | Wallpaper image |
@@ -47,21 +49,27 @@ Comments start with `;`. The shell loads this at startup via
| `height` | 480 | Requested vertical resolution |
| `bpp` | 16 | Preferred color depth (8, 15, 16, 24, 32) |
-The system picks the closest available VESA mode.
+The system picks the closest available VESA mode. If that mode cannot
+be set, or a Shift key is held while DVX starts (or `DVX /SAFE`), the
+shell starts in safe video mode (640x480, 16 bpp or the closest the card
+has) and asks whether to write that mode here.
### [mouse] Section
| Key | Default | Values | Description |
|-----|---------|--------|-------------|
| `wheel` | normal | normal, reversed | Scroll wheel direction |
+| `wheelspeed` | 3 | 1-10 | Lines scrolled per wheel notch |
| `doubleclick` | 500 | 200-900 | Double-click speed (ms) |
| `acceleration` | medium | off, low, medium, high | Mouse acceleration |
+| `speed` | 8 | 2-32 | Mickeys per 8 pixels of pointer travel (lower = faster pointer) |
### [shell] Section
| Key | Default | Description |
|-----|---------|-------------|
-| `desktop` | apps/progman/progman.app | Path to the desktop app loaded at startup |
+| `desktop` | apps/kpunch/progman/progman.app | Path to the desktop app loaded at startup |
+| `welcome` | (none) | Program started after the desktop; the shipped file names the Welcome window, which deletes the key when the user ticks "Don't show this again" |
### [colors] Section
@@ -98,6 +106,42 @@ compiled-in defaults.
| `wallpaper` | (none) | file path | Path to wallpaper image |
| `mode` | stretch | stretch, tile, center | Wallpaper display mode |
+### [network] Section
+
+Read by the networking library (dvxnet) when the stack starts; the
+Control Panel's Network page edits it.
+
+| Key | Default | Values | Description |
+|-----|---------|--------|-------------|
+| `dhcp` | true | true, false | Get the address from a DHCP server |
+| `address` | (none) | dotted IPv4 | Static address (dhcp = false) |
+| `netmask` | (none) | dotted IPv4 | Static subnet mask (dhcp = false) |
+| `gateway` | (none) | dotted IPv4 | Static default gateway (optional) |
+| `dns1`, `dns2` | (none) | dotted IPv4 | Name servers; they win over the DHCP server's |
+| `hostname` | DVX | text | Name sent to the DHCP server and returned by gethostname() |
+| `vector` | auto | auto, 0x60-0x80 | Packet driver interrupt |
+
+### [printer] Section
+
+Read by the printing library (print.lib) for every print; the Control
+Panel's Printer page edits the port and model, File > Page Setup (and
+the Printer page's Page Setup button) the rest. A page setup that
+cannot work (margins leaving no room, values out of range) is ignored
+as a whole in favour of the defaults.
+
+| Key | Default | Values | Description |
+|-----|---------|--------|-------------|
+| `port` | LPT1 | LPT1, LPT2, LPT3, FILE | Where printed output goes |
+| `file` | PRINTER.PRN | file path | The file used with port = FILE |
+| `model` | text | text, epson9, epson24, laserjet | Printer model; all but text print pictures |
+| `linesPerPage` | 0 | 0, 10-200 | Lines per page; 0 = the model's usual length (66, laser 60) |
+| `columns` | 80 | 20-255 | Characters across the page |
+| `marginTop`, `marginBottom` | 3 | lines | Top and bottom margins (header / footer in their middle line) |
+| `marginLeft`, `marginRight` | 5 | characters | Left and right margins |
+| `tabWidth` | 8 | 1-16 | Tab stops for printed text |
+| `wrap` | true | true, false | Wrap long lines at a word, or cut them off |
+| `header`, `footer` | &f, Page &p | text | &f file name, &p page, &n pages, &d date, &t time, &l &c &r left / centre / right, && an ampersand |
+
## Theme Files (.thm)
@@ -111,6 +155,7 @@ Bundled themes:
|------|-------------|
| `cde.thm` | CDE (Common Desktop Environment) -- warm tan/blue palette |
| `geos.thm` | GEOS Ensemble -- cyan/grey palette |
+| `hotdog.thm` | Hot Dog Stand -- the infamous yellow/red/black palette |
| `win31.thm` | Windows 3.1 -- grey/navy palette |
diff --git a/config/dvx.ini b/config/dvx.ini
index df985dc2..cdff7fb8 100644
--- a/config/dvx.ini
+++ b/config/dvx.ini
@@ -14,7 +14,8 @@ bpp = 16
; wheelspeed: lines per wheel notch (1-10, default 3)
; doubleclick: double-click speed in milliseconds (200-900, default 500)
; acceleration: off, low, medium, high (default medium)
-; speed: cursor speed (2-32, default 8; higher = faster)
+; speed: mouse travel needed per step of pointer movement (2-32, default 8;
+; lower = faster pointer)
[mouse]
wheel = normal
@@ -25,6 +26,52 @@ speed = 8
; Shell settings.
; desktop: path to the desktop app loaded at startup
+; welcome: program started after the desktop (the Welcome window shown at
+; the first start); it removes this line itself when you tick
+; "Don't show this again"
[shell]
desktop = apps/kpunch/progman/progman.app
+welcome = apps/kpunch/welcome/welcome.app
+
+; Network settings (TCP/IP through a packet driver loaded before DVX).
+; dhcp: true = get the address from a DHCP server; false = use address,
+; netmask and gateway below
+; dns1, dns2: name servers (empty = the DHCP server's)
+; hostname: this computer's name on the network
+; vector: packet driver interrupt, e.g. 0x60 (auto = search 0x60-0x80)
+
+[network]
+dhcp = true
+address =
+netmask =
+gateway =
+dns1 =
+dns2 =
+hostname = DVX
+vector = auto
+
+; Printer settings (Control Panel's Printer page and File > Page Setup).
+; port: LPT1, LPT2, LPT3 or FILE (print into the file named by file)
+; model: text (any printer, text only), epson9, epson24 (Epson ESC/P
+; dot matrix) or laserjet (HP PCL); all but text print pictures
+; linesPerPage: 0 = the printer's usual page length (66, laser 60)
+; columns: characters across the page; margins in lines (top, bottom)
+; and characters (left, right)
+; header, footer: &f file name, &p page, &n pages, &d date, &t time,
+; &l &c &r left / centre / right, && an ampersand
+
+[printer]
+port = LPT1
+file = PRINTER.PRN
+model = text
+linesPerPage = 0
+columns = 80
+marginTop = 3
+marginBottom = 3
+marginLeft = 5
+marginRight = 5
+tabWidth = 8
+wrap = true
+header = &f
+footer = Page &p
diff --git a/cppcheck.sh b/cppcheck.sh
index 8ec276bc..2ce11418 100755
--- a/cppcheck.sh
+++ b/cppcheck.sh
@@ -39,7 +39,6 @@ INCLUDES=(
# of eliding whole functions behind unknown macro calls.
DEFINES=(
-DDXE_EXPORT=
- -DDVX_WIDGET_IMPL
-D__DJGPP__=2
)
diff --git a/docs/dvx_basic_reference.html b/docs/dvx_basic_reference.html
index 03271d95..0ae484ea 100644
--- a/docs/dvx_basic_reference.html
+++ b/docs/dvx_basic_reference.html
@@ -64,6 +64,7 @@ img { max-width: 100%; }
Keyboard Shortcuts
+Changes in This Release
Data Types
- Operators
@@ -184,6 +185,7 @@ img { max-width: 100%; }
- CASE ELSE
- CBOOL
- CDBL
+- Changes
- CHDIR
- CHDRIVE
- CheckBox
@@ -198,12 +200,17 @@ img { max-width: 100%; }
- Code View
- ComboBox
- comm.bas
+- Command Line
+- COMMAND$
- CommandButton
- commdlg.bas
- Comments
+- CommHandshake
- Common Events
- Common Methods
- Common Properties
+- CommRecvEncrypted
+- CommSetPlain
- Compile Errors
- CONST
- Container
@@ -326,6 +333,7 @@ img { max-width: 100%; }
- Hide
- Hide
- Horizontal Layout
+- HostLookup$
- Hotkeys
- HScrollBar
- IDE
@@ -372,14 +380,19 @@ img { max-width: 100%; }
- LOG
- Long
- LOOP
+- LPRINT
+- LPRINT USING
- LTRIM$
- Master-Detail
+- Max
- Me
- Menu
- Menu Bar
- Menu Editor
- Methods
- MID$
+- Migration
+- Min
- MKDIR
- MOD
- MoveFirst
@@ -388,6 +401,7 @@ img { max-width: 100%; }
- MSGBOX
- Multi-Column List
- NAME
+- net.bas
- New Project
- NEXT
- NOT
@@ -406,6 +420,7 @@ img { max-width: 100%; }
- Option Explicit
- OPTION EXPLICIT
- OptionButton
+- OptionIndex
- OR
- Output Window
- Paste
@@ -419,6 +434,10 @@ img { max-width: 100%; }
- PRINT #
- PRINT Output
- PRINT USING
+- print.bas
+- PrintPageSetup
+- PrintPictureDialog
+- PrintTextDialog
- ProgressBar
- Project Explorer
- Project Files
@@ -435,6 +454,7 @@ img { max-width: 100%; }
- RealMode
- RecordSource
- REDIM
+- Release Notes
- REM
- Remove File
- RemoveControl
@@ -474,6 +494,7 @@ img { max-width: 100%; }
- SetActive
- SETATTR
- SetColumns
+- SetCursor
- SetEvent
- SetPenColor
- SetPenSize
@@ -541,6 +562,8 @@ img { max-width: 100%; }
- TabControl
- TabStrip
- TAN
+- TcpConnect
+- TcpRecv$
- Terminal
- Text
- TextArea
@@ -561,6 +584,7 @@ img { max-width: 100%; }
- TYPE
- UBOUND
- UCASE$
+- UdpSend
- UNLOAD
- Unload
- UNTIL
@@ -598,6 +622,7 @@ img { max-width: 100%; }
- Watch Expressions
- Watch Window
- WEND
+- What's New
- WHILE
- Widget Palette
- Window
@@ -659,11 +684,11 @@ img { max-width: 100%; }
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).
+ Close Project Close the current project (prompts to save unsaved changes; Don't Save also discards unsaved Project Properties changes).
---
- Project Properties... Edit project metadata (name, author, version, startup form, icon, etc.).
+ Project Properties... Edit project metadata (name, author, version, startup form, icon, etc.) and the command line arguments used when the program is run from the IDE.
---
- 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.
+ 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. A file that cannot be read, or is 64 KB or larger, is refused with a message.
Save File Ctrl+S Save the active file to disk.
Save All Save all modified files in the project.
---
@@ -672,6 +697,8 @@ img { max-width: 100%; }
Remove File Remove the selected file from the project (prompts to save if modified).
---
Exit Close the IDE (prompts to save unsaved changes).
+A project (.dbp) or source file (.bas, .frm) named on the IDE's command line opens when the IDE starts, so double-clicking one in the File Manager, or starting it from the Program Manager, opens it in the IDE.
+Files are saved exactly as edited (LF line endings). Each save writes a temporary file first and replaces the original only when the write succeeded. Opening a project that fails to load keeps the current project open and removes the failed entry from the Recent list.
Edit Menu
Back to Overview
@@ -679,17 +706,18 @@ img { max-width: 100%; }
Edit Menu
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.
+ Cut Ctrl+X Cut the selection (text, or the selected control in the form designer) to the clipboard.
+ Copy Ctrl+C Copy the selection to the clipboard.
+ Paste Ctrl+V Paste from the clipboard. A pasted control keeps all of its properties.
---
Select All Ctrl+A Select all text in the active editor.
---
- Delete Del Delete the selected text or control (in the form designer).
+ Delete Del Delete the selected text, or the selected control and everything inside it (in the form designer).
---
Find... Ctrl+F Open the Find/Replace dialog.
- Find Next F3 Find the next occurrence of the search text.
+ Find Next F3 Find the next occurrence of the search text (also after the dialog is closed).
Replace... Ctrl+H Open the Find/Replace dialog with replace enabled.
+Cut, Copy, Paste, Select All and Delete act on the window you last worked in: the form designer's selected control, or the text of the code, output or immediate window.
Run Menu
Back to Overview
@@ -700,14 +728,14 @@ img { max-width: 100%; }
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.
+ Stop Esc Stop the running program. Run, Debug and the project commands stay disabled until the program has finished shutting down.
---
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.
---
- Output Window to Log Checkbox: when enabled, PRINT output is also mirrored to the DVX log. Persisted in preferences.
+ Output Window to Log Checkbox: when enabled, PRINT output (each line once) and compile and runtime error reports are also written to the DVX log. Persisted in preferences.
---
Toggle Breakpoint F9 Toggle a breakpoint on the current editor line.
---
@@ -722,12 +750,12 @@ img { max-width: 100%; }
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.
+ Designer Shift+F7 Switch to Design view for the active form file. With a module (.bas) active it reports that the file is not a form. The designer keeps its unsaved state while you work in a module.
---
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.
+ Menu Editor... Ctrl+E Open the Menu Editor dialog for the active form (a form must be active). Allows designing menu bars with captions, names, levels, checked state, and enabled state. See Menu Editor below.
Window Menu
Back to Overview
@@ -807,6 +835,7 @@ img { max-width: 100%; }
Function -- lists all event handlers (procedures) for the selected object. Implemented handlers are listed first (plain text); unimplemented handlers follow in brackets (e.g., [Click]). Selecting an unimplemented event creates a new event handler stub.
The editor shows one procedure at a time. Each procedure has its own buffer, and switching between them is instantaneous. The (General) section contains module-level declarations and code.
+Text outside the procedure being shown is never lost: lines typed above or below the SUB move to (General), a second SUB typed into the buffer becomes a procedure of its own, and a procedure whose SUB line was deleted becomes (General) text. When you leave an event handler that was generated and never edited it is removed; empty SUBs and FUNCTIONs you wrote yourself are kept. After a save the editor shows exactly what was stored (blank lines around a procedure are normalized). A section too large for the editor opens read-only, with a message in the status bar.
Syntax Highlighting
The editor applies real-time syntax coloring as you type. Seven categories are highlighted in distinct colors; the colors themselves are editable in Tools > Preferences > Colors.
Category Examples
@@ -836,13 +865,16 @@ img { max-width: 100%; }
Grid snapping -- controls snap to an 8-pixel grid when placed or resized.
Selection -- click a control to select it. The selected control is highlighted with grab handles.
Grab handles -- 6x6 pixel handles appear on the right edge (E), bottom edge (S), and bottom-right corner (SE) of the selected control. Drag a handle to resize the control.
-Reordering -- drag a control vertically to reorder it within the form's layout (VBox/HBox).
-Placing controls -- select a control type in the Toolbox, then click on the form to place a new instance. The control is auto-named (e.g., Command1, Command2). Clicking the same tool again deselects it (toggles back to pointer mode).
+Reordering -- drag a control to reorder it among its siblings in the layout (VBox/HBox). A container moves together with its contents.
+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), skipping names already used by a control, a menu item or the form. Clicking the same tool again deselects it (toggles back to pointer mode). Controls nest at most 15 levels deep; a drop into a container that is already that deep goes into its parent container.
Menu bar preview -- if the form has menu items (defined via the Menu Editor), a preview menu bar is rendered on the design window.
-Delete key -- removes the selected control from the form.
+Delete key -- removes the selected control and everything inside it.
+Opening a form in the designer does not mark it modified. A control whose Visible property is False is still shown on the design surface (the setting applies when the program runs). Disabling a container greys the controls inside it; a control's own Enabled = False is kept when the container is enabled again. A .frm file without an AutoSize line opens without AutoSize; AutoSize = True wins over Width and Height lines. Text values (Caption, Text and so on) are limited to 379 characters.
+Menu Editor
+The Menu Editor (View > Menu Editor, Ctrl+E) edits the active form's menu bar and popup menus. Menus nest at most 15 levels (0-14); indenting refuses when any item below would go deeper. OK rejects an item nested more than one level below the item above it, and a blank item that has sub-items (it must be named); blank items without sub-items are dropped. The window's close box cancels. Renaming a menu item renames its event handlers in the code and updates the ContextMenu setting of the form and its controls; inserting, deleting and moving items does not rename anything.
Form Properties
-Forms have the following design-time properties: Name, Caption, Width, Height, Left, Top, Layout (VBox or HBox), Centered, AutoSize, and Resizable.
+Forms have the following design-time properties: Name, Caption, Width, Height, Left, Top, Layout (VBox or HBox), Centered, AutoSize, Resizable, HelpTopic and ContextMenu.
Properties Panel
Toolbox
Back to Overview
@@ -854,7 +886,9 @@ img { max-width: 100%; }
- Name -- the project display name (up to 32 characters).
- Startup Form -- which form to show automatically when the program starts.
-- Metadata -- Author, Company, Version, Copyright, Description, and Icon Path (for compiled binaries).
+- Metadata -- Author, Company, Version, Copyright, Description (a single line), and Icon Path (for compiled binaries).
+- Arguments -- the command line the program gets (COMMAND$) when it is run from the IDE, for trying out a program that opens the file it is given. It is not built into the compiled program: there COMMAND$ returns whatever the program was started with.
+- Help File -- a compiled help file (.hlp) for the program. It is copied next to the compiled program, and F1 in the running program opens it, at the HelpTopic of the focused control or, failing that, of the form. Add help.bas to the project and call HelpView to open it from a Help menu.
- File list -- relative paths of all .bas and .frm files in the project. Each entry tracks whether it is a form file.
How Projects are Compiled
@@ -863,20 +897,21 @@ img { max-width: 100%; }
Before the source is handed to the compiler, the IDE scans every .frm file and cross-checks the forms against the widget registry and the statements that reference them. Three classes of error are caught and reported without producing a binary:
- Unknown widget types -- any Begin TypeName ... End block whose TypeName does not match a registered widget is flagged. The error message names the offending form, control, and type, and hints that DVX uses VB6-style names (SpinButton, not Spinner).
-- Unknown properties -- statements of the form CtrlName.Property = value, or reads of CtrlName.Property, are checked against the widget's declared property list. A typo such as btn.Captoin triggers a compile error with the form, control, and property name.
+- Unknown properties -- statements of the form CtrlName.Property = value, or reads of CtrlName.Property, are checked against the widget's declared property list. A typo such as btn.Captoin triggers a compile error with the form, control, and property name. A control name that is used with different types on different forms is not checked.
- Unknown methods -- method calls CtrlName.Method ... are checked the same way against the widget's method list, catching mistakes like list.AddTiem before the program ever runs.
+- Menu items -- only Name (read), Checked and Enabled can be used on a menu item in code; Caption, Visible and RadioCheck are design-time settings.
These checks use the same metadata the Properties panel and Toolbox read from each widget DXE, so property and method names always match the current widget set without any separate list to maintain.
Project Operations
Operation Description
--------- -----------
New Project Creates a blank project with a name and directory. A default .frm file is added automatically.
- Open Project Opens a .dbp file and loads all referenced files into memory.
+ Open Project Opens a .dbp file and loads all referenced files into memory. A project file that is 64 KB or larger, or cannot be read, is not loaded; opening it later reports "Cannot load <file>: unreadable or larger than 65535 bytes." Carriage returns are removed when files are loaded.
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).
+ Remove File Removes a file from the project (prompts to save if modified). Removing the startup form clears the Startup Form setting.
+ Project Properties Opens a dialog for editing project metadata (name, author, company, version, copyright, description, icon, help file, startup form) and the Arguments for runs from the IDE.
Project Explorer
The Project Explorer is a tree view window listing all project files. Double-click a file to open it: .bas files open in Code view, .frm files open in Design view. The selected file in the Project Explorer determines the target for View > Code and View > Designer commands.
Back to Overview
@@ -909,8 +944,6 @@ img { max-width: 100%; }
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.
@@ -931,6 +964,7 @@ img { max-width: 100%; }
Terminal ANSI terminal emulator control.
Data Data control for binding to a database.
DBGrid Data-bound grid for displaying database query results.
+Image and ImageButton controls are not in the Toolbox; they can still be written into a .frm file by hand and are then edited in the Properties panel like any other control.
Form Designer
Back to Overview
@@ -970,7 +1004,7 @@ img { max-width: 100%; }
The current debug line (when paused) has a yellow background.
Breakpoint Adjustment on Edit
-When lines are added or removed in the editor, breakpoints below the edit point are automatically shifted to stay on the correct line.
+Breakpoints follow their statements when lines are added, removed, joined, split or pasted. A breakpoint whose line is deleted is removed.
Stepping
Action Shortcut Behavior
------ -------- --------
@@ -983,7 +1017,7 @@ img { max-width: 100%; }
- The program runs in short cooperative slices so the IDE remains responsive.
- When the program hits a breakpoint, execution pauses immediately. The IDE switches to Code View, navigates to the breakpoint line, highlights it in yellow, and opens the Locals and Call Stack windows if they are not already visible.
-- While paused, you can inspect variables in Locals and Watch, evaluate expressions in the Immediate window, assign new values to variables, toggle breakpoints, step, continue, or stop.
+- While paused, you can inspect variables in Locals and Watch, evaluate expressions in the Immediate window, assign new values to variables, toggle breakpoints, step, continue, or stop. A pause in module-level code works the same way as a pause in an event handler.
- Resuming (F5, Shift+F5, or any Step command) returns the program to Running state.
Stopping
@@ -1005,11 +1039,11 @@ img { max-width: 100%; }
Value Current value. Strings are shown in quotes. Booleans as True/False. Arrays show bounds and element count (e.g., Integer(0 To 9) [10]). Uninitialized arrays show (uninitialized).
The Locals window displays:
-- Local variables for the current procedure (matched by proc index).
-- Global (module-level) variables.
-- Form-scoped variables for the current form (if the program is executing within a form context).
+- Local variables of the current procedure, including its STATIC variables and the module variables it names in a SHARED statement.
+- Module-level variables. While execution is paused inside a SUB or FUNCTION, only the variables declared with DIM SHARED (or REDIM SHARED) are listed, because the procedure cannot see the others. This also applies inside a DEF FN function, although a DEF FN can read every module variable.
+- Form-scoped variables for the current form (if the program is executing within a form context), with the same SHARED rule.
-Up to 64 variables are displayed. The window is resizable.
+The Watch window and the Immediate window follow the same rules. The window is resizable.
Call Stack Window
Back to Overview
@@ -1067,7 +1101,7 @@ img { max-width: 100%; }
@@ -1121,12 +1155,12 @@ img { max-width: 100%; }
Buttons
Button Action
------ ------
- Find Next Find the next occurrence. Wraps across procedures, files, and the entire project depending on the scope setting.
+ Find Next Find the next occurrence. Function scope searches the current procedure, Object scope the selected object's procedures, File scope the current file and Project scope every file. At the end of the current procedure the search wraps around to its start.
Replace Replace the current match and find the next one.
Replace All Replace all occurrences within the selected scope.
Close Close the dialog.
Keyboard Shortcut
-F3 repeats the last search (Find Next) without opening the dialog.
+F3 repeats the last search (Find Next) without opening the dialog, also after the dialog was closed (then searching the whole project, ignoring case). Scope and direction chosen with the keyboard take effect like mouse clicks.
Back to Overview
@@ -1148,7 +1182,7 @@ img { max-width: 100%; }
Publisher Default publisher/company name. (empty)
Version Default version string. 1.0
Copyright Default copyright notice. (empty)
- Description Default project description (multi-line). (empty)
+ Description Default project description (one line). (empty)
Colors Tab
Customizes the syntax-highlighting colors used in the code editor. The left side is a list of seven color entries (Default Text, Keywords, Strings, Comments, Numbers, Operators, Types). Select an entry and adjust its red, green, and blue components using the three sliders on the right. The Preview swatch shows the current color. Changes are applied to the open editor when you click OK.
Back to Overview
@@ -1180,6 +1214,118 @@ img { max-width: 100%; }
Ctrl+F8 Run to Cursor
F9 Toggle Breakpoint
Del Delete
+
Changes in This Release
+
Back to Overview
+
+
Changes in This Release
+
This release fixes a large number of problems in the language, the runtime, the controls and the IDE. Most programs keep working unchanged. The one change that needs attention in existing programs is variable scope: see Module Variables Need SHARED below.
+
Module Variables Need SHARED
+
DVX BASIC now uses the QBasic scope rules. A SUB or FUNCTION sees a variable declared at module level (including the code section of a form) only when it is declared with DIM SHARED, or named in a SHARED statement inside the procedure. Before, every module variable was visible everywhere.
+
+- In an existing program, change DIM to DIM SHARED for every module-level variable that a SUB, FUNCTION or event handler uses.
+- Without that change such a name silently becomes a local variable of the procedure (or a compile error with OPTION EXPLICIT, or when the procedure indexes or dots it).
+- New: the SHARED statement inside a procedure, and REDIM SHARED at module level. DIM SHARED inside a procedure is a compile error.
+- CONSTs, TYPEs, procedures, forms and controls are visible everywhere as before; a DEF FN still sees every module variable.
+
+
See: Variable Scope and SHARED
+
Language
+
+- GOSUB and RETURN work inside SUB and FUNCTION: each procedure call has its own GOSUB stack. RETURN with no pending GOSUB in the procedure raises error 3 (RETURN without GOSUB); before, RETURN inside a procedure left the procedure (use EXIT SUB / EXIT FUNCTION for that).
+- Labels belong to their SUB or FUNCTION (or to the module level). GOTO, GOSUB, ON GOTO/GOSUB and ON ERROR GOTO reach only labels of the same procedure; the same label name can be used in several procedures, and a label may share a name with a variable. An undefined label, or a jump to a SUB or variable name, is a compile error. "SubName:" at the start of a line is an error instead of a silent label.
+- A CONST inside a SUB or FUNCTION is local and no longer overrides a module constant. CONST name AS type converts the literal (Integer and Long round and range-check); a string/number mismatch or an overflow is a compile error.
+- DEF FN must be defined before it is used; its free names are module variables.
+- DEFINT, DEFLNG and the other DEFtype statements also apply to parameters, STATIC variables and FUNCTION results. A typed FUNCTION converts the value assigned to it (FUNCTION F AS INTEGER with F = 2.5 returns 2). STATIC variables convert on store and their names no longer leak out of the procedure.
+- DIM a, b AS STRING, c(3) declares several variables in one statement.
+- name(...) in an expression only calls FUNCTIONs; a SUB there, or indexing a scalar or CONST, is a compile error.
+- A FUNCTION can be called as a statement (F 3), discarding its result.
+- DECLARE must match the definition's BYVAL and OPTIONAL flags too.
+- SWAP and GET #n, , arr(i) evaluate each subscript exactly once. A BYREF argument written as an expression such as arr(i) + 1 is passed by value.
+- Numeric literals: an Integer/Long suffix on a literal with a fraction or exponent rounds (1E3% is 1000); -32768% and -2147483648& are accepted; 1. is a valid literal; an over-long literal is an error.
+- DATA: unquoted items are raw text up to the next comma, colon, comment or end of line.
+- READ, INPUT, INPUT # and LINE INPUT # accept array elements and TYPE fields; PRINT #n, alone writes an empty line.
+- PRINT USING: ; and , both separate values, and a trailing ; or , suppresses the newline.
+- More than 8 array dimensions, or an LBOUND/UBOUND dimension outside 1..8, is a compile error.
+- A missing END SUB, END FUNCTION, END TYPE or END DECLARE is a compile error.
+- FOR: a constant fractional STEP with an Integer or Long counter is a compile error, and a computed STEP is rounded to the counter's type. A fractional STEP no longer turns a Single counter into a Double.
+- DECLARE LIBRARY arguments are always passed by value, converted to the declared parameter type (a Single parameter receives a Single).
+- Name(idx).Member works with any member name (including keywords such as Name and Text), with method calls and in chains; Me.Method (x) is a method call.
+- Compile errors read "Line N, Col C: message".
+- New: COMMAND$ returns the arguments the program was started with (for example the document it was opened with), and COMMAND$(n) returns the nth argument without its quotes. The DVX programs that open documents (Notepad, Image Viewer, Icon Editor, Resource Editor, Help Editor) open the file named there when they start. In the IDE, set the arguments under Project Properties. A program that uses COMMAND$ does not run on an older DVX.
+- A SUB or FUNCTION may use at most 64 local slots (parameters, local variables and hidden temporaries). More is a compile error "Too many local variables in X (n, limit is 64)" instead of a runtime error 9; READ and INPUT # into many array elements no longer use a slot per target.
+- SHARED naming a variable that does not exist at module level creates it there; in a form's code it becomes a variable of that form, not a program-wide one.
+
+
Runtime
+
+- Nested BYREF parameters reach the original variable or array element.
+- ON ERROR is per procedure. A procedure called from a handler can trap its own errors, returning from a procedure that only installed a handler leaves the caller's ERR alone, and an error inside a running handler passes to the caller's handler.
+- RESUME NEXT after an error in an IF/ELSEIF/WHILE/DO/LOOP condition skips the block or leaves the loop; after an error in a FOR statement the loop is skipped; after an error in the SELECT CASE expression the whole SELECT CASE block is skipped; after an error in a CASE test that test counts as false and the next value or CASE is tried; after an error in an ON selector no branch is taken.
+- New error numbers: 3 RETURN without GOSUB, 14 Out of string space, 28 Out of stack space (was reported as 7), 63 Bad record number, 91 Object variable not set. ERR is a Long, and ERROR n reports the standard message for known numbers.
+- Using a property or method (or Show, Hide, Unload) on a value that is not a form or control raises error 91 instead of doing nothing.
+- EXP, ^ and other math that leaves the numeric range raise error 6 (Overflow); an undefined result raises error 5.
+- INT, FIX and SGN return an Integer (Long or Double when needed); RND returns a Double and follows QBasic (RND(0) repeats the last number, a negative argument reseeds). RANDOMIZE with a negative or very large seed, and RND with a very large negative argument, seed predictably (the seed is taken modulo 2^32), so the sequence for a negative RANDOMIZE seed may differ from before. -x of the most negative Integer or Long widens like 0 - x.
+- INSTR follows OPTION COMPARE TEXT. INSTR and the MID$ statement reject a start below 1 (error 5); MID$ with a length of 0 replaces nothing.
+- PRINT # writes a space after numbers, as PRINT does. PRINT USING and FORMAT$ show a value too wide for the field in scientific notation.
+- SEEK on a RANDOM file works in records (statement and function); a position below 1 is error 63. PUT of a value longer than the record length raises error 59 before writing anything.
+- SLEEP keeps the desktop and the program's forms running, SLEEP 0 just processes events, and closing the program ends the sleep.
+- DIR$ returns only files. GETATTR and SETATTR on a missing file raise error 53; SETATTR raises 75 when it cannot change the attributes.
+- IniRead and IniWrite use the same INI reader as the DVX system settings. IniWrite keeps the text of every other line (of any length) unchanged, ends every line of the saved file with CR LF, and raises error 75 when it cannot read the existing file or write the new one (a write failure used to be ignored); a failed write leaves the old file intact. IniRead no longer finds keys in the tail of a long line, and keys above the first section header are read with section "". Section names are matched with surrounding blanks ignored.
+- VAL keeps the magnitude of very long digit strings. Running out of memory while building a string raises error 14.
+- REDIM PRESERVE of a TYPE array keeps the existing elements.
+- Appending to a String variable with s = s + x or s = s & x no longer copies the whole string each time, so building long strings in a loop is much faster. When x is InputBox$, MsgBox, CreateForm, CreateControl or Shell, s is still read before x runs (left to right).
+- Programs compiled with an older release must be rebuilt. A program whose procedure table records more than 64 locals for a procedure is refused when it is loaded.
+
+
Forms and Controls
+
+- A reference to a removed control or to a control of an unloaded form raises an "unknown control" runtime error. CreateControl with a parent that is not a container on the same form raises "CreateControl: invalid parent".
+- SetEvent works on forms (Me) and menu items; a handler without parameters is called without the event's arguments.
+- Form.Visible = True/False behaves exactly like Show/Hide, but only on a real change: Visible = True on a form that is already shown does nothing (a modal form stays modal), and on a form that has no window it is ignored. MinWidth and MinHeight read back the value that was set. Size properties are limited to 0..32767.
+- Disabling a container (for example Frame.Enabled = False) blocks mouse and keyboard input to every control inside it (also inside a disabled ScrollPane or Splitter), and SetFocus on such a control does nothing.
+- OptionButton.Value is a read/write Boolean (True = selected); the button's index is the new read-only OptionIndex. Setting Value raises no Click.
+- HScrollBar has Min and Max properties. SpinButton's RealMode uses the range set with SetRange. PictureBox has read-only ImageWidth and ImageHeight.
+- ListBox SetItems "" empties the list, and every | separates items. ListView SetColumns has no length limit. TreeView Clear resets scrolling. TextArea FindNext finds a match that starts at the cursor, and the new SetCursor method moves the caret without selecting.
+- TabStrip/TabControl: a negative tab index selects the first tab and an index past the end the last one.
+- The mouse wheel over a DBGrid scrolls the rows without moving the current record, and over a Terminal scrolls its history locally.
+- .frm files: End followed by blanks or a comment (also End'comment) closes its block while End followed by a word does not, in the compiler, the build and the release renamer exactly as in the loader, Begin followed by a tab is accepted, Enabled = False on popup-menu items is applied, properties after a nested child's End apply to the parent, and Layout on a control that is not a container is reported.
+- Include libraries: sql.bas, comm.bas and commdlg.bas take and return Long (SQLFieldInt and SQLAffected no longer wrap above 32767); resource.bas string functions are declared AS STRING. CommHandshake takes an optional passphrase, and the new CommSetPlain accepts unencrypted data on a channel.
+- commdlg.bas functions are renamed to match the other include libraries: basFileOpen is now DlgFileOpen$, basFileSave is DlgFileSave$, basInputBox2 is DlgInputBox$, basInputCancelled is DlgInputCancelled, basChoiceDialog is DlgChoice, basIntInput is DlgIntInput and basPromptSave is DlgPromptSave. The old names are gone; programs that use them must be updated and rebuilt.
+- New in comm.bas: CommRecvEncrypted(handle, channel) returns True when every byte the last CommRecv$ on that channel returned arrived encrypted and authenticated (also when it returned nothing), and False when any arrived unencrypted (before CommHandshake or on a CommSetPlain channel).
+- KeyDown: Shift, Ctrl or Alt with F1-F12, and Alt with Home, End, PgUp, PgDn, Ins, Del and the arrow keys, report the plain key's KeyCode with the modifier in Shift, even when the modifier is released before the program sees the key.
+- Data control: while its Validate handler runs, MoveFirst, MoveLast, MoveNext, MovePrevious, AddNew, Refresh and Update on the same Data control are ignored (they used to validate the same record again without end); Delete is allowed. Only unloading the Data control itself from Validate or Reposition stops the operation that fired it; removing other controls does not.
+- Data control: writing a field back with the value it already has is not an edit, so leaving a bound control no longer fires Validate. With a SELECT query as RecordSource, edits are dropped when the current record changes. Update and Delete still find a record whose key is a number stored without a declared column type, or is NULL, when the key names exactly one record; Delete keeps the record shown when the database row could not be deleted.
+- DBGrid re-sorts and re-measures its columns when the Data control's records change (Refresh, AddNew, Delete or an edit), keeping the chosen sort column, and not on a plain record move.
+- Image and ImageButton: Picture = "" clears the picture (Picture then reads back ""); a file that cannot be loaded leaves the picture and Picture unchanged. A disabled Image keeps its transparent color transparent.
+- Timer: a Timer whose handler shows a modal dialog no longer fires a second time from inside that dialog.
+- TextArea: the horizontal scroll bar appears as soon as the longest line fills the visible width, and the caret stays visible while typing at the right edge.
+- Terminal: pasting with Ctrl+V returns the view to the live screen and sends the text in small pieces.
+- ListBox and ListView: changing the items while an item is being dragged ends the drag.
+- TabControl: switching tabs closes an open drop-down list only when it belongs to a control on the page being hidden. A Label on a Toolbar is drawn on the toolbar's color.
+- Compile errors from the command-line compiler name the file and line. A .frm without a Begin Form line is an error. A release build that runs out of memory while renaming names fails instead of producing a broken program.
+- A form shown modal has no minimize gadget.
+- Menu items accept only Name (read-only), Checked and Enabled in code; Caption, Visible and RadioCheck are design-time settings, and using them in code is a compile error in the IDE.
+
+
IDE
+
+- Immediate window: Enter evaluates the line it is pressed on, assignments accept any expression, and a statement that does not finish is stopped.
+- Output window: always shows the newest output and drops the oldest lines when full; Output Window to Log also logs errors.
+- Find/Replace: Object and File scopes search only that object or file; F3 works after the dialog is closed.
+- Edit commands act on the window last worked in (designer control or text window). A pasted control keeps all its properties.
+- The code editor never drops text outside the shown procedure; only untouched generated event handlers are removed.
+- Files are saved exactly as written, with LF line endings, through a temporary file (for FORM1.FRM, FORM1.$FR, with the old file kept as FORM1.~FR until the save is complete; your own name.BAK is never touched); carriage returns are removed when files are loaded. Don't Save discards Project Properties changes too. A project file may hold up to 64 KB of text not counting carriage returns; a file of twice that size or more is refused without being read.
+- Debugger: while paused inside a SUB or FUNCTION, Locals and Watch show only the variables the procedure can see (its locals, its STATIC and SHARED names, and DIM SHARED module variables), and STATIC variables are now listed.
+- Compile-time checks of control properties and methods use the control on the form whose code is being compiled, so a control name used for different control types on different forms is checked too.
+- Form designer: Image and ImageButton are no longer in the Toolbox, controls nest at most 15 levels, Delete removes a control with its contents, AutoSize matches the runtime, TabStrip TabIndex and the form's ContextMenu are kept on save, control arrays inside containers no longer duplicate controls, and a control keeps any number of design-time properties.
+- Error and debugger line numbers in a form's code match the editor exactly (the indentation of the first code line is kept).
+- Menu Editor: at most 15 levels, the close box cancels, and only real renames rewrite event handlers.
+- Project Properties: Description is a single line.
+- A Sub or Function whose name already exists (typed or pasted) stays its own procedure, and the compiler reports the duplicate; before, it was moved into (General).
+- Breakpoints and the caret follow lines that the editor moves when it tidies a procedure (blank lines after End Sub, text typed outside a Sub, a deleted Sub line); a breakpoint whose line disappears is removed.
+- Immediate window: output leaves room for typing, and Enter in a completely full window evaluates nothing and says so in the status bar.
+- Debugger: a breakpoint reached while a stopped program is unwinding no longer pauses it.
+- The title bar's * also shows for a form changed in the designer but not yet saved.
+- Form designer: a property value may be as long as a full .frm line (511 characters); a value too long for the line it is saved on (deeply nested controls) stops the save with "A property value is too long to save at its position in the form". Making a container part of a control array keeps its contents. Only one OptionButton per container keeps Value = True: setting it on one (in the property grid or by pasting a selected one) clears the others.
+
+
Back to Overview
DVX BASIC 1.0 -- Copyright 2026 Scott Duensing
Note: Both E and D can introduce an exponent (e.g. 1.5E10 and 2.5D3 are equivalent forms of a scientific-notation double).
+A literal with an Integer or Long suffix and a fraction or exponent is rounded (1E3% is 1000, 2.5% is 2). The most negative values -32768% and -2147483648& are valid. A trailing decimal point is allowed (1. is the Double 1). A numeric literal too long to read is a compile error.
Type Promotion
-When mixing types in expressions, values are automatically promoted to a common type: Integer -> Long -> Single -> Double. Strings are not automatically converted to numbers (use VAL and STR$).
+When mixing types in expressions, values are automatically promoted to a common type: Integer -> Long -> Single -> Double. + joins two strings; when a string meets a number in an arithmetic operator (including +) the string is converted as VAL does ("1" + 2 is 3, "abc" + 2 is 2). Use & to join text and numbers, and VAL / STR$ to convert explicitly.
Assignment Conversion
-Storing a value into a variable declared as Integer, Long, Single or Boolean (by suffix, by AS clause, by DEFINT/DEFLNG/DEFSNG, or as a typed parameter, TYPE field or array element) converts the value to that type. Integer and Long round to the nearest whole number, with halves rounding to the nearest even number (2.5 becomes 2, 3.5 becomes 4), and raise error 6 (Overflow) when the result does not fit. Single keeps about 7 significant digits, so PRINT shows at most 7 digits of it. Boolean stores True for any non-zero number or non-empty string and False otherwise. A variable declared with DIM but without a type is Single (or the DEFtype for its first letter). A variable that is never declared keeps whatever type the assigned value has.
+Storing a value into a variable declared as Integer, Long, Single or Boolean (by suffix, by AS clause, by DEFINT/DEFLNG/DEFSNG, or as a typed parameter, STATIC variable, FUNCTION result, TYPE field or array element) converts the value to that type. DEFtype statements also give parameters, STATIC variables and FUNCTION results their default type. Integer and Long round to the nearest whole number, with halves rounding to the nearest even number (2.5 becomes 2, 3.5 becomes 4), and raise error 6 (Overflow) when the result does not fit. Single keeps about 7 significant digits, so PRINT shows at most 7 digits of it. Boolean stores True for any non-zero number or non-empty string and False otherwise. A variable declared with DIM but without a type is Single (or the DEFtype for its first letter). A variable that is never declared keeps whatever type the assigned value has.
Dim n As Integer
n = 3.7 ' n is 4
n = 40000 ' Error 6: Overflow
@@ -1327,10 +1474,12 @@ DIM variable(dim1, dim2, ...) AS type
DIM variable() AS type
DIM variable AS UdtName
DIM variable AS STRING * n
-DIM SHARED variable AS type
+DIM SHARED variable AS type
+DIM variable1 [AS type], variable2 [AS type], ...
An array declared with bounds is a fixed array. DIM variable() with empty parentheses declares a dynamic array that has no storage until a REDIM gives it bounds; using it before then raises error 13. An array that is first created by REDIM, and an array parameter, are dynamic too (see ERASE for the difference).
-Multiple variables can be declared at module level so their values persist between procedure calls. Arrays can have up to 8 dimensions. A variable declared with type suffix does not need the AS clause:
-Dim name$, count%, total& ' suffixes infer the types
+One DIM can declare several variables, separated by commas. Each one takes its own AS clause; a name without one gets its suffix or DEFtype type (Single by default), so DIM a, b AS STRING makes only b a String. Arrays can have up to 8 dimensions; more is a compile error. A variable declared with type suffix does not need the AS clause:
+Dim name$, count%, total& ' suffixes infer the types
+Dim first, last As String, list(10) As Integer
Examples:
Dim name As String
Dim count As Integer
@@ -1339,12 +1488,39 @@ Dim matrix(1 To 10, 1 To 10) As Single
Dim Shared globalFlag As Boolean
Dim record As PersonType
Dim fixedStr As String * 20
-Note: DIM SHARED at module level makes a variable accessible from every procedure without passing it as a parameter. Inside a SUB or FUNCTION, DIM declares a local variable that is recreated on each call (use STATIC to retain its value between calls). A variable that is first used inside a SUB or FUNCTION without a DIM is also local to that procedure; to share it with module-level code or other procedures, declare it with DIM SHARED at module level.
+Note: A module-level variable is visible inside a SUB or FUNCTION only when it is declared with DIM SHARED (or named in a SHARED statement in that procedure). See Variable Scope below. Inside a SUB or FUNCTION, DIM declares a local variable that is recreated on each call (use STATIC to retain its value between calls). A SUB or FUNCTION holds at most 64 parameters and local variables together, including a few hidden ones that statements such as ON ... GOTO, SWAP and READ into array elements use while they run; a procedure that needs more fails to compile with "Too many local variables".
Fixed-length strings (STRING * n) are padded with spaces and truncated when assigned so their length is always exactly n.
+Variable Scope and SHARED
+DVX BASIC follows the QBasic scope rules:
+
+- Variables declared (or first used) at module level -- outside every SUB and FUNCTION -- are module variables. The code section of a form (.frm) is module-level code of that form.
+- A SUB or FUNCTION sees a module variable only when it was declared with DIM SHARED at module level, or when the procedure names it in a SHARED statement. This applies to arrays as well.
+- Any other name used inside a SUB or FUNCTION is a local variable of that procedure, even when a module variable of the same name exists. With OPTION EXPLICIT, using such a name without a DIM is a compile error that says the module variable is not SHARED.
+- Indexing (name(...)) or dotting (name.member) a module variable the procedure cannot see is a compile error.
+- CONSTs declared at module level, TYPEs, SUBs, FUNCTIONs, forms and controls are visible everywhere; no SHARED is needed for them.
+- A DEF FN is module-level code: its expression sees every module variable.
+
+DIM SHARED total AS LONG ' visible in every SUB and FUNCTION
+DIM count AS INTEGER ' module code only
+
+SUB AddUp(n AS INTEGER)
+ total = total + n ' the module variable
+ count = 1 ' a local variable, not the module's count
+END SUB
+
+SUB ShowCount
+ SHARED count ' this procedure uses the module's count
+ PRINT count
+END SUB
+DIM SHARED and REDIM SHARED are only allowed at module level. Inside a procedure use the SHARED statement:
+SHARED variable [()] [AS type] [, variable [()] [AS type] ...]
+SHARED gives the procedure access to the named module variables (write name() for an array). The AS type, when given, must match the module variable's declaration. Naming a variable that does not exist at module level creates it there (in a form's code, as a variable of that form).
REDIM
Reallocates an array, optionally preserving existing data. The array may have been declared with DIM name() or with bounds, or not declared at all (REDIM then declares a dynamic array).
REDIM array(newBounds) AS type
-REDIM PRESERVE array(newBounds) AS type
+REDIM PRESERVE array(newBounds) AS type
+REDIM SHARED array(newBounds) AS type
+REDIM SHARED (module level only) also makes the array visible in every SUB and FUNCTION, like DIM SHARED.
ReDim items(newSize) As String
ReDim Preserve scores(1 To newCount) As Integer
CONST
@@ -1356,7 +1532,8 @@ Const PI = 3.14159265
Const APP_NAME = "DVX App"
Const DEBUG_MODE = True
Const HEADER As String = "=== Report ==="
-Constants are scoped to the file or procedure in which they are declared. Constants declared at module level are visible to all procedures in the same module.
+With an AS clause the literal is converted to that type: Integer and Long values are rounded and must fit the type, and a string literal for a numeric type (or a number for String) is a compile error. Without an AS clause an integer literal makes a Long constant and a literal with a fraction a Double constant.
+Constants declared at module level are visible to all procedures. A CONST declared inside a SUB or FUNCTION is local to that procedure; it may reuse the name of a module constant without changing it.
TYPE...END TYPE
Defines a user-defined type (record/structure).
TYPE TypeName
@@ -1378,6 +1555,7 @@ p.age = 30
Forward-declares a SUB or FUNCTION. This is rarely required because the compiler supports forward references within a module, but it is still accepted for compatibility:
DECLARE SUB name ([BYVAL] [OPTIONAL] param AS type, ...)
DECLARE FUNCTION name ([BYVAL] [OPTIONAL] param AS type, ...) AS returnType
+A DECLARE must match the SUB or FUNCTION it declares: the same parameter types, BYVAL and OPTIONAL flags, and return type.
DECLARE LIBRARY
Declares external functions from a native library bundled with DVX. This is how BASIC programs reach operating-system services, serial ports, databases, and other native facilities. Rather than writing DECLARE LIBRARY blocks yourself, add one of the shipped include files (such as commdlg.bas or sql.bas) to your project; the include file contains the proper declarations.
DECLARE LIBRARY "libraryName"
@@ -1385,9 +1563,10 @@ DECLARE FUNCTION name ([BYVAL] [OPTIONAL] param AS type, ...) AS returnType
Declare Library "basrt"
- Declare Function SQLOpen(ByVal path As String) As Integer
- Declare Sub SQLClose(ByVal db As Integer)
+ Declare Function SQLOpen(ByVal path As String) As Long
+ Declare Sub SQLClose(ByVal db As Long)
End Declare
+Arguments are always passed by value. Each argument is converted to the type its parameter is declared with before the call, so a Double passed to a Long parameter arrives as a whole number and a Single parameter receives a Single. Declare Integer only for native values that fit in 16 bits; use Long for 32-bit values, or large results are cut down to 16 bits.
See also: BASIC Runtime Libraries
STATIC
Declares a local variable that retains its value between calls.
@@ -1504,6 +1683,7 @@ For x = 10 To 0 Step -2
Print x
Next
The variable name after NEXT is optional. Use EXIT FOR to break out early.
+With an Integer or Long counter a constant STEP must be a whole number (STEP 0.5 is a compile error); a STEP computed at run time is rounded to the counter's type. A Single or Double counter takes any step.
DO...LOOP
General-purpose loop with pre-test, post-test, or infinite forms.
DO [WHILE condition | UNTIL condition]
@@ -1545,7 +1725,7 @@ END SUB
Sub Greet(ByVal name As String)
Print "Hello, " & name
End Sub
-Parameters are passed by reference by default; BYREF may be written out to say so, and BYVAL selects value semantics. Writes to a by-reference parameter update the caller's variable, including individual array elements: `bump a(3)` passed to a by-reference parameter will modify `a(3)` in place. A parameter written as name() receives a whole array by reference; the caller passes `arr()` (or just `arr`), and the SUB may index, REDIM or ERASE it. Use EXIT SUB to return early. A SUB is called either with or without parentheses; when used as a statement, parentheses are optional:
+Parameters are passed by reference by default (nested calls pass the same variable on, so a SUB called from a SUB can still change the original); BYREF may be written out to say so, and BYVAL selects value semantics. Writes to a by-reference parameter update the caller's variable, including individual array elements: `bump a(3)` passed to a by-reference parameter will modify `a(3)` in place. A parameter written as name() receives a whole array by reference; the caller passes `arr()` (or just `arr`), and the SUB may index, REDIM or ERASE it. Use EXIT SUB to return early. A SUB is called either with or without parentheses; when used as a statement, parentheses are optional:
Greet "World"
Greet("World")
Call Greet("World")
@@ -1579,9 +1759,18 @@ END FUNCTION
Function Square(ByVal n As Double) As Double
Square = n * n
End Function
-Assign to the function name to set the return value. Use EXIT FUNCTION to return early.
+Assign to the function name to set the return value. The value is converted to the function's type (AS clause, type suffix or DEFtype), so FUNCTION F AS INTEGER with F = 2.5 returns 2. Use EXIT FUNCTION to return early.
+A FUNCTION can also be called as a statement, with or without parentheses; its result is discarded:
+Function Beep2(ByVal n As Integer) As Integer
+ Beep2 = n * 2
+End Function
+
+Beep2 3 ' result discarded
+name(...) in an expression calls a FUNCTION; using a SUB there is a compile error.
+Labels, GOSUB and Variables in Procedures
+Labels belong to the SUB or FUNCTION they are written in (or to the module level). GOTO, GOSUB, ON ... GOTO/GOSUB and ON ERROR GOTO can only reach a label of the same procedure, and different procedures can reuse the same label name. GOSUB and RETURN work inside a procedure; see GOTO / GOSUB / RETURN. A procedure sees module variables only when they are SHARED; see Variable Scope and SHARED.
DEF FN
-Defines a single-expression function. The function name begins with FN and is invoked just like a normal function. DEF FN functions cannot span multiple statements.
+Defines a single-expression function. The function name begins with FN and is invoked just like a normal function. DEF FN functions cannot span multiple statements. A DEF FN must be defined before it is used, and only at module level (not inside a SUB or FUNCTION). Names in the expression other than the parameters are module variables, SHARED or not; the parameters are always passed by value.
DEF FNname(params) = expression
Def FnSquare(x) = x * x
Print FnSquare(5) ' prints 25
@@ -1606,7 +1795,8 @@ CALL name(args)
GOTO label
GOSUB label
RETURN
-GOSUB pushes the return address, executes code at the label, and RETURN jumps back. At module level, RETURN returns from a GOSUB. Inside a SUB/FUNCTION, RETURN returns from the procedure.
+A label is a name followed by a colon at the start of a line. Labels belong to the SUB or FUNCTION they are in (module-level labels to the module level): a jump can only reach a label of the same procedure, the same label name can be used in several procedures, and a label may have the same name as a variable. A jump to a label that is not defined in the procedure, or to a SUB or variable name, is a compile error.
+GOSUB records where it was called from, runs the code at the label, and RETURN goes back to the statement after the GOSUB. This works at module level and inside a SUB or FUNCTION alike. Each procedure call has its own set of pending GOSUBs: RETURN only returns from a GOSUB made in the same procedure call, and leaving the procedure (END SUB, EXIT SUB, EXIT FUNCTION or an error handled in a caller) discards the ones still pending. RETURN with no pending GOSUB raises error 3 (RETURN without GOSUB). To leave a SUB or FUNCTION, use EXIT SUB / EXIT FUNCTION.
GoSub Initialize
Print "Done"
End
@@ -1615,11 +1805,19 @@ Initialize:
count = 0
name$ = ""
Return
+Sub Report(n As Integer)
+ GoSub Heading
+ Print "value"; n
+ Exit Sub
+Heading:
+ Print "--- report ---"
+ Return
+End Sub
ON...GOTO / ON...GOSUB
Computed branch based on an integer expression.
ON expression GOTO label1, label2, ...
ON expression GOSUB label1, label2, ...
-If the expression evaluates to 1, control goes to the first label; 2, the second; and so on. If out of range, execution falls through.
+If the expression evaluates to 1, control goes to the first label; 2, the second; and so on. If out of range, execution falls through. The labels follow the same rules as GOTO and GOSUB (same procedure only).
Input/Output Statements
@@ -1631,9 +1829,10 @@ PRINT USING format$; expression [; expression] ...
- ; between items -- no separator (items appear next to each other, or separated by a space for numbers)
- , between items -- advance to the next 14-column tab zone
-- A trailing ; or , suppresses the newline normally written at the end of the statement
+- A trailing ; or , suppresses the newline normally written at the end of the statement (PRINT USING and PRINT # too)
- ? is an alias for PRINT
+
PRINT # writes numbers exactly as PRINT shows them, with the space after each number, so PRINT #1, 1; 2 writes "1 2 ". PRINT #n, with nothing after the comma writes an empty line.
Special functions inside PRINT:
- SPC(n) -- print n spaces
@@ -1642,8 +1841,17 @@ PRINT USING format$; expression [; expression] ...
Print "Name:"; Tab(20); name$
Print "X="; x, "Y="; y ' comma = next 14-column zone
Print #1, "Written to file"
+
LPRINT
+
Prints on the printer instead of the screen. Everything PRINT accepts works the same way: ; and , between items, SPC, TAB and LPRINT USING. The printer keeps its own column for TAB and the 14-column zones.
+
LPRINT [expression [{; | ,} expression] ...]
+LPRINT USING format$; expression [; expression] ...
+
The output goes to the printer chosen in the Control Panel (a printer port, or a file). Each LPRINT is sent at once, and lines end the way printers expect. Nothing starts a new page by itself: LPRINT CHR$(12) ejects the page. If the printer has a problem (out of paper, off line), the user is asked to fix it and choose Retry, or Cancel; after Cancel the LPRINT raises error 57. With no printer to print on, LPRINT raises error 68.
+
LPrint "Invoice"; Tab(40); Date$
+LPrint Using "Total: $$####.##"; total
+LPrint Chr$(12) ' eject the page
+
For a whole document with margins, a header, a footer and page numbers, and for the Print dialog, use the Printing Library (print.bas, see Include Libraries).
PRINT USING
-
PRINT USING formats each following expression according to a format string and prints the result. The format string is a mix of fields and literal text: each expression consumes the next field, the literal text before it is printed as it is, and the literal text after the last field is printed at the end. If more expressions are supplied than there are fields, the format string is reused from the start.
+
PRINT USING formats each following expression according to a format string and prints the result. The expressions after the format are separated by ; or , (both work the same here). The format string is a mix of fields and literal text: each expression consumes the next field, the literal text before it is printed as it is, and the literal text after the last field is printed at the end. If more expressions are supplied than there are fields, the format string is reused from the start.
Format character Meaning
---------------- -------
# Digit position; unused positions on the left become spaces
@@ -1659,7 +1867,7 @@ Print #1, "Written to file"
& Entire string (variable length)
\ ... \ Fixed-length string field (width = 2 + number of spaces between backslashes)
_ The next character is printed literally
-
A numeric field is as wide as its format characters; the value is right-aligned in it and a negative sign (or a leading +) floats directly in front of the first digit. A value that does not fit is printed in full with a leading %. A string expression must meet a string field and a numeric expression a numeric field, otherwise error 13 (Type mismatch) is raised.
+
A numeric field is as wide as its format characters; the value is right-aligned in it and a negative sign (or a leading +) floats directly in front of the first digit. A value that does not fit is printed in full with a leading %; a value too long to print in full is shown in scientific notation behind the %. A trailing + in a format with no digit positions is printed as literal text. A string expression must meet a string field and a numeric expression a numeric field, otherwise error 13 (Type mismatch) is raised.
Print Using "###.##"; -3.14159 ' " -3.14"
Print Using "+###"; 42 ' " +42"
Print Using "$$#,##0.00"; 1234.5 ' " $1,234.50"
@@ -1677,12 +1885,13 @@ INPUT "prompt"; variable
INPUT #channel, variable
Input "Enter your name: "; name$
Input #1, line$
+
The target may be a variable, an array element or a TYPE field (INPUT, INPUT #, LINE INPUT # and READ alike).
DATA / READ / RESTORE
Inline data pool for constants.
DATA value1, value2, "string", ...
READ variable1, variable2, ...
RESTORE
-
DATA statements define a pool of values. READ reads the next value from the pool into a variable. RESTORE resets the read pointer to the beginning.
+
DATA statements define a pool of values. READ reads the next value from the pool into a variable, array element or TYPE field. RESTORE resets the read pointer to the beginning. An item in quotes is a string; an unquoted item is taken as raw text up to the next comma, colon, comment or end of line (so keywords, several words and text such as 12abc are read as they are written) and converted when READ into a numeric variable. The most negative Integer and Long values (-32768, -2147483648) are accepted.
Data 10, 20, 30, "Hello"
Read a, b, c, msg$
Print a; b; c; msg$
@@ -1696,7 +1905,16 @@ ON ERROR GOTO 0 ' Disable error handler
RESUME ' Retry the statement that caused the error
RESUME NEXT ' Continue at the next statement after the error
ERROR n ' Raise a runtime error with error number n
-
The ERR keyword returns the current error number in expressions and ERL the source line the error was raised on (both are 0 when no error is active, and both reset after RESUME). RESUME or RESUME NEXT executed while no error is active raises error 20 (RESUME without error).
+
The ERR keyword returns the current error number (a Long) in expressions and ERL the source line the error was raised on (both are 0 when no error is active, and both reset after RESUME). RESUME or RESUME NEXT executed while no error is active raises error 20 (RESUME without error). ERROR n raises error n with its standard message (ERROR 11 reports "Division by zero"); numbers without a standard message report "User-defined error".
+
Each SUB and FUNCTION has its own ON ERROR handler:
+
+- An error is handled by the handler of the procedure it happens in; if that procedure has none, the calling procedures are searched outward.
+- A procedure called from a running handler can trap its own errors with its own handler.
+- Returning from a procedure that merely installed a handler leaves the caller's ERR and handler alone.
+- An error raised inside a running handler passes to the calling procedure's handler (untrapped if there is none).
+- The label named by ON ERROR GOTO must be in the same procedure.
+
+
RESUME NEXT continues after the failing statement. When the error happened in the condition of an IF, ELSEIF, WHILE, DO or LOOP, the condition counts as false (the block is skipped, the loop is left); after an error in a FOR statement the loop is skipped; after an error in the SELECT CASE expression the whole SELECT CASE block is skipped; after an error in a CASE test that test counts as false (the next value or CASE is tried); after an error in an ON ... GOTO/GOSUB selector no branch is taken and execution continues with the next statement.
On Error GoTo ErrorHandler
Open "missing.txt" For Input As #1
Exit Sub
@@ -1708,24 +1926,31 @@ ErrorHandler:
Number Meaning
------ -------
1 FOR loop error (NEXT without FOR, NEXT variable mismatch, FOR stack underflow)
+ 3 RETURN without GOSUB
4 Out of DATA
- 5 Illegal function call (bad argument to a built-in function)
- 6 Overflow (value does not fit the target type)
+ 5 Illegal function call (bad argument to a built-in function; an undefined math result such as a negative number to a fractional power)
+ 6 Overflow (value does not fit the target type; EXP, ^ or other math leaving the numeric range)
7 Out of memory
9 Subscript out of range / invalid variable or field index
11 Division by zero
13 Type mismatch / not an array / not a TYPE instance
+ 14 Out of string space (no memory to build a string)
20 RESUME without error
26 FOR loop nesting too deep
+ 28 Out of stack space (calls or expressions nested too deeply)
51 Internal error (bad opcode)
52 Bad file number or file not open
53 File not found (OPEN for INPUT, KILL, FILELEN, ...)
- 54 Bad file mode
+ 54 Bad file mode (also: a printer opened for anything but OUTPUT or APPEND)
+ 57 Device I/O error (printing failed or was cancelled)
58 File already exists or rename failed
59 Bad record length (OPEN ... LEN must be 1 to 32767; GET/PUT data longer than LEN)
+ 63 Bad record number (SEEK, GET or PUT position below 1)
67 Too many files open
+ 68 Device unavailable (no printer to print on)
75 Path/file access error
76 Path not found
+ 91 Object variable not set (property, method, Show/Hide/Unload on a value that is not a form or control)
1000 No form runtime (a form or control statement ran without the form runtime, e.g. under a headless runner)
SHELL
Executes an operating-system command.
@@ -1734,7 +1959,7 @@ ErrorHandler:
Shell "DIR /B"
exitCode = Shell("COPY A.TXT B.TXT")
SLEEP
-Pauses execution for the given number of seconds. With no argument, sleeps for 1 second.
+Pauses execution for the given number of seconds. With no argument, sleeps for 1 second. The desktop and the program's own forms keep running while it sleeps, SLEEP 0 just lets pending events run, and closing the program ends the sleep.
SLEEP [seconds]
RANDOMIZE
Seeds the random number generator. Without an argument (not shown here) and without a prior RANDOMIZE, the sequence is the same on every run. Use RANDOMIZE TIMER to get a different sequence each run.
@@ -1760,11 +1985,17 @@ OPEN filename$ FOR BINARY AS #channel
APPEND Open for sequential writing at end of file.
RANDOM Open for random-access record I/O. LEN sets the record size in bytes (default 128).
BINARY Open for raw binary I/O.
+
Printing Through OPEN
+
The names LPT1:, LPT2:, LPT3: (a printer port) and PRN (the printer chosen in the Control Panel) open a printer, in any case and with or without the colon. Only OUTPUT and APPEND work (anything else raises error 54). PRINT # and WRITE # collect the output, and CLOSE sends it to the printer; a printer problem the user cancels makes CLOSE raise error 57, and a printer that cannot be reached makes OPEN raise error 68.
+
Open "LPT1:" For Output As #1
+Print #1, "Line one"
+Print #1, "Line two"
+Close #1 ' now it prints
CLOSE
Closes an open file channel.
CLOSE #channel
PRINT #
-
Writes text to a file.
+
Writes text to a file, formatted exactly as PRINT shows it (numbers are followed by a space). See PRINT.
PRINT #channel, expression
INPUT #
Reads comma-delimited data from a file, one field per variable. Quoted strings written by WRITE # are read back without their quotes; numeric variables receive the converted value.
@@ -1784,10 +2015,10 @@ Close #1
Read and write records in RANDOM or BINARY mode files. When recordNum is omitted the transfer starts at the current file position.
GET #channel, [recordNum], variable
PUT #channel, [recordNum], variable
-
In RANDOM mode recordNum is a 1-based record number and each record is LEN bytes (see OPEN). Numbers are stored in their binary form (Integer and Boolean 2 bytes, Long 4, Single 4, Double 8); a String is stored as a 2-byte length followed by its characters. PUT always writes a whole record, padding the unused part with zero bytes, and GET always advances to the next record; data longer than LEN raises error 59.
+
In RANDOM mode recordNum is a 1-based record number and each record is LEN bytes (see OPEN). Numbers are stored in their binary form (Integer and Boolean 2 bytes, Long 4, Single 4, Double 8); a String is stored as a 2-byte length followed by its characters. PUT always writes a whole record, padding the unused part with zero bytes, and GET always advances to the next record; data longer than LEN raises error 59 before anything is written.
In BINARY mode recordNum is a 1-based byte position. Numbers are stored as in RANDOM mode. PUT writes the characters of a String with no length prefix, and GET reads as many bytes as the String variable currently holds, so set its length first (for example with SPACE$ or by declaring it as STRING * n).
The variable may be a TYPE variable. Its fields are packed in declaration order with the sizes above; a STRING * n field takes exactly n bytes (padded with spaces), a variable-length String field is stored with its 2-byte length prefix in both modes, and nested TYPE fields are packed inline. GET fills the fields of the existing variable in place.
-
The variable may also be an array element, arr(i), of any type including a TYPE: PUT writes that element and GET reads into it. The index expression of a GET target is evaluated twice (once to fetch the element, once to store it back), so keep it free of side effects.
+
The variable may also be an array element, arr(i), of any type including a TYPE: PUT writes that element and GET reads into it. The index expression is evaluated once.
Type RecT
id As Integer
score As Double
@@ -1806,7 +2037,7 @@ Get #1, 1, buf ' read bytes 1-16
Put #1, 33, "TAG" ' write 3 bytes at position 33
Close #1
SEEK
-
Sets the file position. As a function, returns the current position.
+
Sets the file position. As a function, returns the current position. On a RANDOM file the position is a record number (statement and function); on other files it is a 1-based byte position. A position below 1 raises error 63 (Bad record number).
SEEK #channel, position ' Statement: set position
pos = SEEK(channel) ' Function: get current position
@@ -1838,7 +2069,7 @@ CHDRIVE drive$
ChDir "C:\DVX\PROJECTS"
ChDrive "D"
GETATTR / SETATTR
-GETATTR returns the attributes of a file (as a function). SETATTR sets them (as a statement). Attributes are a bitmask of the vb file-attribute constants.
+GETATTR returns the attributes of a file (as a function). SETATTR sets them (as a statement). Attributes are a bitmask of the vb file-attribute constants. A missing file raises error 53 (File not found); SETATTR raises error 75 when the attributes cannot be changed.
attrs = GETATTR(filename$)
SETATTR filename$, attrs
Constant Value Attribute
@@ -1855,7 +2086,7 @@ End If
SetAttr "secret.dat", vbHidden + vbReadOnly
CURDIR$ / DIR$
-CURDIR$ returns the current directory. DIR$ returns the first file matching a pattern; subsequent calls with no arguments return additional matches (or "" when done).
+CURDIR$ returns the current directory. DIR$ returns the first file matching a pattern; subsequent calls with no arguments return additional matches (or "" when done). DIR$ returns only files: never ".", ".." or subdirectories.
cwd$ = CURDIR$
first$ = DIR$("*.txt")
WHILE first$ <> ""
@@ -1891,7 +2122,7 @@ WEND
TRIM$(s$) String Removes leading and trailing spaces from s$
UCASE$(s$) String Converts s$ to uppercase
VAL(s$) Double Converts string s$ to a numeric value; stops at first non-numeric character
-A negative count or position passed to LEFT$, RIGHT$, MID$, SPACE$ or STRING$, or a count above 65535 passed to SPACE$ or STRING$, raises error 5 (Illegal function call).
+A negative count or position passed to LEFT$, RIGHT$, MID$, SPACE$ or STRING$, or a count above 65535 passed to SPACE$ or STRING$, raises error 5 (Illegal function call). INSTR follows OPTION COMPARE TEXT (a case-insensitive search), and an INSTR start position below 1 raises error 5.
FORMAT$
FORMAT$ formats a numeric value using a BASIC-style format string. The format characters are the same as the ones used by PRINT USING.
s$ = FORMAT$(value, fmt$)
@@ -1909,7 +2140,7 @@ Print Format$(0.5, "PERCENT") ' "50%"
s$ = "Hello, World!"
Mid$(s$, 8, 5) = "DVX--"
Print s$ ' Hello, DVX--!
-If length is omitted, MID$ replaces up to LEN(replacement$) characters. The target string's total length never changes -- extra characters in replacement$ are truncated and shorter replacements leave trailing characters in place.
+If length is omitted, MID$ replaces up to LEN(replacement$) characters; a length of 0 replaces nothing. The target string's total length never changes -- extra characters in replacement$ are truncated and shorter replacements leave trailing characters in place. A start position below 1 or a negative length raises error 5 (Illegal function call).
Math Functions
@@ -1928,7 +2159,9 @@ Print s$ ' Hello, DVX--!
SQR(n) Double Square root of n
TAN(n) Double Tangent of n (n in radians)
TIMER Double Seconds since midnight
-
Note: RND with no argument returns the next number in the sequence. Use RANDOMIZE or RANDOMIZE TIMER to seed the generator so you don't get the same sequence each run.
+
RND follows QBasic: RND or RND(n) with n > 0 returns the next number in the sequence, RND(0) repeats the last number, and RND(n) with n < 0 reseeds the generator from n (the same n always gives the same number). The result is a Double, 0 <= RND < 1.
+
INT, FIX and SGN return an Integer, widening to Long or Double when the value does not fit. EXP, ^ and the other functions raise error 6 (Overflow) when the result leaves the numeric range, and error 5 when it is undefined (for example a negative number to a fractional power).
+
Note: Use RANDOMIZE or RANDOMIZE TIMER to seed the generator so you don't get the same sequence each run.
Color Functions
The color functions work with 24-bit RGB colors packed into a Long.
Function Returns Description
@@ -1962,7 +2195,7 @@ Me.BackColor = RGB(0, 0, 128) ' dark blue background
INPUT$(n, #channel) String Reads exactly n characters from the file
LOC(channel) Long BINARY: position of the last byte read or written (0 at the start); RANDOM: number of the last record read or written; sequential: number of 128-byte blocks read or written
LOF(channel) Long Length of the file in bytes
- SEEK(channel) Long 1-based position of the next byte to be read or written
+ SEEK(channel) Long RANDOM: number of the next record; other modes: 1-based position of the next byte to be read or written
FILELEN(path$) Long Length of the named file in bytes (no OPEN needed; error 53 when missing)
GETATTR(path$) Integer File attribute bits (see vbReadOnly, vbHidden, etc.)
CURDIR$ String Current working directory
@@ -1970,6 +2203,7 @@ Me.BackColor = RGB(0, 0, 128) ' dark blue background
DIR$ String Next match from the last DIR$(pattern$), or "" when done
LBOUND(array [, dim]) Integer Lower bound of an array dimension (default dim = 1)
UBOUND(array [, dim]) Integer Upper bound of an array dimension (default dim = 1)
+
The dim argument of LBOUND and UBOUND must be a constant from 1 to 8.
Miscellaneous Functions
@@ -1979,8 +2213,16 @@ Me.BackColor = RGB(0, 0, 128) ' dark blue background
TIME$ String Current time as "HH:MM:SS" (24-hour)
TIMER Double Seconds since midnight
ENVIRON$(name$) String Value of the environment variable; empty string if not set
- ERR Integer Current runtime error number (0 if no error)
+ COMMAND$ String The arguments the program was started with; empty string if none
+ COMMAND$(n) String The nth argument (1 = first) without its quotes; empty string when there are fewer; COMMAND$(0) is the same as COMMAND$
+ ERR Long Current runtime error number (0 if no error)
SHELL(cmd$) Integer Exit code of the command (also usable as a statement, discarding the code)
+
COMMAND$
+
COMMAND$ returns the program's arguments exactly as they were given, as in Visual Basic (QBasic turned them into capitals; DVX keeps them as they are). Arguments are separated by blanks; an argument with blanks in it is written in double quotes. COMMAND$(n) picks out one argument with its quotes removed, so a program that opens the document it was started with only needs:
+
IF COMMAND$(1) <> "" THEN
+ OpenFile COMMAND$(1)
+END IF
+
A program gets arguments when a document of a type associated with it is opened (the document is the argument), from a Program Manager item's Arguments, or from a command typed in a Run box. When the program runs in the IDE, COMMAND$ returns the Arguments set in Project Properties. A negative n is error 5 (Illegal function call).
Form and Control Statements
@@ -2006,6 +2248,7 @@ value = ControlName.Property
Label1.Caption = "Name: " & name$
x = Text1.Left
A control on another form is reached through that form's name, or through a variable holding a form reference: FormName.ControlName.Property works in both assignments and expressions, and so does FormName.ControlName.Method. Me.ControlName.Property does the same for the current form.
+
Using a property or method (or Show, Hide, Unload) on a variable that does not hold a form or control raises error 91 (Object variable not set). In the IDE, a property or method name that the control's type does not have is reported when the program is compiled.
Form2.Label1.Caption = "From Form1"
total = Form2.List1.ListCount
Form2.List1.Clear
@@ -2045,13 +2288,13 @@ End With
Creates a new form with the given name and initial size. Returns a form reference.
CreateControl
SET ctrlVar = CreateControl(formRef, typeName$, ctrlName$ [, parentCtrlRef])
-
Creates a control on the given form. typeName$ is the control type (e.g. "CommandButton", "Label", "TextBox"). ctrlName$ is the unique name for the new control. If a parentCtrlRef is supplied, the new control is nested inside it (useful for placing controls inside containers like HBox or Frame).
+
Creates a control on the given form. typeName$ is the control type (e.g. "CommandButton", "Label", "TextBox"). ctrlName$ is the unique name for the new control. If a parentCtrlRef is supplied, the new control is nested inside it (useful for placing controls inside containers like HBox or Frame); the parent must be a container on the same form, otherwise a runtime error (CreateControl: invalid parent) is raised.
SetEvent
SETEVENT ctrlRef, eventName$, handlerName$
-
Wires an arbitrary SUB as the handler for a control's event. The default event-handler convention (ControlName_EventName) is used automatically for controls defined in a .frm file; SetEvent is for controls you create dynamically or for reusing a single handler across multiple controls.
+
Wires an arbitrary SUB as the handler for an event of a control, a form (Me or a form reference) or a menu item. The default event-handler convention (ControlName_EventName) is used automatically for controls defined in a .frm file; SetEvent is for controls you create dynamically or for reusing a single handler across multiple controls. A handler declared without parameters is called without the event's arguments.
RemoveControl
REMOVECONTROL formRef, ctrlName$
-
Removes a control from a form.
+
Removes a control from a form. A later reference to the removed control raises a runtime error (unknown control), as does a reference to a control of a form that has been unloaded.
Dim frm As Long
Dim lbl As Long
@@ -2133,10 +2376,10 @@ End Sub
SQL Functions
-
DVX BASIC includes SQLite database support through the sql.bas include library. Add sql.bas to your project to gain access to these functions. All functions use database handles and result-set handles (integers) returned by SQLOpen and SQLQuery.
+
DVX BASIC includes SQLite database support through the sql.bas include library. Add sql.bas to your project to gain access to these functions. All functions use database handles and result-set handles (Long integers) returned by SQLOpen and SQLQuery. Numeric parameters and results are Long, so row counts and integer column values keep their full 32-bit range.
Opening and Closing Databases
SQLOpen
-
Opens a SQLite database file and returns a database handle (> 0) or 0 on failure. The file is created if it does not exist.
+
Opens a SQLite database file and returns a database handle (> 0) or 0 on failure. The file is created if it does not exist. A file that cannot be changed (for example one marked read-only) still opens, but only for reading. When SQLOpen returns 0, SQLError$(0) tells you why.
db = SQLOpen(path$)
db = SQLOpen(App.Data & "\mydata.db")
SQLClose
@@ -2149,6 +2392,7 @@ End Sub
SQLExec db, "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"
SQLExec db, "INSERT INTO users (name) VALUES ('Scott')"
ok = SQLExec(db, "DELETE FROM users WHERE id = 5")
+
Put text values in single quotes, as in the examples. Text in double quotes is read as a column name, so "Scott" in place of 'Scott' gives the error "no such column: Scott".
SQLAffected
Returns the number of rows affected by the last INSERT, UPDATE, or DELETE.
count = SQLAffected(db)
@@ -2174,7 +2418,7 @@ first$ = SQLFieldText$(rs, 0)
Returns the column name for a given 0-based column index.
colName$ = SQLFieldName$(rs, columnIndex)
SQLFieldInt
-
Returns a field value as an integer.
+
Returns a field value as a Long integer.
value = SQLFIELDINT(rs, columnIndex)
SQLFieldDbl
Returns a field value as a double.
@@ -2190,9 +2434,10 @@ first$ = SQLFieldText$(rs, 0)
SQLError$
Returns the last error message for the database.
msg$ = SQLError$(db)
+
When a database file could not be opened, read or written, the message ends with the reason in parentheses, for example "unable to open database file (No such file or directory)". If another program, or another handle in your own program, is changing the same database at that moment, the message is "database is locked": try again once the other change is finished, and free result sets with SQLFreeResult as soon as you are done with them, because an open result set stops other handles from saving changes.
Complete SQL Example
-
Dim db As Integer
-Dim rs As Integer
+Dim db As Long
+Dim rs As Long
db = SQLOpen(App.Data & "\contacts.db")
SQLExec db, "CREATE TABLE IF NOT EXISTS contacts (name TEXT, phone TEXT)"
@@ -2221,12 +2466,12 @@ Print "Running from: " & App.Path
INI Functions
DVX BASIC provides built-in functions for reading and writing standard INI configuration files (the same text format used by DVX system configuration).
IniRead
-Reads a value from an INI file. Returns the default value if the file, section, or key is not found. All four arguments are required.
+Reads a value from an INI file. Returns the default value if the file, section, or key is not found. All four arguments are required. Section and key names match without regard to case, and blanks around them are ignored ([ User ] is section User). If a name appears twice, the first one counts. Keys above the first section header belong to section "" (an empty section name). Lines starting with ; or # are comments.
value$ = IniRead(file$, section$, key$, default$)
name$ = IniRead(App.Config & "\app.ini", "User", "Name", "Unknown")
fontSize = Val(IniRead(App.Config & "\app.ini", "Display", "FontSize", "12"))
IniWrite
-Writes a value to an INI file. Creates the file, section, or key if they do not exist.
+Writes a value to an INI file. Creates the file, section, or key if they do not exist. A new key goes after the last key of its section and a new section at the end of the file. Every other line -- comments, blank lines, other keys, lines of any length -- is kept exactly as it is. The changed key is written as key = value. Every line of the saved file ends in a carriage return and line feed (CR LF). The file is saved through a temporary file, so a failed write leaves the old file intact. If the file exists but cannot be read, or the new file cannot be written, IniWrite raises error 75 (Path/file access error) and leaves the file alone.
INIWRITE file$, section$, key$, value$
IniWrite App.Config & "\app.ini", "User", "Name", "Scott"
IniWrite App.Config & "\app.ini", "Display", "FontSize", Str$(fontSize)
@@ -2287,17 +2532,82 @@ IniWrite App.Config & "\app.ini", "Display", "FontS
sql.bas SQLite database access (SQLOpen, SQLQuery, SQLNext, SQLField$, etc.)
comm.bas Serial-port I/O (raw and packet) and optional encrypted links
resource.bas Read and write DVX resource blocks (icons, text, binary data) in bundled files
- help.bas Compile help source files and open the DVX help viewer
+ help.bas Compile help source files and open the DVX help viewer
+ net.bas Network connections: TCP (TcpConnect, TcpListen, TcpSend, TcpRecv$, ...), UDP messages and name lookups
+ print.bas Printing: text with the page setup and pictures, with or without the Print dialog; the Page Setup dialog
Using an Include Library
' With commdlg.bas added to the project
Dim path As String
-path = basFileOpen("Open a file", "Text Files (*.txt)|All Files (*.*)")
+path = DlgFileOpen$("Open a file", "Text Files (*.txt)|All Files (*.*)")
If path <> "" Then
Print "Selected: " & path
End If
Note: DVX BASIC does not have an $INCLUDE directive. Libraries are added to the project so that the compiler sees their DECLARE LIBRARY blocks.
-
See also: BASIC Runtime Library
+
Encrypted Serial Links
+
With comm.bas in the project, CommOpen opens a packet link and CommHandshake sets up encryption. Give both ends the same passphrase to authenticate the connection. Without a passphrase the link is still encrypted and tamper-checked, but it cannot tell who is on the other end. CommHandshake returns False if the passphrases differ, if only one side gives one, or if the link fails.
+
Dim link As Long
+link = CommOpen(1, 115200, 8, "N", 1, SER_HANDSHAKE_NONE)
+
+If CommHandshake(link, "shared secret") Then
+ CommSend link, "hello", 0, True
+Else
+ Print "Handshake failed"
+End If
+
After the handshake, data that arrives unencrypted is ignored unless that channel is opened for it with CommSetPlain link, channel, True.
+
Printing
+
With print.bas in the project, a program prints like the programs that come with DVX. PrintTextDialog shows the Print dialog (printer, copies, pages) and prints the text on pages laid out by the page setup: margins, a header and a footer with the document name, date and page number. PrintPageSetup shows the Page Setup dialog, which the user's choices are saved from for every program. PrintPictureDialog prints a picture file scaled to the page, on printer models that print pictures (PrintCanPrintPictures says whether the chosen one does). PrintText and PrintPicture print without asking first. Each returns True when it printed.
+
Sub mnuPrint_Click ()
+ PrintTextDialog txtNotes.Text, "Notes"
+End Sub
+
+Sub mnuPageSetup_Click ()
+ PrintPageSetup
+End Sub
+
For printer output a line at a time, see LPRINT and OPEN "LPT1:".
+
Network Connections
+
With net.bas in the project, a program talks to other computers over the network set up in the Control Panel. TcpConnect returns a handle (0 when it failed; NetError$ says why), TcpSend sends text, and TcpRecv$ returns whatever has arrived without waiting, so a Timer keeps the program responsive:
+
Dim conn As Long
+
+Sub Form_Load ()
+ conn = TcpConnect("bbs.example.org", 23)
+
+ If conn = 0 Then
+ Print "Could not connect: " & NetError$()
+ End If
+End Sub
+
+Sub Timer1_Timer ()
+ If TcpPending(conn) > 0 Then Print TcpRecv$(conn)
+ If TcpConnected(conn) = 0 Then Timer1.Enabled = False
+End Sub
+
Function Description
+ -------- -----------
+ HostLookup$(hostName) The address of a name, such as "192.0.2.10", or "" when it is not found.
+ NetAddress$() This computer's address ("" while it has none).
+ NetError$() Why the last call failed, in plain words.
+ TcpConnect(host, port) Connect; a handle, or 0. Waits up to 20 seconds; other programs keep running.
+ TcpListen(port) Wait for connections on port; a listening handle, or 0.
+ TcpAccept(handle) A connection that arrived on a listening handle, or 0 when none is waiting.
+ TcpSend(handle, text) Send text; the bytes sent, or -1.
+ TcpPending(handle) Bytes waiting to be read (-1 for a bad handle).
+ TcpRecv$(handle) What has arrived (up to 4096 bytes), or "".
+ TcpConnected(handle) 1 while the connection is open, 0 once the other side closed it.
+ TcpClose handle Close a connection or a listening handle.
+ UdpOpen(port) A UDP handle on port (0 = any free port), or 0.
+ UdpSend(handle, host, port, text) Send one message; the bytes sent, or -1. "255.255.255.255" reaches every computer nearby.
+ UdpRecv$(handle) The next message that arrived, or "".
+ UdpFrom$() "address:port" of the sender of the last UdpRecv$ message.
+ UdpClose handle Close a UDP handle.
+
The functions work with text: a string stops at a zero byte. Every connection a program opens is closed for it when the program ends.
+
CommRecvEncrypted(handle, channel) tells whether the data the last CommRecv$ on that channel returned can be trusted. It returns True when every byte of it arrived encrypted and authenticated, and also when that CommRecv$ returned nothing or CommRecv$ has not been called on the channel yet. It returns False when any byte arrived unencrypted, which can only happen before CommHandshake or on a channel opened with CommSetPlain, and for an invalid handle or a channel outside 0-127.
+
Dim msg As String
+msg = CommRecv$(link, 1)
+
+If msg <> "" And Not CommRecvEncrypted(link, 1) Then
+ Print "Unencrypted: " & msg
+End If
+
See also: DECLARE LIBRARY
Common Properties, Events, and Methods
@@ -2310,17 +2620,19 @@ End If
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.
+ MinWidth Integer R/W Minimum width for layout. Setting it works like setting Width; reading it returns the minimum that was set.
+ MinHeight Integer R/W Minimum height for layout. Setting it works like setting Height; reading it returns the minimum that was set.
MaxWidth Integer R/W Maximum width cap (0 = no limit, stretch to fill).
MaxHeight Integer R/W Maximum height cap (0 = no limit, stretch to fill).
Weight Integer R/W Layout weight. 0 = fixed size, >0 = share extra space proportionally.
Visible Boolean R/W Whether the control is visible.
- Enabled Boolean R/W Whether the control accepts user input.
+ Enabled Boolean R/W Whether the control accepts user input. Disabling a container (Frame, VBox, HBox...) also blocks mouse and keyboard input to every control inside it.
BackColor Long R/W Background color as a 24-bit RGB value packed in a Long (use the RGB function to construct).
ForeColor Long R/W Foreground (text) color as a 24-bit RGB value packed in a Long (use the RGB function to construct).
TabIndex Integer R Accepted for VB compatibility but ignored. DVX has no tab order.
- ToolTipText String R/W Tooltip text shown after the mouse hovers over the control. Empty string or unset = no tooltip.
+ ToolTipText String R/W Tooltip text shown after the mouse hovers over the control. Empty string or unset = no tooltip.
+ HelpTopic String R/W Help topic opened by F1 while the control has the focus. Empty = the form's HelpTopic. F1 uses the project's help file.
+
Size properties (Width, Height and the Min/Max sizes) are limited to 0..32767.
Common Events
These events are wired on every control loaded from a .frm file. Controls created dynamically at runtime via code only receive Click, DblClick, Change, GotFocus, and LostFocus; the keyboard, mouse, and scroll events below require the control to be defined in the .frm file.
Event Parameters Description
@@ -2444,11 +2756,21 @@ End Sub
End
End
Menu Item Properties
-
Property Type Description
- -------- ------- -------------------------------------------
- Caption String The text displayed. Use & for accelerator key. Set to "-" for a separator.
- Checked Boolean Whether the menu item shows a checkmark.
- Enabled Boolean Whether the menu item is enabled (default True).
+
In the .frm file a menu item takes these keys:
+
Key Type Description
+ ---------- ------- -------------------------------------------
+ Caption String The text displayed. Use & for accelerator key. Set to "-" for a separator.
+ Checked Boolean Whether the menu item shows a checkmark.
+ RadioCheck Boolean Show the check as a radio dot instead of a checkmark.
+ Enabled Boolean Whether the menu item is enabled (default True).
+ Visible Boolean On a top-level menu only: False makes it a popup menu (for ContextMenu) instead of a menu bar entry.
+
At run time code can use only these properties of a menu item:
+
Property Type R/W Description
+ -------- ------- --- -------------------------------------------
+ Name String R The menu item's name.
+ Checked Boolean R/W Whether the menu item shows a checkmark.
+ Enabled Boolean R/W Whether the menu item is enabled.
+
Caption, RadioCheck and Visible are design-time only: using them on a menu item in code is a compile error in the IDE and a runtime error (Unknown menu property) otherwise.
Nesting
Menu items are nested by placing Begin Menu blocks inside other Begin Menu blocks:
@@ -2586,14 +2908,17 @@ End Sub
---------- ------- -------------- -------------------------------------------
Name String "Form1" The form's name, used for event dispatch and Load statement.
Caption String (same as Name) Window title bar text.
- Width Integer 400 Window width in pixels. Setting this disables AutoSize.
- Height Integer 300 Window height in pixels. Setting this disables AutoSize.
+ Width Integer 400 Window width in pixels. In the .frm file it is ignored when AutoSize is True.
+ Height Integer 300 Window height in pixels. In the .frm file it is ignored when AutoSize is True.
Left Integer 0 Initial X position. Used when Centered is False.
Top Integer 0 Initial Y position. Used when Centered is False.
Layout String "VBox" Content box layout: "VBox" (vertical) or "HBox" (horizontal).
AutoSize Boolean False When True, the window shrink-wraps to fit its content.
Resizable Boolean True Whether the user can resize the window at runtime.
- Centered Boolean True When True, the window is centered on screen. When False, Left/Top are used.
+ Centered Boolean True When True, the window is centered on screen. When False, Left/Top are used.
+ Visible Boolean False True shows the form and False hides it, exactly like Show and Hide (the first show fires Activate).
+ ContextMenu String "" Name of a popup menu shown when the form is right-clicked.
+ HelpTopic String "" Help topic opened by F1 while the form is active and the focused control has no HelpTopic of its own. Empty opens the project's help file at its default page.
Form Events
Event Parameters Description
----------- --------------------- -------------------------------------------
@@ -2632,13 +2957,13 @@ End Sub
Terminal
DVX Extension -- DVX Widget: ansiterm
-
A VT100/ANSI terminal emulator with a text-mode cell buffer, 16-color CGA palette, and scrollback history. Processes standard ANSI escape sequences (cursor control, erase, scroll, SGR colors, DEC private modes) typically used by DOS BBS software. Default size is 80 columns by 25 rows. Supports text selection with the mouse, Ctrl+C to copy, and Ctrl+V to send clipboard text as input.
+
A VT100/ANSI terminal emulator with a text-mode cell buffer, 16-color CGA palette, and scrollback history. Processes standard ANSI escape sequences (cursor control, erase, scroll, SGR colors, DEC private modes) typically used by DOS BBS software. Default size is 80 columns by 25 rows. Supports text selection with the mouse, Ctrl+C to copy, and Ctrl+V to send clipboard text as input. Shift+PgUp and Shift+PgDn page through the scrollback history and the mouse wheel scrolls it; any other key is sent to the host and returns the view to the live screen.
Type-Specific Properties
Property Type Description
---------- ------- -------------------------------------------
Cols Integer Number of character columns (read-only).
Rows Integer Number of character rows (read-only).
- Scrollback Integer Maximum number of scrollback lines. Older lines are dropped (write-only; default 500).
+ Scrollback Integer Maximum number of scrollback lines. Older lines are dropped (default 500). Setting it discards the existing history.
Type-Specific Methods
Method Description
------ -----------
@@ -2648,11 +2973,16 @@ End Sub
No default event. Uses common events only.
Serial Communication
Use the comm.bas library to connect a Terminal to a serial link:
-
Dim link As Integer
-link = CommOpen(1, 115200)
-CommHandshake link
-CommAttach link, "Terminal1"
-
See comm.bas for the full communications API.
+
Dim link As Long
+link = CommOpen(1, 115200, 8, "N", 1, SER_HANDSHAKE_NONE)
+If link <> 0 Then
+ If CommHandshake(link, "secret") Then
+ CommAttach link, "Terminal1", 0, True
+ Else
+ MsgBox "Handshake failed"
+ End If
+End If
+
The passphrase is optional. Both ends must give the same passphrase, or both give none; otherwise CommHandshake returns False. See comm.bas for the full communications API.
Example
Begin Terminal Terminal1
MinWidth = 640
@@ -2673,6 +3003,7 @@ End Sub
-------- ------ -------------------------------------------
Caption String The title displayed in the frame border.
No type-specific methods or events.
+
Setting Enabled = False on a Frame disables every control inside it for mouse and keyboard input.
Container: Yes
Default Event: Click
Example
@@ -2752,8 +3083,14 @@ End Sub
PictureBox
VB Equivalent: PictureBox -- DVX Widget: canvas | Name Prefix: Picture
-
A drawing surface (canvas). Supports drawing lines, rectangles, circles, text, and individual pixels. Can save and load BMP images. The default canvas size is 64x64 pixels.
+
A drawing surface (canvas). Supports drawing lines, rectangles, circles, text, and individual pixels. Can load BMP, PNG, JPEG and GIF images and save BMP or PNG images. The default canvas size is 64x64 pixels.
Colors are specified as 0x00RRGGBB integers (e.g. &HFF0000 for red).
+
Type-Specific Properties
+
Property Type Description
+ -------- ---- -----------
+ ImageHeight Integer Height of the drawing in pixels (read-only). After Load it is the loaded image's height.
+ ImageWidth Integer Width of the drawing in pixels (read-only). After Load it is the loaded image's width.
+
Load and Save return 0 on success and -1 on failure (missing or unreadable file, unsupported format, path that cannot be written). Call them as functions to check the result, or as statements to ignore it. A failed Load leaves the drawing unchanged.
Type-Specific Methods
Method Description
------ -----------
@@ -2764,11 +3101,11 @@ End Sub
FillCircle cx%, cy%, radius%, color% Draw a filled circle.
FillRect x%, y%, w%, h%, color% Draw a filled rectangle.
GetPixel(x%, y%) Returns the color at a pixel.
- Load path$ Load a BMP image onto the canvas.
- Resize w%, h% Resize the canvas to new dimensions.
- Save path$ Save the canvas as a BMP file.
+ Load(path$) Load a BMP, PNG, JPEG or GIF image; the canvas takes the image's size. Returns 0 on success, -1 on failure.
+ Resize w%, h% Resize the canvas to new dimensions. The drawing is cleared to white.
+ Save(path$) Save the canvas: BMP when path$ ends in .bmp, PNG otherwise. Returns 0 on success, -1 on failure.
SetPenColor color% Set the drawing color for subsequent operations.
- SetPenSize size% Set the pen/brush size in pixels.
+ SetPenSize size% Set the pen/brush size in pixels (1 to 255; larger values use 255).
SetPixel x%, y%, color% Set the color of a single pixel.
Default Event: Click
Example
@@ -2778,7 +3115,9 @@ Picture1.SetPenSize 2
Picture1.DrawRect 10, 10, 180, 130, &H000000
Picture1.FillCircle 100, 75, 40, &HFF0000
Picture1.DrawText 60, 130, "Hello!"
-Picture1.Save "output.bmp"
+If Picture1.Save("output.bmp") <> 0 Then
+ MsgBox "Could not save output.bmp"
+End If
Common Properties, Events, and Methods
@@ -2822,7 +3161,7 @@ End Sub
Clear Remove all items.
List(index%) Return the text of the item at the given index.
ListCount() Return the number of items in the list.
- RemoveItem index% Remove the item at the given index.
+ RemoveItem index% Remove the item at the given index. The selection stays on the same item; removing the selected item leaves no selection (the text is kept).
Default Event: Click
Example
Begin ComboBox Combo1
@@ -2843,7 +3182,7 @@ End Sub
Data
VB Equivalent: Data -- DVX Widget: data | Name Prefix: Data
-
A data access control that connects to a SQLite database and provides record navigation. Other controls bind to a Data control via their DataSource and DataField properties. The Data control cache is populated by calling Refresh. Move operations auto-save the current row if dirty.
+
A data access control that connects to a SQLite database and provides record navigation. Other controls bind to a Data control via their DataSource and DataField properties. The Data control cache is populated by calling Refresh. Move operations and Refresh auto-save the current row if dirty; a move is refused while the save fails, and Refresh discards an edit that cannot be saved. Updates find the record by the key value it was loaded with, so the key column itself can be edited; a key stored as a number in a column without a declared type, or a missing (NULL) key, is still found as long as it identifies exactly one record. Writing a field back with the value it already has is not an edit and does not fire Validate. While a Validate handler runs, MoveFirst, MoveLast, MoveNext, MovePrevious, AddNew, Refresh and Update on the same Data control are ignored (they would save, and validate, the same record again); Delete is allowed. A RecordSource that is a SELECT query is read-only, and edits made to its records are dropped when the current record changes.
See Data Binding for details
Type-Specific Properties
Property Type Description
@@ -2896,13 +3235,13 @@ End Sub
DBGrid
VB Equivalent: DBGrid -- DVX Widget: dbgrid | Name Prefix: DBGrid
-
A data-bound grid that displays records from a Data control in a tabular format. Columns auto-populate from the query results. Bind the grid using the DataSource property. Click a column header to sort; drag a column border to resize. Selecting a row moves the bound Data control's cursor to that row.
+
A data-bound grid that displays records from a Data control in a tabular format. Columns auto-populate from the query results. Bind the grid using the DataSource property. Click a column header to sort; drag a column border to resize. The highlighted row is always the bound Data control's current record: selecting a row moves the Data control's cursor, and navigating the Data control moves the highlight. Re-binding keeps the sort order and column settings, and a column width set by dragging a border is kept. Text wider than its column is clipped. The mouse wheel scrolls the rows without changing the current record.
Type-Specific Properties
Property Type Description
---------- ------- -------------------------------------------
DataSource String Name of the Data control that supplies records.
GridLines Boolean Show or hide grid lines between cells (default: True).
- SelectedRow Integer Index of the currently selected row (-1 = no selection).
+ SelectedRow Integer Index of the current record's row (-1 = no records). Setting it moves the Data control's cursor; negative values are ignored.
Type-Specific Methods
Method Parameters Description
---------------- ------------------------------- -------------------------------------------
@@ -2941,7 +3280,7 @@ End Sub
DropDown
DVX Extension -- DVX Widget: dropdown (non-editable drop-down list)
-
A read-only drop-down list. Unlike ComboBox, the user cannot type free text; they can only select from the provided items. Supports AddItem / RemoveItem / Clear / List. Use the arrow keys to navigate and Enter to commit when the list is open.
+
A read-only drop-down list. Unlike ComboBox, the user cannot type free text; they can only select from the provided items. Supports AddItem / RemoveItem / Clear / List. Use the Up and Down keys to change the choice. F4, Alt+Down, Space or Enter opens the list; in the open list use the arrow keys to move and Enter (or F4, Alt+Down) to pick. Esc closes the list without changing the choice.
Type-Specific Properties
Property Type Description
--------- ------- -------------------------------------------
@@ -2953,7 +3292,7 @@ End Sub
Clear Remove all items.
List(index%) Return the text of the item at the given index.
ListCount() Return the number of items in the list.
- RemoveItem index% Remove the item at the given index.
+ RemoveItem index% Remove the item at the given index. The selection stays on the same item; removing the selected item leaves no selection.
Default Event: Change (fires when the user picks a new item; Click fires only when the arrow opens the popup)
Example
Begin DropDown DropDown1
@@ -2979,7 +3318,7 @@ End Sub
Type-Specific Properties
Property Type Description
----------- ------- -------------------------------------------
- Picture String Path to an image file to load.
+ Picture String Path to an image file to load. Reads back the file the image came from. Setting it to "" clears the image. A file that cannot be loaded leaves the image and Picture unchanged.
ImageWidth Integer Width of the loaded image in pixels (read-only).
ImageHeight Integer Height of the loaded image in pixels (read-only).
No type-specific methods or events.
@@ -3006,8 +3345,8 @@ End Sub
Type-Specific Properties
Property Type Description
----------- ------- -------------------------------------------
- Picture String Path to an image file to load.
- Stretch Boolean When True, the image stretches to fill the widget; when False, shown at natural size.
+ Picture String Path to an image file to load. Reads back the file the image came from. Setting it to "" clears the image. A file that cannot be loaded leaves the image and Picture unchanged. A disabled Image is drawn grayed (its transparent color stays transparent).
+ Stretch Boolean When True, an image larger than the control is scaled down to fit, keeping its proportions; a smaller image stays at natural size. When False, the image is shown at natural size.
ImageWidth Integer Width of the loaded image in pixels (read-only).
ImageHeight Integer Height of the loaded image in pixels (read-only).
No type-specific methods or events.
@@ -3058,10 +3397,10 @@ End
IsItemSelected Index As Integer Returns True if the item at Index is selected.
List Index As Integer Return the text of the item at the given index.
ListCount (none) Return the number of items in the list.
- RemoveItem Index As Integer Remove the item at the given index.
+ RemoveItem Index As Integer Remove the item at the given index. Items after it keep their selection; removing the selected item leaves no selection.
SelectAll (none) Select all items (multi-select mode).
SetItemSelected Index As Integer, Selected As Boolean Select or deselect a specific item.
- SetItems Items As String Bulk-load items from a pipe-delimited string (e.g. "Red|Green|Blue"). Replaces existing items.
+ SetItems Items As String Bulk-load items from a pipe-delimited string (e.g. "Red|Green|Blue"). Replaces existing items. Every "|" separates two items ("a|" is "a" and an empty item); "" empties the list.
SetMultiSelect Multi As Boolean Enable or disable multi-select mode.
SetReorderable Reorderable As Boolean Enable or disable drag-to-reorder.
Default Event: Click
@@ -3099,7 +3438,7 @@ End Sub
ClearSelection Deselect all rows.
GetCell$(row%, col%) Returns the text of a cell.
IsItemSelected(index%) Returns True if the row is selected.
- RemoveItem index% Remove a row by index.
+ RemoveItem index% Remove a row by index. Rows after it keep their selection; removing the selected row leaves no selection.
RowCount() Returns the number of rows.
SelectAll Select all rows.
SetCell row%, col%, text$ Set the text of a cell.
@@ -3107,7 +3446,7 @@ End Sub
SetItemSelected index%, selected Select or deselect a row.
SetMultiSelect multi Enable or disable multi-select.
SetReorderable reorderable Enable or disable row reordering.
- SetSort col%, dir% Sort by column. dir: 0=none, 1=ascending, 2=descending.
+ SetSort col%, dir% Sort by column. dir: 0=none, 1=ascending, 2=descending. An invalid column or direction clears the sort. Has no effect while reordering is enabled.
Default Event: Click
Example
ListView1.SetColumns "Name,20|Size,10|Type,15"
@@ -3131,23 +3470,24 @@ ListView1.SetSort 0, 1