420 lines
15 KiB
Text
420 lines
15 KiB
Text
# 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.
|
|
ToolTipText String R/W Tooltip text shown after the mouse hovers over the control. Empty string or unset = no tooltip.
|
|
.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
|