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

## IDE Windows

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

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

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.

File Menu

Edit Menu

Run Menu

View Menu

Window Menu

Tools Menu

Help Menu

Toolbar

Code Editor

Form Designer

Project System

Properties Panel

Toolbox

Debugger

Locals Window

Call Stack Window

Watch Window

Breakpoints Window

Immediate Window

Output Window

Find / Replace

Preferences

Keyboard Shortcuts

# File Menu

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

Edit Menu

Back to Overview

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

Run Menu

Back to Overview

# Run Menu

      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.

View Menu

Back to Overview

# View Menu

      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.

Window Menu

Back to Overview

# Window Menu

      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.

Tools Menu

Back to Overview

# Tools Menu

      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.

Help Menu

Back to Overview

# Help Menu

      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.

Back to Overview

# Toolbar

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

## File Group

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

## Run Group

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

## Debug Group

      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.

## View Group

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

Back to Overview

# Code Editor

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

## Object and Function Dropdowns

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

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

## 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
      --------          --------
      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         =, <, >, +, -, *, /, \, &

## Editor Features

- Line numbers -- displayed in the gutter on the left side.
- Auto-indent -- new lines are automatically indented to match the previous line.
- 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).
- Gutter click -- clicking in the line number gutter toggles a breakpoint on that line.
- Line decorations -- breakpoint lines show a red dot in the gutter. The current debug line (when paused) is highlighted with a yellow background.

Back to Overview

# Form Designer

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

## Design Surface

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

## Form Properties

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

Properties Panel

Toolbox

Back to Overview

# Project System

## Project Files (.dbp)

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

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

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.

## Compile-Time Validation

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

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

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

# Properties Panel

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

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

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

Form Designer

Back to Overview

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

## Available Controls

      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.

Form Designer

Back to Overview

# Debugger

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

      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.

## Starting a Debug Session

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

## Breakpoints

### Setting Breakpoints

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

### Breakpoint Validation

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

- Blank lines
- Comment lines (' or REM)
- SUB and FUNCTION declaration lines
- END SUB and END FUNCTION lines

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

### Visual Indicators

- Breakpoint lines show a red dot in the gutter.
- 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.

## Stepping

      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.

## Debug Run Behavior

When a program is running under the debugger:

- 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.
- Resuming (F5, Shift+F5, or any Step command) returns the program to Running state.

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

Locals Window

Call Stack Window

Watch Window

Breakpoints Window

Back to Overview

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

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

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

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

Call Stack Window

Back to Overview

# Call Stack Window

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

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

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

Watch Window

Back to Overview

# Watch Window

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

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

## Adding Watch Expressions

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

## Watch Expression Syntax

Watch expressions support:

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

## Editing and Deleting

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

Breakpoints Window

Back to Overview

# Breakpoints Window

Lists all set breakpoints as a three-column ListView:

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

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

Debugger

Back to Overview

# Immediate Window

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

## Expression Evaluation

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

You can also type full statements:

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

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

## Inspecting Variables While Paused

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

## Assigning Variables While Paused

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

    variableName = newValue

The optional LET keyword is also accepted:

    LET variableName = newValue

Assignment works for:

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

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.

Back to Overview

# Output Window

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

- PRINT output -- all PRINT statement output from the running program is appended here.
- 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.
- Compile errors -- if compilation fails, the error message and location are shown.

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.

Back to Overview

# Find / Replace

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

## Dialog Controls

      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.

## Buttons

      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.

## Keyboard Shortcut

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

Back to Overview

# Preferences

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

## General Tab

### Editor Section

      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

### New Project Defaults Section

These fields set the default values for new project metadata:

      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)

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

# Keyboard Shortcuts

      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

DVX BASIC 1.0 -- Copyright 2026 Scott Duensing

# Data Types

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

## Primary Types

      Type       Size       Suffix   Range / Description
      ----       ----       ------   -------------------
      Integer    2 bytes    %        -32768 to 32767
      Long       4 bytes    &        -2147483648 to 2147483647
      Single     4 bytes    !        32-bit float, approximately 7 digits precision
      Double     8 bytes    #        64-bit float, approximately 15 digits precision
      String     variable   $        Variable-length, reference-counted, dynamic string
      Boolean    2 bytes    (none)   True (-1) or False (0)

## Internal Types

These types are not directly declarable but are used internally by the runtime.

      Internal Type   Description
      -------------   -----------
      Array           Reference-counted multi-dimensional array (up to 8 dimensions)
      UDT             User-defined type instance (created with TYPE...END TYPE)
      Object          Opaque host object (form reference, control reference)
      Ref             ByRef pointer to a variable slot (used for ByRef parameters)

## Type Suffixes

Type suffixes can be appended to variable names to declare their type implicitly:

    count%  = 42         ' Integer
    total&  = 100000     ' Long
    rate!   = 3.14       ' Single
    pi#     = 3.14159265 ' Double
    name$   = "Hello"    ' String

## Numeric Literals

      Form               Example                Description
      ----               -------                -----------
      Decimal integer    42                     Values -32768..32767 are Integer; larger are Long
      Hex integer        &HFF, &H1234           Hexadecimal literal (0-9, A-F)
      Octal integer      &O10, &O77             Octal literal (0-7)
      Binary integer     &B1010, &B11111111     Binary literal (0-1)
      Integer suffix     42%                    Force Integer type
      Long suffix        42&, &HFF&             Force Long type
      Floating-point     3.14, 1.5E10, 2.5D3    Any number containing a decimal point or exponent is Double by default
      Single suffix      3.14!                  Force Single type
      Double suffix      3.14#                  Force Double type

> Note: Both E and D can introduce an exponent (e.g. 1.5E10 and 2.5D3 are equivalent forms of a scientific-notation double).

## 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$).

## Assignment Conversion

Storing a value into a variable declared as Integer, Long or Single (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. A variable with no declared type keeps whatever type the assigned value has.

    Dim n As Integer
    n = 3.7            ' n is 4
    n = 40000          ' Error 6: Overflow
    x = 3.7            ' x has no declared type and keeps 3.7

## Boolean Values

Boolean values use -1 for True and 0 for False. Any non-zero numeric value is treated as True in a conditional context. The keywords True and False are reserved and may be used anywhere a Boolean value is expected.

See also: Conversion Functions

# Operators

Operators listed from highest precedence (evaluated first) to lowest precedence (evaluated last). Parentheses override precedence and may be nested freely.

      Precedence     Operator                  Description
      ----------     --------                  -----------
      1 (highest)    ^                         Exponentiation
      2              - (unary), + (unary)      Negation (unary plus is a no-op)
      3              *  /                      Multiply, float divide
      4              \                         Integer divide
      5              MOD                       Modulus
      6              +  -                      Addition, subtraction (+ also concatenates strings)
      7              &                         String concatenation
      8              =  <>  <  >  <=  >=       Comparison (returns Boolean)
      9              NOT                       Logical/bitwise NOT
      10             AND                       Logical/bitwise AND
      11             XOR                       Logical/bitwise exclusive-or
      12             OR                        Logical/bitwise OR
      13             EQV                       Logical/bitwise equivalence
      14 (lowest)    IMP                       Logical/bitwise implication

## Arithmetic Operators

      Operator   Description
      --------   -----------
      +          Addition (or string concatenation when both operands are strings)
      -          Subtraction (or negation when used as a unary prefix)
      *          Multiplication
      /          Floating-point division (result is always Single or Double)
      \          Integer division (result is Long, fractional part discarded)
      MOD        Integer modulus (remainder)
      ^          Exponentiation (result is Double)

## Comparison Operators

Comparison operators return True (-1) or False (0).

      Operator   Description
      --------   -----------
      =          Equal to
      <>         Not equal to
      <          Less than
      >          Greater than
      <=         Less than or equal to
      >=         Greater than or equal to

String comparisons are controlled by OPTION COMPARE. With OPTION COMPARE BINARY (the default) strings are compared by byte value. With OPTION COMPARE TEXT comparisons are case-insensitive.

## Logical / Bitwise Operators

The logical operators work on Boolean values and also perform bitwise operations on integer values.

      Operator   Description
      --------   -----------
      NOT        Logical/bitwise complement
      AND        Logical/bitwise AND
      OR         Logical/bitwise OR
      XOR        Logical/bitwise exclusive-or
      EQV        Logical/bitwise equivalence (same as NOT (a XOR b))
      IMP        Logical/bitwise implication (same as (NOT a) OR b)

## String Concatenation

Use & to concatenate strings. The + operator also concatenates when both operands are strings. Prefer & because it does not depend on operand types.

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

    ' + also concatenates when both operands are strings
    greeting$ = "Hi " + name$

# Statements

Multiple statements can appear on one line separated by : (colon). A line can be continued onto the next physical line by ending it with an underscore (_) preceded by whitespace. Comments start with ' (apostrophe) or the REM keyword and run to the end of the line. The character ? is a shorthand for PRINT.

    a = 10 : b = 20 : c = a + b        ' three statements on one line

    total = price * quantity _
          + shipping + tax              ' one statement continued across lines

    REM This is a comment
    ' So is this
    ? "Hello"                           ' same as PRINT "Hello"

Declaration Statements (DIM, REDIM, CONST, TYPE, DECLARE)

Conditional Statements (IF, SELECT CASE)

Loop Statements (FOR, DO, WHILE)

Procedures (SUB, FUNCTION, DEF FN)

Flow Control (EXIT, CALL, GOTO, GOSUB, ON)

Input/Output (PRINT, INPUT, DATA/READ)

Miscellaneous Statements (ON ERROR, SHELL, SLEEP, END)

# Declaration Statements

## DIM

Declares variables and arrays with an explicit type. If no type is given, the type defaults to whatever DEFtype (if any) is in effect for the variable's first letter; without a DEFtype statement the default is Single.

    DIM variable AS type
    DIM variable(upperBound) AS type
    DIM variable(lower TO upper) AS type
    DIM variable(dim1, dim2, ...) AS type
    DIM variable AS UdtName
    DIM variable AS STRING * n
    DIM SHARED variable AS type

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

Examples:

    Dim name As String
    Dim count As Integer
    Dim values(100) As Double
    Dim matrix(1 To 10, 1 To 10) As Single
    Dim Shared globalFlag As Boolean
    Dim record As PersonType
    Dim fixedStr As String * 20

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

Fixed-length strings (STRING * n) are padded with spaces and truncated when assigned so their length is always exactly n.

## REDIM

Reallocates a dynamic array, optionally preserving existing data.

    REDIM array(newBounds) AS type
    REDIM PRESERVE array(newBounds) AS type

    ReDim items(newSize) As String
    ReDim Preserve scores(1 To newCount) As Integer

## CONST

Declares a named constant. The value must be a literal (integer, long, float, string, or boolean). Constants are not variables -- you cannot assign a new value to them or pass them by reference.

    CONST name = value
    CONST name AS type = value

    Const MAX_SIZE = 100
    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.

## TYPE...END TYPE

Defines a user-defined type (record/structure).

    TYPE TypeName
        fieldName AS type
        ...
    END TYPE

    Type PersonType
        firstName As String
        lastName  As String
        age       As Integer
    End Type

    Dim p As PersonType
    p.firstName = "Scott"
    p.age = 30

UDT fields can themselves be UDTs (nested types).

## DECLARE

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

## 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"
        DECLARE SUB name ([BYVAL] param AS type, ...)
        DECLARE FUNCTION name ([BYVAL] param AS type, ...) AS returnType
    END DECLARE

    Declare Library "basrt"
        Declare Function SQLOpen(ByVal path As String) As Integer
        Declare Sub SQLClose(ByVal db As Integer)
    End Declare

See also: BASIC Runtime Libraries

## STATIC

Declares a local variable that retains its value between calls.

    STATIC variable AS type

    Sub Counter()
        Static count As Integer
        count = count + 1
        Print count
    End Sub

## OPTION

Sets compiler options. Must appear before any executable code.

    OPTION BASE 0          ' Arrays start at index 0 (default)
    OPTION BASE 1          ' Arrays start at index 1
    OPTION COMPARE BINARY  ' Case-sensitive string comparisons (default)
    OPTION COMPARE TEXT    ' Case-insensitive string comparisons
    OPTION EXPLICIT        ' All variables must be declared with DIM

## DEFtype Statements

Set the default type for variables based on their first letter.

    DEFINT letterRange
    DEFLNG letterRange
    DEFSNG letterRange
    DEFDBL letterRange
    DEFSTR letterRange

    DefInt I-N     ' Variables starting with I through N default to Integer
    DefStr S       ' Variables starting with S default to String

## Assignment

Assigns a value to a variable, array element, or UDT field.

    variable = expression
    array(index) = expression
    udt.field = expression
    LET variable = expression

The LET keyword is optional and supported for compatibility.

## SWAP

Exchanges the values of two variables. The variables must be the same type.

    SWAP variable1, variable2

    Swap a, b

## SET

Assigns an object reference (form or control) to a variable. Required when creating a form or control with CreateForm / CreateControl so that the returned reference is stored in the variable:

    SET variable = objectExpression

    Dim frm As Long
    Set frm = CreateForm("MyForm", 320, 240)
    frm.Caption = "Built in code"

For ordinary numeric or string assignment, SET is not used.

## ERASE

Frees the memory of a dynamic array and resets it to undimensioned state. Fixed-size arrays (declared with constant bounds) reset their elements but keep their shape.

    ERASE arrayName

# Conditional Statements

## IF...THEN...ELSE...END IF

Conditional execution. Supports single-line and multi-line forms.

### Single-line form

    IF condition THEN statement
    IF condition THEN statement ELSE statement

### Multi-line form

    IF condition THEN
        statements
    ELSEIF condition THEN
        statements
    ELSE
        statements
    END IF

    If x > 10 Then
        Print "Large"
    ElseIf x > 5 Then
        Print "Medium"
    Else
        Print "Small"
    End If

    If ready Then Print "Go!"

## SELECT CASE

Multi-way branch based on an expression value.

    SELECT CASE expression
        CASE value
            statements
        CASE value1, value2
            statements
        CASE low TO high
            statements
        CASE IS operator value
            statements
        CASE ELSE
            statements
    END SELECT

    Select Case grade
        Case 90 To 100
            Print "A"
        Case 80 To 89
            Print "B"
        Case Is >= 70
            Print "C"
        Case 60, 65
            Print "D (borderline)"
        Case Else
            Print "F"
    End Select

CASE items can be combined with commas. The IS keyword allows comparison operators: <, >, <=, >=, =, <>.

# Loop Statements

## FOR...NEXT

Counted loop with an optional step value.

    FOR variable = start TO limit [STEP step]
        statements
    NEXT [variable]

    For i = 1 To 10
        Print i
    Next i

    For x = 10 To 0 Step -2
        Print x
    Next

The variable name after NEXT is optional. Use EXIT FOR to break out early.

## DO...LOOP

General-purpose loop with pre-test, post-test, or infinite forms.

    DO [WHILE condition | UNTIL condition]
        statements
    LOOP [WHILE condition | UNTIL condition]

    ' Pre-test
    Do While count < 10
        count = count + 1
    Loop

    ' Post-test
    Do
        line$ = ReadLine()
    Loop Until line$ = "quit"

    ' Infinite loop (exit with EXIT DO)
    Do
        DoEvents
        If done Then Exit Do
    Loop

## WHILE...WEND

Simple pre-test loop (legacy form; prefer DO...LOOP).

    WHILE condition
        statements
    WEND

    While Not EOF(1)
        Line Input #1, line$
        Print line$
    Wend

# Procedures

## SUB...END SUB

Defines a subroutine (no return value).

    SUB name ([BYVAL] [OPTIONAL] param AS type, ...)
        statements
    END SUB

    Sub Greet(ByVal name As String)
        Print "Hello, " & name
    End Sub

Parameters are passed by reference by default. Use ByVal for value semantics; there is no separate ByRef keyword (omitting ByVal is the by-reference form). 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. 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")

### Optional Parameters

Mark a parameter OPTIONAL to allow callers to omit it. An optional parameter must be positioned after all required parameters and receives an empty/zero default when not supplied.

    Sub Announce(ByVal msg As String, Optional ByVal loud As Integer)
        If loud Then
            Print UCase$(msg)
        Else
            Print msg
        End If
    End Sub

    Announce "hello"            ' loud defaults to 0
    Announce "hello", True      ' loud is -1

## FUNCTION...END FUNCTION

Defines a function with a return value.

    FUNCTION name ([BYVAL] [OPTIONAL] param AS type, ...) AS returnType
        statements
        name = returnValue
    END FUNCTION

    Function Square(ByVal n As Double) As Double
        Square = n * n
    End Function

Assign to the function name to set the return value. Use EXIT FUNCTION to return early.

## DEF FN

Defines a single-expression function. The function name begins with FN and is invoked just like a normal function. DEF FN functions cannot span multiple statements.

    DEF FNname(params) = expression

    Def FnSquare(x) = x * x
    Print FnSquare(5)     ' prints 25

    Def FnCelsius(f As Double) = (f - 32) * 5 / 9
    Print FnCelsius(212)  ' prints 100

# Flow Control

## EXIT

Exits the current block early.

    EXIT FOR
    EXIT DO
    EXIT SUB
    EXIT FUNCTION

## CALL

Explicitly calls a subroutine or function. The return value (if any) is discarded.

    CALL name
    CALL name(args)

Normally you can omit CALL and just use the name directly.

## GOTO / GOSUB / RETURN

    GOTO label
    GOSUB label
    RETURN

GOSUB pushes the return address, executes code at the label, and RETURN jumps back. At module level, RETURN returns from a GOSUB. Inside a SUB/FUNCTION, RETURN returns from the procedure.

    GoSub Initialize
    Print "Done"
    End

    Initialize:
        count = 0
        name$ = ""
    Return

## ON...GOTO / ON...GOSUB

Computed branch based on an integer expression.

    ON expression GOTO label1, label2, ...
    ON expression GOSUB label1, label2, ...

If the expression evaluates to 1, control goes to the first label; 2, the second; and so on. If out of range, execution falls through.

# Input/Output Statements

## PRINT

Writes expressions to the output window (or to a file channel).

    PRINT [expression [{; | ,} expression] ...]
    PRINT #channel, expression [; expression] ...
    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
- ? is an alias for PRINT

Special functions inside PRINT:

- SPC(n) -- print n spaces
- TAB(n) -- advance to column n (first column is 1)

    Print "Name:"; Tab(20); name$
    Print "X="; x, "Y="; y        ' comma = next 14-column zone
    Print #1, "Written to file"

### PRINT USING

PRINT USING formats each following expression according to a format string and prints the result. If more expressions are supplied than the format string consumes, the format string is reused from the start for each.

      Format character   Meaning
      ----------------   -------
      #                  Digit (replaced with a digit or space to pad on the left)
      .                  Decimal-point position
      ,                  Insert thousands separator
      +                  At start or end: always show a sign character
      -                  At end: show a trailing minus sign only when negative
      **                 At start: fill leading spaces with asterisks
      $$                 At start: floating dollar sign
      ^^^^               Anywhere: format the value in scientific notation
      !                  First character of a string only
      &                  Entire string (variable length)
      \ ... \            Fixed-length string field (width = 2 + number of spaces between backslashes)

    Print Using "###.##"; 3.14159             ' "  3.14"
    Print Using "$$#,##0.00"; 1234567.89      ' "$1,234,567.89"
    Print Using "**#,##0.00"; 42.5            ' "*****42.50"
    Print Using "####.####^^^^"; 0.000123     ' scientific notation
    Print Using "\  \"; "Hello"               ' fixed-width 4-char: "Hell"
    Print Using "& likes &"; name$; food$

## INPUT

Reads a line of text from the user or from a file channel.

    INPUT variable
    INPUT "prompt"; variable
    INPUT #channel, variable

    Input "Enter your name: "; name$
    Input #1, line$

## DATA / READ / RESTORE

Inline data pool for constants.

    DATA value1, value2, "string", ...
    READ variable1, variable2, ...
    RESTORE

DATA statements define a pool of values. READ reads the next value from the pool into a variable. RESTORE resets the read pointer to the beginning.

    Data 10, 20, 30, "Hello"
    Read a, b, c, msg$
    Print a; b; c; msg$
    Restore

# Miscellaneous Statements

## Error Handling

    ON ERROR GOTO label     ' Enable error handler
    ON ERROR GOTO 0         ' Disable error handler
    RESUME                  ' Retry the statement that caused the error
    RESUME NEXT             ' Continue at the next statement after the error
    ERROR n                 ' Raise a runtime error with error number n

The ERR keyword returns the current error number in expressions (it is 0 when no error is active). RESUME or RESUME NEXT executed while no error is active raises error 20 (RESUME without error).

    On Error GoTo ErrorHandler
    Open "missing.txt" For Input As #1
    Exit Sub

    ErrorHandler:
        Print "Error number:"; Err
        Resume Next

### Common Error Numbers

      Number   Meaning
      ------   -------
      1        FOR loop error (NEXT without FOR, NEXT variable mismatch, FOR stack underflow)
      4        Out of DATA
      5        Illegal function call (bad argument to a built-in function)
      6        Overflow (value does not fit the target type)
      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
      20       RESUME without error
      26       FOR loop nesting too deep
      51       Internal error (bad opcode)
      52       Bad file number or file not open
      53       File not found
      54       Bad file mode
      58       File already exists or rename failed
      59       Bad record length (OPEN ... LEN must be 1 to 32767)
      67       Too many files open
      75       Path/file access error
      76       Path not found

## SHELL

Executes an operating-system command.

    SHELL "command"

When used as a function, SHELL returns the exit code of the command.

    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.

    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.

    RANDOMIZE seed
    RANDOMIZE TIMER          ' Seed from system clock

## END

Terminates program execution immediately. Any form that is loaded is unloaded before the program exits.

    END

# File I/O

## OPEN

Opens a file for reading, writing, or appending.

    OPEN filename$ FOR INPUT AS #channel
    OPEN filename$ FOR OUTPUT AS #channel
    OPEN filename$ FOR APPEND AS #channel
    OPEN filename$ FOR RANDOM AS #channel [LEN = recordSize]
    OPEN filename$ FOR BINARY AS #channel

      Mode      Description
      ----      -----------
      INPUT     Open for sequential reading. File must exist.
      OUTPUT    Open for sequential writing. Creates or truncates.
      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.

## CLOSE

Closes an open file channel.

    CLOSE #channel

## PRINT #

Writes text to a file.

    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.

    INPUT #channel, variable [, variable ...]

    Open "data.txt" For Input As #1
    Input #1, name$, age%, score#
    Close #1

## LINE INPUT #

Reads an entire line from a file into a string variable.

    LINE INPUT #channel, variable$

## WRITE #

Writes comma-delimited data to a file. Strings are enclosed in quotes, numbers are undecorated. Each statement writes a newline at the end.

    WRITE #channel, expr1, expr2, ...

    Write #1, "Scott", 42, 3.14
    ' Output: "Scott",42,3.14

## GET / PUT

Read and write records in RANDOM or BINARY mode files. 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 2 bytes, Long 4, Single 4, Double 8); a String is stored as a 2-byte length followed by its characters.

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

    Dim buf As String
    Open "raw.bin" For Binary As #1
    buf = Space$(16)
    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.

    SEEK #channel, position       ' Statement: set position
    pos = SEEK(channel)           ' Function: get current position

# File System Statements

DVX BASIC provides statements for working with the file system -- creating, deleting, renaming, and copying files and directories, and reading or setting file attributes.

## KILL

Deletes a file.

    KILL filename$

    Kill "temp.bak"

## NAME ... AS

Renames (or moves) a file.

    NAME oldName$ AS newName$

    Name "draft.txt" As "final.txt"

## FILECOPY

Copies a file. If the destination already exists it is overwritten.

    FILECOPY source$, destination$

    FileCopy "data.db", "data.bak"

## MKDIR / RMDIR

Creates or removes a directory.

    MKDIR path$
    RMDIR path$

    MkDir App.Data & "\backups"
    RmDir "C:\OLD"

## CHDIR / CHDRIVE

Changes the current working directory or drive.

    CHDIR path$
    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.

    attrs = GETATTR(filename$)
    SETATTR filename$, attrs

      Constant       Value    Attribute
      --------       -----    ---------
      vbNormal       0        Normal file (no attributes set)
      vbReadOnly     1        Read-only
      vbHidden       2        Hidden
      vbSystem       4        System file
      vbDirectory    16       Entry is a directory
      vbArchive      32       File has been modified since last backup

    If (GetAttr("readme.txt") And vbReadOnly) <> 0 Then
        Print "File is read-only."
    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).

    cwd$ = CURDIR$
    first$ = DIR$("*.txt")
    WHILE first$ <> ""
        Print first$
        first$ = DIR$        ' next match, no argument
    WEND

## FILELEN

Returns the length of a file in bytes.

    bytes = FILELEN(filename$)

# String Functions

      Function                          Returns   Description
      --------                          -------   -----------
      ASC(s$)                           Integer   ASCII code of the first character of s$
      CHR$(n)                           String    Character with ASCII code n
      FORMAT$(value, fmt$)              String    Formats a numeric value using a format string
      HEX$(n)                           String    Hexadecimal representation of n (uppercase, no leading &H)
      INSTR(s$, find$)                  Long      Position of find$ in s$ (1-based), 0 if not found
      INSTR(start, s$, find$)           Long      Search starting at position start (1-based)
      LCASE$(s$)                        String    Converts s$ to lowercase
      LEFT$(s$, n)                      String    Leftmost n characters of s$
      LEN(s$)                           Long      Length of s$ in characters
      LTRIM$(s$)                        String    Removes leading spaces from s$
      MID$(s$, start)                   String    Substring from start (1-based) to end of string
      MID$(s$, start, length)           String    Substring of length characters starting at start
      OCT$(n)                           String    Octal representation of n (no leading &O)
      RIGHT$(s$, n)                     String    Rightmost n characters of s$
      RTRIM$(s$)                        String    Removes trailing spaces from s$
      SPACE$(n)                         String    String of n spaces (n up to 65535)
      STR$(n)                           String    Converts number n to string (leading space for non-negative)
      STRING$(n, char)                  String    String of n copies of char (char can be an ASCII code or single-character string; n up to 65535)
      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).

## 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$)

    Print Format$(3.14159, "###.##")      ' "  3.14"
    Print Format$(42, "00000")            ' "00042"
    Print Format$(1234.5, "#,##0.00")     ' "1,234.50"
    Print Format$(0.5, "PERCENT")         ' "50%"

The accepted format characters are # (digit or pad space), 0 (digit or pad zero), . (decimal point), , (thousands separator), + and - (sign placement), $$ (floating dollar sign), ** (asterisk fill), and the literal word PERCENT (multiplies by 100 and appends %). See PRINT USING for details on each.

## MID$ Assignment

MID$ can also be used on the left side of an assignment to replace a portion of a string without changing its length:

    Mid$(s$, start [, length]) = replacement$

    Dim s$
    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.

# Math Functions

      Function   Returns   Description
      --------   -------   -----------
      ABS(n)     Double    Absolute value of n
      ATN(n)     Double    Arctangent of n (result in radians)
      COS(n)     Double    Cosine of n (n in radians)
      EXP(n)     Double    e raised to the power n
      FIX(n)     Integer   Truncates n toward zero (drops the fractional part)
      INT(n)     Integer   Largest integer less than or equal to n (floor)
      LOG(n)     Double    Natural logarithm (base e) of n
      RND[(n)]   Double    Random number in the range 0 <= RND < 1
      SGN(n)     Integer   Sign of n: -1 if negative, 0 if zero, 1 if positive
      SIN(n)     Double    Sine of n (n in radians)
      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.

## Color Functions

The color functions work with 24-bit RGB colors packed into a Long.

      Function           Returns   Description
      --------           -------   -----------
      RGB(r, g, b)       Long      Combine red, green, and blue components (0-255) into a 24-bit color
      GETRED(color)      Integer   Red component (0-255) of a color built with RGB
      GETGREEN(color)    Integer   Green component (0-255) of a color built with RGB
      GETBLUE(color)     Integer   Blue component (0-255) of a color built with RGB

    Dim c As Long
    c = RGB(255, 128, 0)           ' bright orange
    Print GetRed(c); GetGreen(c); GetBlue(c)    ' 255 128 0
    Me.BackColor = RGB(0, 0, 128)  ' dark blue background

# Conversion Functions

      Function   Returns   Description
      --------   -------   -----------
      CBOOL(n)   Boolean   Returns True (-1) if n is nonzero or a non-empty string; False (0) otherwise
      CDBL(n)    Double    Converts n to Double
      CINT(n)    Integer   Converts n to Integer; halves round to the nearest even number (2.5 -> 2, 3.5 -> 4); error 6 (Overflow) outside -32768 to 32767
      CLNG(n)    Long      Converts n to Long with the same rounding; error 6 (Overflow) outside the Long range
      CSNG(n)    Single    Converts n to Single
      CSTR(n)    String    Converts n to its String representation

# File I/O Functions

      Function                    Returns   Description
      --------                    -------   -----------
      EOF(channel)                Boolean   True if the file pointer is at end of file
      FREEFILE                    Integer   Next available file channel number (1..16)
      INPUT$(n, #channel)         String    Reads exactly n characters from the file
      LOC(channel)                Long      Current read/write position in the file
      LOF(channel)                Long      Length of the file in bytes
      SEEK(channel)               Long      Current file position (function form)
      FILELEN(path$)              Long      Length of the named file in bytes (no OPEN needed)
      GETATTR(path$)              Integer   File attribute bits (see vbReadOnly, vbHidden, etc.)
      CURDIR$                     String    Current working directory
      DIR$(pattern$)              String    First filename matching pattern, or ""
      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)

# Miscellaneous Functions

      Function          Returns   Description
      --------          -------   -----------
      DATE$             String    Current date as "MM-DD-YYYY"
      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)
      SHELL(cmd$)       Integer   Exit code of the command (also usable as a statement, discarding the code)

# Form and Control Statements

DVX BASIC supports Visual Basic-style forms and controls for building graphical user interfaces. A form is normally designed visually in the IDE and saved as a .frm file, but forms and their controls can also be built entirely in code.

## Loading and Unloading Forms

    LOAD FormName
    UNLOAD FormName

LOAD creates the form and its controls in memory. It fires Form_Load when the form is first loaded. UNLOAD destroys the form, firing Form_QueryUnload (which can cancel the close) and then Form_Unload. The form name here is the literal name of the form as it appears in its .frm file.

## Showing and Hiding Forms

    FormName.Show [mode]
    FormName.Hide
    Me.Show [mode]
    Me.Hide

Pass vbModal (1) to Show for a modal dialog that blocks until the user closes it. Omit the mode for a modeless (non-blocking) window.

    Form2.Show vbModal
    Me.Hide

## Property Access

Read and write control properties using dot notation:

    ControlName.Property = value
    value = ControlName.Property

    Text1.Text = "Hello"
    Label1.Caption = "Name: " & name$
    x = Text1.Left

## Method Calls

    ControlName.Method [args]

    List1.AddItem "New entry"
    List1.Clear

## Me Keyword

Me refers to the current form -- that is, the form whose event handler is running. Use it to access the form's own properties, controls, and methods from within event handlers, especially when the form's name may change or when the same code runs from multiple forms.

    Me.Caption = "Updated Title"
    Me.Text1.Text = ""
    Me.Hide

## Nothing

Nothing is a null object reference. Assign it to an object-typed variable to indicate "no object".

    Set myCtrl = Nothing

## Control Arrays

Multiple controls can share a name with unique indices. Access individual controls with parenthesized indices:

    Option1(0).Value = True
    Label1(idx).Caption = "Item " & Str$(idx)
    Me.Label1(i).Visible = True

## WITH

The WITH block provides a shorthand for setting several properties on the same control or for making several method calls. Inside the block, begin each property or method with a dot and omit the control name.

    WITH ControlName
        .Property1 = value1
        .Property2 = value2
        .Method arg1, arg2
    END WITH

    With Label1
        .Caption = "Status: Ready"
        .ForeColor = RGB(0, 128, 0)
        .Visible   = True
    End With

## Building Forms in Code

In addition to loading forms from .frm files, you can build a form entirely from code with CreateForm, CreateControl, SetEvent, and RemoveControl. The returned reference should be stored with SET.

### CreateForm

    SET formVar = CreateForm(name$, width%, height%)

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

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

### RemoveControl

    REMOVECONTROL formRef, ctrlName$

Removes a control from a form.

    Dim frm As Long
    Dim lbl As Long

    Set frm = CreateForm("MyDlg", 300, 200)
    frm.Caption = "Built in code"

    Set lbl = CreateControl(frm, "Label", "StatusLabel")
    StatusLabel.Caption = "Hello, world!"

    Dim btn As Long
    Set btn = CreateControl(frm, "CommandButton", "BtnClose")
    BtnClose.Caption = "Close"
    SetEvent btn, "Click", "OnCloseClick"

    frm.Show

    Sub OnCloseClick
        Unload Me
    End Sub

## DoEvents

Yields control to DVX so the GUI can process pending events. Call this in long-running loops to keep the UI responsive (otherwise the window will appear frozen).

    DOEVENTS

    For i = 1 To 10000
        ' process data
        If i Mod 100 = 0 Then DoEvents
    Next

## MsgBox

Displays a message-box dialog. Can be used as a statement (discards the result) or as a function (returns the button clicked).

    MSGBOX message$ [, flags [, title$]]
    result = MSGBOX(message$ [, flags [, title$]])

flags is the sum of a button-style constant and an icon constant. See Predefined Constants for the complete list.

    MsgBox "Operation complete"
    answer = MsgBox("Continue?", vbYesNo + vbQuestion, "Confirm")
    If answer = vbYes Then
        ' proceed
    End If

## InputBox$

Displays an input dialog and returns the user's text entry. Returns an empty string if the user cancels.

    result$ = INPUTBOX$(prompt$ [, title$ [, default$]])

    name$ = InputBox$("Enter your name:", "Name Entry", "")
    If name$ <> "" Then
        Print "Hello, "; name$
    End If

## Event Handler Convention

Event handlers are named ControlName_EventName and defined as SUBs:

    Sub Command1_Click()
        MsgBox "Button clicked!"
    End Sub

    Sub Form_Load()
        Me.Caption = "My App"
    End Sub

    Sub Text1_Change()
        Label1.Caption = "You typed: " & Text1.Text
    End Sub

### Common Events

      Event                Description
      -----                -----------
      Click                Control was clicked
      DblClick             Control was double-clicked
      Change               Control value or text changed
      KeyPress             Printable key was pressed (receives ASCII code)
      KeyDown              Any key was pressed (receives key code and shift state)
      KeyUp                Key was released
      MouseDown            Mouse button pressed (receives button, X, Y)
      MouseUp              Mouse button released
      MouseMove            Mouse moved over the control
      Scroll               Control was scrolled (mouse wheel or scrollbar)
      GotFocus             Control received input focus
      LostFocus            Control lost input focus
      Form_Load            Form is being loaded (fires once, after controls are created)
      Form_QueryUnload     Form is about to close; set Cancel = 1 to abort
      Form_Unload          Form is being unloaded
      Form_Resize          Form was resized
      Form_Activate        Form gained focus
      Form_Deactivate      Form lost focus
      Timer1_Timer         Timer control interval elapsed (Timer control's default event)

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

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

    db = SQLOpen(path$)

    db = SQLOpen(App.Data & "\mydata.db")

### SQLClose

Closes an open database.

    SQLClose db

## Executing SQL

### SQLExec

Executes a SQL statement that does not return data (INSERT, UPDATE, DELETE, CREATE TABLE, etc.). Returns True on success.

    ok = SQLExec(db, sql$)

    SQLExec db, "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)"
    SQLExec db, "INSERT INTO users (name) VALUES ('Scott')"
    ok = SQLExec(db, "DELETE FROM users WHERE id = 5")

### SQLAffected

Returns the number of rows affected by the last INSERT, UPDATE, or DELETE.

    count = SQLAffected(db)

## Querying Data

### SQLQuery

Executes a SELECT query and returns a result-set cursor.

    rs = SQLQuery(db, sql$)

    rs = SQLQuery(db, "SELECT id, name FROM users ORDER BY name")

### SQLNext

Advances the cursor to the next row. Returns True if a row is available, False when there are no more rows.

    hasRow = SQLNext(rs)

### SQLEof

Returns True if the cursor is past the last row.

    done = SQLEof(rs)

## Reading Fields

### SQLField$ / SQLFieldText$

Returns a field value as a string. Use SQLField$ to look up by column name; use SQLFieldText$ to look up by 0-based column index.

    value$ = SQLField$(rs, columnName$)
    value$ = SQLFieldText$(rs, columnIndex)

    name$  = SQLField$(rs, "name")
    first$ = SQLFieldText$(rs, 0)

### SQLFieldName$

Returns the column name for a given 0-based column index.

    colName$ = SQLFieldName$(rs, columnIndex)

### SQLFieldInt

Returns a field value as an integer.

    value = SQLFIELDINT(rs, columnIndex)

### SQLFieldDbl

Returns a field value as a double.

    value# = SQLFIELDDBL(rs, columnIndex)

### SQLFieldCount

Returns the number of columns in the result set.

    count = SQLFieldCount(rs)

## Result Set Cleanup

### SQLFreeResult

Frees a result-set cursor. Always call this when finished iterating a query.

    SQLFreeResult rs

## Error Information

### SQLError$

Returns the last error message for the database.

    msg$ = SQLError$(db)

## Complete SQL Example

    Dim db As Integer
    Dim rs As Integer

    db = SQLOpen(App.Data & "\contacts.db")
    SQLExec db, "CREATE TABLE IF NOT EXISTS contacts (name TEXT, phone TEXT)"
    SQLExec db, "INSERT INTO contacts VALUES ('Alice', '555-1234')"

    rs = SQLQuery(db, "SELECT name, phone FROM contacts")
    Do While SQLNext(rs)
        Print SQLField$(rs, "name"); Tab(20); SQLField$(rs, "phone")
    Loop
    SQLFreeResult rs
    SQLClose db

# App Object

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

      Property      Returns   Description
      --------      -------   -----------
      App.Path      String    Directory containing the application's executable
      App.Config    String    Directory for application configuration files
      App.Data      String    Directory for application data files (databases, etc.)

    configFile$ = App.Config & "\settings.ini"
    dbPath$ = App.Data & "\myapp.db"
    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.

    value$ = IniRead(file$, section$, key$, default$)

    name$ = IniRead(App.Config & "\app.ini", "User", "Name", "Unknown")
    fontSize = Val(IniRead(App.Config & "\app.ini", "Display", "FontSize", "12"))

## IniWrite

Writes a value to an INI file. Creates the file, section, or key if they do not exist.

    INIWRITE file$, section$, key$, value$

    IniWrite App.Config & "\app.ini", "User", "Name", "Scott"
    IniWrite App.Config & "\app.ini", "Display", "FontSize", Str$(fontSize)

# Predefined Constants

The following constants are predefined by the compiler and available in all programs. No DIM or CONST declaration is required to use them.

## MsgBox Button Style Flags

      Constant        Value   Description
      --------        -----   -----------
      vbOKOnly        0       OK button only (default)
      vbOKCancel      1       OK and Cancel buttons
      vbYesNo         2       Yes and No buttons
      vbYesNoCancel   3       Yes, No, and Cancel buttons
      vbRetryCancel   4       Retry and Cancel buttons

## MsgBox Icon Flags

Add an icon flag to the button style (with + or OR) to display an icon in the message box.

      Constant        Value   Description
      --------        -----   -----------
      vbInformation   &H10    Information icon (i)
      vbExclamation   &H20    Warning icon (!)
      vbCritical      &H30    Error/critical icon (X)
      vbQuestion      &H40    Question icon (?)

## MsgBox Return Values

      Constant   Value   Description
      --------   -----   -----------
      vbOK       1       User clicked OK
      vbCancel   2       User clicked Cancel
      vbYes      3       User clicked Yes
      vbNo       4       User clicked No
      vbRetry    5       User clicked Retry

## Show Mode Flags

      Constant   Value   Description
      --------   -----   -----------
      vbModal    1       Show form as modal dialog

## File Attribute Flags

Bit values used with GETATTR and SETATTR.

      Constant      Value   Description
      --------      -----   -----------
      vbNormal      0       Normal file (no attributes)
      vbReadOnly    1       Read-only
      vbHidden      2       Hidden
      vbSystem      4       System file
      vbDirectory   16      Entry is a directory
      vbArchive     32      File has been modified since last backup

## Boolean Constants

      Constant   Value   Description
      --------   -----   -----------
      True       -1      Boolean true
      False      0       Boolean false

# Include Libraries

DVX ships a set of BASIC include files (.bas) in the sdk/include/basic directory. Each file is a small library of DECLARE LIBRARY wrappers around native DVX runtime functions. Add an include file to your project (the IDE's Add File command, or editing the .dbp with another tool) and the declared functions become available to your code.

      File           Provides
      ----           --------
      commdlg.bas    File Open/Save dialogs, input dialogs, choice dialogs, save-prompt dialogs
      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

## 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 (*.*)")

    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

# Common Properties, Events, and Methods

Every control in DVX BASIC inherits a set of common properties, events, and methods. These are handled by the form runtime before dispatching to widget-specific interface descriptors.

## Common Properties

      Property     Type      R/W   Description
      ----------   -------   ---   -------------------------------------------
      Name         String    R     The control's name (e.g. "Command1"). Read-only at runtime.
      Left         Integer   R/W   X position in pixels relative to the parent container.
      Top          Integer   R/W   Y position in pixels relative to the parent container.
      Width        Integer   R/W   Current width in pixels. Setting this changes the minimum width constraint.
      Height       Integer   R/W   Current height in pixels. Setting this changes the minimum height constraint.
      MinWidth     Integer   R/W   Minimum width for layout. Alias for Width in the setter.
      MinHeight    Integer   R/W   Minimum height for layout. Alias for Height in the setter.
      MaxWidth     Integer   R/W   Maximum width cap (0 = no limit, stretch to fill).
      MaxHeight    Integer   R/W   Maximum height cap (0 = no limit, stretch to fill).
      Weight       Integer   R/W   Layout weight. 0 = fixed size, >0 = share extra space proportionally.
      Visible      Boolean   R/W   Whether the control is visible.
      Enabled      Boolean   R/W   Whether the control accepts user input.
      BackColor    Long      R/W   Background color as a 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.

## 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
      ---------   -------------------------------------------   -------------------------------------------
      Click       (none)                                        Fires when the control is clicked.
      DblClick    (none)                                        Fires when the control is double-clicked.
      Change      (none)                                        Fires when the control's value or text changes.
      GotFocus    (none)                                        Fires when the control receives keyboard focus.
      LostFocus   (none)                                        Fires when the control loses keyboard focus.
      KeyPress    KeyAscii As Integer                           Fires when a printable key is pressed. KeyAscii is the ASCII code.
      KeyDown     KeyCode As Integer, Shift As Integer          Fires when any key is pressed down. KeyCode is the scan code; Shift indicates modifier keys.
      KeyUp       KeyCode As Integer, Shift As Integer          Fires when a key is released.
      MouseDown   Button As Integer, X As Integer, Y As Integer Fires when a mouse button is pressed over the control.
      MouseUp     Button As Integer, X As Integer, Y As Integer Fires when a mouse button is released over the control.
      MouseMove   Button As Integer, X As Integer, Y As Integer Fires when the mouse moves over the control.
      Scroll      Delta As Integer                              Fires when the control is scrolled (mouse wheel or scrollbar).

## Common Methods

      Method     Parameters   Description
      --------   ----------   -------------------------------------------
      SetFocus   (none)       Gives keyboard focus to this control.
      Refresh    (none)       Forces the control to repaint.

Form

Data Binding

FRM File Format

# Data Binding

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

      Property     Set On        Description
      ----------   -----------   -------------------------------------------
      DataSource   Any control   Name of the Data control to bind to (e.g. "Data1").
      DataField    Any control   Column name from the Data control's recordset to display.

## How It Works

- Place a Data control on the form and set its DatabaseName and RecordSource properties.
- Place one or more display/edit controls (TextBox, Label, etc.) and set their DataSource to the Data control's name and DataField to a column name.
- When the form loads, the Data control auto-refreshes: it opens the database, runs the query, and navigates to the first record.
- Bound controls are updated automatically each time the Data control repositions (the Reposition event fires, and the runtime pushes the current record's field values into all bound controls).
- When a bound control loses focus (LostFocus), its current text is written back to the Data control's record cache, and Update is called automatically to persist changes.

## Master-Detail Binding

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

- A master Data control bound to the parent table.
- A detail Data control with its MasterSource set to the master's name, MasterField set to the key column in the master, and DetailField set to the foreign key column in the detail table.

When the master record changes, the detail Data control automatically re-queries using the master's current value for filtering. All controls bound to the detail are refreshed.

## DBGrid Binding

Set the DBGrid's DataSource to a Data control name. The grid auto-populates columns from the query results and refreshes whenever the Data control refreshes.

## Example

    VERSION DVX 1.00
    Begin Form frmData
        Caption      = "Data Binding Example"
        AutoSize     = False
        Width        = 400
        Height       = 280
        Begin Data Data1
            DatabaseName = "myapp.db"
            RecordSource = "customers"
        End
        Begin Label lblName
            Caption = "Name:"
        End
        Begin TextBox txtName
            DataSource = "Data1"
            DataField  = "name"
        End
        Begin Label lblEmail
            Caption = "Email:"
        End
        Begin TextBox txtEmail
            DataSource = "Data1"
            DataField  = "email"
        End
    End

    Sub Data1_Reposition ()
        Print "Current record changed"
    End Sub

    Sub Data1_Validate (Cancel As Integer)
        If txtName.Text = "" Then
            MsgBox "Name cannot be empty!"
            Cancel = 1
        End If
    End Sub

Data

DBGrid

# Menu System

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

## FRM Syntax

    Begin Form Form1
        Caption = "Menu Demo"

        Begin Menu mnuFile
            Caption = "&File"
            Begin Menu mnuOpen
                Caption = "&Open"
            End
            Begin Menu mnuSave
                Caption = "&Save"
            End
            Begin Menu mnuSep1
                Caption = "-"
            End
            Begin Menu mnuExit
                Caption = "E&xit"
            End
        End

        Begin Menu mnuEdit
            Caption = "&Edit"
            Begin Menu mnuCopy
                Caption = "&Copy"
            End
            Begin Menu mnuPaste
                Caption = "&Paste"
            End
        End
    End

## Menu Item Properties

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

## Nesting

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

- Level 0: top-level menu bar headers (e.g. "File", "Edit").
- Level 1: items within a top-level menu.
- Level 2+: submenu items.

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

## Event Dispatch

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

    Sub mnuOpen_Click ()
        MsgBox "Open was clicked"
    End Sub

    Sub mnuExit_Click ()
        Unload Form1
    End Sub

Form

FRM File Format

# Control Arrays

DVX BASIC supports VB-style control arrays. Multiple controls can share the same name, differentiated by an Index property. When an event fires on a control array element, the element's index is passed as the first parameter.

## Defining Control Arrays in FRM

    Begin CommandButton Command1
        Caption = "Button A"
        Index   = 0
    End
    Begin CommandButton Command1
        Caption = "Button B"
        Index   = 1
    End
    Begin CommandButton Command1
        Caption = "Button C"
        Index   = 2
    End

## Event Handler Convention

When a control has an Index property (>= 0), the event handler receives Index As Integer as the first parameter, before any event-specific parameters.

    Sub Command1_Click (Index As Integer)
        Select Case Index
            Case 0
                MsgBox "Button A clicked"
            Case 1
                MsgBox "Button B clicked"
            Case 2
                MsgBox "Button C clicked"
        End Select
    End Sub

## Accessing Array Elements in Code

Use the indexed form ControlName(Index) to access a specific element:

    Command1(0).Caption = "New Text"
    Command1(1).Enabled = False

> Note: Control array elements share the same event handler Sub. The runtime prepends the Index argument automatically. If you define parameters on the Sub, Index comes first, followed by the event's own parameters (e.g. KeyPress would be Sub Ctrl1_KeyPress (Index As Integer, KeyAscii As Integer)).

Common Properties, Events, and Methods

FRM File Format

# FRM File Format

The .frm file is a text file that describes a form's layout, controls, menus, and code. It follows a format compatible with VB3 .frm files, with DVX-specific extensions.

## Structure

    VERSION DVX 1.00
    Begin Form FormName
        form-level properties...

        Begin Menu mnuFile
            Caption = "&File"
            Begin Menu mnuOpen
                Caption = "&Open"
            End
        End

        Begin TypeName ControlName
            property = value
            ...
        End

        Begin Frame Frame1
            Caption = "Group"
            Begin TypeName ChildName
                ...
            End
        End
    End

    BASIC code follows...

    Sub FormName_Load ()
        ...
    End Sub

## Rules

- The VERSION line is optional. VERSION DVX 1.00 marks a native DVX form. VB forms with version <= 2.0 are accepted for import.
- The form block begins with Begin Form Name and ends with End.
- Controls are nested with Begin TypeName Name / End.
- Container controls (Frame, VBox, HBox, Toolbar, TabStrip, ScrollPane, Splitter, WrapBox) can have child controls nested inside them.
- Properties are assigned as Key = Value. String values are optionally quoted.
- Everything after the form's closing End is BASIC source code.
- Comments in the form section use ' (single quote).
- Blank lines are ignored in the form section.

## Common FRM Properties

      Property                  Applies To        Description
      -----------------------   ---------------   -------------------------------------------
      Caption                   Form, controls    Display text or window title.
      Text                      TextBox, ComboBox Initial text content.
      MinWidth / Width          Controls          Minimum width. Both names are accepted.
      MinHeight / Height        Controls          Minimum height. Both names are accepted.
      MaxWidth                  Controls          Maximum width (0 = no cap).
      MaxHeight                 Controls          Maximum height (0 = no cap).
      Weight                    Controls          Layout weight for flexible sizing.
      Left                      Form, controls    X position (used by Form when Centered=False; informational for controls).
      Top                       Form, controls    Y position.
      Index                     Controls          Control array index (-1 or absent = not in array).
      Visible                   Controls          Initial visibility.
      Enabled                   Controls          Initial enabled state.
      Layout                    Form              "VBox" or "HBox".
      AutoSize                  Form              Auto-fit window to content.
      Resizable                 Form              Allow runtime resizing.
      Centered                  Form              Center window on screen.
      DatabaseName              Data              SQLite database file path.
      RecordSource              Data              Table name or SQL query.
      DataSource                Bound controls    Name of the Data control.
      DataField                 Bound controls    Column name in the recordset.

Form

Common Properties, Events, and Methods

Menu System

Control Arrays

# Form

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

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

## Form Properties

      Property    Type      Default          Description
      ----------  -------   --------------   -------------------------------------------
      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.
      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.

## Form Events

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

## Form Methods

      Statement           Description
      ------------------  -------------------------------------------
      Load FormName       Load the form (creates the window and controls, fires Load event).
      Unload FormName     Unload the form (fires Unload, destroys window).
      FormName.Show       Make the form visible.
      FormName.Show 1     Show as modal dialog (blocks until closed).
      FormName.Hide       Hide the form without unloading it.

## Example

    Sub Form_Load ()
        Form1.Caption = "Hello World"
        Print "Form loaded!"
    End Sub

    Sub Form_QueryUnload (Cancel As Integer)
        If MsgBox("Really quit?", 4) <> 6 Then
            Cancel = 1
        End If
    End Sub

    Sub Form_Resize ()
        Print "Window resized"
    End Sub

Common Properties, Events, and Methods

FRM File Format

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

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

## Type-Specific Methods

      Method             Description
      ------             -----------
      Clear              Clear the terminal screen and reset the cursor to the home position.
      Poll               Poll the attached communication channel for incoming bytes and feed them into the ANSI parser.
      Write text$        Write a string to the terminal with full ANSI escape processing.

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.

## Example

    Begin Terminal Terminal1
        MinWidth  = 640
        MinHeight = 400
    End

    Sub Form_Load ()
        Terminal1.Write "Welcome!" & Chr$(13) & Chr$(10)
    End Sub

Common Properties, Events, and Methods

# Frame

VB Equivalent: Frame -- DVX Widget: frame (titled container)

A container with a titled border. Child controls are placed inside the frame using VBox layout. In the .frm file, nest Begin/End blocks inside the Frame block.

## Type-Specific Properties

      Property   Type     Description
      --------   ------   -------------------------------------------
      Caption    String   The title displayed in the frame border.

No type-specific methods or events.

Container: Yes

Default Event: Click

## Example

    Begin Frame Frame1
        Caption = "Options"
        Begin CheckBox Check1
            Caption = "Option A"
        End
        Begin CheckBox Check2
            Caption = "Option B"
        End
    End

Common Properties, Events, and Methods

# HBox

DVX Extension -- DVX Widget: hbox (horizontal layout container)

A container that arranges its children horizontally, left to right. No visible border. Use Weight on children to distribute extra space proportionally.

No type-specific properties, methods, or events.

Container: Yes

Default Event: Click

## Example

    Begin HBox ButtonRow
        Spacing = 4
        Begin CommandButton Command1
            Caption = "OK"
        End
        Begin CommandButton Command2
            Caption = "Cancel"
        End
    End

Common Properties, Events, and Methods

VBox

# VBox

DVX Extension -- DVX Widget: vbox (vertical layout container)

A container that arranges its children vertically, top to bottom. No title or border. Use Weight on children to distribute extra space proportionally.

No type-specific properties, methods, or events.

Container: Yes

Default Event: Click

## Example

    Begin VBox Column1
        Spacing = 4
        Begin Label Label1
            Caption = "Name:"
        End
        Begin TextBox Text1
        End
    End

Common Properties, Events, and Methods

HBox

# CommandButton

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

A push button that triggers an action when clicked. The Caption may include a '&' before a character to mark an accelerator key (e.g. "&OK" underlines 'O', and Alt+O activates the button).

## Type-Specific Properties

      Property   Type     Description
      --------   ------   -------------------------------------------
      Caption    String   The text displayed on the button. Use '&' for an accelerator key.

No type-specific methods or events.

Default Event: Click

## Example

    Begin Form Form1
        Caption = "Button Demo"
        Begin CommandButton Command1
            Caption = "&Click Me!"
        End
    End

    Sub Command1_Click ()
        MsgBox "Button was clicked!"
    End Sub

Common Properties, Events, and Methods

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

Colors are specified as 0x00RRGGBB integers (e.g. &HFF0000 for red).

## Type-Specific Methods

      Method                                        Description
      ------                                        -----------
      Clear color%                                  Fill the entire canvas with the specified color.
      DrawLine x0%, y0%, x1%, y1%, color%           Draw a line between two points.
      DrawRect x%, y%, w%, h%, color%               Draw a rectangle outline.
      DrawText x%, y%, text$                        Draw text at the given position.
      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.
      SetPenColor color%                            Set the drawing color for subsequent operations.
      SetPenSize size%                              Set the pen/brush size in pixels.
      SetPixel x%, y%, color%                       Set the color of a single pixel.

Default Event: Click

## Example

    Picture1.Resize 200, 150
    Picture1.Clear &HFFFFFF
    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"

Common Properties, Events, and Methods

# CheckBox

VB Equivalent: CheckBox -- DVX Widget: checkbox

A toggle control with a label. The checked state is exposed as a Boolean. Supports accelerator keys (put '&' before a character in the Caption). Press Space or Enter to toggle when focused.

## Type-Specific Properties

      Property   Type      Description
      --------   -------   -------------------------------------------
      Caption    String    The text displayed next to the checkbox.
      Value      Boolean   True if checked, False if unchecked.

No type-specific methods or events.

Default Event: Click

## Example

    Begin CheckBox Check1
        Caption = "Enable feature"
    End

    Sub Check1_Click ()
        If Check1.Value Then
            Label1.Caption = "Feature ON"
        Else
            Label1.Caption = "Feature OFF"
        End If
    End Sub

Common Properties, Events, and Methods

# ComboBox

VB Equivalent: ComboBox -- DVX Widget: combobox (editable text field + drop-down list, default maxLen 256)

A combination of a single-line text input and a drop-down list. The user can either type a value or pick one from the list. Selecting a list item copies its text into the edit field. Supports the same AddItem / RemoveItem / Clear / List methods as ListBox.

## Type-Specific Properties

      Property    Type      Description
      ---------   -------   -------------------------------------------
      Text        String    The text in the editable field.
      ListIndex   Integer   Index of the currently selected list item (-1 = user typed something not in the list).

## Type-Specific Methods

      Method              Description
      ------              -----------
      AddItem text$       Append an item to the drop-down list.
      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.

Default Event: Click

## Example

    Begin ComboBox Combo1
    End

    Sub Form_Load ()
        Combo1.AddItem "Small"
        Combo1.AddItem "Medium"
        Combo1.AddItem "Large"
    End Sub

    Sub Combo1_Change ()
        Label1.Caption = "Selected: " & Combo1.Text
    End Sub

Common Properties, Events, and Methods

See ListBox for details

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

See Data Binding for details

## Type-Specific Properties

      Property       Type      Description
      ------------   -------   -------------------------------------------
      DatabaseName   String    Path to the SQLite database file.
      RecordSource   String    Table name or SQL SELECT query for the recordset.
      KeyColumn      String    Primary key column name (used for UPDATE/DELETE operations).
      Caption        String    Text displayed on the navigator bar.
      BOF            Boolean   True if the current position is the first record or there are no records (read-only).
      EOF            Boolean   True if the current position is past the last record or there are no records (read-only).
      MasterSource   String    Name of a master Data control (for master-detail binding).
      MasterField    String    Column in the master recordset to read for the filter value.
      DetailField    String    Column in this recordset that matches the master field.

## Type-Specific Methods

      Method         Parameters   Description
      ------------   ----------   -------------------------------------------
      MoveFirst      (none)       Navigate to the first record.
      MoveLast       (none)       Navigate to the last record.
      MoveNext       (none)       Navigate to the next record.
      MovePrevious   (none)       Navigate to the previous record.
      AddNew         (none)       Append a blank record and move to it.
      Delete         (none)       Delete the current record.
      Refresh        (none)       Re-query the database and reload records.
      Update         (none)       Write pending changes to the database.

## Type-Specific Events

      Event        Parameters          Description
      ----------   -----------------   -------------------------------------------
      Reposition   (none)              Fires after the current record changes. Default event.
      Validate     Cancel As Integer   Fires before writing. Set Cancel = 1 to abort.

Default Event: Reposition

## Example

    Begin Data Data1
        DatabaseName = "books.db"
        RecordSource = "titles"
        KeyColumn    = "id"
    End

    Begin TextBox Text1
        DataSource = "Data1"
        DataField  = "title"
    End

    Sub Form_Load ()
        Data1.Refresh
    End Sub

Common Properties, Events, and Methods

Data Binding

DBGrid

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

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

## Type-Specific Methods

      Method             Parameters                        Description
      ----------------   -------------------------------   -------------------------------------------
      Refresh            (none)                            Reload and redraw the grid from the Data control.
      SetColumnHeader    Field As String, Header As String  Set the displayed header text for a column.
      SetColumnVisible   Field As String, Visible As Boolean  Show or hide a column by field name.
      SetColumnWidth     Field As String, Width As Integer  Set the pixel width of a column by field name.

## Type-Specific Events

      Event      Parameters   Description
      --------   ----------   -------------------------------------------
      Click      (none)       Fires when a row is clicked.
      DblClick   (none)       Fires when a row is double-clicked. Default event.

Default Event: DblClick

## Example

    Begin Data Data1
        DatabaseName = "books.db"
        RecordSource = "titles"
    End

    Begin DBGrid DBGrid1
        DataSource = "Data1"
        GridLines  = True
    End

    Sub Form_Load ()
        Data1.Refresh
    End Sub

    Sub DBGrid1_DblClick ()
        MsgBox "Opening row " & Str$(Data1.BOF)
    End Sub

Common Properties, Events, and Methods

Data

Data Binding

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

## Type-Specific Properties

      Property    Type      Description
      ---------   -------   -------------------------------------------
      ListIndex   Integer   Index of the currently selected item (-1 = none).

## Type-Specific Methods

      Method              Description
      ------              -----------
      AddItem text$       Append an item to the drop-down list.
      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.

Default Event: Change (fires when the user picks a new item; Click fires only when the arrow opens the popup)

## Example

    Begin DropDown DropDown1
    End

    Sub Form_Load ()
        DropDown1.AddItem "Small"
        DropDown1.AddItem "Medium"
        DropDown1.AddItem "Large"
        DropDown1.ListIndex = 1
    End Sub

    Sub DropDown1_Change ()
        Label1.Caption = "Picked: " & DropDown1.List(DropDown1.ListIndex)
    End Sub

Common Properties, Events, and Methods

See ListBox for details

# ImageButton

DVX Extension -- DVX Widget: imagebutton

A button that displays an image instead of text. Has the same press/release behavior as CommandButton, but shows a bitmap. Typically used inside a Toolbar.

## Type-Specific Properties

      Property      Type      Description
      -----------   -------   -------------------------------------------
      Picture       String    Path to an image file to load.
      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.

Default Event: Click

## Example

    Begin Toolbar Toolbar1
        Begin ImageButton ImageButton1
            Picture = "icons/save.bmp"
        End
        Begin ImageButton ImageButton2
            Picture = "icons/open.bmp"
        End
    End

    Sub ImageButton1_Click ()
        MsgBox "Save clicked"
    End Sub

Common Properties, Events, and Methods

# Image

VB Equivalent: Image -- DVX Widget: image

A static image display control. Loads bitmap images from file. Set the Picture property at design-time (in the .frm file) or at runtime to load a file.

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

Default Event: Click

## Example

    Begin Image Image1
        Picture = "assets/logo.bmp"
        Stretch = True
    End

    Sub Image1_Click ()
        MsgBox "Size: " & Str$(Image1.ImageWidth) & "x" & Str$(Image1.ImageHeight)
    End Sub

Common Properties, Events, and Methods

# Label

VB Equivalent: Label -- DVX Widget: label

A static text label. Supports left, center, and right alignment. Put '&' before a character in the Caption to define an accelerator that moves focus to the next focusable control.

## Type-Specific Properties

      Property    Type   Description
      ---------   ----   -------------------------------------------
      Caption     String The text displayed by the label.
      Alignment   Enum   Text alignment: Left (default), Center, or Right.

No type-specific methods or events.

Default Event: Click

## Example

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

Common Properties, Events, and Methods

# ListBox

VB Equivalent: ListBox -- DVX Widget: listbox

A scrollable list of selectable items. Items are managed via methods (AddItem, RemoveItem, Clear). Supports single and multi-select modes, drag-to-reorder, and keyboard navigation with type-ahead search.

## Type-Specific Properties

      Property    Type      Description
      ---------   -------   -------------------------------------------
      ListIndex   Integer   Index of the currently selected item (-1 = no selection).

## Type-Specific Methods

      Method            Parameters                                Description
      ---------------   ---------------------------------------   -------------------------------------------
      AddItem           Text As String                            Add an item to the end of the list.
      Clear             (none)                                    Remove all items from the list.
      ClearSelection    (none)                                    Deselect all items.
      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.
      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.
      SetMultiSelect    Multi As Boolean                          Enable or disable multi-select mode.
      SetReorderable    Reorderable As Boolean                    Enable or disable drag-to-reorder.

Default Event: Click

## Example

    Sub Form_Load ()
        List1.AddItem "Apple"
        List1.AddItem "Banana"
        List1.AddItem "Cherry"
    End Sub

    Sub List1_Click ()
        Dim idx As Integer
        idx = List1.ListIndex
        If idx >= 0 Then
            Label1.Caption = "Selected: " & List1.List(idx)
        End If
    End Sub

Common Properties, Events, and Methods

ComboBox

DropDown

# ListView

VB Equivalent: ListView -- DVX Widget: listview

A multi-column list with column headers. Supports sorting, multi-select, and drag-to-reorder.

## Type-Specific Properties

      Property    Type      R/W   Description
      ---------   -------   ---   -------------------------------------------
      ListIndex   Integer   R/W   Index of the currently selected row (-1 = none).

## Type-Specific Methods

      Method                                        Description
      ------                                        -----------
      AddItem text$                                 Add a row (sets first column text).
      Clear                                         Remove all rows.
      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.
      RowCount()                                    Returns the number of rows.
      SelectAll                                     Select all rows.
      SetCell row%, col%, text$                     Set the text of a cell.
      SetColumns spec$                              Define columns. Pipe-delimited "Name,Width|Name,Width" (width in characters).
      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.

Default Event: Click

## Example

    ListView1.SetColumns "Name,20|Size,10|Type,15"
    ListView1.AddItem "readme.txt"
    ListView1.SetCell 0, 1, "1024"
    ListView1.SetCell 0, 2, "Text"
    ListView1.SetSort 0, 1

Common Properties, Events, and Methods

# ProgressBar

VB Equivalent: ProgressBar -- DVX Widget: progressbar

A horizontal progress indicator bar.

## Type-Specific Properties

      Property   Type      Description
      --------   -------   -------------------------------------------
      Value      Integer   Current progress value (0-100).

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

Common Properties, Events, and Methods

# OptionButton

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

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

## Type-Specific Properties

      Property   Type      Description
      --------   -------   -------------------------------------------
      Caption    String    The text displayed next to the radio button.
      Value      Integer   The index of this radio button within its group (read-only).

## Type-Specific Methods

      Method        Parameters          Description
      -----------   -----------------   -------------------------------------------
      SetSelected   Index As Integer    Select the radio button at the given index within the group.

Default Event: Click

Common Properties, Events, and Methods

# ScrollPane

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

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

## Type-Specific Properties

      Property   Type      Description
      --------   -------   -------------------------------------------
      NoBorder   Boolean   When True, suppresses the border around the scroll pane.

Container: Yes

No default event.

Common Properties, Events, and Methods

# Line

VB Equivalent: Line -- DVX Widget: separator

A visual separator line. The underlying widget supports both horizontal and vertical orientations. The default (via BASIC) is horizontal.

No type-specific properties, events, or methods.

Common Properties, Events, and Methods

# HScrollBar

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

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

## Type-Specific Properties

      Property   Type      Description
      --------   -------   -------------------------------------------
      Value      Integer   The current slider position (clamped to min/max range).

Default Event: Change

## Example

    Begin HScrollBar HScroll1
        MinWidth = 200
    End

    Sub HScroll1_Change ()
        Label1.Caption = "Value: " & Str$(HScroll1.Value)
    End Sub

Common Properties, Events, and Methods

# Spacer

DVX Extension -- DVX Widget: spacer

An invisible layout spacer. Takes up space in the layout without rendering anything. Useful for pushing controls apart. Give it a Weight to absorb extra space.

No type-specific properties, events, or methods.

Common Properties, Events, and Methods

# SpinButton

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

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

## Type-Specific Properties

      Property   Type      Description
      --------   -------   -------------------------------------------
      Value      Integer   Current integer value (in integer mode).
      RealMode   Boolean   True to use floating-point mode; False for integer mode.
      Decimals   Integer   Number of decimal places shown in real mode.

## Type-Specific Methods

      Method     Parameters                       Description
      --------   ------------------------------   -------------------------------------------
      SetRange   Min As Integer, Max As Integer   Set the allowed value range.
      SetStep    Step As Integer                  Set the increment per button click.

Default Event: Change

Common Properties, Events, and Methods

# Splitter

DVX Extension -- DVX Widget: splitter

A resizable split pane. Holds exactly two child widgets separated by a draggable divider. Default orientation is vertical (vertical divider, panes side-by-side).

## Type-Specific Properties

      Property   Type      Description
      --------   -------   -------------------------------------------
      Position   Integer   Position of the divider in pixels from the top (or left).

Container: Yes

No default event.

Common Properties, Events, and Methods

# StatusBar

VB Equivalent: StatusBar -- DVX Widget: statusbar

A horizontal container styled as a status bar, typically placed at the bottom of a form. At the C API level it holds child widgets (such as labels), each drawn with a sunken-panel border for the classic segmented status-bar look. It is not registered as a container in the form runtime, so child controls cannot be nested inside it in .frm files.

No type-specific properties, events, or methods.

Common Properties, Events, and Methods

# TabStrip

VB Equivalent: TabStrip -- DVX Widget: tabcontrol

A tabbed container. Each tab page is a separate container that holds child controls. Switching tabs shows one page and hides others.

## Type-Specific Properties

      Property   Type      Description
      --------   -------   -------------------------------------------
      TabIndex   Integer   Index of the active tab (0-based). Note: this property name collides with the common VB-compatibility TabIndex property, which shadows it at runtime. Use the SetActive method instead to switch tabs.

## Type-Specific Methods

      Method                   Description
      ------                   -----------
      AddPage title$           Add a new tab page with the given title.
      GetActive()              Returns the index of the active tab.
      SetActive index%         Switch to the tab at the given index. This is the recommended way to change tabs at runtime (the TabIndex property is shadowed by the common property handler).

Container: Yes

Default Event: Click

> Warning: The TabIndex property is shadowed by the common property handler at runtime. Use the SetActive method to change tabs programmatically.

Common Properties, Events, and Methods

# TextBox

VB Equivalent: TextBox -- DVX Widget: textbox (single-line text input, max 256 chars)

A single-line text input field. Supports data binding via DataSource and DataField properties.

## Type-Specific Properties

      Property     Type     Description
      ----------   ------   -------------------------------------------
      Text         String   The text content of the input field.
      DataSource   String   Name of a Data control for data binding.
      DataField    String   Column name for data binding.

Default Event: Change

## Example

    Begin TextBox Text1
        Text = "Enter text here"
    End

    Sub Text1_Change ()
        Label1.Caption = "You typed: " & Text1.Text
    End Sub

Common Properties, Events, and Methods

Data Binding

# TextArea

VB Equivalent: TextArea (DVX extension) -- DVX Widget: textarea (multi-line text input, default max 65536 chars)

A multi-line text editing area. This is a DVX extension with no direct VB3 equivalent (VB uses a TextBox with MultiLine=True). Supports line numbers, auto-indent, find/replace, and tab configuration.

## Type-Specific Properties

      Property     Type      R/W   Description
      ----------   -------   ---   -------------------------------------------
      Text         String    R/W   The full text content.
      CursorLine   Integer   R     Current cursor line number (0-based).

## Type-Specific Methods

      Method                                          Description
      ------                                          -----------
      AppendText text$                                Append text to the end of the buffer and invalidate the widget.
      FindNext needle$, caseSensitive, forward        Search for text. Returns True if found.
      GetWordAtCursor()                               Returns the word under the cursor.
      GoToLine line%                                  Scroll to and position cursor at the given line.
      ReplaceAll needle$, replacement$, caseSensitive Replace all occurrences. Returns count of replacements.
      SetAutoIndent enabled                           Enable or disable automatic indentation.
      SetCaptureTabs enabled                          When True, Tab key inserts a tab/spaces instead of moving focus.
      SetShowLineNumbers show                         Show or hide the line number gutter.
      SetSyntaxMode mode$                             Activate built-in syntax highlighting. Modes: "dhs" (help source), "bas" (BASIC). Pass "" to disable.
      SetTabWidth width%                              Set the tab stop width in characters.
      SetUseTabChar useChar                           When True, Tab inserts a tab character; when False, inserts spaces.

Default Event: Change

## Example

    TextArea1.SetShowLineNumbers True
    TextArea1.SetAutoIndent True
    TextArea1.SetTabWidth 4
    TextArea1.SetCaptureTabs True

    ' Search for text
    If TextArea1.FindNext("TODO", False, True) Then
        Print "Found at line"; TextArea1.CursorLine
    End If

    ' Replace all occurrences
    Dim count As Integer
    count = TextArea1.ReplaceAll("old", "new", False)
    Print "Replaced"; count; "occurrences"

Common Properties, Events, and Methods

# Timer

VB Equivalent: Timer -- DVX Widget: timer (non-visual)

A non-visual control that fires its event at a regular interval. The Timer widget is invisible at runtime -- it has no on-screen representation.

## Type-Specific Properties

      Property   Type      Description
      --------   -------   -------------------------------------------
      Enabled    Boolean   True to start the timer, False to stop it.
      Interval   Integer   Timer interval in milliseconds.

## Type-Specific Methods

      Method   Parameters   Description
      ------   ----------   -------------------------------------------
      Start    (none)       Start the timer.
      Stop     (none)       Stop the timer.

## Type-Specific Events

      Event   Parameters   Description
      -----   ----------   -------------------------------------------
      Timer   (none)       Fires each time the interval elapses. This is the default event.

> Note: The Timer control fires the Timer event instead of Change. The onChange callback on the underlying widget is remapped automatically.

## Example

    Begin Timer Timer1
        Interval = 1000
        Enabled  = True
    End

    Dim counter As Integer

    Sub Timer1_Timer ()
        counter = counter + 1
        Label1.Caption = "Ticks: " & Str$(counter)
    End Sub

Common Properties, Events, and Methods

# Toolbar

VB Equivalent: Toolbar -- DVX Widget: toolbar

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

Container: Yes

No type-specific properties, events, or methods.

Common Properties, Events, and Methods

# TreeView

VB Equivalent: TreeView -- DVX Widget: treeview

A hierarchical tree of expandable/collapsible nodes. Supports multi-select and drag-to-reorder. Items are accessed by depth-first index (0-based).

## Type-Specific Methods

      Method                                  Description
      ------                                  -----------
      AddChildItem parentIndex%, text$        Add a child node under the node at the given index.
      AddItem text$                           Add a root-level node.
      Clear                                   Remove all nodes.
      GetItemText$(index%)                    Returns the text of the node at the given index.
      IsExpanded(index%)                      Returns True if the node at the given index is expanded.
      IsItemSelected(index%)                  Returns True if the node at the given index is selected.
      ItemCount()                             Returns the total number of nodes (all levels).
      SetExpanded index%, expanded            Expand or collapse the node at the given index.
      SetItemSelected index%, selected        Select or deselect the node at the given index.
      SetMultiSelect multi                    Enable or disable multi-select mode.
      SetReorderable reorderable              Enable or disable node reordering.

Default Event: Click

## Example

    TreeView1.AddItem "Animals"
    TreeView1.AddChildItem 0, "Cat"
    TreeView1.AddChildItem 0, "Dog"
    TreeView1.AddItem "Plants"
    TreeView1.AddChildItem 3, "Oak"
    TreeView1.SetExpanded 0, True
    Print "Items:"; TreeView1.ItemCount()

Common Properties, Events, and Methods

# WrapBox

DVX Extension -- DVX Widget: wrapbox | Name Prefix: WrapBox

A container that arranges children in a flowing layout, wrapping to the next row when the available width is exceeded. Similar to CSS flexbox with flex-wrap: wrap.

## Type-Specific Properties

      Property    Type   Description
      ---------   ----   -------------------------------------------
      Alignment   Enum   Horizontal alignment of items: Left, Center, or Right.

Container: Yes

Default Event: Click

Common Properties, Events, and Methods