# The MIT License (MIT)
#
# Copyright (C) 2026 Scott Duensing
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

.topic ide.overview
.title DVX BASIC IDE Guide
.toc 0 Overview
.default
.index DVX BASIC
.index IDE
.index Visual Basic
.index Development Environment

.h1 DVX BASIC IDE Guide

DVX BASIC is a Visual BASIC development environment for DVX. It provides a VB3-style integrated development environment with a code editor, form designer, project system, and a full interactive debugger -- all integrated into DVX itself.

This guide covers every feature of the IDE: menus, toolbar, editor, form designer, project management, debugger, and auxiliary windows.

.h2 IDE Windows

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

.list
.item Main Toolbar Window -- anchored at the top of the screen. Contains the menu bar, toolbar buttons, and status bar.
.item Code Editor -- the primary editing surface for BASIC source code, with Object/Event dropdowns, syntax highlighting, and line numbers.
.item Form Designer -- a visual design surface for .frm files, showing a WYSIWYG preview of the form with grab handles for resizing controls.
.item Project Explorer -- a tree view listing all files in the project.
.item Toolbox -- a palette of available controls for placing on forms.
.item Properties Panel -- a tree of controls and a list of editable properties for the selected control.
.item Output Window -- displays PRINT output and runtime errors.
.item Immediate Window -- an interactive REPL for evaluating expressions and modifying variables at runtime.
.item Debug Windows -- Locals, Call Stack, Watch, and Breakpoints windows that appear automatically when debugging.
.endlist

The IDE compiles BASIC source into bytecode and runs it in an integrated virtual machine. Programs execute in cooperative slices, yielding to DVX between slices so the GUI remains responsive. Call DoEvents in long-running loops to keep the event loop flowing.

.link ide.menu.file File Menu
.link ide.menu.edit Edit Menu
.link ide.menu.run Run Menu
.link ide.menu.view View Menu
.link ide.menu.window Window Menu
.link ide.menu.tools Tools Menu
.link ide.menu.help Help Menu
.link ide.toolbar Toolbar
.link ide.editor Code Editor
.link ide.designer Form Designer
.link ide.project Project System
.link ide.properties Properties Panel
.link ide.toolbox Toolbox
.link ide.debugger Debugger
.link ide.debug.locals Locals Window
.link ide.debug.callstack Call Stack Window
.link ide.debug.watch Watch Window
.link ide.debug.breakpoints Breakpoints Window
.link ide.immediate Immediate Window
.link ide.output Output Window
.link ide.findreplace Find / Replace
.link ide.preferences Preferences
.link ide.shortcuts Keyboard Shortcuts

.topic ide.menu.file
.title File Menu
.toc 1 Menu Reference
.toc 2 File Menu
.index File Menu
.index New Project
.index Open Project
.index Save Project
.index Close Project
.index Project Properties
.index Add File
.index Save File
.index Save All
.index Remove File
.index Exit

.h1 File Menu

.table
  Menu Item              Shortcut   Description
  ---------              --------   -----------
  New Project...                    Create a new DVX BASIC project.
  Open Project...                   Open an existing .dbp project file.
  Save Project                      Save the current project file to disk.
  Close Project                     Close the current project (prompts to save unsaved changes).
  ---
  Project Properties...             Edit project metadata (name, author, version, startup form, icon, etc.).
  ---
  Add File...            Ctrl+O     Add a .bas or .frm file to the project. If no project is open, creates an implicit project from the file.
  Save File              Ctrl+S     Save the active file to disk.
  Save All                          Save all modified files in the project.
  ---
  Make Executable...                Compile the project and save it as a standalone .app file. Prompts for a debug or release build.
  ---
  Remove File                       Remove the selected file from the project (prompts to save if modified).
  ---
  Exit                              Close the IDE (prompts to save unsaved changes).
.endtable

.link ide.menu.edit Edit Menu
.link ide.overview Back to Overview

.topic ide.menu.edit
.title Edit Menu
.toc 2 Edit Menu
.index Edit Menu
.index Cut
.index Copy
.index Paste
.index Select All
.index Delete
.index Find
.index Find Next
.index Replace

.h1 Edit Menu

.table
  Menu Item    Shortcut   Description
  ---------    --------   -----------
  Cut          Ctrl+X     Cut selected text to the clipboard.
  Copy         Ctrl+C     Copy selected text to the clipboard.
  Paste        Ctrl+V     Paste text from the clipboard.
  ---
  Select All   Ctrl+A     Select all text in the active editor.
  ---
  Delete       Del        Delete the selected text or control (in the form designer).
  ---
  Find...      Ctrl+F     Open the Find/Replace dialog.
  Find Next    F3         Find the next occurrence of the search text.
  Replace...   Ctrl+H     Open the Find/Replace dialog with replace enabled.
.endtable

.link ide.menu.run Run Menu
.link ide.overview Back to Overview

.topic ide.menu.run
.title Run Menu
.toc 2 Run Menu
.index Run Menu
.index Run
.index Debug
.index Run Without Recompile
.index Stop
.index Step Into
.index Step Over
.index Step Out
.index Run to Cursor
.index Toggle Breakpoint
.index Clear Output
.index Save on Run

.h1 Run Menu

.table
  Menu Item                Shortcut         Description
  ---------                --------         -----------
  Run                      F5               Compile and run the program. If paused at a breakpoint, resumes execution with debugging disabled (runs free).
  Debug                    Shift+F5         Compile and run with the debugger active. Breakpoints are active but execution does not pause at the first statement. If paused, resumes to the next breakpoint.
  Run Without Recompile    Ctrl+F5          Re-run the last compiled module without recompiling.
  Stop                     Esc              Stop the running program immediately.
  ---
  Step Into                F8               Execute one statement, stepping into SUB/FUNCTION calls. If idle, starts a debug session and breaks at the first statement.
  Step Over                Shift+F8         Execute one statement, stepping over SUB/FUNCTION calls.
  Step Out                 Ctrl+Shift+F8    Run until the current SUB/FUNCTION returns.
  Run to Cursor            Ctrl+F8          Run until execution reaches the line where the cursor is positioned.
  ---
  Output Window to Log                      Checkbox: when enabled, PRINT output is also mirrored to the DVX log. Persisted in preferences.
  ---
  Toggle Breakpoint        F9               Toggle a breakpoint on the current editor line.
  ---
  Clear Output                              Clear the Output window.
  ---
  Save on Run                               Checkbox: when enabled, all modified files are saved automatically before compiling. Persisted in preferences.
.endtable

.link ide.menu.view View Menu
.link ide.overview Back to Overview

.topic ide.menu.view
.title View Menu
.toc 2 View Menu
.index View Menu
.index Code View
.index Design View
.index Toolbar Toggle
.index Status Bar Toggle
.index Menu Editor

.h1 View Menu

.table
  Menu Item        Shortcut   Description
  ---------        --------   -----------
  Code             F7         Switch to Code view for the active file (or the file selected in the Project Explorer).
  Designer         Shift+F7   Switch to Design view for the active form file.
  ---
  Toolbar                     Checkbox: show or hide the toolbar. Persisted in preferences.
  Status Bar                  Checkbox: show or hide the status bar. Persisted in preferences.
  ---
  Menu Editor...   Ctrl+E     Open the Menu Editor dialog for the active form. Allows designing menu bars with captions, names, levels, checked state, and enabled state.
.endtable

.link ide.menu.window Window Menu
.link ide.overview Back to Overview

.topic ide.menu.window
.title Window Menu
.toc 2 Window Menu
.index Window Menu

.h1 Window Menu

.table
  Menu Item          Description
  ---------          -----------
  Code Editor        Show or raise the Code Editor window.
  Output             Show or raise the Output window.
  Immediate          Show or raise the Immediate window.
  Locals             Show or raise the Locals debug window.
  Call Stack         Show or raise the Call Stack debug window.
  Watch              Show or raise the Watch debug window.
  Breakpoints        Show or raise the Breakpoints window.
  ---
  Project Explorer   Show or raise the Project Explorer window.
  Toolbox            Show or raise the Toolbox window.
  Properties         Show or raise the Properties panel.
.endtable

.link ide.menu.tools Tools Menu
.link ide.overview Back to Overview

.topic ide.menu.tools
.title Tools Menu
.toc 2 Tools Menu
.index Tools Menu
.index Preferences
.index Debug Layout

.h1 Tools Menu

.table
  Menu Item        Description
  ---------        -----------
  Preferences...   Open the Preferences dialog (editor settings and project defaults).
  ---
  Debug Layout     Checkbox: toggle a debug overlay that shows widget layout boundaries. Useful for diagnosing widget layout issues.
.endtable

.link ide.menu.help Help Menu
.link ide.overview Back to Overview

.topic ide.menu.help
.title Help Menu
.toc 2 Help Menu
.index Help Menu
.index About

.h1 Help Menu

.table
  Menu Item            Shortcut   Description
  ---------            --------   -----------
  DVX BASIC Help       F1         Open the DVX BASIC help (language reference, IDE guide, and control reference).
  DVX API Reference               Open the DVX developer API reference.
  ---
  About DVX BASIC...              Show the About dialog with version and copyright information.
.endtable

.link ide.overview Back to Overview

.topic ide.toolbar
.title Toolbar
.toc 1 Toolbar
.index Toolbar

.h1 Toolbar

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

.h2 File Group

.table
  Button   Shortcut   Action
  ------   --------   ------
  Open     Ctrl+O     Add a file to the project (same as File > Add File).
  Save     Ctrl+S     Save the active file.
.endtable

.h2 Run Group

.table
  Button   Shortcut   Action
  ------   --------   ------
  Run      F5         Compile and run the program.
  Stop     Esc        Stop the running program.
.endtable

.h2 Debug Group

.table
  Button          Shortcut         Action
  ------          --------         ------
  Debug           Shift+F5         Start or resume a debug session.
  Step Into       F8               Step into the next statement.
  Step Over       Shift+F8         Step over the next statement.
  Step Out        Ctrl+Shift+F8    Step out of the current procedure.
  Run to Cursor   Ctrl+F8          Run to the cursor position.
.endtable

.h2 View Group

.table
  Button   Shortcut   Action
  ------   --------   ------
  Code     F7         Switch to Code view.
  Design   Shift+F7   Switch to Design view.
.endtable

.link ide.overview Back to Overview

.topic ide.editor
.title Code Editor
.toc 1 Code Editor
.index Code Editor
.index Syntax Highlighting
.index Object Dropdown
.index Function Dropdown
.index Line Numbers
.index Auto-indent

.h1 Code Editor

The Code Editor is the primary editing window for BASIC source code. It occupies the center of the screen, below the toolbar and above the Output and Immediate windows.

.h2 Object and Function Dropdowns

At the top of the Code Editor are two dropdown lists:

.list
.item Object -- lists (General) plus all objects (form name, control names, menu item names). Selecting an object filters the Function dropdown.
.item 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.
.endlist

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.

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

.table
  Category          Examples
  --------          --------
  Default Text      Identifiers, whitespace.
  Keywords          IF, THEN, FOR, NEXT, SUB, FUNCTION, DIM, PRINT, SELECT, CASE, DO, LOOP, WHILE, WEND, END, EXIT, CALL, GOSUB, GOTO, RETURN, DECLARE, CONST, TYPE, AND, OR, NOT, XOR, MOD, etc.
  Types             INTEGER, LONG, SINGLE, DOUBLE, STRING, BOOLEAN, TRUE, FALSE
  Strings           "Hello, World!"
  Comments          ' This is a comment, REM This is a comment
  Numbers           42, 3.14, &HFF
  Operators         =, <, >, +, -, *, /, \, &
.endtable

.h2 Editor Features

.list
.item Line numbers -- displayed in the gutter on the left side.
.item Auto-indent -- new lines are automatically indented to match the previous line.
.item Tab handling -- the Tab key is captured by the editor. Tab width and whether to insert spaces or tab characters are configurable in Preferences (default: 3 spaces).
.item Gutter click -- clicking in the line number gutter toggles a breakpoint on that line.
.item Line decorations -- breakpoint lines show a red dot in the gutter. The current debug line (when paused) is highlighted with a yellow background.
.endlist

.link ide.overview Back to Overview

.topic ide.designer
.title Form Designer
.toc 1 Form Designer
.index Form Designer
.index Design Surface
.index Grid Snapping
.index Grab Handles
.index Control Placement
.index WYSIWYG

.h1 Form Designer

The Form Designer provides a visual design surface for editing .frm files. Switch to it with Shift+F7 or the Design toolbar button. It opens in a separate window showing a WYSIWYG preview of the form.

.h2 Design Surface

.list
.item Grid snapping -- controls snap to an 8-pixel grid when placed or resized.
.item Selection -- click a control to select it. The selected control is highlighted with grab handles.
.item 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.
.item Reordering -- drag a control vertically to reorder it within the form's layout (VBox/HBox).
.item 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).
.item Menu bar preview -- if the form has menu items (defined via the Menu Editor), a preview menu bar is rendered on the design window.
.item Delete key -- removes the selected control from the form.
.endlist

.h2 Form Properties

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

.link ide.properties Properties Panel
.link ide.toolbox Toolbox
.link ide.overview Back to Overview

.topic ide.project
.title Project System
.toc 1 Project System
.index Project System
.index Project Files
.index .dbp Files
.index Project Explorer
.index Source Map

.h1 Project System

.h2 Project Files (.dbp)

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

.list
.item Name -- the project display name (up to 32 characters).
.item Startup Form -- which form to show automatically when the program starts.
.item Metadata -- Author, Company, Version, Copyright, Description, and Icon Path (for compiled binaries).
.item File list -- relative paths of all .bas and .frm files in the project. Each entry tracks whether it is a form file.
.endlist

.h2 How Projects are Compiled

When the project is compiled, all source files are concatenated into a single source stream. The IDE tracks which lines belong to which file so error messages and debugger locations point to the correct .bas or .frm file. The code section of each .frm file is preceded by a hidden BEGINFORM marker that ties its code to its form.

.h2 Project Operations

.table
  Operation             Description
  ---------             -----------
  New Project           Creates a blank project with a name and directory. A default .frm file is added automatically.
  Open Project          Opens a .dbp file and loads all referenced files into memory.
  Save Project          Writes the .dbp file to disk.
  Close Project         Closes the project, prompting to save unsaved changes.
  Add File              Adds a .bas or .frm file to the project. Opening a file without a project auto-creates an implicit project.
  Remove File           Removes a file from the project (prompts to save if modified).
  Project Properties    Opens a dialog for editing project metadata (name, author, company, version, copyright, description, icon, startup form).
.endtable

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

.link ide.overview Back to Overview

.topic ide.properties
.title Properties Panel
.toc 1 Properties Panel
.index Properties Panel
.index Control Properties
.index Property List
.index Control Tree

.h1 Properties Panel

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

.list
.item Control tree -- a TreeView at the top listing the form and all its controls in layout order. Click a control name to select it in both the Properties panel and the Form Designer. Drag items in the tree to reorder controls in the form's layout.
.item Property list -- a two-column ListView below the tree showing property names and values for the selected control. Double-click a property value to edit it via an InputBox dialog. Changes take effect immediately in the designer preview.
.endlist

Each control type exposes different properties (e.g., Caption, Text, Width, Height, MaxWidth, MaxHeight, Weight, Alignment, Enabled, Visible, and type-specific properties like DataSource and DataField for data-bound controls).

.link ide.designer Form Designer
.link ide.overview Back to Overview

.topic ide.toolbox
.title Toolbox
.toc 1 Toolbox
.index Toolbox
.index Controls
.index Widget Palette

.h1 Toolbox

The Toolbox (Window > Toolbox) is a floating palette of buttons, one for each available control type. Every widget registered with DVX that has a BASIC name appears in the toolbox.

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

.h2 Available Controls

.table
  VB Name         Description
  -------         -----------
  CommandButton   Push button that triggers a Click event.
  Label           Static text label.
  TextBox         Single-line text input field.
  TextArea        Multi-line text editor.
  CheckBox        On/off checkbox.
  OptionButton    Radio button (mutually exclusive within a group).
  ListBox         Scrollable list of items.
  ComboBox        Drop-down combo box.
  DropDown        Simple drop-down list.
  PictureBox      Canvas for drawing and images.
  Image           Static image display.
  ImageButton     Clickable image button.
  Frame           Grouping container with a labeled border.
  VBox            Vertical layout container.
  HBox            Horizontal layout container.
  WrapBox         Flow layout container that wraps items to the next row.
  Splitter        Resizable split between two child panes.
  ScrollPane      Scrollable container for large content.
  TabStrip        Tabbed container with multiple pages.
  ListView        Multi-column list with headers.
  TreeView        Hierarchical tree control.
  ProgressBar     Progress indicator bar.
  HScrollBar      Horizontal slider/scrollbar.
  SpinButton      Numeric up/down spinner.
  Line            Horizontal or vertical separator line.
  Spacer          Invisible spacing element for layout.
  Timer           Non-visual timer that fires periodic events.
  Toolbar         Toolbar container for buttons.
  StatusBar       Status bar at the bottom of a form.
  Terminal        ANSI terminal emulator control.
  Data            Data control for binding to a database.
  DBGrid          Data-bound grid for displaying database query results.
.endtable

.link ide.designer Form Designer
.link ide.overview Back to Overview

.topic ide.debugger
.title Debugger
.toc 1 Debugger
.index Debugger
.index Breakpoints
.index Stepping
.index Debug Mode

.h1 Debugger

The DVX BASIC IDE includes a full interactive debugger. The debugger has three states:

.table
  State       Description
  -----       -----------
  Idle        No program loaded or running.
  Running     The program is executing.
  Paused      Execution is paused at a breakpoint or step point. The IDE is fully interactive -- you can inspect and change variables, set or clear breakpoints, step, continue, or stop.
.endtable

.h2 Starting a Debug Session

.list
.item Shift+F5 (Debug) -- compiles the project and starts execution in debug mode. Breakpoints are active but execution does not pause at the first statement.
.item F8 (Step Into) -- if idle, starts a debug session and breaks at the first statement.
.item F5 (Run) -- compiles and runs without the debugger. No breakpoints are active. If already paused, resumes execution with debugging disabled.
.endlist

.h2 Breakpoints

.h3 Setting Breakpoints

.list
.item Press F9 to toggle a breakpoint on the current editor line.
.item Click in the line number gutter to toggle a breakpoint on that line.
.endlist

.h3 Breakpoint Validation

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

.list
.item Blank lines
.item Comment lines (' or REM)
.item SUB and FUNCTION declaration lines
.item END SUB and END FUNCTION lines
.endlist

.h3 Breakpoint Storage

Each breakpoint records the file it belongs to, the line number within that file, and the procedure name (Object.Event). Breakpoints are stored in the project and survive compilation.

.h3 Visual Indicators

.list
.item Breakpoint lines show a red dot in the gutter.
.item The current debug line (when paused) has a yellow background.
.endlist

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

.h2 Stepping

.table
  Action          Shortcut         Behavior
  ------          --------         --------
  Step Into       F8               Execute one statement. If the statement is a SUB/FUNCTION call, step into it.
  Step Over       Shift+F8         Execute one statement. If the statement is a SUB/FUNCTION call, execute the entire call and break at the next line in the current scope.
  Step Out        Ctrl+Shift+F8    Run until the current SUB/FUNCTION returns to its caller.
  Run to Cursor   Ctrl+F8          Run until execution reaches the line under the cursor.
.endtable

.h2 Debug Run Behavior

When a program is running under the debugger:

.list
.item The program runs in short cooperative slices so the IDE remains responsive.
.item 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.
.item 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.
.item Resuming (F5, Shift+F5, or any Step command) returns the program to Running state.
.endlist

.h2 Stopping

Press Esc or click the Stop toolbar button at any time to halt execution. The program is terminated, the debugger returns to Idle, and the IDE restores any designer or code windows that were hidden at the start of the run.

.link ide.debug.locals Locals Window
.link ide.debug.callstack Call Stack Window
.link ide.debug.watch Watch Window
.link ide.debug.breakpoints Breakpoints Window
.link ide.overview Back to Overview

.topic ide.debug.locals
.title Locals Window
.toc 1 Debug Windows
.toc 2 Locals Window
.index Locals Window
.index Variable Inspection

.h1 Locals Window

When the debugger pauses, the Locals and Call Stack windows are auto-opened (if not already visible). The Watch and Breakpoints windows can be opened manually from the Window menu.

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

.table
  Column   Content
  ------   -------
  Name     Variable name (internal mangled names like static variable placeholders are filtered out).
  Type     Data type: Integer, Long, Single, Double, String, Boolean, Array, UDT. Array types show the element type (e.g., Integer()).
  Value    Current value. Strings are shown in quotes. Booleans as True/False. Arrays show bounds and element count (e.g., Integer(0 To 9) [10]). Uninitialized arrays show (uninitialized).
.endtable

The Locals window displays:

.list
.item Local variables for the current procedure (matched by proc index).
.item Global (module-level) variables.
.item Form-scoped variables for the current form (if the program is executing within a form context).
.endlist

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

.link ide.debug.callstack Call Stack Window
.link ide.overview Back to Overview

.topic ide.debug.callstack
.title Call Stack Window
.toc 2 Call Stack Window
.index Call Stack
.index Stack Trace

.h1 Call Stack Window

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

.table
  Column      Content
  ------      -------
  Procedure   Procedure name (or (module) for module-level code).
  Line        Line number where execution is paused (shown for the topmost frame).
.endtable

The current location is shown first, followed by each caller in the call stack (walking from the deepest frame back to the module entry point). Up to 32 frames are displayed.

.link ide.debug.watch Watch Window
.link ide.overview Back to Overview

.topic ide.debug.watch
.title Watch Window
.toc 2 Watch Window
.index Watch Window
.index Watch Expressions

.h1 Watch Window

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

.table
  Column       Content
  ------       -------
  Expression   The watch expression text.
  Value        Evaluated result (or <error> if evaluation fails). Blank when not paused.
.endtable

.h2 Adding Watch Expressions

Type an expression in the text input and press Enter. Up to 16 watch expressions can be active at once.

.h2 Watch Expression Syntax

Watch expressions support:

.list
.item Simple variable names: x, count
.item Array subscripts: arr(5), matrix(2, 3)
.item UDT field access: player.name
.item Combined: items(i).price
.item Arbitrary BASIC expressions (compiled and evaluated against the paused VM's state): x + y * 2, Len(name$)
.endlist

.h2 Editing and Deleting

.list
.item Double-click or press Enter on a watch entry to move it back into the input box for editing.
.item Press Delete to remove the selected watch expression.
.endlist

.link ide.debug.breakpoints Breakpoints Window
.link ide.overview Back to Overview

.topic ide.debug.breakpoints
.title Breakpoints Window
.toc 2 Breakpoints Window
.index Breakpoints Window

.h1 Breakpoints Window

Lists all set breakpoints as a three-column ListView:

.table
  Column      Content
  ------      -------
  File        Project file path.
  Procedure   Procedure name (Object.Event format, or (General)).
  Line        Code line number within the file.
.endtable

.list
.item Double-click a breakpoint to navigate the code editor to that location.
.item Press Delete to remove selected breakpoints (multi-select is supported).
.endlist

.link ide.debugger Debugger
.link ide.overview Back to Overview

.topic ide.immediate
.title Immediate Window
.toc 1 Immediate Window
.index Immediate Window
.index REPL
.index Expression Evaluation
.index Variable Assignment

.h1 Immediate Window

The Immediate window is an interactive REPL at the bottom-right of the screen. Type a line of BASIC and press Enter to evaluate it. Results appear inline below your input.

.h2 Expression Evaluation

If the input is not a recognized statement keyword, it is automatically wrapped in a PRINT statement. For example, typing 2 + 2 evaluates as PRINT 2 + 2 and displays 4.

You can also type full statements:

.list
.item PRINT x * 2 -- evaluate and print an expression.
.item DIM tmp As Integer -- declare a temporary variable.
.item LET x = 42 -- explicit assignment (see below).
.endlist

Parse or runtime errors are displayed inline with an Error: prefix.

.h2 Inspecting Variables While Paused

When the debugger is paused at a breakpoint, the Immediate window has access to the running program's state. Expressions like count or name$ & " test" display live values.

.h2 Assigning Variables While Paused

When paused, you can modify variables in the running program directly from the Immediate window using assignment syntax:

.code
variableName = newValue
.endcode

The optional LET keyword is also accepted:

.code
LET variableName = newValue
.endcode

Assignment works for:

.list
.item Scalar variables -- x = 42, name$ = "test"
.item Array elements -- arr(5) = 100, matrix(2, 3) = 7.5
.item UDT fields -- player.score = 1000
.item Combined -- items(0).price = 9.99
.endlist

The new value is written directly into the running program's variable (local, global, or form scope). A confirmation message is displayed, and the Locals and Watch windows update automatically to reflect the change.

If the assignment target cannot be resolved (unknown variable, out-of-bounds index, wrong type), an error message is displayed.

.link ide.overview Back to Overview

.topic ide.output
.title Output Window
.toc 1 Output Window
.index Output Window
.index PRINT Output
.index Runtime Errors
.index Compile Errors

.h1 Output Window

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

.list
.item PRINT output -- all PRINT statement output from the running program is appended here.
.item Runtime errors -- if the VM encounters a runtime error (division by zero, out-of-bounds, etc.), the error message and line number are displayed in the output with an Error on line N: prefix.
.item Compile errors -- if compilation fails, the error message and location are shown.
.endlist

The output buffer holds up to 32,768 characters. Use Run > Clear Output to clear it.

INPUT statements prompt the user via a modal InputBox dialog; the prompt text is also echoed to the Output window.

.link ide.overview Back to Overview

.topic ide.findreplace
.title Find / Replace
.toc 1 Find / Replace
.index Find
.index Replace
.index Find Next
.index Search

.h1 Find / Replace

Open with Ctrl+F (Find) or Ctrl+H (Replace). The Find/Replace dialog is modeless -- it stays open while you continue editing.

.h2 Dialog Controls

.table
  Control                    Description
  -------                    -----------
  Find input                 The text to search for.
  Replace checkbox + input   Enable replacement mode and enter replacement text.
  Scope                      Radio group: Function, Object, File, or Project. Default is Project.
  Direction                  Radio group: Forward or Backward.
  Match Case                 Checkbox: case-sensitive search.
.endtable

.h2 Buttons

.table
  Button        Action
  ------        ------
  Find Next     Find the next occurrence. Wraps across procedures, files, and the entire project depending on the scope setting.
  Replace       Replace the current match and find the next one.
  Replace All   Replace all occurrences within the selected scope.
  Close         Close the dialog.
.endtable

.h2 Keyboard Shortcut

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

.link ide.overview Back to Overview

.topic ide.preferences
.title Preferences
.toc 1 Preferences
.index Preferences
.index Settings
.index Tab Width
.index Option Explicit

.h1 Preferences

Open via Tools > Preferences. Settings are saved to dvxbasic.ini in the app's config directory. The dialog has two tabs.

.h2 General Tab

.h3 Editor Section

.table
  Setting                                          Description                                                                           Default
  -------                                          -----------                                                                           -------
  Skip comments/strings when renaming              When renaming a control or form, skip occurrences inside comments and string literals.  On
  Require variable declaration (OPTION EXPLICIT)   When enabled, newly created projects have OPTION EXPLICIT on by default.                Off
  Tab width                                        Number of spaces per tab stop.                                                         3
  Insert spaces instead of tabs                    When enabled, pressing Tab inserts spaces. When disabled, inserts a real tab character. On
.endtable

.h3 New Project Defaults Section

These fields set the default values for new project metadata:

.table
  Field         Description                                   Default
  -----         -----------                                   -------
  Author        Default author name.                          (empty)
  Publisher     Default publisher/company name.               (empty)
  Version       Default version string.                       1.0
  Copyright     Default copyright notice.                     (empty)
  Description   Default project description (multi-line).     (empty)
.endtable

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

.link ide.overview Back to Overview

.topic ide.shortcuts
.title Keyboard Shortcuts
.toc 1 Keyboard Shortcuts
.index Keyboard Shortcuts
.index Hotkeys
.index Accelerators

.h1 Keyboard Shortcuts

.table
  Shortcut         Action
  --------         ------
  Ctrl+O           Add File
  Ctrl+S           Save File
  Ctrl+A           Select All
  Ctrl+X           Cut
  Ctrl+C           Copy
  Ctrl+V           Paste
  Ctrl+F           Find
  Ctrl+H           Replace
  Ctrl+E           Menu Editor
  F1               DVX BASIC Help
  F3               Find Next
  F5               Run
  Shift+F5         Debug
  Ctrl+F5          Run Without Recompile
  Esc              Stop
  F7               Code View
  Shift+F7         Design View
  F8               Step Into
  Shift+F8         Step Over
  Ctrl+Shift+F8    Step Out
  Ctrl+F8          Run to Cursor
  F9               Toggle Breakpoint
  Del              Delete
.endtable

.hr

DVX BASIC 1.0 -- Copyright 2026 Scott Duensing
