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 32-bit ARGB value.
  ForeColor    Long      R/W   Foreground (text) color as a 32-bit ARGB value.
  TabIndex     Integer   R     Accepted for VB compatibility but ignored. DVX has no tab order.

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

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