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

.topic ctrl.common.props
.title Common Properties, Events, and Methods
.toc 0 Common Properties, Events, and Methods
.default
.index Common Properties
.index Common Events
.index Common Methods
.index Properties
.index Events
.index Methods

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

.h2 Common Properties

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

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

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

.h2 Common Methods

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

.link ctrl.form Form
.link ctrl.databinding Data Binding
.link ctrl.frm FRM File Format


.topic ctrl.databinding
.title Data Binding
.toc 1 Data Binding
.index Data Binding
.index DataSource
.index DataField
.index Master-Detail

.h1 Data Binding

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

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

.h2 How It Works

.list
.item Place a Data control on the form and set its DatabaseName and RecordSource properties.
.item 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.
.item When the form loads, the Data control auto-refreshes: it opens the database, runs the query, and navigates to the first record.
.item 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).
.item 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.
.endlist

.h2 Master-Detail Binding

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

.list
.item A master Data control bound to the parent table.
.item 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.
.endlist

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.

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

.h2 Example

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

.link ctrl.data Data
.link ctrl.dbgrid DBGrid


.topic ctrl.menus
.title Menu System
.toc 1 Menu System
.index Menu
.index Menu Bar
.index Submenu
.index Separator

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

.h2 FRM Syntax

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

.h2 Menu Item Properties

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

.h2 Nesting

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

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

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

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

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

Sub mnuExit_Click ()
    Unload Form1
End Sub
.endcode

.link ctrl.form Form
.link ctrl.frm FRM File Format


.topic ctrl.arrays
.title Control Arrays
.toc 1 Control Arrays
.index Control Arrays
.index Index Property

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

.h2 Defining Control Arrays in FRM

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

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

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

.h2 Accessing Array Elements in Code

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

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

.note info
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)).
.endnote

.link ctrl.common.props Common Properties, Events, and Methods
.link ctrl.frm FRM File Format


.topic ctrl.frm
.title FRM File Format
.toc 1 FRM File Format
.index FRM
.index .frm
.index Form File

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

.h2 Structure

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

.h2 Rules

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

.h2 Common FRM Properties

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

.link ctrl.form Form
.link ctrl.common.props Common Properties, Events, and Methods
.link ctrl.menus Menu System
.link ctrl.arrays Control Arrays
